\n\n# proto\n\nA local, privacy-first AI agent for the terminal. Part of the [protoLabs Studio](https://protolabs.studio) ecosystem.\n\n[](./LICENSE)\n[](https://nodejs.org/)\n\nproto is a fork of [Qwen Code](https://github.com/QwenLM/qwen-code) (itself forked from [Gemini CLI](https://github.com/google-gemini/gemini-cli)), rebuilt as a local, privacy-first coding agent. It runs in your terminal and works against the models you choose — local, self-hosted, or any OpenAI-compatible, Anthropic, or Gemini endpoint — so your code, keys, and context stay yours.\n\n## Installation\n\nOne-shot installer — ensures Node, installs proto, and runs the setup wizard:\n\n```bash\ncurl -fsSL https://cli.protolabs.studio/install.sh | sh\n```\n\nOr with npm (Node.js 20+; Rust toolchain optional, for beads_rust):\n\n```bash\n# Install from npm\nnpm install -g @protolabsai/proto\nproto --version\n\n# Or install from source\ngit clone https://github.com/protoLabsAI/protoCLI.git\ncd protoCLI\nnpm install && npm run build && npm link\n\n# Optional: task manager for persistent task tracking\ncargo install beads_rust\n```\n\n## Quick Start\n\n### 1. Run the setup wizard\n\n```bash\nproto setup\n```\n\n`proto setup` is an interactive wizard that picks a provider (OpenAI, Anthropic, Gemini, or any OpenAI-compatible endpoint), discovers the available models, optionally configures voice/STT, and writes everything to `~/.proto/settings.json` for you. Re-run it any time to switch providers or pick a different default model.\n\n### 2. Set your API key\n\nThe wizard tells you which env var it expects (e.g. `OPENAI_API_KEY`). Set it once:\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n```\n\nOr persist it in `~/.proto/.env`:\n\n```\nOPENAI_API_KEY=sk-your-key-here\n```\n\n### 3. Run proto\n\n```bash\nproto # interactive mode\nproto -p \"explain this codebase\" # one-shot mode\n```\n\nNo auth screen — proto connects directly to your endpoint.\n\n### Manual setup (advanced)\n\nIf you'd rather skip the wizard, drop a `~/.proto/settings.json` of your own:\n\n```json\n{\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"my-model\",\n \"name\": \"My Model\",\n \"baseUrl\": \"http://localhost:8000/v1\",\n \"envKey\": \"MY_API_KEY\"\n }\n ]\n },\n \"security\": {\n \"auth\": { \"selectedType\": \"openai\" }\n },\n \"model\": { \"name\": \"my-model\" }\n}\n```\n\n### Example: Multiple models via a gateway\n\nIf you run a gateway like [LiteLLM](https://github.com/BerriAI/litellm) in front of multiple providers, register them all under `modelProviders.openai` and switch between them with `/model`:\n\n```json\n{\n \"modelProviders\": {\n \"openai\": [\n {\n \"id\": \"local/qwen-122b\",\n \"name\": \"Qwen3.5-122B (local vLLM)\",\n \"baseUrl\": \"http://my-gateway:4000/v1\",\n \"envKey\": \"GATEWAY_KEY\",\n \"generationConfig\": { \"contextWindowSize\": 65536 }\n },\n {\n \"id\": \"claude-sonnet-4-6\",\n \"name\": \"Claude Sonnet 4.6\",\n \"baseUrl\": \"http://my-gateway:4000/v1\",\n \"envKey\": \"GATEWAY_KEY\",\n \"capabilities\": { \"vision\": true },\n \"generationConfig\": { \"contextWindowSize\": 200000 }\n },\n {\n \"id\": \"gpt-5.4\",\n \"name\": \"GPT-5.4\",\n \"baseUrl\": \"http://my-gateway:4000/v1\",\n \"envKey\": \"GATEWAY_KEY\",\n \"capabilities\": { \"vision\": true },\n \"generationConfig\": { \"contextWindowSize\": 200000 }\n }\n ]\n },\n \"security\": {\n \"auth\": { \"selectedType\": \"openai\" }\n },\n \"model\": { \"name\": \"local/qwen-122b\" }\n}\n```\n\n### Model config reference\n\n| Field | Required | Description |\n| ------------------------------------ | -------- | ---------------------------------------------------------------- |\n| `id` | yes | Model ID sent to the API (must match what your endpoint expects) |\n| `name` | no | Display name in proto UI (defaults to `id`) |\n| `baseUrl` | no | API base URL (defaults to OpenAI's) |\n| `envKey` | no | Environment variable name for the API key |\n| `description` | no | Shown in model picker |\n| `capabilities.vision` | no | Enable image/vision inputs |\n| `generationConfig.contextWindowSize` | no | Context window in tokens |\n\n## Configuration\n\nproto uses `~/.proto/settings.json` for global config and `.proto/settings.json` for per-project overrides.\n\n### MCP Servers\n\nAdd MCP servers directly in settings:\n\n```json\n{\n \"mcpServers\": {\n \"my_server\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server/dist/index.js\"],\n \"env\": { \"API_KEY\": \"...\" },\n \"trust\": true\n }\n }\n}\n```\n\nTools are exposed as `mcp____` and available to the agent immediately.\n\n### Plugin Discovery\n\nproto auto-discovers Claude Code plugins installed at `~/.claude/plugins/`. Any plugin's `commands/` directory is automatically loaded as slash commands — no additional config needed.\n\n### Environment variable overrides\n\n| Variable | Default | Description |\n| ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `PROTO_STREAM_STALL_TIMEOUT_MS` | `90000` | Max ms to wait between streaming chunks before declaring the connection stalled (then retrying) |\n| `PROTO_SYSTEM_DEFAULTS_PATH` | — | Override path to the system defaults settings file |\n| `PROTO_SYSTEM_SETTINGS_PATH` | — | Override path to the system settings override file |\n| `PROTO_LEGACY_ERASE_LINES` | — | Set to `1` to disable the cursor-collapse optimizer that prevents Ink scrollback bouncing during streaming renders. Only set this if it interferes with your terminal. |\n| `PROTO_FORCE_SYNCHRONIZED_OUTPUT` | — | Set to `1` to force-enable BSU/ESU atomic-frame escape codes regardless of terminal auto-detect (useful if your terminal supports DEC mode 2026 but isn't on the allowlist below). |\n| `PROTO_DISABLE_SYNCHRONIZED_OUTPUT` | — | Set to `1` to opt out of synchronized output even on supported terminals. |\n\n### TUI flicker mitigation\n\nproto installs two stdout interventions to reduce flicker during streaming renders:\n\n1. **Cursor-collapse optimizer** — collapses Ink's per-line `{ERASE_LINE, CURSOR_UP_ONE}` sequences into a single bounded erase. Universal; bypass via `PROTO_LEGACY_ERASE_LINES=1`.\n2. **Synchronized output** — wraps each render frame in BSU/ESU escape codes (DEC mode 2026) on terminals that support it. Auto-detected for: **Alacritty (≥0.14), Ghostty, Kitty, WezTerm, iTerm2**. For other DEC-2026-capable terminals, set `PROTO_FORCE_SYNCHRONIZED_OUTPUT=1`.\n\nBoth no-op outside a TTY, in screen-reader mode, or under tmux/SSH.\n\n## Observability\n\nproto ships OpenTelemetry-native, with both a Tempo/LGTM-style ops backend and Langfuse for prompt-grade trace UI. Both are **opt-in** — nothing is sent anywhere until `telemetry.enabled` is `true`.\n\n### Setup\n\nAdd to `~/.proto/settings.json`:\n\n```json\n{\n \"telemetry\": { \"enabled\": true },\n \"env\": {\n \"OTEL_INGRESS_TOKEN\": \"\",\n \"LANGFUSE_PUBLIC_KEY\": \"pk-lf-...\",\n \"LANGFUSE_SECRET_KEY\": \"sk-lf-...\",\n \"LANGFUSE_BASE_URL\": \"https://your-langfuse-instance.example.com\"\n }\n}\n```\n\nWith `telemetry.enabled = true`:\n\n- **OTLP traces** ship to `https://otel.proto-labs.ai` over HTTP, bearer-auth via `OTEL_INGRESS_TOKEN`. Override `telemetry.otlpEndpoint` / `telemetry.otlpProtocol` to point at a local OTel collector or a different vendor.\n- **Langfuse traces** ship to `LANGFUSE_BASE_URL` (defaults to `https://cloud.langfuse.com`) when both Langfuse keys are present.\n\nWithout `telemetry.enabled = true`, neither exporter activates regardless of env vars.\n\n> **Why `settings.json` and not `.env`?** proto walks up from your CWD loading `.env` files, so a project-level `.env` with telemetry keys would bleed into proto's tracing and mix your traces into the wrong dataset. The `env` block in `settings.json` is proto-namespaced and completely isolated from your projects.\n\n### What gets traced\n\n| Span | Attributes |\n| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |\n| `turn` | `session.id`, `turn.id` — root span per user prompt |\n| `gen_ai chat {model}` | `gen_ai.usage.{input,output,thinking}_tokens`, `gen_ai.request.model`, `gen_ai.response.thinking` (when present) — one per LLM call |\n| `tool/{name}` | `tool.name`, `tool.type`, `tool.duration_ms` — one per tool execution |\n| `agent/{name}` | `agent.name`, `agent.status`, `agent.duration_ms` — one per subagent |\n\nAll three provider backends are covered: OpenAI-compatible, Anthropic, and Gemini.\n\n### Prompt content logging\n\nFull prompt messages, response text, and reasoning text are included in traces by default. To disable:\n\n```json\n// ~/.proto/settings.json\n{\n \"telemetry\": { \"enabled\": true, \"logPrompts\": false }\n}\n```\n\n> **Privacy note:** Telemetry is off by default. When you opt in, `logPrompts` defaults to `true` — full prompt, response, and reasoning content are attached to spans (truncated at 10K chars each). Set `logPrompts: false` if you want token counts and timings without message content.\n\n## Task Management\n\nproto integrates [beads_rust](https://github.com/Dicklesworthstone/beads_rust) for persistent, SQLite-backed task tracking. When `br` is on PATH, the 6 task tools (`task_create`, `task_get`, `task_list`, `task_update`, `task_stop`, `task_output`) use it as the backend. Tasks persist across sessions in `.beads/` within the project directory.\n\nIf `br` is not installed, tasks fall back to the original in-memory JSON store.\n\n```bash\n# The agent uses these automatically, but you can also use br directly:\nbr list # See all tasks\nbr list --json # Machine-readable output\nbr create --title \"Fix auth bug\" --type task --priority 1\nbr close --reason \"Fixed in commit abc123\"\n```\n\n## Long-running Background Shells\n\nproto captures the output of shell commands run with `is_background: true` to disk so detached processes never silently lose their stdout. The agent gets a stable task ID and an absolute output file path it can read at any time, plus an automatic `` on the next turn when the task exits.\n\n- **Output file:** `//tasks/.output` — written by the OS via shell-level redirection, so it keeps growing even after the parent wrapper exits.\n- **Completion:** when the bg process exits, the next user prompt is prefixed with a `` block carrying `task_id`, `output_file`, `status` (completed/failed/killed), and `exit_code`. The agent can then `read_file` the output for results.\n- **`/bg`** lists running and recently-completed background tasks.\n- **`bg_stop` tool** — sends SIGTERM to the process group, escalating to SIGKILL after a 3s grace.\n\nThis is what fixes the \"agent runs an eval, can't find the results\" failure mode that plagued earlier versions where backgrounded `&` commands streamed into nowhere.\n\n## Memory\n\nproto has a persistent memory system inspired by Claude Code. Memories are individual markdown files with YAML frontmatter, organized by type and stored per-project or globally.\n\n### Memory types\n\n| Type | Purpose | Example |\n| ----------- | ------------------------------------- | ---------------------------------------------- |\n| `user` | Preferences, role, knowledge | \"prefers tabs over spaces\" |\n| `feedback` | Approach corrections or confirmations | \"don't mock the database in integration tests\" |\n| `project` | Deadlines, decisions, ongoing work | \"merge freeze starts April 5\" |\n| `reference` | Pointers to external systems | \"bugs tracked in Linear project INGEST\" |\n\n### How it works\n\nEach memory is a `.md` file in `.proto/memory/` (project) or `~/.proto/memory/` (global):\n\n```markdown\n---\nname: prefer-dark-theme\ndescription: User prefers dark themes in all editors\ntype: user\n---\n\nUser explicitly stated they prefer dark themes.\n```\n\nA `MEMORY.md` index is auto-generated and loaded into the system prompt at the start of each session. The agent can create memories via the `save_memory` tool, or you can use slash commands:\n\n```\n/memory add --project I prefer dark themes\n/memory list\n/memory forget prefer-dark-theme\n/memory show\n/memory refresh\n```\n\nAfter each conversation turn, a background extraction agent reviews recent messages and auto-creates memories for notable facts. This runs fire-and-forget with restricted tools (read/write/glob in the memory directory only).\n\n## Agent Harness\n\nproto includes a harness system that enforces quality gates, limits scope, and recovers from failures automatically.\n\n### Sprint Contract (Scope Lock)\n\nPrevents agents from modifying files outside an agreed scope. The agent (or a user-supplied skill) constructs a contract that defines exactly which files will be created or modified, and the scope lock arms automatically — any write outside scope is rejected with a recovery message.\n\n**Behavior:**\n\n- Write to `src/auth.ts` (in scope) → ALLOWED\n- Write to `tests/foo.test.ts` (out of scope) → BLOCKED with scope violation message\n\nContracts persist at `.proto/sprint-contract.json` and auto-restore on session resume. The opinionated `sprint-contract` _skill_ that used to walk agents through negotiating one has been removed; the underlying scope-lock primitive remains and can be driven by your own skill or directly via `SprintContractService`.\n\n### Behavior Verification Gate\n\nPost-run smoke tests that verify changes actually work. After a subagent completes, the gate runs your defined scenarios (shell commands) in parallel. Failures inject a remediation message back to the agent for self-correction.\n\n**Setup** — create `.proto/verify-scenarios.json`:\n\n```json\n[\n { \"name\": \"tests pass\", \"command\": \"npm test -- --run\", \"timeoutMs\": 60000 },\n { \"name\": \"build works\", \"command\": \"npm run build\", \"timeoutMs\": 30000 },\n { \"name\": \"no TypeScript errors\", \"command\": \"npm run typecheck\" }\n]\n```\n\n**Behavior:**\n\n1. Agent completes task, reports GOAL\n2. Gate fires, runs all scenarios in parallel\n3. If any fail → remediation message injected, agent self-corrects\n4. Gate fires again until all pass\n\n### Multi-Sample Retry\n\nWhen a subagent fails (ERROR, MAX_TURNS, or TIMEOUT), proto retries up to 2 more times with escalating temperatures (0.7 → 1.0 → 1.3). Each retry gets a `[RETRY CONTEXT]` block summarizing previous failures. Best result by score is returned.\n\nThis reduces false negatives from single-run failures and gives the model multiple chances with different sampling strategies.\n\n### Repo Map\n\nPageRank-based file importance ranking. Analyzes the project's TypeScript/JS import graph to surface the most central files. Useful for understanding codebase structure or finding related files.\n\n**Usage:**\n\n```bash\nproto -p \"Use the repo_map tool to find the most important files in this codebase\"\nproto -p \"Use repo_map with seedFiles=['src/auth.ts'] to find related files\"\n```\n\nResults are cached at `.proto/repo-map-cache.json` and auto-invalidate on file changes.\n\n## Skills\n\nproto ships with a small set of bundled utility skills. Workflow skills (TDD, plan authoring, sprint contracts, code-review choreography, etc.) are intentionally **not** baked in — drop them into `~/.proto/skills/` or a project's `.proto/skills/` when you want them, so build-outs aren't forced into one opinionated process.\n\n- **browser-automation** — Web browser automation (navigate, click, fill forms, screenshot, extract content)\n- **review** — Generic code-review workflow\n- **proto-helper** — protoCLI usage, features, configuration, and troubleshooting\n- **harness-reference** — Reference for proto's agent-harness internals (sprint contracts, verification gates, retry logic, etc.)\n\nUse `/skills` to list every skill available in a session (bundled + user + project).\n\n### Browser Automation\n\nproto includes a native browser automation tool powered by [agent-browser](https://github.com/nickinack/agent-browser). This enables AI agents to interact with websites — navigate, click, fill forms, take screenshots, and extract content.\n\n#### Installation\n\n```bash\nnpm install -g agent-browser\nagent-browser install # Downloads Chrome\n```\n\n#### Usage\n\n```javascript\n// Open a website\nbrowser({ action: 'open', url: 'https://example.com' });\n\n// Get interactive elements\nbrowser({ action: 'snapshot', flags: JSON.stringify({ interactive: true }) });\n\n// Click an element\nbrowser({ action: 'click', selector: '@e2' });\n\n// Fill a form\nbrowser({ action: 'fill', selector: '@e1', text: 'user@example.com' });\n\n// Take screenshot\nbrowser({ action: 'screenshot', outputPath: '/path/to/screenshot.png' });\n```\n\n#### Key Actions\n\n| Action | Description |\n| ------------------------------ | ------------------------------------------ |\n| `open` / `close` | Navigate to URL or close browser |\n| `click` / `dblclick` / `hover` | Element interaction |\n| `fill` / `type` | Form input |\n| `snapshot` | Get accessibility tree with element refs |\n| `screenshot` | Capture page screenshot |\n| `get` / `is` / `find` | Query element properties |\n| `wait` | Wait for elements, network, or URL changes |\n| `batch` | Execute multiple commands in sequence |\n\nThe browser skill (`/skills` → browser-automation) provides comprehensive documentation for all 38 available actions.\n\n## Agent Teams\n\nRun multiple coordinated agents that share tasks and communicate directly with each other.\n\n```\n/team start my-team lead:coordinator scout:Explore coder:general-purpose\n```\n\nThis spawns three live agents immediately. Each member runs as an in-process agent and gets two extra tools injected automatically:\n\n- **`mailbox_send`** — send a message to a teammate by their agentId\n- **`mailbox_receive`** — drain all unread messages from your inbox\n\nMembers share the same task list (`task_create`, `task_list`, `task_update`) so any agent can create tasks and others can claim them.\n\n### Team commands\n\n| Command | Description |\n| -------------------------------------- | ------------------------------------- |\n| `/team start [member:type ...]` | Spawn live agents and start the team |\n| `/team status ` | Show live member status |\n| `/team stop ` | Kill all agents and release resources |\n| `/team list` | List all teams in the project |\n| `/team delete ` | Delete a team config |\n\n**Default team** (no members specified): `lead` (coordinator) + `scout` (Explore).\n\nAgent IDs follow the pattern `-` (e.g. `lead-0`, `scout-1`). Use these when sending mailbox messages between agents.\n\n### Member types\n\n| Type | Purpose |\n| ----------------- | ----------------------------------------- |\n| `coordinator` | Orchestrate subtasks across other members |\n| `Explore` | Fast codebase search and analysis |\n| `general-purpose` | Multi-step implementation tasks |\n| `verify` | Review and correctness checking |\n| `plan` | Design plans before implementation |\n\nAny user-defined sub-agent from `.proto/agents/` can also be used as a member type.\n\n## Talk to A2A Agents\n\nproto is a first-class **terminal client for [A2A](https://a2a-protocol.org/) agents** — register an agent once, then chat with it by name. This is the client direction (proto reaches out to a remote agent); it mirrors [driving proto as an ACP coding agent](./docs/guides/acp-coding-agent.md), so proto and the protoLabs **[protoAgent](https://github.com/protoLabsAI/protoAgent)** fleet talk both ways (ACP one way, A2A the other).\n\n```bash\nproto agents # list registered + auto-discovered agents, with status\nproto agent add roxy https://roxy:7870 # register a named shortcut\nproto agent roxy # connect → streaming chat (no URL to retype)\n```\n\nDiscovery is built in (it scans localhost for agent cards, like protoAgent's own fleet broadcast/scan), so a protoAgent running locally shows up in `proto agents` with no setup. proto targets **A2A 1.0** (`SendStreamingMessage` over SSE, `contextId` continuity, `cost-v1`/`tool-call-v1` extensions, Bearer/API-key auth), so it works against any conformant A2A agent. See the [A2A agents guide](./docs/guides/a2a-agents.md).\n\n## Commands\n\n| Command | Description |\n| ----------------------- | ----------------------------------------- |\n| `/help` | Show available commands |\n| `/auth` | Configure authentication |\n| `/model` | Switch models |\n| `/skills` | List available skills |\n| `/memory show` | Display loaded memory content |\n| `/memory list` | List all memories with type, scope, age |\n| `/memory add ` | Save a memory (`--global` or `--project`) |\n| `/memory forget ` | Delete a memory |\n| `/memory refresh` | Reload memories from disk |\n| `/clear` | Clear conversation |\n| `/compress` | Compress history to save tokens |\n| `/stats` | Session info |\n| `/exit` | Exit proto |\n\n## Keyboard Shortcuts\n\n| Shortcut | Action |\n| ----------- | --------------------------------------------------------------- |\n| `Ctrl+C` | Cancel ongoing request. Press twice to exit. |\n| `Ctrl+D` | Exit if input is empty. |\n| `Ctrl+L` | Clear the screen |\n| `Ctrl+Y` | Retry the last failed request |\n| `Shift+Tab` | Cycle approval modes: `plan` → `default` → `auto-edit` → `yolo` |\n| `Up/Down` | Navigate command history |\n\nSee [Keyboard Shortcuts reference](docs/reference/keyboard-shortcuts.md) for the full list.\n\n## Voice Integration\n\nproto supports push-to-talk voice input. Press the mic button in the footer or use `/voice` to toggle.\n\n### Requirements\n\nVoice capture requires a system audio backend:\n\n| OS | Backend | Install |\n| ----- | ------- | ------------------------------------- |\n| macOS | sox | `brew install sox` |\n| Linux | sox | `apt install sox` / `dnf install sox` |\n| Linux | arecord | `apt install alsa-utils` (fallback) |\n\nVerify detection: `/voice status`\n\n### STT backend\n\nVoice input transcribes audio via a Whisper-compatible `/v1/audio/transcriptions` endpoint. Self-host one (e.g. [faster-whisper-server](https://github.com/fedirz/faster-whisper-server)):\n\n```bash\ndocker run --gpus all -p 8000:8000 fedirz/faster-whisper-server:latest-cuda\n```\n\n```json\n// ~/.proto/settings.json\n{\n \"voice\": {\n \"enabled\": true,\n \"sttEndpoint\": \"http://localhost:8000/v1/audio/transcriptions\"\n }\n}\n```\n\nThe default endpoint is `http://localhost:8000/v1/audio/transcriptions` if none is configured.\n\n## Architecture\n\n```\npackages/\n├── cli/ # Terminal UI (Ink + React)\n├── core/ # Agent engine, tools, skills, MCP client\n├── sdk-typescript/# TypeScript SDK\n├── web-templates/ # Shared web templates\n├── webui/ # Shared UI components\n└── test-utils/ # Testing utilities\n```\n\n## Acknowledgments\n\nBuilt on [Qwen Code](https://github.com/QwenLM/qwen-code) (Apache 2.0), which is built on [Gemini CLI](https://github.com/google-gemini/gemini-cli) (Apache 2.0). Task management powered by [beads_rust](https://github.com/Dicklesworthstone/beads_rust).\n\n## License\n\nApache 2.0 — see [LICENSE](./LICENSE).\n","readmeFilename":"README.md"}
![\"proto](\"https://cli.protolabs.studio/og-protocli.png\")
\n