xonecas.io
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```