OrbitMap CLI

Project management for AI coding agents — without MCP.

What is this?

OrbitMap CLI gives AI agents (Gemini CLI, GPT Codex, Claude Code without MCP, etc.) access to OrbitMap project management through simple shell commands. It's the non-MCP alternative to orbitmap-mcp, and tracks the same Agent API contract (currently schema_version 6.3.0).

Use cases:

• AI agents that can run shell commands but don't support MCP (Gemini CLI, GPT Codex CLI)
• Environments where MCP configuration is impractical
• Quick task management from your terminal

Quick Start

# 1. Run the setup wizard — it asks where your data should live:
#    [1] Orbitmap.ai account (cloud)  [2] Local files (no account)
npx orbitmap init

# 2. Cloud: enter your credentials
#    - API Key (from OrbitMap dashboard)
#    - Area ID (optional — auto-detected if you belong to a single area)
#    Local: pick a workspace directory, a workspace name and a first area

# 3. Confirm the agent skills — `init` installs them in the same run, creating
#    CLAUDE.md / AGENTS.md if this directory has none yet. `--agent claude`
#    picks the type without asking; `--no-skills` opts out.

# 4. Start working
npx orbitmap start

init is the whole install: config, credentials, MCP block and the agent skills. There is no mandatory second command.

Local mode

The CLI runs in one of two modes, chosen once during orbitmap init:

| | Cloud mode | Local mode | |---|---|---| | Storage | Orbitmap.ai workspace (Agent API) | Markdown files with YAML frontmatter on your disk | | Account | required | none | | Web UI, team, multiple agents | yes | no — solo developer | | Commands | all of them | all of them, minus the limitations below |

Both modes speak the same commands with the same output — orbitmap start, orbitmap log, orbitmap tasks --json behave identically, and agent skills installed by orbitmap init never need to know which mode is active.

Set up local mode

Interactive — answer 2 at the mode question, then accept or override the three defaults (workspace directory ./.orbitmap, workspace name, first area):

npx orbitmap init

Scripted / CI:

npx orbitmap init --local \
  --workspace ~/orbits/personal \   # where the files live (default: ./.orbitmap)
  --workspace-name "My Orbit" \     # default: current directory name
  --area "My App" \                 # first area (default: current directory name)
  --no-skills                       # skip installing agent skills

If the workspace directory is outside the project, init writes a pointer at <project>/.orbitmap/link.json ({"workspace": "…", "area": "…"}) and adds .orbitmap/link.json and .orbitmap/docs/ to .gitignore (not the whole .orbitmap/ directory — .orbitmap/config.json, see Configuration, is meant to be committed). The pointer is found by walking up from the current directory, like .git, so commands work from any subdirectory. If the workspace is ./.orbitmap, nothing is gitignored — the data is meant to be committable.

Resolution order for the workspace directory: --workspace → ORBITMAP_WORKSPACE → .orbitmap/link.json → ./.orbitmap/workspace.yml → workspace_path in ~/.orbitmap/config.json. The mode itself is resolved per-project, first match wins: --workspace (explicit → local) → ORBITMAP_MODE=local|cloud → nearest .orbitmap/config.json mode field → auto-detect (walk up from cwd looking for .orbitmap/workspace.yml or .orbitmap/link.json, same as git looking for .git → local) → mode in the global config file, defaulting to cloud when absent. The auto-detect rung (and the project config rung above it) is what lets one project stay local and another stay cloud on the same machine — init never writes mode to the global config for the local path.

Where the data lives

<workspace-dir>/
  workspace.yml                # workspace header, default area + entity-number counters
  missions/MS-<num>.md
  intents/IN-<num>.md
  ideas/ID-<num>.md
  docs/<slug>.md               # one copy of each document, same path and format as the
                               # cloud doc cache (`<project>/.orbitmap/docs/`)
  issues/IS-<num>.md           # workspace-level issues (no area)
  areas/
    <area-slug>/
      area.yml                 # area header (git url, default branch, …)
      tasks/TS-<num>.md
      issues/IS-<num>.md       # area-scoped issues
      vibes/VB-<num>.md

Every entity is one Markdown file: the YAML frontmatter holds the fields, the body holds the long text (## Description, and for tasks an append-only ## Work Log). Relations are stored as entity numbers and slugs, so the files stay readable and diff cleanly in git.

The CLI is the only writer. Editing these files by hand (or letting an agent do it) bypasses validation and the counters — always go through orbitmap commands.

Current limitations

Local mode is a proof of concept. Not supported yet:

• No import/export between a local workspace and the cloud (planned next; entity-number format and response shapes are already identical so the future import is a data copy).
• No orbits — orbit * commands fail with NOT_SUPPORTED_IN_LOCAL_MODE and exit 1.
• No document section-patching, sharing or presigned uploads — doc-patch, doc-share, doc-unshare, doc-visibility fail the same way. docs, doc, doc-import and doc-update work.
• No OAuth (login / logout) — meaningless without a server.
• No human team members: exactly one implicit user (me) and one implicit agent (local-agent). members returns them; assign accepts only them.
• No sync or merge between machines — you may sync the workspace directory with git yourself, the CLI does not mediate conflicts.

See docs/architecture.md for the adapter split and docs/adr/0001-local-mode.md for why local storage exists at all.

Object model

OrbitMap organises work on several levels. The CLI mirrors them 1:1:

| Level | Prefix | What it is | |-------|--------|-----------| | Workspace | — | Top-level container that owns areas, orbits, intents and missions | | Area | — | A single product/repo/domain (formerly called project) — the default scope of most commands | | Orbit | — | Cross-area grouping of work (a theme, an initiative); items of any type can be attached | | Intent | IN- | A desired outcome at workspace level; tasks and issues can be linked to it | | Mission | MS- | A time-boxed workspace focus; only one mission can be active | | Task | TS- | The unit of work agents execute | | Issue | IS- | A reported problem | | Idea | ID- | A future possibility | | Vibe | VB- | Ad-hoc work context outside the task lifecycle |

Project → Area rename. What used to be called a project is now an area. The global flag is --area, the env var is ORBITMAP_AREA, and the config key is area. The legacy ORBITMAP_PROJECT_ID env var and project_id config key were read-only fallbacks for one release and were removed by ADR 0002 — they had the same cross-project leak as the machine-wide area they aliased. Set area in your project's .orbitmap/config.json instead.

Commands

Task Management

| Command | Description | |---------|-------------| | orbitmap tasks | List your assigned tasks (--status, --priority, --orbit) | | orbitmap task <id-or-number> | Show full task details | | orbitmap start [id-or-number] | Start working on a task (auto-picks next TODO if no ID) | | orbitmap status <id-or-number> <status> | Update task status (--force to move a parent to done with unfinished subtasks) | | orbitmap create <title> | Create a new task (--from-issue, --intent, --orbit) | | orbitmap subtask <parent-id-or-number> <title> | Create a subtask | | orbitmap assign <id-or-number> [agent-id] | Assign a task, issue, idea, or intent to an agent or user | | orbitmap get <prefixed-id> | Show any object by prefixed ID (TS-, IS-, ID-, VB-, IN-, MS-) | | orbitmap dep add <id-or-number> <target-id-or-number> | Add a dependency between tasks | | orbitmap dep remove <id-or-number> <target-id-or-number> | Remove a dependency | | orbitmap task-edit-content <id-or-number> | Edit task title, description, or agent instructions |

Valid statuses: backlog, todo, in_progress, in_review, review_changes, done, blocked

Referring to objects: <id-or-number>

Every command that takes an object reference accepts all three forms interchangeably:

• the prefixed display ID the CLI prints — TS-uw9yh5, IS-4k2p9q, IN-6htga8
• the bare 6-character code — uw9yh5
• the UUID

You can therefore paste any identifier straight out of orbitmap tasks, orbitmap context or the message orbitmap create prints. This was previously true of orbitmap task and orbitmap get only: status, log, subtask, start, assign, task-edit-content and dep add/dep remove rejected prefixed IDs with a 404, including identifiers the CLI had just printed itself.

The Agent API resolves a prefixed ID inline for issues, ideas, intents and missions, but not for tasks — a task reference that is not a UUID needs a /tasks/by-number/{n} lookup first. The CLI now does that once, in the adapter layer, so every task command behaves the same and a UUID still costs exactly one request. See src/id-resolve.ts.

assign auto-detects the object type from the prefix (IS-… → issue, IN-… → intent, …); pass --type task|issue|idea|intent for bare UUIDs and bare codes.

Work Logging

| Command | Description | |---------|-------------| | orbitmap log <id-or-number> <message> | Log work on a task, intent or mission |

The target follows from the reference: TS-… writes against the task, IN-… against the intent, MS-… against the mission. A bare UUID or bare code means a task unless --target says otherwise.

Options:

• --type <type> — Log type: note (default), code_change, decision, blocker. For discovery, exploration and fix use orbitmap vibe log — those are vibe types, not work-log types. status_change is written by the server on a status change and cannot be authored by a client.
• --target <kind> — Which object a bare UUID names: task (default), intent, mission
• --meta <json> — JSON metadata, e.g. '{"files":["src/app.ts"]}'

Examples:

orbitmap log abc123 "Implemented user auth endpoint" --type code_change
orbitmap log abc123 "Using JWT over sessions for stateless auth" --type decision
orbitmap log abc123 "Blocked on missing API credentials" --type blocker
orbitmap log IN-a1b2c3 "Chose 3 FKs + a CHECK over a polymorphic target" --type decision
orbitmap log MS-a1b2c3 "Mission scope trimmed to the two gating intents" --type note

Work log entries on a status change

intent update, mission update and mission status take a repeatable --log <type>:<content>, sent as one batch with the update. The content is split on the FIRST colon only, so it may contain colons of its own.

orbitmap intent update IN-a1b2c3 --status plan \
  --log decision:"chose 3 FKs + CHECK" \
  --log note:"resume: CLI next"

The API requires at least one entry when the status changes and writes nothing at all when there is none — so a rejected transition is re-run with --log, not retried as-is.

Documents

| Command | Description | |---------|-------------| | orbitmap docs | List area documents | | orbitmap doc <id-or-slug> | Show document (TOC by default, --full, --section) | | orbitmap doc-import <title> | Import a markdown file (--context to set when-to-use hint) | | orbitmap doc-update <id-or-slug> | Replace a document from a file | | orbitmap doc-patch <id-or-slug> | Patch a document with section operations | | orbitmap doc-share <doc-id> <area-id> | Share a document with another area | | orbitmap doc-unshare <doc-id> <area-id> | Remove document sharing | | orbitmap doc-visibility <doc-id> <area-id> | Restrict a share to specific agents (or allow all) | | orbitmap docs pull [slug] | Download document(s) to local cache | | orbitmap docs list-cache | Show locally cached documents | | orbitmap docs clean | Remove stale cached documents |

Examples:

# List all API docs
orbitmap docs --type api

# Search documents by title
orbitmap docs --search "auth"

# Read cheaply: TOC → one section → full content
orbitmap doc api-specification
orbitmap doc api-specification --section "## Authentication"
orbitmap doc api-specification --full

# Import a new document
orbitmap doc-import "API Spec" --type api --file ./docs/api-spec.md

# Update existing document
orbitmap doc-update api-specification --file ./docs/api-spec.md --changelog "Added auth section"

# Patch a single section (optimistic locking via --base-version)
orbitmap doc-patch api-specification --base-version 7 \
  --replace-section "## Authentication" --content "Bearer tokens only." \
  --changelog "Reworded auth"

# Share with another area
orbitmap doc-share <doc-uuid> <area-uuid> --agents agent1-uuid,agent2-uuid

Area & Agent Info

| Command | Description | |---------|-------------| | orbitmap context | Show agent identity and current area | | orbitmap areas | List all areas assigned to this agent | | orbitmap create-area <name> | Create a new area (--desc, --slug, --workspace-id) | | orbitmap members <area-id> | List agents and users in an area (accepts slug) | | orbitmap overview [area-id] | Area overview with task statistics (uses default area) |

Issues, Ideas & Vibes

| Command | Description | |---------|-------------| | orbitmap issues | List open issues | | orbitmap issue show <id> | Show issue details (UUID or number) | | orbitmap issue register | Register a new issue (--intent to link it to an intent) | | orbitmap issue status <id> <status> | Update issue status | | orbitmap issue resolve <id> | Resolve an issue | | orbitmap ideas | List ideas | | orbitmap idea add | Add a new idea | | orbitmap idea show <id> | Show idea details (UUID or number) | | orbitmap idea status <id> | Update idea status | | orbitmap vibes | List vibes | | orbitmap vibe log | Log a new vibe | | orbitmap vibe show <id> | Show vibe details | | orbitmap vibe update <id> | Update a vibe |

Intents

Workspace-level desired outcomes. Tasks and issues hang off an intent; an intent can sit in an orbit.

| Command | Description | |---------|-------------| | orbitmap intents | List intents (shortcut for intent list) | | orbitmap intent show <id-or-number> | Show an intent (UUID or IN-xxxxxx) | | orbitmap intent create <title> | Create an intent (--outcome, --design, --plan, --status, --orbit) | | orbitmap intent update <id> | Update title, outcome, design, plan, or status (--log <type>:<content>, repeatable) | | orbitmap intent link <id> --type task\|issue --id <uuid> | Link a task or issue | | orbitmap intent unlink <id> --type task\|issue --id <uuid> | Unlink a task or issue | | orbitmap intent orbit <id> [orbit-id] | Set the intent's orbit (--clear to remove) |

Statuses: new, design, plan, build, done, cancelled

orbitmap intent create "Cut onboarding time in half" \
  --outcome "New users reach first value in under 5 minutes" \
  --design "Two-step wizard replacing the current five-step form." \
  --plan "Phase 1: wizard skeleton. Phase 2: inline validation." \
  --status design --orbit growth-q3

orbitmap intent link IN-a1b2c3 --type task --id <task-uuid>

# A status change carries its reason — the API rejects it (422) without at least one entry.
orbitmap intent update IN-a1b2c3 --status plan \
  --log decision:"chose 3 FKs + CHECK" \
  --log note:"resume: CLI next"

intent create --orbit is create-then-attach. If the attach step fails the intent is still created — the CLI reports the failure and does not retry.

Missions

Time-boxed workspace focus. Only one mission can be active at a time.

| Command | Description | |---------|-------------| | orbitmap missions | List missions (shortcut for mission list) | | orbitmap mission show <id-or-number> | Show a mission (UUID or MS-xxxxxx) | | orbitmap mission create <title> | Create a mission (--desc, --outcome, --end-date) | | orbitmap mission update <id> | Update title, description, outcome, or end date (--log <type>:<content>, repeatable) | | orbitmap mission status <id> <status> | Set lifecycle status (--move-to to relocate unfinished work; --log required by the API) | | orbitmap mission link <id> --type <t> --id <uuid> | Link a task, issue, idea, or intent | | orbitmap mission unlink <id> --type <t> --id <uuid> | Unlink a directly-linked item |

Statuses: created as new; then active, completed, cancelled.

orbitmap mission create "Ship v2 beta" --outcome "Beta live for 50 customers" --end-date 2026-09-30
orbitmap mission status MS-a1b2c3 active
orbitmap mission status MS-a1b2c3 completed --move-to MS-d4e5f6

Linking a task or issue to a mission clears its intent_id — an item belongs either to an intent or directly to a mission.

Orbits

| Command | Description | |---------|-------------| | orbitmap orbit list | List orbits (workspace-scoped from the area context, --workspace) | | orbitmap orbit show <id-or-slug> | Show orbit details (areas, task counts, resources) | | orbitmap orbit create <name> | Create an orbit (--desc, --color, --areas) | | orbitmap orbit update <id-or-slug> | Update name, description, status, or color | | orbitmap orbit items <id-or-slug> | List items in an orbit (--type) | | orbitmap orbit attach <id-or-slug> | Attach an object to an orbit | | orbitmap orbit detach <id-or-slug> | Detach an object from an orbit | | orbitmap orbit area link <id-or-slug> <area-id> | Link an area to an orbit | | orbitmap orbit area unlink <id-or-slug> <area-id> | Unlink an area from an orbit | | orbitmap orbit dep <id-or-slug> <target-orbit-id> | Add an orbit-to-orbit dependency |

Item types: task, issue, vibe, idea, document Orbit statuses: active, completed, archived

orbitmap orbit create "Growth Q3" --color "#5B8DEF" --areas <area-uuid>,<area-uuid>
orbitmap orbit attach growth-q3 --type task --id <task-uuid> --note "core flow"
orbitmap orbit items growth-q3 --type task

There is no orbit delete and no dependency remove in the API — archive via orbit update --status archived.

Delivery Status

Track code delivery lifecycle on tasks:

orbitmap status abc123 done --delivery on_branch
orbitmap status abc123 done --delivery merged
orbitmap status abc123 done --delivery released

Setup helpers

| Command | Description | |---------|-------------| | orbitmap init | Full setup — mode, then the workspace + its area directories (cloud) or a local workspace, then .mcp.json and the agent skills (--key, --workspace-id, --area, --profile, --allow-nested, --advanced, --global; --local, --workspace, --workspace-name; --agent <type>, --no-skills) | | orbitmap login / orbitmap logout | Browser-based OAuth login / token revocation | | orbitmap setup-agent | Refresh the installed instructions (after a CLI upgrade) or add another agent type — init installs them once already | | orbitmap setup-mcp | Write/merge an orbitmap entry into .mcp.json (no API calls) |

Global Options

| Option | Description | |--------|-------------| | --json | Output raw JSON (for scripting/piping) | | --area <id> | Override area context (UUID or slug) | | --workspace <path> | Override the local workspace directory (local mode only) |

Configuration

See docs/adr/0002-project-scoped-config.md for the full design and rationale (this replaced a single global config file — breaking for scripted init callers that relied on that, see the ADR's Consequences section).

Setup

Run npx orbitmap init for interactive setup. Cloud setup is workspace-first: the key is validated with GET /areas, you pick the workspace (--workspace-id in a script), and init works out which directory holds which area — by directory name, by the origin git remote matched against the area's repository URL, by the slugified name, or by asking. It writes <root>/.orbitmap/config.json (committable, no secrets) by default; pass --global to write ~/.orbitmap/config.json instead (a machine-wide default, like git config --global). The API key always goes to ~/.orbitmap/credentials.json, under a named agent profile — never into a config file, either way. Re-running init merges, so running it inside a newly cloned area adds that area to the workspace map that already exists above it.

Project config file — <project>/.orbitmap/config.json

{
  "schema_version": 1,
  "mode": "cloud",
  "agent": "orbitmap-app-bot",
  "workspace": "my-workspace",
  "areas": { "orbitmap-cli": "orbitmap-cli", "packages/api": "api" }
}

mode is "cloud" (the default when the key is absent) or "local". agent names a profile in ~/.orbitmap/credentials.json — the project says which agent to use, the credentials file (below) holds that agent's key. workspace is a workspace slug or UUID, never a path. areas maps directories (relative to this file's parent; "." is that directory) to area slugs, which is how one root can hold several areas; each mapped subdirectory also gets a marker config of its own holding nothing but {"area": "<slug>"}. The older single area field is still read for back-compat. This file is meant to be committed: a team shares the workspace, the agent name and the area layout through version control, and each member's own copy of credentials.json supplies their own agent's key. Areas living outside the tree cannot be expressed portably, so they go to the gitignored <root>/.orbitmap/link.json instead ("areas": { "<slug>": "/abs/path" }).

Global config file — ~/.orbitmap/config.json

Same shape, used as the fallback for any field a project's own config doesn't set, and as the only place workspace_path (the default local workspace directory) is read from. Only written by orbitmap init --global, or left over from before ADR 0002 — in which case a lingering area is still honoured but prints a one-time deprecation warning telling you to move it into a project's own .orbitmap/config.json.

Credentials file — ~/.orbitmap/credentials.json

Never committed, never leaves the machine. Also holds the OAuth session used by orbitmap login/orbitmap logout (unrelated top-level fields, unchanged shape):

{
  "agents": {
    "orbitmap-app-bot": { "api_key": "orbitmap_..." },
    "orbitmap-cli-bot": { "api_key": "orbitmap_..." }
  }
}

An agent name that resolves to nothing here (nothing named agent anywhere, including the global config) falls back to the "default" profile — which is also where a pre-ADR-0002 global api_key is migrated to. That migration runs inside loadConfig(), i.e. on the first command of any kind after upgrading, not only on orbitmap init; it rewrites ~/.orbitmap/config.json without the key (preserving every other key in the file) and prints a one-time notice. If the write fails — read-only $HOME, a credentials.json owned by another user — it says so and keeps using the key from the config file, so the CLI never locks you out over a key that is right there on disk.

~/.orbitmap itself can be relocated with ORBITMAP_CONFIG_HOME or the standard XDG_CONFIG_HOME (as $XDG_CONFIG_HOME/orbitmap); reads fall back to the legacy ~/.orbitmap location when the new one has nothing yet.

Environment Variables

Environment variables take precedence over every config file:

| Variable | Description | |----------|-------------| | ORBITMAP_API_KEY | Agent API key (bypasses agent-profile lookup entirely) | | ORBITMAP_API_URL | API base URL — the only remaining override; there is no config-file equivalent any more (see the ADR) | | ORBITMAP_AGENT | Name of the agent profile in credentials.json to use | | ORBITMAP_AREA | Area UUID or slug | | ORBITMAP_MODE | cloud or local — overrides the config mode | | ORBITMAP_WORKSPACE | Local workspace directory (local mode) | | ORBITMAP_CONFIG_HOME / XDG_CONFIG_HOME | Relocate ~/.orbitmap |

Resolution Priority

Area (first match wins):

1. Explicit --area flag
2. ORBITMAP_AREA env
3. .orbitmap/link.json (area) found by walking up from the current directory — local mode
4. Nearest .orbitmap/config.json that sets area, found the same way. Resolution is per field: a packages/api/.orbitmap/config.json that sets only agent does not hide an area pinned by the repository root
5. default_area in the workspace's workspace.yml — local mode; written by orbitmap init for the first area, so a workspace outranks the machine-wide default of an unrelated project
6. Global config area (deprecated — prints a warning when hit)
7. Defaults (local mode: the only area in the workspace, when there is exactly one)

Agent / API key (first match wins):

1. ORBITMAP_API_KEY env — used directly, no profile lookup
2. Otherwise resolve an agent name (ORBITMAP_AGENT env → nearest .orbitmap/config.json that sets agent → global config agent → "default") and look up its key in credentials.json

Mode (first match wins): --workspace (explicit → local) → ORBITMAP_MODE → nearest .orbitmap/config.json that sets mode → local auto-detect (.orbitmap/workspace.yml or .orbitmap/link.json found by walking up) → mode in the global config, defaulting to cloud.

Workspace directory (local mode, first match wins): --workspace → ORBITMAP_WORKSPACE → .orbitmap/link.json (workspace) → nearest .orbitmap/workspace.yml → the .orbitmap/ directory of the nearest config that sets mode: "local", when it is itself a workspace → workspace_path in the global config, which must be an absolute path (a relative one would mean a different directory in every project, so it is ignored with a warning).

Authentication

In cloud mode, OrbitMap CLI uses a single Agent API Key for authentication (Authorization: Bearer header). Local mode has no authentication at all — access to the workspace directory is the only credential. Each agent has its own key, named by an agent profile in ~/.orbitmap/credentials.json — get the key itself from the OrbitMap dashboard. Area context travels in the X-Orbitmap-Area header.

Optionally, set a default Area ID if your agent is assigned to multiple areas.

Error handling

API errors are printed as Error [CODE] (status): message. Alongside the regular envelope, the client normalises the flat billing/usage shape returned by 402/429 responses into:

| Code | When | |------|------| | PAYMENT_REQUIRED | HTTP 402 — billing action needed | | RATE_LIMITED | HTTP 429 — too many requests | | USAGE_LIMIT | Other flat-error responses | | TIMEOUT | No response within 30s |

For AI Agents

orbitmap init already teaches your agent about OrbitMap — the skills are its last step, in both cloud and local mode, and it creates the agent config file when the directory has none:

npx orbitmap init --agent claude   # or let it detect / ask; --no-skills opts out

setup-agent does the same install on its own, for the two cases init does not cover: refreshing the content after upgrading the CLI, and adding a second agent type to a directory that is already set up.

npx orbitmap setup-agent          # auto-detects your agent
npx orbitmap setup-agent --agent claude

Where it installs: --scope user (global) vs --scope project

Run interactively, both commands ask where the skills should go — global (your home directory) or project (this directory only) — right after the agent-type question. Global is recommended and is what Enter picks; --scope skips the question; a scripted run takes global without prompting and says so in its output.

Global (user) scope means ~/.claude/skills/ and ~/.claude/CLAUDE.md for Claude Code, ~/.gemini/GEMINI.md and ~/.codex/AGENTS.md for Gemini and Codex. Agent skills do not traverse directories: a project-level .claude/skills/ is invisible to a session started in a sibling or child repository, while CLAUDE.md is inherited downwards. A user-scope install is the only one that is consistent everywhere — and it matters now that one workspace routinely spans several area directories, where a single project install would cover just one.

A user-scope install writes nothing into your project directory.

npx orbitmap setup-agent --scope project   # this directory only (the old behaviour)
npx orbitmap init --agent claude --scope project

At project scope the hook says so explicitly, so an agent that inherits CLAUDE.md from a parent directory but cannot load the skills knows why, and knows to re-run with --scope user.

Upgrading from an older setup? If you already have skills in ./.claude/skills/, that project copy silently wins in this directory. A user-scope install detects it and names the paths; it offers to clean up when run interactively, and otherwise tells you to run:

npx orbitmap setup-agent --agent claude --scope user --clean-project

Cleanup removes only the six OrbitMap skill directories and OrbitMap's own marker block — never your own skills, never unrelated CLAUDE.md content, never a whole .claude directory.

Either way it installs two layers, mirroring the OrbitMap MCP server:

• A thin always-on hook (~10 lines) in your agent config (CLAUDE.md, AGENTS.md, …) so the agent always knows the project uses OrbitMap and knows the workflow skeleton.
• The deep, on-demand instructions — full parity with the MCP full profile (plus orbitmap-brainstorm and orbitmap-design, CLI-native, no MCP counterpart). For Claude Code these are installed as loaded-on-demand skills (orbitmap, orbitmap-execute, orbitmap-plan, orbitmap-brainstorm, orbitmap-design, orbitmap-docs, zero per-turn context cost) under ~/.claude/skills/ (or ./.claude/skills/ at project scope); for other agents they're inlined as a markdown fallback.

A skill is not always a single file: orbitmap-execute ships SKILL.md plus references/worker-contract.md (the rules a dispatched worker subagent follows). init and setup-agent install every file a skill carries, and refresh them all on a re-run.

The instructions are mode-agnostic: they reference CLI commands only, so the same skills drive an agent whether the data goes to the cloud or to local files.

Executing work: two flows

The installed orbitmap-execute skill covers two ways of working, chosen by what you ask for:

• "work on TS-x" runs a single tracked task — start or resume it, implement, log, and finish with the correct status (in_review by default, so a human verifies before closing).
• "execute IN-x" delivers a whole planned intent in the background: tasks are built by parallel workers in dependency-ordered waves, each task gated by its own tests, then the intent-level test and an impact pass diffed against a test baseline captured before the run, with a goal-based fix loop (no retry cap) until the gates are green. A stuck task ends blocked with a logged blocker while the rest of the intent completes. The run ends with every completed task in_review on an intent/<number>-<slug> branch — merging is left to you: the run never merges and never pushes to the default branch.

See Agent Instructions for details.

Requirements

• Node.js 18+

License

MIT