Skip to content

Cut the README to a way in and let the docs carry the depth #987

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheGreatAxios merged 1 commit into from
Sep 13, 2026
Merged

Cut the README to a way in and let the docs carry the depth #987

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 44 additions & 164 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ 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
## Install

### Homebrew (macOS / Linux)

Expand Down Expand Up @@ -42,201 +42,81 @@ ln -s "$PWD/dist/corbits" ~/.local/bin/corbits

After pulling new changes, re-run `bun run build:bin` to refresh the binary.

## Usage

### TUI (default)
## First run

```sh
corbits "Add JWT auth to the API"
```

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`.
That opens the full-screen terminal UI: event log, permission and operator
prompts, diff and cost visibility, and a chat input for follow-ups. **Tab**
toggles focus between the prompt and the transcript, **Shift+Tab** cycles
reasoning effort, **Ctrl+C** interrupts a run, and `/help` lists the rest.

### Exec (non-TUI)
For scripts and CI, `corbits exec` runs the same directors, tools, permissions,
MCP, plugins, and hooks without the terminal UI, streaming assistant text to
stdout:

```sh
corbits exec "Add JWT auth to the API"
# alias:
corbits run "Add JWT auth to the API"
```

Same directors, tools, permissions, MCP, plugins, and hooks as the TUI — without
the OpenTUI shell. Streams assistant text to stdout for scripts and CI.

### Resume

```sh
corbits resume
# or:
corbits resume <session-id>
```

Plain `corbits` always starts a fresh conversation. `corbits resume` opens a
picker of the 10 most recently persisted sessions for this checkout,
including completed ones. Type to filter by name.

### Mid-run steering

While a run is in progress:

- **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`.

## 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).

### What auto allows

- File tools inside the workspace: `write_file`, `edit_file`, `delete_file` (and
other non-shell built-ins such as `manage_tasks`, `spawn_agent`, `wait_agents`, …)
- 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`, …)
- 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)
- Shell that references a path outside the workspace
- Writes under the in-workspace 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`, …)

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).

Details live in `docs/PRODUCT.md` (safety model) and `docs/ARCHITECTURE.md`
(permission gate and auto-shell policy).

## 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`)

## 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`
then idle (mailbox mail inbound) and `search_agents`. `wait_agents` stays
mounted only on headless `corbits exec` primary runs.

```
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 then idle → mailbox mail inbound → closed directors (builder, explorer, …)
→ event stream → OpenTUI host (TUI) or stdout (exec)
```
`corbits resume` reopens one of the 10 most recent sessions for this checkout;
plain `corbits` always starts fresh.

The chat director adds context management on top of the reactor:
Behavior, keybindings, and steering in depth: `docs/TUI.md` and
`docs/PRODUCT.md`.

- **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.
## Permissions

Deep design: `docs/ARCHITECTURE.md`, `docs/IMPLEMENTATION.md`, `docs/PRODUCT.md`.
Corbits Code defaults to **auto mode**, where workspace file edits and ordinary
shell commands run without a prompt so a long task is not interrupted every few
seconds. It still stops and asks before anything consequential — dependency
installs, recursive deletes, touching paths outside the workspace or anything
that looks like a credential — and it refuses outright to edit files through
shell redirects or `sed -i` when the file tools exist for that. Catastrophic
patterns are denied by authorization regardless of mode.

## Extensibility
Start with `--no-auto` to be asked before every consequential action.

- **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`)
The full policy — every rule, what is peeled from wrappers, and how the gate
composes with authorization — is in `docs/ARCHITECTURE.md`, with the safety
model behind it in `docs/PRODUCT.md`.

## Agent workspace
## Where to go next

Corbits Code keeps repository guidance and the closed director fleet separate:

- `AGENTS.md` — shared startup instructions and project context
- `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, tester, gauntlet, prober, migrator, and warden. 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
| 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 |

Named workers resolve through `spawn_agent(agent=...)`: closed directors first,
then enabled agent plugins, then local `.agents/agents/*.json|*.yaml` profiles.
Use `search_agents` to discover ids before dispatching.
`AGENTS.md` carries the repository's own instructions to agents working in it —
conventions, scope discipline, and how to validate a change.

## 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`.
Behavior changes come with tests. Coding conventions live in `AGENTS.md`;
commit, pull request, and Linear/GitHub linking rules live in
`CONTRIBUTING.md`, and a pull request that does not follow them will be
declined.

```bash
bun install
bun run check
```

## 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

Copyright (C) 2026 ABK Labs, Inc.
Expand Down
Loading