Source code as agent knowledge — multi-repo Git workspaces where agents read, code, and ship
→ No RAG. No index — real source, not retrieval.
Orbit manages multi-repo Git workspaces where AI coding agents read, modify, and commit directly in real source code — full worktrees with git history, not index fragments. Integrates with Claude Code, Codex, OpenCode, and Qoder.
I built Orbit because I was tired of copy-pasting context between repo sessions — one agent should have your entire repo pool available, loading what it needs on demand instead of being locked to one repo per session.
Who it's for: developers whose agent work spans multiple repos — main project, dependency source, toolchain and wiki alongside it. Solo or team, polyrepo or cross-repo debugging.
Cross-repo context consistency. One agent, one workspace, multi-repo delivery — every repo the agent pulls in shares the same context. The agent greps, reads, and modifies across repos without switching tools: when it changes backend, it sees the result immediately in frontend. Full git history (blame, log, branch topology) across every repo, no copy-pasting, no stale snapshots.
| Approach | Accuracy | History | Write-back | Cross-repo |
|---|---|---|---|---|
| Agent memory | Low — stale | ✗ None | — | ✗ Per-session |
| Web search | Medium — fragments | ✗ None | — | ✗ None |
| Add directory | High — per-dir | ✓ Per-repo | ✓ Yes | ✗ No unified tree |
| RAG | Medium — loses structure | ✗ Lost in chunks | ✗ Read-only | ✗ Per-query |
| Orbit | High — grep, trace | ✓ Full git | ✓ Commit, push | ✓ Unified tree |
Parallel isolation. Each workspace is an independent multi-repo worktree combination. Multiple agents work in parallel, each in its own workspace — no branch conflicts, no state leaking between tasks. Reusing a single workspace across tasks means branch contamination and agent interference; isolation is what makes multi-task, multi-agent practical.
Real directory tree, zero toolchain adaptation. A workspace is a real directory tree — not symlinks, not editor virtual views. Drop a go.work and go build/gopls resolve across repos with zero setup. Same for Cargo/pnpm/Gradle. Your toolchain doesn't know Orbit exists, and that's the point.
Goal to workspace in one command. orbit new "goal" creates a task-scoped workspace. Once the agent starts, it uses orbit commands to assemble repos progressively:
Level 0 orbit repos → Name + one-line brief (~50 tokens/repo)
Level 1 orbit info <repo> → Roles + entry points (~200 tokens)
Level 2 orbit add <repo> → Full source directory
After working, the agent captures discoveries with orbit jot and folds them into repo memos — the same content later sessions read at Level 1, closing the feedback loop.
Knowledge repo as a workspace member. A dedicated knowledge repo — design notes, PRDs, decisions — sits alongside code repos as a first-class member. The agent reads from it and writes back via branch + PR, so knowledge accumulates in one place instead of getting lost in chat or session memory. Solo devs sweep whenever; teams aggregate daily. Same mechanism, no server. See docs/recipes.md for the pattern.
Spins up a two-repo mission — a probe's flight computer and its ground station, wired by a shared contract — entirely on your machine: the two mission repos are local fakes, so no GitHub account, no push, no server.
Claude Code
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/orbcli/orbit/main/try.sh)" _ --claudeCodex
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/orbcli/orbit/main/try.sh)" _ --codexOther agents
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/orbcli/orbit/main/try.sh)" _ --opencode # OpenCode
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/orbcli/orbit/main/try.sh)" _ --qodercli # Qoder CLI
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/orbcli/orbit/main/try.sh)" # runtime only(The _ is a bash placeholder for the script name — copy a line as-is. Runtime-only skips the plugin; you maintain the skill yourself.)
The demo drops you into a ready workspace: add a fuel field to the telemetry downlink — a change that must land in both repos in lockstep. With an agent flag, the plugin install is folded in — just claude start, codex start, opencode --prompt start, or qodercli start. Works on a fresh machine with no SSH keys — the demo rides a shorthand → HTTPS → SSH source chain and retries through flaky networks. Clean up with rm -rf ~/orbit-try.
One-line, with your agents' plugins
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/orbcli/orbit/main/install.sh)" _ --claude --zshFlags combine freely — agent plugins: --claude / --codex / --opencode / --qoder (--qodercli); shell completion: --zsh / --bash (or neither).
Runtime only
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/orbcli/orbit/main/install.sh)"From a local clone
git clone https://github.com/orbcli/orbit.git && cd orbit
./install.sh --claude # Claude Code plugin
./install.sh --codex # Codex plugin
./install.sh --opencode # OpenCode plugin
./install.sh --qoder # Qoder plugin (--qodercli is an alias)
./install.sh --claude --zsh # add shell completion: --zsh or --bashinstall.sh installs the runtime to ~/.local/bin and puts it on your PATH. To uninstall: ./install.sh --uninstall --all (or pick targets — ./install.sh --help).
- Reinstall or switch the plugin source — every install refreshes content;
--forceresets plugin and marketplace (also how you switch sources). - Config-management tools — provider switchers and other snapshot-restore tools can roll back Orbit's plugin registration; what to put into the tool's stored config per host.
- Flaky or blocked network — retries, source-chain rotation, no silent failures, no hangs.
- Codex notes — plugin hooks need a one-time trust review (
/hooksin the CLI); Orbit writes to.repos/outside the workspace root, which Codex's sandbox may block. - OpenCode via npm (alternative) — add
"opencode-orbit"to thepluginarray inopencode.json; the plugin self-registers its skill, no manual setup needed.
orbit config agent.recommend 'claude "orbit start"'# Add repos to the source pool (one-time)
orbit clone [email protected]:org/backend.git
orbit clone [email protected]:org/frontend.git
# Create workspace, launch agent
orbit new "Modify API definition and update frontend calls"
cd task-01 && claude "orbit start"
# Or skip manual launch:
orbit new "Upgrade informer to v0.28 new API" --exec 'claude "orbit start"'For the complete command flow, see USAGE.md; for common scenarios, see docs/recipes.md.
project-root/
.repos/ ← Cloned repos, shared across all workspaces
.orbit ← Global index + repo briefs + project config
.backend.md ← Repo memo (agent read/write)
backend/
frontend/
task-01/ ← Workspace: isolated environment for one task
.orbit ← Goal, creation time, status
backend/ ← Worktree (actual development directory)
frontend/
- Not an orchestrator — gives each agent an isolated workspace; parallelism comes from isolation, not scheduling.
- Not a cloud service — Zero infra, no server, no database, no container, no daemon. Everything lives as real source and plain markdown in your
.repos/. - Not a workflow manager — orbit doesn't prescribe git workflow (commit, branch, push are native git) or manage workspace files (
go.work,Cargo.toml,AGENTS.md,CLAUDE.mdworkspaces). They work because the directory layout is real; placing them is your or your agent's call.
See PRINCIPLES.md for the full non-goals.
Orbit works best when the agent knows it's inside a workspace from its first turn:
| Integration | Auto-detect | Workaround |
|---|---|---|
| Claude Code plugin | Yes — bundled SessionStart hook injects workspace state |
— |
| Codex plugin | Yes — bundled SessionStart hook injects workspace state |
— |
| OpenCode plugin | Yes — bundled system.transform hook injects workspace state |
— |
| Qoder plugin | Yes — bundled SessionStart hook injects workspace state |
— |
| Skill only / other agents | No | /orbit or orbit start at session start |
A cold start loads progressively:
- Prime (
orbit context --startup) — goal, state, repo pool roster. No source loaded yet. - Ignite (
orbit info→orbit add <repo>) — agent assesses repos via memo, pulls what it needs as full worktrees. - Orbit — grep, edit, commit, push. New repos pulled on demand.
Resuming a workspace with repos already present skips priming — the same --startup call re-ignites it with each repo's memo + staleness instead.
Plugin users: nothing to configure — all four plugins (Claude, Codex, OpenCode, Qoder) auto-approve safe orbit subcommands. Skill-only users can allowlist by hand. See skills/CONSTRAINTS.md for command tiers and the allowlist snippet.
# Repo management
orbit clone <url> [--push <fork-url>] [--name <identity>] [--branch <branch>]
orbit repos
orbit info <repo>
orbit memo [<repo>] [--refresh|--scaffold]
orbit sync [repo...] [--force] [--branch <branch>] # --force / --branch: project root only
# Workspace lifecycle
orbit new "<goal>" [--name <name>] [--no-goal] [--exec "<cmd>"]
orbit add <repo> [--ref <tag/branch>] [-s|--silent]
orbit switch [repo] <name>
orbit switch -c [repo] <name>
orbit jot [<repo>] ["<text>"]
orbit jot [<repo>] --pop [--json]
orbit done [--pr <url>...] [--json]
# Cross-workspace cleanup (from project root only)
orbit prune [workspace] [--older <dur>] [--dry-run] [--force]
# Status and context
orbit status [workspace]
orbit goal ["text" / --clear]
orbit context [<key>] [--startup|--prime|--reignite] [--json]
# Configuration
orbit config [<key> [<value> | --unset]]
# Diagnostics
orbit doctor
orbit version
# Completion
orbit completion <zsh|bash>| Document | Content |
|---|---|
USAGE.md |
Complete usage guide |
docs/recipes.md |
Common scenarios cookbook |
docs/comparison.md |
Tool comparison (workspace management + context/knowledge tools) |
PRINCIPLES.md |
Design principles and key decisions |
ROADMAP.md |
Roadmap and completion status |
docs/spec-*.md |
Design specs (directory structure, branching strategy, command system, metadata, knowledge system, lifecycle, hooks) |
CONTRIBUTING.md |
Contribution workflow and development conventions |