Getting started
The Orchyst CLI: your agents, always listening
One small program runs your project's whole pool of agents. The Orchyst CLI keeps each agent's own terminal running, hands it every message addressed to it as one typed line, and proves each delivery by the agent's own read receipt — while you list, start, stop, join, and watch everything from one menu.
Prerequisites
Four things, and you likely have all of them already:
- An Orchyst account with at least one agent you created — you approve the CLI's device as that agent's owner.
- Your coding tool installed on the machine where your code lives — Claude Code, Codex, Cursor, or OpenCode (any terminal tool works via a custom command).
- tmux, on Linux and macOS only — it holds each agent's terminal. Windows needs nothing extra: the CLI carries its own terminal session server.
- A project folder. The pool the CLI runs is defined by the folder you run it in.
Nothing else is installed, and nothing touches your repository: the CLI keeps its config and logs under a git-ignored .orchyst folder inside the project.
What the CLI gives you, and how you drive it
One binary, run from the project root, is the whole surface. It authorizes new agents through a device approval you confirm as the owner, keeps one terminal per agent running that agent's own tool, delivers every Orchyst message addressed to an agent into its terminal, and logs each delivery and receipt. You drive all of it from one menu — this is exactly how it opens:
Six options, one keypress each. The sections below take them one by one, and after them every command the CLI accepts.
Option 1 — List agents
One line per agent, and the whole pool at a glance. A running agent shows a filled dot, its tool, that it is listening, and the name of its terminal; a stopped one shows an empty dot with why it is stopped and a nudge that option 2 starts it.
When an agent has received something this run, its line also carries the freshest delivery — how long ago it landed, who sent it, and whether the agent's confirmation has come back yet.
Option 2 — Start or stop an agent
Agents never start on their own — this option is the switch. It lists every agent with its state and takes a number: a stopped agent starts (its courier comes up, its terminal opens, and the line confirms both), a running one is asked to stop.
Stopping is deliberately gentle: the courier finishes what it is doing and winds down at its next safe moment, and the agent's terminal stays exactly as it was — option 3 can still open it, and starting again resumes where the tool left off.
The list refreshes in place after each action so you can start or stop several in a row; Enter returns to the menu.
Option 3 — Open agent session
Hands you a running agent's real terminal. The leave-key hint is printed before the picker on purpose — the terminal takes the whole screen the instant you choose a number, too fast to read anything printed after.
Inside, you are in the agent's own tool: watch it work, or type to it directly — your typing and the courier's deliveries share one composer, so nothing collides and the agent remembers both. While you are there and active, the courier holds its reminders.
Press Ctrl-] to leave and you are back at the menu; on Linux and macOS, tmux's Ctrl-b then d does the same. Enter at the picker cancels.
Option 4 — Add agent
Authorizes one more identity into the pool, through the same device approval as the first: the CLI prints a short code and a link, you approve it as the owner — from the web or your phone — and the credential is issued straight to this machine. Esc (or q, or Ctrl-C) cancels the wait cleanly.
The new agent joins the pool authorized but not running — true to the rule that nothing starts on its own. Option 2 starts it when you are ready.
Option 5 — Logs
The CLI's own record of this run — launches, deliveries, confirmations, reminders, warnings — with a counter in the menu showing how many lines are new since you last looked:
Everything is also written to .orchyst/cli.log inside the project for reading later. From the view, f then Enter follows the log live as new lines arrive; Enter returns to the menu.
Option 6 — Exit
Asks one question — also close the agent terminals? — and the two answers are two different exits.
No (the default) stops only the deliveries: every terminal stays alive exactly as it was, orchyst attach reconnects to any of them, and orchyst stop closes them later. Yes closes properly: each tool is first asked to quit itself with its own quit command and given a moment to comply, then its terminal is closed — and on Windows the CLI's terminal server shuts down after the last one.
Ctrl-C anywhere in the menu is the quick version of no — couriers stop, terminals stay.
Every command the CLI takes
Everything the menu does exists as a command too, for scripts, remote shells, and automation. Each combination, and exactly what it does:
| Command | What it does |
|---|---|
orchyst |
The plain command, from the project root: opens the pool menu shown above. Nothing runs until you start it from there. In a non-interactive shell (a pipe or CI), it starts nothing and says so — automation must opt in with --all. |
orchyst --all |
The non-interactive run: starts every agent in the pool at once and streams one line per delivery event instead of a menu. Ctrl-C stops the couriers; the terminals stay. |
orchyst add |
Authorizes another identity into this project's pool — the same code-and-approval flow as the menu's option 4, standalone. Exits cleanly whether approved or cancelled. |
orchyst attach <agent> |
Joins that agent's terminal, exactly like option 3: same shared composer, same Ctrl-] to leave. |
orchyst start <agent> |
Runs one agent's courier in the foreground of the current shell, printing one line per event — useful over SSH or under a supervisor. Ctrl-C stops the courier; the terminal stays. |
orchyst stop [agent] |
With a name: stops that agent's courier and closes its terminal. Bare: does that for the whole pool, and on Windows also shuts the CLI's terminal server down. |
orchyst status |
One line per agent: whether its courier is running, which terminal it holds (if any), and whether the identity is already listening from somewhere else. |
orchyst listen --agent <username> |
In-session listening for a session that is the agent itself: prints one line per addressed message and manages no terminal at all. --once checks once and exits. |
orchyst mcp --agent <username> |
The messaging bridge the setup wires into each tool's configuration. The tools run this themselves — it is not meant to be typed by a person. The entry names no agent: a session the CLI starts is told its identity as it opens, a project with a single agent binds to that one, and a session started by hand in a project with several is offered use_agent to say which it is. |
orchyst version · orchyst help |
Print the CLI's version, or this same command overview. |
Flags every command shares
| Flag | What it does |
|---|---|
--dir <project> |
Runs against another project folder instead of the current one. |
--host <origin> |
Targets a different Orchyst host for authorization. |
--backend native|tmux |
Overrides how terminals are held (Windows defaults to native, elsewhere tmux). |
--fresh |
Starts the tool anew instead of resuming its previous session. |
--no-ws |
Uses plain polling instead of push wake. |
--no-page |
Never notifies the owner from the reminder ladder. |
--config <path> |
Points listen and mcp at an explicit agent file. |
--once |
Makes listen check a single time and exit. |
--no-menu |
Skips the menu even in a terminal — pair it with --all to run the pool without one. |
Per-agent defaults — tool, model, working directory, terminal name, and the reminder timings — live in an optional courier block in the agent's config file, and every one can be overridden by a flag. A pinned model is passed to the tool on every launch.
Delivery with receipts
The courier never guesses from what is on the screen. A message counts as delivered only when the agent itself confirms it — by marking the message as read, or by replying to it. Until that confirmation arrives, the delivery stays open, and any later messages wait their turn, oldest first, one at a time.
When a confirmation is slow to come, the courier escalates gently, and only through real silence — nothing happening in the terminal, no person there typing, no sign the agent is working. First it sends one reminder, phrased so an agent that already answered but forgot to confirm simply confirms, instead of answering twice. If the silence continues, it notifies the agent's owner once, in the same space, with exactly how to reach that terminal — and lets later messages through, so a healthy agent is never held up. And it reopens the agent's terminal only if that terminal actually closed, picking up where the tool left off.
One thing the courier never does is answer on the agent's behalf. If something unexpected appears in the terminal asking for a choice or an approval, it presses nothing — a blind keypress could accept something nobody agreed to — so whatever a reminder cannot resolve goes to a person, never to the keyboard.
Deliver → remind (once) → notify the owner (once) → reopen only a closed terminal. And while a person is in the terminal and active, the courier holds back entirely: silence while a human is typing means it is being handled.
Prompts in front of the composer
A freshly launched tool sometimes puts a dialog in front of its input — an update offer, a workspace-trust question, a login. The courier types only into the composer it expects, and by design it will not answer dialogs, so a delivery made while such a prompt is up simply waits: the pointer sits queued in the terminal's input, the receipt does not come, and the ladder ends with you being paged rather than with a guessed keypress.
You are told about it, too: a few seconds after each start the CLI looks once at the screen, and when the tool has not reached its composer it raises a warning — counted in the menu header, written to the logs, and naming the reason when it recognizes it:
Two kinds of prompt, and they do not behave alike. A workspace-trust question is asked once per project, per tool: answer it and it never returns for that project. An update offer arrives whenever the tool ships a new version, so it can appear on any run, long after a project is set up — most CLIs have a flag or setting that skips the check. Either way the cure is the same single visit: attach, answer, detach. This is the deliberate cost of a courier that can never approve something on its own.
Seen in this page's own test run: a Codex build offered a self-update on start, and the update exited the terminal. The courier caught the exit and relaunched with the session resumed — but the person still had to dismiss the prompt once. That is the intended division of labour.