xonecas.io
687
Oc

orc-code / commit f4ea76f

docs: improve AGENTS.md with repo structure, example session, and clearer problem statement

xonecas2026-03-26 f4ea76f9b629c20a47e1f59cc1d70e770de1e380 parent 31b526d

1 file changed

AGENTS.md+169−20
@@ -1,26 +1,121 @@
11 # Orc Code
22
3-An coding cli orchestrator, provides an thin orchestration layer to drive multiple cli agents defined by the user.
3+Orc 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.
44
55 ## Philosophy
66
77 Orc is a tool for developers, transparency and detailed reporting of what is happening is crucial.
88 Orc needs to be stable, deterministic and predictable to be a trusted developer tool.
9-CLI and Terminal focused, including support for rendering with ansi codes and varied charatcter widths content.
9+CLI and Terminal focused, including support for rendering with ansi codes and varied character widths content.
10+Treat agent CLIs as user-owned execution backends, and build a stable terminal UX on top of them.
1011
1112 ## Problem
1213
13-Claude Code, Codex, Opencode, Pi Coding agent, my own mini-coder, all are incredible tools with varied use cases, mostly cross provider compatability and efficient use of existing subscription models. Anthropic forbids 3rd party clients from using subscriptions, and while some coding agents still support it by impersonating Claude Code, this is fragile. Other providers also have mixed usage rules, with the exception of openai, which has publicly stated they allow 3rd party coding agents to use t …
14+Developers 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+
16+Each 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.
1417
1518 ## How does Orc solve it
1619
17-By letting the user configure (or discover at start) the available cli agents available and their commands optionally, we can use them by orchestarting the users requests using said commands. The user has to login or configure each agent they want to use on those agents, outside of orc. Orc is only responsible for the orchestration layer, agent selection and session management.
20+Discover 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.
1821
19-Most coding agents have what is best described as "one-shot" or headless mode, where the prompt and config are provided via arguments. This will allow orc to expose and use those controls to the user.
22+Coding 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.
2023
2124 ## What Orc doesn't do
2225
23-Orc itself is not a coding agent, it delegates to the user configured agent for everything.
26+Orc itself is not a coding agent, it delegates to the user-configured agent CLI for everything.
27+
28+## Architecture Model
29+
30+The 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+
37+We 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+
41+We 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+
43+Each 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+
45+We have claude and codex installed and available to use while we develop.
46+
47+Orc 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+
51+Every 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+
64+The 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+
72+Both 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+
83+Each agent plugin is small — an arg builder and an output parser:
84+
85+1. **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`.
86+2. **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+
88+Plugins 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+
97+Bun workspace monorepo. The core CLI and each agent plugin are separate packages so plugins can be published and consumed independently.
98+
99+```
100+orc-code/
101+├── packages/
102+│ ├── orc-core/ # CLI entrypoint, session management, UI, SQLite
103+│ │ ├── src/
104+│ │ └── package.json # name: "orc-code", bin: { "orc": ... }
105+│ ├── plugin-claude/ # Claude Code agent plugin
106+│ │ ├── src/
107+│ │ └── package.json # name: "@orc-code/plugin-claude"
108+│ ├── plugin-codex/ # Codex agent plugin
109+│ │ ├── src/
110+│ │ └── package.json # name: "@orc-code/plugin-codex"
111+│ └── types/ # Shared types (AgentPlugin, AgentEvent, AgentProcess)
112+│ ├── src/
113+│ └── package.json # name: "@orc-code/types"
114+├── package.json # workspaces: ["packages/*"]
115+└── biome.json
116+```
117+
118+`@orc-code/types` is the plugin contract as a standalone package — third-party plugin authors depend on it and nothing else. The core `orc` package depends on the builtin plugins and wires everything together. Bun workspaces handle linking and resolution across packages.
24119
25120 ## UX/UI
26121
@@ -28,36 +123,40 @@ Orc provides an append-only, shell compliant output and an input prompt to the u
28123
29124 ### First run
30125
31-These are bootstrapping actions, they only happen if its the first run or there are no agents enabled.
126+These are bootstrapping actions, they only happen if it's the first run or there are no agents enabled.
32127
33-- User is presented to select which discovered agents are enabled.
34-- User can add the shell command to use a custom agent that was not discovered.
128+- Orc uses the $PATH env var to search for the commands defined by the available agent plugins (claude and codex initially)
129+- User is presented to select which discovered agent CLIs are enabled.
35130
36131 ### New session
37132
38-Display a minimal prompt input to the user with a banner/statusline displaying the enabled agents and the currently selected one. Creates a title based on the first 50 characters of the first user input.
133+Display 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.
39134
40135 ### Session interaction
41136
42-A coding 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.
137+An 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.
138+
139+For the diff, check if we are in a git repo, if so use git diff, otherwise skip the diff completly.
43140
44141 ### Prompt
45142
46-Minimal prompt with banner/statusline in the live above of the cursor for user input.
143+Minimal prompt with banner/statusline in the line above the cursor for user input.
47144 Filepath shell-like completion. Tab autocompletes if only one match, otherwise shows a select to the user.
48145 Has user input history with CTRL+R to show a select for recent inputs, and a way to clear the input.
49146
50147 ## Session management
51148
52-Most code editors have their own notion of sessions, we will need to manage this and proxy them to the user, so we can maintain continuity in conversations by re-using sessions via cli. When listing sessions we need to clearly label which agent is the owner of that session.
149+Most 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.
53150
54151 ## Commands
55152
56-Commands are exposed both as cli flags `-o, --option <args>` and prompt slash-commands `/option <args>`.
153+Commands are exposed both as CLI flags `-o, --option <args>` and prompt slash-commands `/option <args>`.
154+
155+- `/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`.
156+- `/session` shows a selector of recent sessions and lets the user jump between sessions by selecting one.
157+- `/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.
57158
58-- `/agent <name>` chooses the active agent, name is the command for the agent `/agent claude` or `/agent pi`. This implicitly creates a new session, copying the behaviour of `/fork`
59-- `/session` shows a selector of recent sessions, let's the user jump between sessions by selecting one.
60-- `/fork` uses the agent to create a summary of the conversation and starts a new one with the summary in the context as the first message
159+This is a thin layer on purpose. We don't need more.
61160
62161 ## Tech/dependencies
63162
@@ -66,13 +165,63 @@ Use Typescript and Bun.js
66165 For coloring output:
67166
68167 - yoctocolors
69-- yoctoselect (our library)
70-- yoctomarkdown (our library)
168+- yoctoselect (our library, published in npm)
169+- yoctomarkdown (our library, published in npm)
71170
72171 Runtime, package management, repo tooling
73172
74-- Bun.js - **IMPORTANT** - Always prefer bun natives over node apis when writting code.
173+- Bun.js - **IMPORTANT** - Always prefer bun natives over node apis when writing code.
75174 - biomejs for linting - Very strict linting rules.
76175 - Prettier for formatting everything and sorting imports/whitespace fixes.
77176 - knip and jscpd and typescheck for static analysis
78177 - Left hook for pre-commit hook
178+
179+Persistence:
180+
181+SQLite 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.
182+
183+This 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.
184+
185+## Example Session
186+
187+```
188+ orc v0.1.0 — agents: claude (active) · codex
189+─────────────────────────────────────────────────
190+
191+> Add a retry with exponential backoff to the API client in src/api.ts
192+
193+ claude ⟶ session abc-123
194+ ● tool_use Read src/api.ts
195+ ● tool_result (1.2kb)
196+ ● text I'll add a retry wrapper with exponential backoff…
197+ ● tool_use Edit src/api.ts
198+ ● tool_result Applied edit
199+ ● text Done. Added `withRetry()` that retries up to 3 times with 1s/2s/4s delays.
200+ ✔ done session abc-123
201+
202+ src/api.ts +32 -4
203+
204+> /agent codex
205+
206+ Forking session abc-123 → summarizing…
207+ codex ⟶ session def-456 (forked from abc-123)
208+
209+> Now add tests for the retry logic
210+
211+ codex ⟶ session def-456
212+ ● tool_use Read src/api.ts
213+ ● tool_result (1.5kb)
214+ ● tool_use Create src/api.test.ts
215+ ● tool_result Created file
216+ ● text Added tests covering success, retry on transient failure, and max retries exceeded.
217+ ✔ done session def-456
218+
219+ src/api.test.ts +48 (new)
220+
221+> /session
222+ ┌─────────────────────────────────────────────────┐
223+ │ Sessions │
224+ │ ❯ def-456 codex Add tests for the retry… │
225+ │ abc-123 claude Add a retry with exponenti… │
226+ └─────────────────────────────────────────────────┘
227+```