Claude Code, step by step

This guide gives Claude Code (command claude) the full orboto workflow: tickets, docs, timers, comments, and the wake channel - a message another agent or a colleague sends to your session arrives in the idle session within seconds and starts a turn, with no polling loop and no monitor that expires. Added in v0.199.0 Follow it top to bottom; every step tells you what you should see before you move on.

Never set orboto up before? Connect your agent walks the same path in plain words with what you see after every step. This page is the detail behind it.

The wake channel's own mechanics, the plan gate that allows it, and troubleshooting the channel specifically are on Claude Code: the wake channel. An API key for an unattended agent account, and driving orboto through the CLI with no MCP server at all, are on Claude Code: alternatives.

What a session costs

Added in v0.205.1 The CLI is how agents work; the MCP server carries only the wake channel unless you ask for tools with --toolset. A tool list is sent with every message the agent writes, whether it uses a tool or not: the full list is about 47,500 tokens, the everyday list about 11,000, and the channel-only connection about 400. Fewer tokens per message means a longer session before the context fills up and a smaller bill for the same work. Every tool has a command (orboto help), and a client without a terminal gets the tools back with orboto mcp install --toolset curated. Claude Code itself loads tool descriptions lazily, so there the difference per message is about 4,000 tokens between the full list and the channel-only connection; clients that load every tool up front pay the full amount.

1. Open a terminal and install both tools

• Mac: press Cmd + Space, type Terminal, press Enter.
• Windows: press the Windows key, type PowerShell, press Enter.

A window with a blinking cursor opens. Everything below that looks like code is typed into this window, followed by Enter.

First install Claude Code:

• Mac:

  curl -fsSL https://claude.ai/install.sh | bash

• Windows:

  irm https://claude.ai/install.ps1 | iex

Then install the orboto CLI:

• Mac:

  curl -fsSL https://raw.githubusercontent.com/orboto/orboto-cli/main/install.sh | sh

• Windows:

  npm install -g orboto

Wait until the cursor comes back, then close the terminal window and open a new one so both commands are found. Check:

orboto version

You should see a version number. If you see "command not found" or "not recognized", open a new terminal window and try again. orboto self-update keeps the CLI current afterwards.

2. Sign in to Claude Code

In the terminal type claude and press Enter. The first start asks you to log in; follow the prompt, your browser opens, log in with your Claude account and confirm. Back in the terminal Claude Code shows its prompt. Type /exit and press Enter to close it again.

3. Sign the orboto CLI in

orboto login

It asks for your workspace address, opens your browser, and you approve the login there. No key to copy, and the login renews itself. On a machine without a browser add --no-browser and open the printed address elsewhere.

What you see: orboto whoami prints your name and email address. The login is stored in your home directory, never in a project. A second account lives next to it as a named profile (orboto login --profile work), and every command takes --profile work to act as that one - see CLI profiles.

4. Connect the folder you work in

Change into the folder you open Claude Code in, and run:

orboto connect

Added in v0.200.0 This is the whole setup of one directory in a single command, one step at a time, and it says what it found after each one: Node, Claude Code, your login, the orboto server entry it writes, the optional context-size status line, and the exact start command including the standing arguments. Only what needs a person is left to you.

orboto connect --yes          # answer every question with its default (the form an agent runs)
orboto connect --replace      # overwrite an "orboto" entry that is already there
orboto connect --verify       # after the restart: probe the session, report the channel

--statusline / --no-statusline, --scope, --toolset and --profile decide the rest without a prompt, so nothing waits for input under --yes.

What you see: a file .mcp.json in the folder with one entry named orboto. The entry is the command orboto mcp serve --profile <name> - no API key in the file, so .mcp.json can be committed to git and your colleagues get the same setup.

The single step on its own, without the questions around it:

orboto mcp install                  # write the "orboto" entry into ./.mcp.json
orboto mcp install --statusline     # the same, plus context-size reporting (see below)
orboto mcp install --scope user     # write it for every repository of your user
orboto mcp install --toolset full --replace
orboto mcp status                   # what is configured here, which proxy versions are cached
orboto mcp uninstall                # remove the entry again

An existing orboto entry is only replaced with --replace, and the command prints what it replaced; every other server, unknown key and the key order of the file survive untouched.

The connector itself (@orboto/mcp) is installed on first start under ~/.orboto/mcp/ and always matches the version of your instance: when the workspace is upgraded, the next start brings the matching connector. The three newest versions are kept. Nothing points into a checkout of any source repository.

5. Start Claude Code

The last thing orboto connect printed is your start command:

orboto claude                       # new session
orboto claude --continue            # continue the most recent conversation here
orboto claude --resume <session id> # a specific conversation
orboto claude --yolo                # Claude Code's full-permission mode, --dangerously-skip-permissions

Added in v0.213.0 --yolo and --skip are two spellings of one request, and --skip-permissions stays as the third. The flags are read anywhere before a bare --. If you typed --dangerously-skip-permissions yourself after --, it is not added a second time. The same three flags exist on orboto codex, orboto gemini, orboto kimi and orboto ollama; see Launchers and the uniform flags. To run a private and a company account, see Login profiles.

Added in v0.200.0 Everything you pass after -- reaches claude unchanged, so orboto claude -- --help shows Claude Code's own help.

Two confirmations, and both are yours to give:

• Claude Code asks once per folder whether to use the servers from .mcp.json. Until you agree, claude mcp list shows the entry as pending approval and orboto stays dark.
• Claude Code asks on every such start to confirm the local-development use of the channel. Confirm it; decline it and the session starts normally, with the tools, but nothing will wake it.

In the session, /mcp lists orboto as connected.

The session declares its project

Added in v0.207.0 Start Claude Code with orboto claude inside a repository and the session declares that repository's orboto project as its scope before Claude Code starts - and again on every resume:

orboto claude: session 3f9a1c2e declares scope ACME · worker - from origin acme/widgets

orboto takes the project key from the first of these that names one:

1. ORBOTO_PROJECT_KEY in the environment,
2. the env block of the checkout's .claude/settings.local.json ({"env": {"ORBOTO_PROJECT_KEY": "ACME"}}),
3. the repository's origin remote, matched against the git connections of the projects you are a member of (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea and Forgejo, also on a self-hosted address).

When no project of yours connects the repository, Added in v0.211.0 orboto claude asks for one in a terminal and stores the answer. Added in v0.213.0 The question is the project picker: a list of 20 per page that you filter by typing, ?2 for a project's details, new to create the project (orboto connect --project new:KEY[:name] in scripts), and a repository linked to several projects opens on exactly those; without a terminal it prints the orboto connect checklist and exits 2, unless you pass --no-scope or --role. If your instance does not answer the lookup, the start warns and goes on with the scope undeclared. orboto connect --project KEY sets the project once and for all. Added in v0.213.0 A session that coordinates across projects needs no project: orboto claude --role coordinator starts a control session in any folder, and the picker offers it as 0 or none and remembers the choice for the folder in ORBOTO_SESSION_ROLE. A control session does not take the checkout's project unless --scope-projects names one. See control sessions. A session that already declares a scope keeps it. --role, --scope-projects and --scope-tickets on orboto claude override the detection; --no-scope declares nothing.

orboto connect writes the same key into the orboto server entry of the directory, so a session started without orboto claude declares it too. orboto connect --verify then sends a second probe to the project and tells you whether the session receives the project's mail. The status line shows the session with its scope (3f9a1c2e ACME · worker), and orboto doctor prints a scope line with the fix when the two differ.

Added in v0.230.0 A second orboto claude in the same checkout starts beside the first one when its scope shares no project and no ticket with it, for example orboto claude --scope-projects BETA next to a session on ACME. Each session has its own row, its own mail, its own ticket leases and its own status line, which shows the ticket that session works on. With an overlapping scope the second start is refused, see One session per account, checkout and scope. A session started with orboto claude is woken by its channel; run no Monitor beside it.

Standing arguments

Added in v0.200.0 Flags you always start with ride along without being typed, so the command an agent hands you stays short and correct:

orboto claude --set-default-args -- --dangerously-skip-permissions
orboto claude --show-default-args
orboto claude --clear-default-args
orboto claude --no-default-args     # start once without them

They live in ~/.orboto/claude.json; the environment variable ORBOTO_CLAUDE_ARGS overrides them for one shell. Every start names the standing arguments on stderr and orboto mcp status lists them, so a permission-free start is never silent.

6. Declare what the session is for

Since 0.207.0 a session started from a connected repository declares that project by itself (see "The session declares its project" above). This step is for a session that needs a different or wider scope.

In the session, the first call is orboto_session_start. Pass a scope once:

orboto_session_start { scope: { role: "lead", projectKeys: ["ACME"] } }

A session with a scope is woken by mail addressed to it, by mail inside its projects and tickets, and by broadcasts. A session without a scope is woken by mail addressed to it and by broadcasts only, and is reminded once per connection to declare one Added in v0.200.0 - so several sessions on one account do not wake each other. The full model is on Sessions, scope and the wake ledger.

7. Prove the channel works

From a second terminal in the same directory:

orboto connect --verify             # probe plus the ledger's verdict; exit code 1 with the cause
orboto connect --verify --json      # the same as a record an agent can read
orboto connect --verify --session <short id> --timeout 90s

Added in v0.200.0 It addresses a session of your account that announced the channel, sends one probe message and waits for orboto's own wake record. A verdict of channel is the pass; another transport means the session was started without orboto claude or the local-development prompt was declined; no record at all means the message did not match the scope that session declared.

What you see in the session: a channel event appears on its own, within seconds, without you typing anything.

A probe by hand, from any other account:

orboto agent-notify you@example.com "probe" --project ACME --kind request

Daily use

Requests, errors and questions arrive at once; info and complete mail arrives as one digest per fifteen minutes. What you do with a message:

• Handled it: orboto_messages { ackIds: [...] }, or orboto messages --ack <id>,<id>.
• Not yours, outdated or a duplicate: dismiss it with a reason Added in v0.200.0 - orboto messages --dismiss <id> --reason not-mine hides it for your session only and tells the sender once that it was misrouted; obsolete and duplicate close it for the whole account and need a --note or a --duplicate-of.
• Reply to exactly one session: orboto agent-notify <email> "..." --session <short id>, or orboto_agent_notify { toSessionRef }.
• See what woke you, and whether that was right: orboto agent-wakes, and --stats for the precision per session.

All of it, including the paths for harnesses without a channel, is on Agent inbox and wake-up delivery.

Restart a session without finding its terminal

Added in v0.202.0 orboto claude stays the parent of the Claude Code process it starts and supervises it: the session keeps your terminal, your signals and its own exit code, and that parent is what a restart request reaches later. A restart resumes the same conversation (claude --resume <session id>) with the same arguments and your standing defaults.

Set it up once per folder: orboto mcp install --session-reporting (then restart that one session by hand). It installs the status line and Claude Code lifecycle hooks into .claude/settings.local.json; the hooks tell the supervisor exactly when a turn runs and when the session is idle.

Ask for a restart in any of these ways:

1. orboto claude --restart --reason "..." from any terminal on the machine (--session <short id> or --all when several run; orboto claude --sessions lists them).
2. orboto agent-session restart <short id> --reason "..." from anywhere, or the Restart session button in Admin -> Agents -> Live. Both need admin:agents:write, are written to the audit log with the reason, and show as restart pending until the session is back.
3. The agent itself runs the first command in its shell - for example after orboto self-update.

What the supervisor guarantees:

• It never interrupts a running turn. A ten-minute test run inside one tool call is still a running turn; the request waits for it, up to --when-idle-timeout (10 minutes by default).
• Without the hooks it cannot tell a running turn from an idle session, so it declines and names the command above instead of guessing.
• A session that ends while a request is waiting stays ended.
• Claude Code's development-channel confirmation is its own safety prompt and orboto never answers it: after a restart the terminal bell rings once and you confirm it there. Start without the confirmation removes the prompt where your plan allows it.

orboto claude --no-supervise starts a session the old way; nothing can then restart it but you.

Context size reporting

Added in v0.200.0 With orboto mcp install --statusline the Claude Code status line runs orboto claude-statusline. It reads the status line data on stdin, records the session's context size under ~/.orboto/claude-context/ and prints a short line; the connector reports the value with its heartbeat, so the wake ledger can say what a wrong wake cost. A status line command you already had is carried into --wrap "<your command>" and keeps printing exactly what it printed before - nothing is replaced. Two Claude Code sessions in the same directory cannot be told apart; the ledger then reads unknown rather than guessing.

Tips: where the tokens go in long sessions

Measured on our own agent fleet over two weeks (Claude Code 2.1.289, main sessions plus the subagents they spawn). The orboto side of a session - the wake channel, the hooks and the command output - was at most a tenth of the bill. The rest is how the session itself is run, and most of it is cheap to fix.

• Give subagents the one-hour prompt cache. Claude Code caches the prompt prefix of a main session for an hour, but a subagent's cache lives only five minutes. A subagent that waits for a test run, a build or CI is often idle for longer than that, and the next call then rewrites its whole context at the full price: in our fleet this was almost one fifth of all spend, and nine out of ten subagent calls after a pause of five to sixty minutes paid for it. Set "subagentPromptCacheTtl": "1h" in ~/.claude/settings.json (the setting is present in Claude Code 2.1.289; the environment variable CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL takes precedence). The longer cache costs about twice as much to write, which the saved rewrites pay back several times over. Claude Code ignores the one-hour value while a subscription is in overage, so check the effect rather than assume it.
• After a pause of more than an hour, start a new session instead of resuming the old one. Both caches have expired by then; the first message of a resumed session rewrites the entire context, and every later message carries it. A fresh session with orboto claude finds its ticket and its open work through orboto session-start anyway.
• Hand over before the context passes about 250,000 tokens. Every message pays for the whole context again, so a session at 300,000 tokens costs about three times a session at 100,000 for the same question. The status line command (above) shows the size; a long-running coordinator stays small when the builds and reviews run in subagents and only their reports come back.
• Use the smaller model for subagents that build and fix. In our measurements the large model's subagents cost about three times as much per run, and on precisely specified tickets the first diffs of both models needed a review round equally often; the review is where quality comes from, so spend the large model there.
• Let the wake channel show, not wake. With the orboto mod set to actionable, digests and informational mail appear in the pane and as a toast without a model turn (Claude Code mod).
• Wait in the background, not in a loop. A foreground sleep or polling loop inside a subagent keeps its clock running past the cache lifetime; a background watch that reports once when the state changes does not.

Switch subscriptions at the usage limit

Added in v0.230.0 With two or more login profiles, every orboto claude session moves to another subscription before and at the usage limit and continues the same conversation there. You control it from the command line, also while sessions run:

orboto claude accounts setup third                  # add an account - running sessions take it into their rotation
orboto claude accounts disable second               # hold one out - it leaves every rotation at once
orboto claude accounts config --auto-switch off     # new starts do not switch (on brings the default back)
orboto claude switching status                      # what every running session does at the limit
orboto claude switching off --all                   # running sessions stop switching, no restart
orboto claude switching on --session 1a2b3c4d       # switch over every profile again
orboto claude switching switch:work,third --session 1a2b3c4d   # a fixed order that new profiles do not join

Each session you address answers applied, refused, superseded, pending or older-cli, and the command exits 0 only when every one applied it (1 otherwise, 2 for a usage error). orboto claude --sessions and the status line show the policy next to the profile (profile work on-limit switch all at 90%), and Admin -> Agents -> Live shows and changes it under At the usage limit. A session started with a single profile already carries the switch and starts acting when you add the second one. The thresholds, the strategies, what a change withdraws and the remote input are on Switching on and off.

An agent prepares the folder, you only restart

Everything except the start flag is work a session's own agent can do; the flag belongs to the process it runs in, so that one step is yours:

1. The agent runs orboto connect --yes --replace --profile <name> in the folder and stops any older wake path it was using.
2. It reports "ready for restart" with the exact command, verbatim: orboto claude --continue, or orboto claude --resume followed by a session id.
3. You quit the session, run that command in that directory, and confirm the local-development prompt.
4. The restarted agent declares its scope and runs orboto connect --verify.

Troubleshooting

The wake channel's own troubleshooting (no event on a probe, the channel not registering, double delivery, wrong-project wakes) is on Claude Code: the wake channel.

What next

• Claude Code: the wake channel - how the channel works, the plan gate, and troubleshooting it.
• The orboto mod for Claude Code - a claim guard on edits and commits, the scope in the system prompt, toasts, a status entry and the /orboto pane.
• Claude Code: alternatives - an API key for an unattended agent, and the CLI path without MCP.
• Sessions, scope and the wake ledger - several sessions on one account, addressing one of them, and measuring the wakes.
• Agent inbox and wake-up delivery - the inbox itself, and the wake paths for harnesses without channels.
• The complete command set is on CLI daily workflow; connection profiles for several workspaces on CLI profiles.
• Every other AI client is on the MCP server page.