687
Oc
orc-code / files
orc-code / AGENTS.md
13.3 KB
1# Orc Code 2 3Orc is a terminal-native orchestrator for coding agent CLIs. Instead of implementing its own agent runtime, Orc treats tools like Claude and Codex as interchangeable execution backends, giving the user one stable UX, one session model, and transparent control over which agent is active. 4 5## Philosophy 6 7Orc is a tool for developers, transparency and detailed reporting of what is happening is crucial. 8Orc needs to be stable, deterministic and predictable to be a trusted developer tool. 9CLI and Terminal focused, including support for rendering with ansi codes and varied character widths content. 10Treat agent CLIs as user-owned execution backends, and build a stable terminal UX on top of them. 11 12## Problem 13 14Developers already use multiple coding agents — Claude Code, Codex, Opencode, Pi, mini-coder — because different agents are better at different tasks. But there's no unified way to switch between them, manage sessions across them, or maintain continuity when moving from one to another. 15 16Each agent CLI also comes with its own subscription and access model. Anthropic forbids third-party clients from using Claude subscriptions, and while some agents work around this by impersonating Claude Code, that's fragile. Other providers have mixed rules — OpenAI being the notable exception, publicly allowing third-party agents to use their subscriptions. Using each agent's own CLI sidesteps these restrictions entirely, since the user authenticates directly with each provider. 17 18## How does Orc solve it 19 20Discover at startup the available agent CLIs, Orc can orchestrate the user's requests through them. The user logs in to or configures each agent CLI outside of Orc. Orc is only responsible for orchestration, agent selection, and session proxying. 21 22Coding agents have good CLI interfaces and some can even force structured output. This is essential for Orc and basically the core of the idea. Orc provides a structured plugin api for users to add support for their coding agents. Orc will have a set of builtin plugins for some agent CLIs. 23 24## What Orc doesn't do 25 26Orc itself is not a coding agent, it delegates to the user-configured agent CLI for everything. 27 28## Architecture Model 29 30The basic mental model is that instead of implementing our own agent loops for each provider, we use the CLI interface of the active agent CLI as if it were a provider SDK: 31 32- User inputs a prompt into Orc 33- Orc prepares the command and CLI arguments for the active agent plugin 34- Orc creates a new session with the active agent CLI using the user's prompt. Orc tracks the Orc session ID, the agent session ID, and the active agent plugin. 35- Orc proxies the agent CLI session back to the user through a consistent interface. 36 37We will leverage the agent CLI interface for everything, like appending messages to an existing session through CLI flags such as `--resume <id>`. 38 39### Initial support, extensibility 40 41We can't aim to support all coding agents out of the box, so Orc should support them through agent plugins. We will start with plugins for claude and codex. 42 43Each agent plugin should provide a normalized API for the functionality Orc needs. A TypeScript module that exports functions fulfilling the contract is enough. Or a similar plugin format if that is sufficient. 44 45We have claude and codex installed and available to use while we develop. 46 47Orc runs agents in non-interactive mode with permission/approval bypass flags (`--dangerously-skip-permissions` for claude, `--full-auto` for codex). This is intentional — there is no human at the agent's TTY, Orc is the interface. 48 49## Agent Plugin Contract 50 51Every agent plugin is a TypeScript module that exports functions fulfilling this contract. Each operation has the same shape: build CLI args, spawn the process, stream parsed output, collect the agent session ID on exit. 52 53### Core interface 54 55- `name` — identifier used in `/agent` command and the DB (e.g. `"claude"`, `"codex"`) 56- `command` — the binary name to look for in `$PATH` (e.g. `"claude"`, `"codex"`) 57- `opts` --default flags to use on all invocations 58- `isAvailable()` — checks if the binary exists in `$PATH`, returns boolean 59- `createSession(prompt, opts?)` — spawns a new agent session, returns an `AgentProcess` 60- `resumeSession(sessionId, prompt, opts?)` — sends a follow-up prompt to an existing session, returns an `AgentProcess` 61 62### AgentProcess 63 64The return value of every session operation: 65 66- `child` — the raw `Bun.spawn` subprocess, for lifecycle management (kill, signal, etc.) 67- `events` — an `AsyncIterable<AgentEvent>`, the normalized event stream 68- `result` — a promise that resolves when the process exits, yielding `{ sessionId, exitCode }` 69 70### AgentEvent 71 72Both claude (`--output-format stream-json`) and codex (`--json` JSONL) support structured streaming output. Each agent plugin parses its agent CLI's raw JSON stream and emits normalized events: 73 74- `{ type: "text", content: string }` — assistant text output 75- `{ type: "tool_use", tool: string, args?: unknown }` — agent is invoking a tool 76- `{ type: "tool_result", output: string, error?: boolean }` — tool execution result 77- `{ type: "error", message: string }` — agent error 78- `{ type: "done", sessionId: string }` — agent finished, includes the session ID for Orc to persist 79- `{ type: "usage", tokens: {...} }` --To display token usage/cost 80 81### What each agent plugin actually does 82 83Each agent plugin is small — an arg builder and an output parser: 84 851. **Arg builder**: maps `(prompt, sessionId, opts)` to the agent's specific CLI flags. For example, claude resume is `claude -p "prompt" -r <id> --output-format stream-json --dangerously-skip-permissions`, codex resume is `codex exec resume <id> "prompt" --json --full-auto`. 862. **Output parser**: a transform that reads the agent CLI's raw JSON stream line by line and yields `AgentEvent` objects. This is the only non-trivial part per agent plugin, and it's a pure function — easy to test in isolation. 87 88Plugins own the responsability of updating the contract with the cli agents when these update/change. This is a unfortunate but necessary churn. 89 90### What Orc owns, not the plugins 91 92- **Session listing** — neither agent CLI has a non-interactive list command. Orc's SQLite table handles this. 93- **`/fork` composition** — Orc sends "Please summarize our current conversation" as a `resumeSession`, captures the text, then calls `createSession` on the target agent plugin with that summary. Agent plugins don't need to know about fork semantics. This is a lossy best effort, this is ok. 94 95## Repo Structure 96 97Bun workspace monorepo. The core CLI and each agent plugin are separate packages so plugins can be published and consumed independently. 98 99``` 100orc-code/ 101├── packages/ 102│ ├── orc-core/ # Core library: agent discovery, session DB, plugin registry 103│ │ ├── src/ 104│ │ └── package.json # name: "orc-code" 105│ ├── orc-cli/ # CLI interface: entrypoint, prompt, display 106│ │ ├── src/ 107│ │ └── package.json # name: "@orc-code/cli", bin: { "orc": ... } 108│ ├── plugin-claude/ # Claude Code agent plugin 109│ │ ├── src/ 110│ │ └── package.json # name: "@orc-code/plugin-claude" 111│ ├── plugin-codex/ # Codex agent plugin 112│ │ ├── src/ 113│ │ └── package.json # name: "@orc-code/plugin-codex" 114│ └── types/ # Shared types (AgentPlugin, AgentEvent, AgentProcess) and helpers 115│ ├── src/ 116│ └── package.json # name: "@orc-code/types" 117├── package.json # workspaces: ["packages/*"] 118└── biome.json 119``` 120 121`@orc-code/types` is the plugin contract as a standalone package — third-party plugin authors depend on it and nothing else. `orc-code` (core) is a headless library that owns agent discovery, session persistence, and plugin registration — it has no terminal I/O. `@orc-code/cli` is the terminal interface that imports the core and provides the interactive UX. This separation allows other UIs (TUI, web, editor extensions) to build on the same core. Bun workspaces handle linking and resolution across packages. 122 123## UX/UI 124 125Orc provides an append-only, shell compliant output and an input prompt to the user. Common shell keybinds should all work. And it should feel responsive and fast to the user. 126 127### First run 128 129These are bootstrapping actions, they only happen if it's the first run or there are no agents enabled. 130 131- Orc uses the $PATH env var to search for the commands defined by the available agent plugins (claude and codex initially) 132- User is presented to select which discovered agent CLIs are enabled. 133 134### New session 135 136Display a minimal prompt input to the user with a banner/statusline displaying the enabled agent plugins and the active agent plugin. Creates a title based on the first 50 characters of the first user input. 137 138### Session interaction 139 140An agent-focused conversation log, with high transparency to the user, including reporting errors and warnings. After each agent interaction, Orc checks for updates to the diff and displays the agent response and the diff in a clear readable output. 141 142For the diff, check if we are in a git repo, if so use git diff, otherwise skip the diff completly. 143 144### Prompt 145 146Minimal prompt with banner/statusline in the line above the cursor for user input. 147Filepath shell-like completion. Tab autocompletes if only one match, otherwise shows a select to the user. 148Has user input history with CTRL+R to show a select for recent inputs, and a way to clear the input. 149 150## Session management 151 152Most code editors have their own notion of sessions, and Orc needs to manage and proxy them to the user so continuity can be maintained by reusing agent sessions through the CLI. When listing sessions, Orc needs to clearly label which agent plugin owns each session. Most agent CLIs have CLI options to resume or continue sessions. 153 154## Commands 155 156Commands are exposed both as CLI flags `-o, --option <args>` and prompt slash-commands `/option <args>`. 157 158- `/agent <name>` chooses the active agent plugin. The name matches the plugin name, such as `/agent claude` or `/agent pi`. This implicitly creates a new session, copying the behaviour of `/fork`. 159- `/session` shows a selector of recent sessions and lets the user jump between sessions by selecting one. 160- `/fork` uses the current agent session to create a summary of the conversation and starts a new session with that summary as the first message in context. This is just a synthetic user message: "Please summarize our current conversation", sent before creating the new session. 161 162This is a thin layer on purpose. We don't need more. 163 164## Tech/dependencies 165 166Use Typescript and Bun.js 167 168For coloring output: 169 170- yoctocolors 171- yoctoselect (our library, published in npm) 172- yoctomarkdown (our library, published in npm) 173 174Runtime, package management, repo tooling 175 176- Bun.js - **IMPORTANT** - Always prefer bun natives over node apis when writing code. 177- biomejs for linting - Very strict linting rules. 178- Prettier for formatting everything and sorting imports/whitespace fixes. 179- knip and jscpd and typescheck for static analysis 180- Left hook for pre-commit hook 181 182Persistence: 183 184SQLite local db file. It should have a table for discovered agent CLIs and the user-configured agent plugins. This table should also track which plugins are enabled. Another important table should track the Orc session ID, the agent session ID, the agent plugin name, a simple title from truncated user input, and the parent Orc session ID, so Orc can proxy sessions, let the user switch between them, and create new ones. A table for user input history is also required. 185 186This db file will be in the users app data/config folder; for example `.config/orc-code` in linux. We will use this folder for all persistence needs in the future, like logs and configs. 187 188## Example Session 189 190``` 191 orc v0.1.0 — agents: claude (active) · codex 192───────────────────────────────────────────────── 193 194> Add a retry with exponential backoff to the API client in src/api.ts 195 196 claude ⟶ session abc-123 197 ● tool_use Read src/api.ts 198 ● tool_result (1.2kb) 199 ● text I'll add a retry wrapper with exponential backoff… 200 ● tool_use Edit src/api.ts 201 ● tool_result Applied edit 202 ● text Done. Added `withRetry()` that retries up to 3 times with 1s/2s/4s delays. 203 ✔ done session abc-123 204 205 src/api.ts +32 -4 206 207> /agent codex 208 209 Forking session abc-123 → summarizing… 210 codex ⟶ session def-456 (forked from abc-123) 211 212> Now add tests for the retry logic 213 214 codex ⟶ session def-456 215 ● tool_use Read src/api.ts 216 ● tool_result (1.5kb) 217 ● tool_use Create src/api.test.ts 218 ● tool_result Created file 219 ● text Added tests covering success, retry on transient failure, and max retries exceeded. 220 ✔ done session def-456 221 222 src/api.test.ts +48 (new) 223 224> /session 225 ┌─────────────────────────────────────────────────┐ 226 │ Sessions │ 227 │ ❯ def-456 codex Add tests for the retry… │ 228 │ abc-123 claude Add a retry with exponenti… │ 229 └─────────────────────────────────────────────────┘ 230```