From f9cb0158732592723879565bff1288d17d5e2f7a Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Fri, 28 Aug 2026 15:15:07 -0700 Subject: [PATCH 1/2] Refresh the README to match the shipping product The root README still described Ink + React, a toy agent loop, and an incomplete contribute gate, and it omitted exec, resume, steering, plugins, MCP, and hooks that PRODUCT and ARCHITECTURE already document. --- README.md | 226 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 169 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 197a1fc5..5fa7477f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,13 @@ # Corbits Code -Corbits Code is a local-first coding agent. It lives in your terminal and works with whatever model you point it at — Anthropic, OpenAI, Google, a local Ollama, or any OpenAI-compatible endpoint. Your machine, your keys, your code. +Corbits Code is a local agentic software factory: a single-process coding agent +CLI that runs multi-agent fleets to implement, verify, and land software — with +progress and cost always visible. Point it at Anthropic, OpenAI, Google, a local +Ollama, or any OpenAI-compatible endpoint. Your machine, your keys, your code. + +The product is the **harness** — the loop that dispatches work, watches it, +decides what happens next, and reports to the operator. Agent personas and +skills are content that run inside it. ## Quickstart @@ -10,7 +17,8 @@ Corbits Code is a local-first coding agent. It lives in your terminal and works brew install corbitsdev/tap/corbits-code ``` -Upgrade later with `brew update && brew upgrade corbits-code`. The CLI binary is `corbits`. +Upgrade later with `brew update && brew upgrade corbits-code`. The CLI binary is +`corbits`. ### From source @@ -34,96 +42,200 @@ ln -s "$PWD/dist/corbits" ~/.local/bin/corbits After pulling new changes, re-run `bun run build:bin` to refresh the binary. -## Contributing +## Usage -Before your first commit: `git config core.hooksPath .githooks` and `./bin/check-env`. +### TUI (default) -Every change must pass `bun run typecheck`, `bun run build`, and `bun run test`, and behavior changes come with tests. Coding conventions live in `AGENTS.md` (functional TypeScript, no classes, arktype at boundaries); commit, PR, and Linear/GitHub linking rules live in `CONTRIBUTING.md`. System design is documented in `docs/ARCHITECTURE.md` and `docs/IMPLEMENTATION.md`. +```sh +corbits "Add JWT auth to the API" +``` -## Stack +Full-screen terminal UI (OpenTUI): event log, permission and operator prompts, +diff and cost visibility, and a chat input for follow-ups. Press **Shift+Tab** +to cycle reasoning effort for the current model; **Tab** toggles focus between +the prompt and the transcript. See `docs/TUI.md`. -- **Runtime:** Bun + TypeScript -- **Agent loop:** `@intx/agent` with event-driven reactor -- **Inference:** `@intx/inference` with OpenAI-compatible SSE adapter -- **Tools:** `@intx/tools-posix` with path-escape, authz, and verify plugins -- **Persistence:** `@intx/storage-isogit` for git-backed resume -- **Testing:** `@intx/inference-testing` for deterministic agent loop tests -- **TUI:** Ink + React +### Exec (non-TUI) -## Architecture +```sh +corbits exec "Add JWT auth to the API" +# alias: +corbits run "Add JWT auth to the API" +``` -Corbits Code is a single-process CLI built on Interchange primitives. The goal is raw feature implementation throughput that outperforms other coding agents through deterministic event-loop discipline, better prompts, and a custom reactor director. +Same directors, tools, permissions, MCP, plugins, and hooks as the TUI — without +the OpenTUI shell. Streams assistant text to stdout for scripts and CI. -``` -CLI (src/index.ts) - → load config, load skills - → createPosixTools({ cwd, plugins: [pathEscapePlugin, authzPlugin, verifyPlugin] }) - → createAgent(agentDef, { - sources, // built per active provider: Anthropic, OpenAI, Google, Ollama, or an OpenAI-compatible endpoint - defaultSource, - tools: posixTools, - director: createChatDirector(systemPrompt, tools), - }) - → agent.send(task) - → for await (event of agent.stream()) { handle } - → agent.close() +### Resume + +```sh +corbits resume +# or: +corbits resume ``` -The chat director adds context management on top of the reactor: +Plain `corbits` always starts a fresh conversation. `corbits resume` opens a +picker of saved sessions for the working directory. + +### Mid-run steering + +While a run is in progress: -- **Threshold compaction:** As the context window fills, the conversation is compacted at the next safe point. -- **Idle compaction:** A pending compaction also runs when a turn ends without more work, so a text-only conversation still compacts. -- **Overflow recovery:** A context-overflow error triggers a bounded compact-and-retry instead of failing the turn. -- **Workflow nudges:** When a workflow is active, the director keeps the run on the current step and surfaces a visible message if it stalls. +- **Enter** — soft-steer at the next parent tool boundary (does not stop the run) +- **Alt+Enter** — queue a follow-up delivered when the session is idle +- **Ctrl+C** — stop the run + +Shortcuts are listed in `/help`. Details live in `docs/PRODUCT.md`. ## Permissions and auto mode -Corbits Code defaults to **auto mode** (`auto = true`). Workspace file writes/edits/deletes and unconstrained shell commands run without per-action prompts. Pass `--no-auto` to start in ask-on-every-consequential-action mode (there is currently no in-session key to toggle auto). Press **Shift+Tab** in the TUI to cycle reasoning effort for the current model. Enabling auto prints a one-line reminder of the envelope below. +Corbits Code defaults to **auto mode** (`auto = true`). Workspace file +writes/edits/deletes and unconstrained shell commands run without per-action +prompts. Pass `--no-auto` to start in ask-on-every-consequential-action mode +(there is currently no in-session key to toggle auto). Enabling auto prints a +one-line reminder of the envelope below. ### What auto allows -- File tools inside the workspace: `write_file`, `edit_file`, `delete_file` (and other non-shell built-ins such as `manage_tasks`, `task`, …) -- Unconstrained shell (builds, tests, git, one-off commands that match no deny/ask rule) -- Read-only tools (`read_file`, `grep`, `search_files`, `list_dir`, `lsp`, …) always allow regardless of mode +- File tools inside the workspace: `write_file`, `edit_file`, `delete_file` (and + other non-shell built-ins such as `manage_tasks`, `task`, …) +- Unconstrained shell (builds, tests, git, one-off commands that match no + deny/ask rule) +- Read-only tools (`read_file`, `grep`, `search_files`, `list_dir`, `lsp`, …) + always allow regardless of mode ### What still asks (even in auto) -- Dependency installs and remote runners (`npm install` / `i` / `ci` / `add`, `pip install`, `cargo add`, `brew install`, `npx` / `bunx`, …) +- Dependency installs and remote runners (`npm install` / `i` / `ci` / `add`, + `pip install`, `cargo add`, `brew install`, `npx` / `bunx`, …) - Recursive `rm` (`-r` / `-R` / `--recursive`) -- Force or uncontained git worktree add/remove/prune (contained non-force add/remove/prune and read-only `git worktree list` auto-allow) -- Shell that references sensitive paths (`.env`, private keys, certs, credential files, …) -- Opaque shell wrappers the policy cannot statically inspect (variable expansion or command substitution in a wrapper payload) -- Paths outside the workspace, writes under the session state root, mutating MCP tools, and unknown built-ins +- Force or uncontained git worktree add/remove/prune (contained non-force + add/remove/prune and read-only `git worktree list` auto-allow) +- Shell that references sensitive paths (`.env`, private keys, certs, credential + files, …) +- Opaque shell wrappers the policy cannot statically inspect (variable expansion + or command substitution in a wrapper payload) +- Paths outside the workspace, writes under the session state root, mutating MCP + tools, and unknown built-ins ### What auto hard-denies (use the file tools instead) -- File creation or edits via shell: redirects (`>` / `>>`), `tee`, `sed -i` / `perl -i` / similar, interpreter inline programs or heredocs (`python -c`, `node -e`, …) +- File creation or edits via shell: redirects (`>` / `>>`), `tee`, `sed -i` / + `perl -i` / similar, interpreter inline programs or heredocs (`python -c`, + `node -e`, …) -Wrappers such as `bash -c '…'`, `sh`/`zsh -c`, `xargs`, and transparent prefixes (`env`, `nice`, `timeout`) are peeled so the same rules apply to the inner command. Unparseable wrappers fall through to ask rather than auto-allow. +Wrappers such as `bash -c '…'`, `sh`/`zsh -c`, `xargs`, and transparent prefixes +(`env`, `nice`, `timeout`) are peeled so the same rules apply to the inner +command. Unparseable wrappers fall through to ask rather than auto-allow. -Catastrophic patterns (`rm -rf /`, `sudo`, `curl | bash`, force-push, open-ended `find`/`rg`/`grep -r`, …) are always denied by authorization, independent of auto mode. `--dangerously-skip-permissions` still forces this process; `/yolo` persists as the user-global default. Both bypass the permission gate (not secret-guard path denies or authz hard blocks). +Catastrophic patterns (`rm -rf /`, `sudo`, `curl | bash`, force-push, open-ended +`find`/`rg`/`grep -r`, …) are always denied by authorization, independent of +auto mode. `--dangerously-skip-permissions` still forces this process; `/yolo` +persists as the user-global default. Both bypass the permission gate (not +secret-guard path denies or authz hard blocks). -Details live in `docs/PRODUCT.md` (safety model) and `docs/ARCHITECTURE.md` (permission gate and auto-shell policy). +Details live in `docs/PRODUCT.md` (safety model) and `docs/ARCHITECTURE.md` +(permission gate and auto-shell policy). -## Development +## Stack + +- **Runtime:** Bun + TypeScript +- **Agent loop:** `@intx/agent` with an event-driven reactor +- **Inference:** `@intx/inference` (vendored) with OpenAI-compatible adapters +- **Tools:** `@intx/tools-posix` and `@intx/tools-lsp` +- **Authz:** `@intx/authz` for grant matching; Corbits owns the gate, store, and TUI ask +- **Persistence:** `@intx/storage-isogit` for git-backed resume +- **MCP:** Model Context Protocol SDK for external tool servers +- **TUI:** OpenTUI (`@opentui/core`, `@opentui/solid`) + +## Architecture + +Corbits Code is a single-process CLI built on Interchange primitives. The primary +session is always the **orchestrator** (Skywalker): it can act directly and +delegates substantial work through a closed director fleet via `spawn_agent` / +`wait_agents` / `search_agents` (`task` remains a fused spawn-plus-wait +wrapper). -```bash -bun install -bun run typecheck -bun run build -bun run test ``` +CLI (src/index.ts) + → load config / settings + → runTUI (default) or runExec (corbits exec | run) + → create agent with ChatDirector, posix tools, permission gate + → mount plugins, MCP, hooks, skills + → primary orchestrator turn + ↳ spawn_agent / wait_agents → closed directors (builder, explorer, …) + → event stream → OpenTUI host (TUI) or stdout (exec) +``` + +The chat director adds context management on top of the reactor: + +- **Threshold compaction:** As the context window fills, the conversation is + compacted at the next safe point. +- **Idle compaction:** A pending compaction also runs when a turn ends without + more work, so a text-only conversation still compacts. +- **Overflow recovery:** A context-overflow error triggers a bounded + compact-and-retry instead of failing the turn. +- **Workflow nudges:** When a workflow is active, the director keeps the run on + the current step and surfaces a visible message if it stalls. + +Deep design: `docs/ARCHITECTURE.md`, `docs/IMPLEMENTATION.md`, `docs/PRODUCT.md`. -## Agent Workspace +## Extensibility + +- **Plugins** — discovery and manifests: `docs/PLUGINS.md` +- **MCP** — connect external tool servers: `docs/MCP.md` +- **Hooks** — lifecycle hooks: `docs/HOOKS.md` +- **Skills / slash commands** — first-party actions such as `/implement`, + `/plan`, `/review`, `/create-issue` ship with the `corbits-skills` plugin (on + by default; toggle in `/plugins`) + +## Agent workspace Corbits Code keeps repository guidance and the closed director fleet separate: - `AGENTS.md` — shared startup instructions and project context -- `CLAUDE.md` — Claude-specific workspace notes -- `src/agent/directors/` — closed spawn catalog (`directorProfiles()`). Skywalker is the primary orchestrator; spawnable directors include builder, explorer, counsel, intern, critic, greybeard, and the rest of `DIRECTOR_IDS`. Closed ids cannot be overridden by plugins or local files. -- `.agents/agents/` — optional local profile additions; this directory is not required and may be absent +- `src/agent/directors/` — closed spawn catalog (`directorProfiles()`). Skywalker + is the primary orchestrator; spawnable directors include builder, explorer, + counsel, intern, critic, greybeard, neckbeard, bruckheimer, gaasbot, draper, + emil, rand, shakespeare, testsmith, and tester. Closed ids cannot be + overridden by plugins or local files. +- `.agents/agents/` — optional local profile additions; this directory is not + required and may be absent + +Named workers resolve through `spawn_agent` / `task` (`resolveDirector`): closed +directors first, then enabled agent plugins, then local +`.agents/agents/*.json|*.yaml` profiles. Use `search_agents` to discover ids +before dispatching. + +## Contributing + +Before your first commit: `git config core.hooksPath .githooks` and +`./bin/check-env`. + +Every change must pass `bun run check` (lint, typecheck, build, and test). +Behavior changes come with tests. Coding conventions live in `AGENTS.md` +(functional TypeScript, no classes, arktype at boundaries); commit, PR, and +Linear/GitHub linking rules live in `CONTRIBUTING.md`. + +```bash +bun install +bun run check +``` -Named workers resolve through `spawn_agent` / `task` (`resolveDirector`): closed directors first, then enabled agent plugins, then local `.agents/agents/*.json|*.yaml` profiles. Use `search_agents` to discover ids before dispatching. +## Docs + +| Doc | Covers | +| --- | --- | +| `docs/PRODUCT.md` | What we are building and why | +| `docs/ARCHITECTURE.md` | Reactor, directors, permissions, exec | +| `docs/IMPLEMENTATION.md` | Runtime, config, CLI flags, persistence | +| `docs/TUI.md` | Terminal UI behavior | +| `docs/PLUGINS.md` | Plugin manifests and discovery | +| `docs/MCP.md` | MCP servers | +| `docs/HOOKS.md` | Lifecycle hooks | +| `docs/TELEMETRY.md` | Usage telemetry | +| `docs/PERFTRACE.md` | Local PerfTrace / OTEL export | +| `docs/VENDORING.md` | Vendored Interchange packages | ## License From 96656ab9c2dbe4c9fe292313292188f41402589c Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Sat, 29 Aug 2026 22:35:26 -0700 Subject: [PATCH 2/2] Correct README steering copy and Prettier formatting Enter starts a new primary turn when the parent is idle with a fleet still running; the auto-on reminder sentence is not shipped. --- README.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 5fa7477f..87ce80aa 100644 --- a/README.md +++ b/README.md @@ -81,9 +81,9 @@ picker of saved sessions for the working directory. While a run is in progress: -- **Enter** — soft-steer at the next parent tool boundary (does not stop the run) -- **Alt+Enter** — queue a follow-up delivered when the session is idle -- **Ctrl+C** — stop the run +- **Enter** — soft-steer while the parent is busy (in-flight tool / `wait_agents`); starts a new primary turn when the parent is idle with a fleet still running +- **Alt+Enter** — queue a follow-up delivered when the whole session is idle +- **Ctrl+C** — interrupt the run Shortcuts are listed in `/help`. Details live in `docs/PRODUCT.md`. @@ -92,8 +92,7 @@ Shortcuts are listed in `/help`. Details live in `docs/PRODUCT.md`. Corbits Code defaults to **auto mode** (`auto = true`). Workspace file writes/edits/deletes and unconstrained shell commands run without per-action prompts. Pass `--no-auto` to start in ask-on-every-consequential-action mode -(there is currently no in-session key to toggle auto). Enabling auto prints a -one-line reminder of the envelope below. +(there is currently no in-session key to toggle auto). ### What auto allows @@ -224,18 +223,18 @@ bun run check ## Docs -| Doc | Covers | -| --- | --- | -| `docs/PRODUCT.md` | What we are building and why | -| `docs/ARCHITECTURE.md` | Reactor, directors, permissions, exec | +| Doc | Covers | +| ------------------------ | --------------------------------------- | +| `docs/PRODUCT.md` | What we are building and why | +| `docs/ARCHITECTURE.md` | Reactor, directors, permissions, exec | | `docs/IMPLEMENTATION.md` | Runtime, config, CLI flags, persistence | -| `docs/TUI.md` | Terminal UI behavior | -| `docs/PLUGINS.md` | Plugin manifests and discovery | -| `docs/MCP.md` | MCP servers | -| `docs/HOOKS.md` | Lifecycle hooks | -| `docs/TELEMETRY.md` | Usage telemetry | -| `docs/PERFTRACE.md` | Local PerfTrace / OTEL export | -| `docs/VENDORING.md` | Vendored Interchange packages | +| `docs/TUI.md` | Terminal UI behavior | +| `docs/PLUGINS.md` | Plugin manifests and discovery | +| `docs/MCP.md` | MCP servers | +| `docs/HOOKS.md` | Lifecycle hooks | +| `docs/TELEMETRY.md` | Usage telemetry | +| `docs/PERFTRACE.md` | Local PerfTrace / OTEL export | +| `docs/VENDORING.md` | Vendored Interchange packages | ## License