Starscape Orbit

Spin up an Orbit to track the motion of your project.

Orbit by Starscape is a lightweight, kanban-style project management solution for human-agent collaboration.

Use it when you want the board to live with the code: one SQLite file, one small service, one human UI, and one agent-first API.

• Human UI for creating, editing, and moving tickets kanban-style.
• Agent API/MCP for claiming work, reading context, updating implementation notes, commenting, and writing project memory.

Screenshots

These screenshots show Orbit in dark and light mode. They were captured before the AI Ready lane was added to the board.

🛰️ Zero external runtime dependencies

Orbit's server, CLI, and MCP layer run with zero external runtime dependencies. They use Node.js built-ins: node:sqlite, node:http, node:crypto, and friends.

Build-time packages include Starscape's own @starlove/ui styling and esbuild for bundling the web UI. They are not needed by initialized project boards at runtime.

Install and use Orbit

Install the CLI:

corepack enable
pnpm add -g @starlove/orbit

# or, from source:
git clone [email protected]:brucestarlove/ss-orbit.git
cd ss-orbit
pnpm install
pnpm run build:bundle
pnpm link --global

From the repo you want a board for:

cd path/to/your-app
orbit init            # creates .orbit/board.db + managed SKILL-ORBIT.md + AGENTS.md
orbit init --example  # optional: add onboarding example tickets
orbit init --no-ai    # optional: create or update the board with AI disabled

Start one runtime and keep using it:

orbit run     # host runtime, uses ~/.orbit, refreshes managed SKILL-ORBIT.md copies
# or
orbit docker  # Docker runtime, uses <repo>/.orbit/docker-data

Both runtimes serve from http://localhost:13701 by default; orbit run auto-increments if that port is busy. Use --port <n> to force an exact port and --cwd path/to/repo to bind a specific repo. Use orbit run -d to start the host runtime in the background.

orbit run and orbit docker run the same app but use different registries by default. A board registered in one mode will not appear in the other unless you share DATA_DIR, re-register it, or import a snapshot.

For multiple boards, run your chosen runtime once. In another terminal, cd into another repo and run orbit init; the board joins that runtime's board picker without a restart. SKILL-ORBIT.md is Orbit-managed guidance and may be overwritten by orbit init or refreshed by orbit run; keep repo/team-specific agent rules in AGENTS.md or board Agent Instructions.

Docker options:

orbit docker                 # builds starscape-orbit:local, then serves http://localhost:13701
orbit docker --port 13702    # force a different published port
orbit docker --no-build      # reuse an existing starscape-orbit:local image

orbit docker mounts the selected project into the container. Board data still lives in .orbit/board.db; Docker-only registry, exports, and backups live under <repo>/.orbit/docker-data by default.

Wipe a single board and start over with orbit reset (deletes .orbit/, SKILL-ORBIT.md, and the registry row), then orbit init again. On Windows, close Orbit runtime terminals and restart any AI client using Orbit MCP before deleting or recloning a repo; those helper processes keep SQLite handles open while they are running.

Use with AI

Orbit ships with everything an agent needs to claim work, read tickets, and write back implementation notes. New boards have AI collaboration enabled by default; pass orbit init --no-ai or turn off Enable AI in Settings → AI if you want a human-only board.

1. Confirm AI is enabled. Open Settings (gear icon) → AI tab → toggle Enable AI if needed. Orbit provisions the AI Ready, In Progress, and Review lanes if they're missing, surfaces the agent-context fields, and reveals the MCP setup snippet.
2. Fill in agent context. Settings → AI → Agent Instructions is the project-level briefing every agent reads before touching a ticket. Describe what the project is, who it serves, the stack, and any rules of the road.
3. Register the MCP server with your agent. The AI tab generates copy-pasteable snippets for Claude Code, VS Code, Cursor, Codex, OpenCode, OpenClaw, and other MCP-capable clients — pick your OS + client and paste the command into your agent's MCP config.
4. Restart the agent. On its next boot it discovers the Orbit MCP tools (board_claim_next, board_get_ticket_context, board_update_ticket, etc.).
5. Point the agent at a ticket. From inside the repo, ask the agent to read SKILL-ORBIT.md and then work on a ticket via the Orbit MCP — e.g., "Use the Orbit MCP to claim the next AI-ready card and start work." It pulls a focused context pack, claims the ticket, and updates the board as it goes.

If you initialized with --example, ticket #12 (Try Orbit MCP on this ticket) is a good first exercise once MCP is connected.

Dispatch a local Hermes run

For a first-class handoff to a named Hermes profile, use orbit dispatch instead of writing an ad-hoc prompt file:

orbit dispatch --board my-app --ticket 12 --profile agent --worktree
orbit dispatch 'http://orbit.example/#/b/my-app/t/<ticket-id>' --profile agent --worktree
orbit dispatch --board my-app --ticket 12 --dry-run    # preview only; no writes or spawn
orbit dispatch --board my-app --ticket 12 --no-spawn   # prepare handoff/comment; leave lane unchanged

Dispatch validates the board, ticket, blockers, and Hermes availability before mutating a ticket. Normal spawn mode writes the generated handoff as a linked markdown artifact, stores only a terse plan summary in AI Plan, moves the ticket to In Progress, optionally preserves a git worktree/branch for review, starts Hermes, and comments a compact run record back onto the card. --no-spawn writes the handoff artifact/comment but does not move the ticket to In Progress. The default agent-safe policy allows local inspection, edits, tests, and commits while blocking Docker, pushes, deploys, package installs, destructive git commands, and common network/cloud escape hatches.

orbit dispatch supports hosted boards through a full Orbit ticket URL or --server-url <url> --board <slug> --ticket <id-or-number>. In remote mode, hosted Orbit is the planning-state source of truth while --cwd points at the local code checkout/worktree root. Full operator/user guide: docs/ORBIT_DISPATCH.md.

Vocabulary

• Board — one repo's planning surface. Each board carries its own agent_instructions, lanes, tickets, and memory entries.
• Lane — a column. Lanes are user-defined and freely named/reordered. The default seed gives you Backlog, Todo, AI Ready, In Progress, Review, Done, Cancelled; AI Ready, In Progress, and Review are anchor lanes the agent flow keys off. AI Ready is inserted between Todo and In Progress when AI is enabled.
• Ticket types:
  • epic — index card for a multi-feature initiative. Owns child tickets via parent_ticket_id.
  • feature — a standalone capability or new behavior.
  • task — a smaller, scoped unit of work.
  • bug — defect, regression, or broken behavior.
• Checkpoint — mid-work human judgment: call checkpoint with your question. The ticket moves to Review; the checkpoint comment marks the blocking fork. Use complete when work is finished.
• Two relationship models — hierarchy (parent_ticket_id, set on the row, only epics own children) is separate from the relations table (relates_to, blocks, blocked_by). The server keeps them disjoint.
• Blockers — a per-card blocked_by row in the relations table is the single source of truth. If the row exists, the ticket is blocked. Rows are removed two ways: the user deletes the relation manually in the UI, or the blocking ticket lands in the Done lane and the server auto-deletes every relation row that named it as a blocker. (Epic targets expand to their open children — see GET /api/tickets/:id/blockers.)

Requirements

• Node.js 22.13+. The server uses the built-in node:sqlite module, which is available without an experimental flag starting in 22.13 (or 23.4+). You'll still see an experimental-feature warning on boot — that's expected until the module stabilizes.
• pnpm 10+ for development. The repo pins pnpm through packageManager; use Corepack (corepack enable) to get the right version.

Bun is not used as the Orbit runtime because Orbit depends on Node's built-in node:sqlite module.

How it works

Each repo gets its own board database. Orbit keeps a small central registry that maps repo paths to their board files; the CLI, web app, and MCP server use explicit project roots when provided, then fall back to walking upward to find .orbit/board.db.

• Per-repo board — .orbit/board.db lives in the repo it tracks. orbit init creates it, writes the managed SKILL-ORBIT.md at the repo root, and creates/updates AGENTS.md with a terse pointer so agents load the full Orbit protocol only when relevant. orbit run refreshes managed SKILL-ORBIT.md copies for registered repos on startup. Add --example to create onboarding cards, or --no-ai to disable AI collaboration for the board.
• Central registry — registry.db records each board's path, slug, and last-active timestamp. Host orbit run uses ~/.orbit; orbit docker uses <repo>/.orbit/docker-data. Keep one mode unless you intentionally share DATA_DIR, re-register boards, or import snapshots.
• Project-root discovery — orbit run, orbit mcp, and MCP-attached agents resolve a board from an explicit --cwd / PROJECT_ROOT first, then fall back to walking up from process cwd to find .orbit/board.db. Persistent MCP configs should use an explicit root so the right board attaches even when the agent launches elsewhere.
• Two channels for AI — AGENTS.md is the auto-loaded briefing, with an Orbit-managed pointer to SKILL-ORBIT.md; the MCP config tells the agent runtime how to launch Orbit's MCP server for the right project. The briefing travels with the repo; the MCP registration is per-agent-install.
• Snapshot-portable — Settings → Data → Export downloads a .orbit.json snapshot, with an option to embed attached images. Import on another install (or in the browser preview at orbit.starscape.app/app) to restore the same board.

Developing Orbit

pnpm install
pnpm run dev
pnpm test
pnpm run build

Open the URL printed by orbit run (normally http://localhost:13701).

If you want an AI agent to work this board, point it at SKILL-ORBIT.md. Agent-facing HTTP/MCP details live in docs/AGENT_PROTOCOL.md.

Two channels: MCP config tells your AI app where mcp-server.js lives. SKILL-ORBIT.md is the repo-local briefing the agent reads before working.

Typical Workflow

A normal day on a shared board:

1. Human creates an epic for a new initiative and fills in card description with the high-level breakdown.
2. Human or Agent breaks it into feature / task / bug cards under the epic and moves the workable ones to the AI Ready lane.
3. Human directs Agent to find a ticket by number or name, or tell it to call claim-next to get one from the AI Ready column, which gets context for the ticket and important project notes, and starts work. Blocked tickets are skipped automatically.
4. Agent either:

• calls complete with a summary and PR link, moving the card to Review; or
• calls checkpoint with a question if it is blocked mid-flight. Orbit moves the card to Review and records a checkpoint comment.

5. Human reviews, merges, and moves the card to the Done lane (or sends it back with comments).

MCP

Orbit ships a stdio MCP server for agents that prefer tools over raw HTTP. You don't normally start it yourself; your agent runtime spawns it from the snippet in Settings → AI. To run it standalone:

orbit mcp
# equivalent: node src/mcp-server.js

MCP uses the same registry and board databases when launched with the same DATA_DIR and --cwd as the web runtime.

A copy-editable client config lives at docs/mcp-client.example.json. The web app also generates setup snippets from Settings → AI. More detail is in docs/MCP_SETUP.md.

MCP tools

| Purpose | Tool | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Index | board_list (tiny registry), board_set_active | | Board context | board_context (settings + journal + deployment; optional board + include_struck) | | Read | board_read_ticket, board_read_comments, board_get_ticket_context (lean), board_get_ticket_context_full (manual/journal), board_get_ticket_relations, board_get_ticket_blockers, board_search, board_list_archive | | Agent flow | board_claim_next, board_checkpoint, board_complete | | Write | board_update_ticket, board_add_comment, board_add_board_entry, board_archive_ticket, board_restore_ticket, board_delete_ticket | | Admin | board_export_board, board_update_settings |

First-Run Seed

orbit init (or first server start in a repo without a board) creates a universal board seed in the new .orbit/board.db:

• Board: name from BOARD_NAME env var, otherwise inferred from package.json name or the repo folder name. Slug from BOARD_SLUG or derived from the name.
• Repo metadata: REPO_URL env var or git config --get remote.origin.url; SYSTEM_PATH env var or the repo path passed to orbit init.
• Default branch: DEFAULT_BRANCH env var, otherwise the current git branch.
• Lanes (7): Backlog, Todo (default), AI Ready, In Progress, Review, Done, Cancelled. Pass --no-ai to seed without AI Ready and leave AI collaboration disabled.
• Labels (7): human-only, needs-human-input, needs-decomposition, needs-followup, tech-debt, security, onboarding.
• Onboarding cards (optional): pass --example to create an epic #1 plus children #2, #3, and #12 — Try Orbit MCP on this ticket.
• Free-form fields: project_notes (Notes tab) and agent_instructions (AI tab) get placeholder text you should replace.

Set env vars before orbit init or first runtime start to skip the placeholders:

$env:BOARD_NAME="My App"; $env:BOARD_SLUG="my-app"; $env:REPO_URL="https://github.com/you/my-app"; orbit init

BOARD_NAME="My App" BOARD_SLUG=my-app REPO_URL=https://github.com/you/my-app orbit init

Troubleshooting

• UI loads but lanes are blank — usually a cached app.js. Hard-refresh the page (Ctrl+Shift+R) and check the browser console.
• node:sqlite is not a known module — you're on Node < 22. Upgrade to Node 22+.
• Windows says .orbit/board.db is busy during cleanup - an Orbit web server, MCP helper, editor, or terminal still has the SQLite file open. Stop the Orbit runtime, close or restart AI clients with Orbit MCP enabled, then retry delete from Settings or run orbit reset --cwd <repo> before recloning or deleting the folder.

Data

Orbit stores each board in the repo it belongs to:

• Board data: .orbit/board.db
• Host registry and backups: ~/.orbit by default
• Docker registry and backups: <repo>/.orbit/docker-data by default

Override runtime data with:

DATA_DIR=/path/to/data orbit run
orbit docker --data-dir /path/to/data

$env:DATA_DIR="C:\path\to\data"; orbit run

The UI exposes Export and Import from Settings → Data.

Export downloads a portable .orbit.json file you can move to another computer or import later. By default it stores image attachment records without image bytes; enable Include attached images to embed the images in the snapshot.

Automatic backups are separate from Export. Orbit quietly saves local backup copies after you make changes, waiting about two minutes after your last edit so it does not create a file for every click. Orbit also makes an immediate backup before risky actions like deleting a board, resetting Orbit, or replacing a board during import.

Backups are stored under the active runtime data dir's backups/ folder. They are for local recovery; Export is still the easiest way to intentionally save or share a board.