xonecas.io
687
Oc

orc-code / commit 31b526d

feat: initial agents file and basic idea

xonecas2026-03-26 31b526d4c532b76c6b86e98ba53d110ff03888cd

1 file changed

AGENTS.md+78−0
@@ -0,0 +1,78 @@
1+# Orc Code
2+
3+An coding cli orchestrator, provides an thin orchestration layer to drive multiple cli agents defined by the user.
4+
5+## Philosophy
6+
7+Orc is a tool for developers, transparency and detailed reporting of what is happening is crucial.
8+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.
10+
11+## Problem
12+
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+
15+## How does Orc solve it
16+
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.
18+
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.
20+
21+## What Orc doesn't do
22+
23+Orc itself is not a coding agent, it delegates to the user configured agent for everything.
24+
25+## UX/UI
26+
27+Orc 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.
28+
29+### First run
30+
31+These are bootstrapping actions, they only happen if its the first run or there are no agents enabled.
32+
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.
35+
36+### New session
37+
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.
39+
40+### Session interaction
41+
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.
43+
44+### Prompt
45+
46+Minimal prompt with banner/statusline in the live above of the cursor for user input.
47+Filepath shell-like completion. Tab autocompletes if only one match, otherwise shows a select to the user.
48+Has user input history with CTRL+R to show a select for recent inputs, and a way to clear the input.
49+
50+## Session management
51+
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.
53+
54+## Commands
55+
56+Commands are exposed both as cli flags `-o, --option <args>` and prompt slash-commands `/option <args>`.
57+
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
61+
62+## Tech/dependencies
63+
64+Use Typescript and Bun.js
65+
66+For coloring output:
67+
68+- yoctocolors
69+- yoctoselect (our library)
70+- yoctomarkdown (our library)
71+
72+Runtime, package management, repo tooling
73+
74+- Bun.js - **IMPORTANT** - Always prefer bun natives over node apis when writting code.
75+- biomejs for linting - Very strict linting rules.
76+- Prettier for formatting everything and sorting imports/whitespace fixes.
77+- knip and jscpd and typescheck for static analysis
78+- Left hook for pre-commit hook