ProtoAgent Monorepo
ProtoAgent is a local-first coding agent optimized for inspectable operation with smaller models. The repo is organized around one core idea: keep application logic in the Python core, keep frontends thin, and let ProtoLink own agent discovery, delegation, tools, state, events, actions, approvals, cancellation, transports, and reports.
The current monorepo has three main product surfaces:
| Surface | Path | Version | Status | Responsibility |
|---|---|---|---|---|
| Rust CLI and TUI | cli/ | 0.3.0 | Active | Terminal UX, project selection, model setup, live progress, approvals, cancellation, traces, sessions. |
| Python core | core/protoagent_core/ | 0.3.0 | Active | ProtoLink agent deck, model/provider wiring, Context Loom, config, history, tools, runtime bridge. |
| ACP server | acp/ | 0.0.0-dev.0 | Planned | Editor-facing Agent Client Protocol server. Current docs mark implementation details as TBD. |
The rest of the repo supports those surfaces:
| Path | Purpose |
|---|---|
whitepaper.md | Architecture thesis for local-first Agent-to-Agent orchestration. |
playground/ | Small sample apps used as coding-agent targets and integration sandboxes. |
misc/assets/ | Images and CLI demos used by README and docs. |
Design Principles
ProtoAgent is not a single giant prompt wrapped in a terminal. The system is split into small, inspectable components:
- Frontends stay product-specific. The CLI owns terminal interaction, panels, modal flows, input history, and approval UX.
- The Python core owns app logic. Provider discovery, config, Context Loom,
runtime startup, and the agent deck live under
core/protoagent_core/. - ProtoLink owns runtime semantics. Runs use
RunContext,RunBudget,RunEvent,RunReport, typed actions, capability policies, state APIs, streaming task channels, and cancellation requests. - Context is visible. Context Loom builds a deterministic, source-cited evidence pack before the model reasons.
- State is deliberate. Architect keeps durable conversation memory, while Explorer, Coder, Verifier and enabled optional Tester/Scout/MCP are task-local stateless workers.
- Runs have contracts. Write tasks need executed file changes at their current native resource revisions. Approvals cannot satisfy completion.
- Writes are approval-gated. Native tools prepare exact diff artifacts. Rust resolves scoped broker requests by ID and action fingerprint.
How These Docs Are Organized
These docs are intentionally modular. A future change should usually require updating one page, not rewriting a manual.
| If you change... | Update... |
|---|---|
| A shell command or slash command | CLI / Commands |
| A TUI panel, modal, scrolling rule, or input behavior | CLI / Fullscreen TUI |
| Project config, sessions, or file tagging | CLI / Projects and Sessions |
| Provider discovery, API keys, or model selection | CLI / Models and Config and Core / Config and Models |
| Context Loom scoring, index schema, or prompt format | CLI / Context Loom and Core / Context Loom |
| Runtime transport, budgets, streaming, tracing, or cancellation | Core / Runtime and Reference / Environment |
| Component version source or release marker | Reference / Versioning |
| User-visible release behavior | Root CHANGELOG.md |
| Agent prompts, tools, or policies | Core / Agent Deck and Core / Safety and Tools |
| Optional agent or network capability | Core / Agent Deck, Core / Safety and Tools, CLI / Commands, and Reference / Environment |
| Contributor tooling, linting, type-checking, or formatting | Contributing / Development Workflow and Reference / Verification |
| ACP implementation | ACP / Plan |
Source Of Truth
The docs describe the code currently checked into this repo. When there is a conflict, prefer the implementation and update the relevant doc page in the same change.
Useful source entrypoints:
| Code | What to inspect |
|---|---|
cli/src/main.rs | Shell command routing, PyO3 calls, context commands, config paths. |
cli/src/terminal_ui.rs | Fullscreen TUI command dispatcher and task loop. |
cli/src/terminal_ui/ | Focused TUI modules for render, modals, project picker, model picker, approvals, diff review. |
cli/src/progress.rs | Live JSONL progress tailing, approval decision files, context meter samples. |
cli/src/timeline.rs | Normalized RunEvent trace and timeline formatting. |
cli/src/sessions.rs | Rust UI session ledger. |
core/protoagent_core/agent_engine.py | PyO3-facing functions called by Rust. |
core/protoagent_core/runtime.py | ProtoLink runtime mesh startup and streaming execution. |
core/protoagent_core/agents/ | Required Architect/Explorer/Coder/Verifier, optional Tester/Scout/MCP, and deck assembly. |
Optional workers are user-controlled: /agents tester on|off changes test design
(default on), while Scout/MCP default off. Disabling Tester removes its model
without bypassing required checks. /mcp configures named external tool servers
without an LLM. The broker returns one schema and executes approved allowlisted
calls through ProtoLink 0.8.1, keeping large catalogs out of small-model prompts.
See MCP Broker for setup and effect boundaries.
| core/protoagent_core/context/ | Context Loom index, SQLite store, pack builder, schemas. |
| core/protoagent_core/history.py | ProtoLink state describe, compact, reset, and persistence helpers. |
| core/protoagent_core/tools.py | Workspace-safe read, search, diff preview, and writes. |
| pyproject.toml | Ruff and ty configuration for the Python surface. |
| core/pyproject.toml | Python core package metadata and core release version. |
| VERSIONING.md | Component version policy and source-of-truth map. |
| CHANGELOG.md | Dated user-visible release notes. |
| rustfmt.toml | Rust formatting configuration for the CLI crate. |
| CONTRIBUTING.md | GitHub-facing contributor setup and pull request workflow. |