Orbit — the user guide
This is the practical guide: what Orbit is, how to run it, and how to do each everyday job. The other docs go deeper on each topic; start here.
Contents
- What Orbit is
- Install and run
- Your first session
- Reading the screen
- The everyday loop
- Worktrees: parallel work without collisions
- Reviewing what an agent did
- GitHub: pull requests and issues
- Presets: tasks you repeat
- Agents that drive Orbit
- Running and opening your project
- Settings worth changing
- Key reference
- Command-line reference
- Troubleshooting
- What's coming
1. What Orbit is
Orbit runs your Claude Code sessions — several at once, across projects and branches — and shows them all on one screen, with a coloured dot telling you which one needs you.
It is two programs in one binary:
- The daemon runs in the background and owns every session. Closing the screen, or your laptop lid, does not stop an agent.
- The TUI is the screen you look at. Quit it with
qand reopen it withorbitwhenever you like; every session is where you left it, its output replayed.
Everything is nested three levels deep:
Project a git repository → a tab across the top
└ Worktree a checkout of it (main, or a branch) → a band (a row) on the grid
└ Session one Claude Code conversation → a card in that band
A project can have several worktrees, so two agents can work on two branches of the same repo at the same time without editing the same files.
2. Install and run
Orbit runs on macOS and Linux (Windows through WSL2). Pick one way to install:
Homebrew
brew tap amenadem/orbit https://github.com/AmenAdem/Orbit
brew install amenadem/orbit/orbit
Type the full name amenadem/orbit/orbit: a plain brew install orbit installs an unrelated Mac app.
Install script (no Homebrew needed)
curl -fsSL https://raw.githubusercontent.com/AmenAdem/Orbit/main/install.sh | sh
It puts the prebuilt binary in ~/.local/bin (ORBIT_INSTALL_DIR changes that) and prints the line
to add to your shell if that folder isn't on your PATH.
Then run orbit; the daemon starts by itself. orbit --version says which release you have.
Updating. When a new release is out, the footer shows ⇡ vX.Y.Z beside the version. Run
orbit upgrade. It uses brew upgrade on a Homebrew install and the install script otherwise,
then moves the running daemon onto the new binary without stopping any session. After a plain
brew upgrade, run orbit reload to do that last step yourself.
What you need: git and the claude CLI, plus uv and npm. Orbit installs the tools it
integrates through those two — once per machine, the first time each is needed
(uv tool install graphifyy, npm install -g agent-browser) — and uses the installed copy from then
on. Run orbit doctor to see what your machine has and what each missing piece would unlock;
orbit doctor --fix does those one-time installs right away. On a machine without Python, uv
downloads one the first time, which can take a few minutes; it never happens again.
(gh is the one optional extra worth installing yourself, for pull requests and issues.)
Building from source
Only needed if you work on Orbit itself. You also need Rust (rustup, on your PATH).
Try your latest code without touching anything else — an isolated copy with its own daemon and data:
make dev # build and open it
make dev AGENT=/bin/cat # same, but a stand-in instead of Claude: try the UI for free
make dev-reset # wipe the dev copy's data and start fresh
Quitting make dev also stops its daemon and its sessions.
Install your own build for everyday use:
make install PREFIX=$HOME/.local/bin # build a release and put `orbit` in ~/.local/bin
orbit reload # move a running daemon onto it, sessions kept
(make install alone targets ~/.cargo/bin, which a Homebrew rustup doesn't create.) Don't mix this
with a Homebrew install: whichever orbit comes first on your PATH wins.
3. Your first session
- Open a terminal inside the repository you want to work on and run
orbit(ormake devfrom this repo). - The splash screen offers that repository: press
Enterto open it as your first project. Anywhere else,obrowses for a folder. - Press
p— the task box opens. Type what you want done and pressEnter. (Shift+Enter,Option+EnterorCtrl+Jstart a new line.) - A card appears with a yellow dot: Claude is working. When it turns blue, the turn is done.
- Press
Enteron the card to step into the session and type to Claude directly.Ctrl+Qbrings you back to the cards.
You never name sessions: after the first prompt each one renames itself (Fix Login Redirect, not
agent-3). r renames one by hand.
4. Reading the screen
┌ project tabs ─────────────────────────────────────────────┐
│ my-app ●1 ●2 api ●1 │
├ band: one checkout (branch, changes, pull request) ───────┤
│ ⌂ main ───── +3 files +60 −28 ── ↗ #57 ready ── │
│ ┃● Fix login ┃ ┃● Add tests ┃ ← cards (sessions) │
│ ↳ feat-search ────────────────────── │
│ ┃● Search API ┃ │
├───────────────────────────────────────────────────────────┤
│ ↑↓←→ move ⏎ open p new task ␣ follow-up j jump … │ ← footer: keys for here
└───────────────────────────────────────────────────────────┘
The pane (to the right or below the cards) shows the live terminal of the card under the cursor.
The dots — you read these instead of reading screens:
| Dot | Means |
|---|---|
| yellow | working on a turn |
| red | waiting on you — a permission prompt or a question |
| blue | finished, and you haven't looked yet |
| green | finished, and you've seen it |
| gray | never run yet |
| magenta | the process died mid-run |
Project tabs add their sessions up: api ●1 in red () means one session in that project is waiting on
you, even while you look at another project. A red dot also plays a sound, and sends a desktop
notification when the terminal window is in the background.
Usage and limits
The bottom bar's right side shows your Claude plan limits — 5h 23% ↻14:05 · wk 41%: the 5-hour
window with its reset time, and the weekly window. They turn yellow from 80% and red from 95%, and
the reset time, then the weekly figure, drop on a narrow terminal. Each Claude card also shows its
session's context-window use (ctx 42%, yellow from 80%). Nothing shows until Claude has reported it
(limits appear only for Pro/Max plans, after the first reply). Orbit reads this from Claude Code's
status line; if you already have your own, Orbit chains it, so yours keeps working.
5. The everyday loop
| I want to… | Press |
|---|---|
| Start a new task | p, type, Enter |
| Give a running session its next instruction, without opening it | Space on its card, type, Enter |
| Talk to a session directly | Enter on its card · Ctrl+Q to come back |
| Go to the next session that needs me | ; (and , for the previous one) |
| Find any session by name, in any project | j, type part of its name, Enter |
| Move around the cards | arrow keys · Tab opens/folds a band |
| Switch project | < / > · + lists them all · 1–9 jump to a tab |
| See a session full-screen | Ctrl+F |
| Hide or show the pane | z |
| Archive a finished session | a (⇧A shows archived ones, u restores) |
| Delete a session | d |
| Open a plain shell in this checkout | t |
| See every key | h |
| Quit (sessions keep running) | q |
The loop that makes Orbit worth it: start a few tasks with p, go do something else, and when you
hear a sound or see a red/blue dot, press ; to land on exactly the session that needs you.
Inside the task box (p) the row above the text shows where the task will run. Each part has a
key, so you can change it without losing what you typed:
| In the box | Changes |
|---|---|
Ctrl+P |
the project |
Ctrl+T |
the worktree (checkout) |
Ctrl+N |
run it in a new worktree (the frame turns green) |
Tab |
the harness (Claude, …) |
Ctrl+O |
the model and effort |
Ctrl+S |
pick the Claude skills this task should use (or type / first in an empty box) |
Shift+Tab |
apply a preset |
Esc |
close — what you typed is kept for next time |
Picking skills and workflows
With a hundred skills installed, Claude sometimes reaches for the wrong one. Press Ctrl+S in the
task box (or in the follow-up box that Space opens on a card) — or type / as the first
character of an empty box — and tick exactly the skills this prompt should use:
| In the picker | Does |
|---|---|
| type | filter by name |
Space (or a click) |
tick / untick a skill; on a workflow row, its whole set |
Enter |
back to the box, text intact, with the ticks kept |
Ctrl+W |
save the ticked skills as a workflow — asks for a name |
Esc |
clear the filter, then go back to the box as it was |
Workflows sit at the top of the list, then skills labelled personal (~/.claude/skills),
project (.claude/skills) and plugin (from enabled plugins). The box title shows what is ticked,
and when you send, Orbit puts one line in front of your prompt telling Claude to load those skills with
the Skill tool first. If you close a / picker with nothing ticked, the / goes into the box, so real
slash commands still work.
Workflows are saved in the project's .orbit/config.json under workflows — commit it to share them.
See Configuration.
6. Worktrees: parallel work without collisions
Two agents editing the same checkout trip over each other. A worktree is a separate checkout of the same repo on its own branch, so each agent gets its own folder.
- New task in a new worktree: in the task box press
Ctrl+NbeforeEnter. Orbit cuts a branch, creates the checkout next to your repo (<repo>-worktrees/<branch>), and starts Claude there. It shows up as a new band. - Move a running session into a worktree: just tell Claude "do this in a worktree". It runs
orbit worktree, and the session restarts inside the new checkout, conversation intact. - Change the branch of the main checkout:
con a card in the root band lists branches; type to filter,Enterto switch (it asks what to do with uncommitted changes). - Delete a worktree: delete its last session with
d. The confirmation then asks whether to remove the now-empty checkout from disk too:yyes,nkeep it,Esccancel.
Each band's header shows its branch, its uncommitted changes (+3 files +60 −28) and its pull
request if it has one.
7. Reviewing what an agent did
All of these open for the checkout of the card under the cursor:
| Key | Opens |
|---|---|
g |
the diff of everything changed, file by file; mark files as reviewed as you go |
l |
the git graph: every branch's commits with their refs, the selected one's message and files beside them; type to filter, Enter lists a commit's files (each read as a diff), Ctrl+b all branches / current branch, Ctrl+y copies the sha. Reading only |
f |
find a file by name (fuzzy); Enter opens it, Ctrl+Y copies its path |
⇧F |
search inside files (git grep) |
b |
browse the file tree |
⇧O |
open the checkout in your editor or browser (see section 11) |
Markdown files open as rendered pages, images preview inline, and Mermaid diagrams render when mmdc
is installed.
The code graph (graphify)
Orbit keeps a knowledge graph of your code for every checkout using
graphify, with nothing to set up — it only needs uv
(Orbit installs graphify once per machine with uv tool install graphifyy the first time it's needed,
or uses a copy you already have):
- It is built when you add a project or create a worktree, and refreshed after every Claude turn. It uses code analysis only — no LLM, no cost — and takes a few seconds (incremental after that).
- It lives in
.orbit/local/graph/inside the checkout and is kept out of git automatically (through.git/info/exclude, so no tracked file changes). Orbit points graphify there with itsGRAPHIFY_OUTvariable, which every Orbit session and terminal has set, sographify querythere finds it. Outside Orbit, pass--graph .orbit/local/graph/graph.jsonor setGRAPHIFY_OUT=.orbit/local/graph. - Claude sessions are told the graph exists and query it (
graphify query,explain,path,affected) before searching file by file — those commands are pre-approved, so no prompts. - The graph gate makes that stick. Told is not enough: left alone, Claude reaches for
find,grep, Grep and Glob first. So in a checkout with a graph, a search made before any graph query in a prompt is blocked with a message handing Claude thegraphify queryto run, and once it has queried the graph every search works normally for the rest of that prompt. At most two searches a prompt are blocked, so a session is never stuck. Filters such asps aux | grep xare not searches and always run. orbit graph-usageshows whether it is working. Run it in the checkout and it prints the graph queries, the searches that ran, how often a session was steered to the graph and how often it then used it, plus the recent queries. The data comes from.orbit/local/graph/orbit-usage.jsonl.kopens the graph in your browser (and builds it first if there isn't one yet).
Is it working? Any of these tells you:
- the checkout has a
.orbit/local/graph/folder withGRAPH_REPORT.mdandgraph.jsonin it; kopens the graph;- Claude runs
graphify query "…"(orexplain,path,affected) before searching files; orbit graph-usagein the checkout lists graph queries;orbit doctorshows✓ graphify.
The files in .orbit/local/graph/cache/ change after every turn; graph.json only changes when the
code did. A checkout without a graph gets one when a session starts in it, or straight away with k.
Earlier Orbit versions kept the graph in graphify-out/; Orbit no longer reads or writes it, so
delete that folder once .orbit/local/graph/ exists (unless you built it yourself with /graphify). Claude is told about the graph when a session starts, so a
session started before its checkout's first graph was built won't know about it; a new session will.
To turn it off: "graphify": false in config.json for every project, or in a project's
.orbit/config.json for just that one.
Browser testing
Ask a Claude session to check or test something in a browser and it hands the job to a cheaper
model driving agent-browser (Vercel's browser CLI),
with nothing to set up — it only needs npm (Orbit installs agent-browser once per machine with
npm install -g agent-browser the first time a Claude session starts, or uses a copy you have):
browser-checkruns on Haiku for quick, single-page checks: open a URL, confirm something renders or a text appears, read a value, take a screenshot.browser-testruns on Sonnet for multi-step flows: logging in, filling and submitting forms, navigating across pages, reproducing a UI bug, end-to-end checks.- Claude picks one by the task and gets back a short report — what was checked, what was seen, pass or fail, and where the screenshots are. agent-browser commands are pre-approved, so no prompts.
- The Claude in Chrome extension is switched off for sessions Orbit starts (for that launch only — your Claude settings are not changed), so browser work never lands in your own Chrome.
To turn it off: "browser_testing": false in config.json.
8. GitHub: pull requests and issues
Orbit asks the gh CLI what's open on the repo, so gh must be installed and logged in.
v— every open pull request. Read the description, checks and conversation;Ctrl+Gshows its diff,Ctrl+Ccomments,Enterstarts a Claude session on it in the PR's own checkout.i— every open issue.Enteropens the task box for it; the issue's link travels with the session so Claude knows what it is fixing.Ctrl+Eedits the issue.⇧Vopens a card's pull request in the browser,⇧Iits issue,⇧Gthe repository.
A band whose branch has a pull request shows it on its header — red when it no longer merges or a check failed, purple once merged.
9. Presets: tasks you repeat
If you keep typing the same framing ("review this for security…", "write tests for…"), save it as a preset:
eon any card lists your presets.Ctrl+Acreates one: a name, the model and effort, and text that goes before and/or after whatever task you type.Enteron a preset asks for the task and launches it. Set Task toskipfor presets that need no task at all (a "commit and push"), soEnterlaunches immediately.
In the task box, Shift+Tab applies a preset to what you've already typed.
10. Agents that drive Orbit
Claude sessions started by Orbit know a few orbit commands, so you can ask in plain words:
| Say to Claude | It runs |
|---|---|
| "do this in a worktree" | orbit worktree <name> — the session moves into a new checkout |
| "start a new session that writes the tests" | orbit spawn "<task>" — a second agent starts beside it |
| "show me that file" / "show the diagram" | orbit open <file> — it opens in a viewer inside Orbit |
| "what did the research session find?" | orbit read research |
| "ask the api session which library it chose" | orbit ask api "<question>" |
| "list the other sessions" | orbit sessions |
F10 switches to the orchestrator view: one pinned Claude chat that can list, read, message and start sessions across all your projects for you. See Orchestrator.
11. Running and opening your project
Commit a .orbit/config.json (a root .orbit.json still works) at the root of a repository to tell Orbit how to run it.
Orbit always reads it from the project's main checkout, so one file serves every worktree:
{
"run": "npm run dev",
"open": "open http://localhost:3000"
}
- Run — right-click a card (or the project tab) → Run. The command runs in a terminal card in that worktree; Stop run stops it.
- Open —
⇧Oon a worktree runs theopencommand once (a browser tab, your editor, …).
Nothing in the file runs until you press its key. To keep the commands out of the repo, set them in
Settings (s) → Project instead.
12. Settings worth changing
Press s. Each tab is a list; Enter or ←/→ change a row. Suggested for a Claude-only setup:
| Where | Setting | Why |
|---|---|---|
| Agents | turn Codex, Cursor, Pi, Muse, Grok, OpenCode off | the pickers then only offer Claude |
| Agents | Claude → Model / Effort | the default every new task uses |
| Sessions | Warm spare agent off | otherwise an idle Claude waits in the background (150–300 MB) to make launches instant |
| Sessions | Prewarm dead sessions off | otherwise sleeping sessions are woken as soon as your cursor rests on their checkout |
| Sessions | Idle session timeout | how long an unwatched session lives before it is put to sleep (it resumes when you return) |
| Sessions | Done sound / Feedback sound | the sounds for "finished" and "needs you" |
| Appearance | Worktree layout: list | one line per session — calmer with many sessions |
| Appearance | Theme, Session pane: right/bottom | taste |
| Hotkeys | any action | rebind any key; it warns before taking one already in use |
Settings live in ~/Library/Application Support/dev.orbit.orbit/config.json on macOS and
~/.local/share/orbit/config.json on Linux (orbit config path prints it). orbit config export
backs them up; orbit config import <file> restores them.
13. Key reference
Keys on the grid (where the cards are). Inside a box or a list, the footer shows that screen's keys. Every key is rebindable in Settings → Hotkeys.
Move
| Key | Action |
|---|---|
↑ ↓ ← → |
move between bands and cards |
Tab |
open / fold the band under the cursor |
Enter |
step into the session (type to Claude) |
Ctrl+Q |
step back out to the cards |
j (or /) |
jump to any session, any project |
; / , |
next / previous session that needs you |
< / > |
previous / next project tab |
+ |
list every project |
1 … 9 |
project tab by position |
x |
close the project tab (sessions keep running) |
Ctrl+D / Ctrl+U |
half a page down / up |
Sessions
| Key | Action |
|---|---|
p |
new task (the task box) |
n |
new session without a task |
Space |
follow-up: send the next instruction to the card |
e |
presets |
r |
rename |
a / u / ⇧A |
archive / unarchive / show archived |
d / ⇧D |
delete / delete all |
m |
move the session to another worktree |
⇧P |
duplicate the session |
t |
new shell terminal |
⇧T |
a shell in a new Ghostty tab, outside Orbit |
w |
cycle the pane through this checkout's terminals |
z |
hide / show the pane |
Ctrl+F |
full-screen session |
Code and GitHub
| Key | Action |
|---|---|
g |
diff |
l |
git graph (commits, branches, refs) |
f / ⇧F |
find a file / search in files |
b |
file tree |
c |
switch the main checkout's branch |
⇧O |
open the checkout (editor / browser) |
k |
the code graph (graphify) in the browser |
v / i |
pull requests / issues |
⇧V / ⇧I / ⇧G |
open PR / issue / repo in the browser |
y |
comment on the pull request |
⇧R |
reload from GitHub |
General
| Key | Action |
|---|---|
o |
open a folder as a new project |
s |
settings |
h (or ?) |
help: every key, grouped by job; / filters it, s goes to rebinding |
F10 |
orchestrator view |
⇧H |
SSH hosts |
⇧M |
memory usage |
q |
quit (sessions keep running) |
14. Command-line reference
orbit # open the TUI
orbit add <dir> # add a repository as a project (orbit add . for the current one)
orbit graph-usage [dir] # how much Claude sessions use the code graph there
orbit sessions # list every session
orbit read <session> # print a session's recent output
orbit ask <session> "…" # ask a session something and print the answer
orbit kill # stop the daemon and every session
orbit reload # move the daemon onto a new build, keeping sessions
orbit upgrade # install the latest release (through brew on a Homebrew install)
orbit --version # which release you're running
orbit doctor # what's installed, what's missing, what each tool unlocks
orbit doctor --fix # install graphify and agent-browser now (once, through uv / npm)
orbit config path # where the settings files are
orbit config export # back up settings
orbit ssh <host> # open Orbit on another machine
The full list, with every flag: Commands, or orbit <command> --help.
15. Troubleshooting
| Problem | Fix |
|---|---|
| A card's dot stays gray while Claude works | the status hooks didn't install. Check .claude/settings.local.json in that checkout has entries tagged _orbitManaged, and that curl is on your PATH |
| "daemon did not come up" | run orbit kill, then orbit again. Logs: ~/Library/Application Support/dev.orbit.orbit/state/daemon.log (Linux: ~/.local/state/orbit/) |
The footer shows ⇡ vX.Y.Z |
a newer release is out: orbit upgrade |
brew install orbit installed some other app |
that's an unrelated cask with the same name: brew uninstall --cask orbit, then brew install amenadem/orbit/orbit |
| A change I built isn't there | the old daemon is still running: orbit reload (or orbit kill then orbit) |
path must be shorter than SUN_LEN |
the socket folder path is too long for macOS; set ORBIT_RUNTIME_DIR to a short path such as /tmp/orbit |
k says graphify couldn't start, or no graph appears |
an old copy of graphify may come first on your PATH (which -a graphify); Orbit skips copies whose Python is gone, but remove stale ones or run uv tool upgrade graphifyy |
make ci fails with fatal: no tag message? |
your global git config signs tags (tag.gpgsign). Run tests as GIT_CONFIG_GLOBAL=/dev/null make ci |
cargo: command not found |
rustup isn't on your PATH: export PATH="/opt/homebrew/opt/rustup/bin:$PATH" in ~/.zshrc |
For more detail, set ORBIT_LOG=debug before starting.
16. What's coming
These are planned for this fork and not built yet:
- Command palette —
:and type what you want ("diff", "rename"); see the action and its key,Enterruns it. No more remembering keys. - Calmer view with many sessions — a filter for "needs me / active only", and a compact layout that switches on by itself past a number of sessions.
- Lessons learned —
orbit lesson addlets an agent record a hard-won fix in.orbit/lessons/(committed), and new sessions start with the relevant ones. - MCP manager — choose which MCP servers each project's sessions load.