Install and init

The OrbitMap CLI connects a folder on your machine to your workspace and teaches your agent how to work with it. One command, orbitmap init, does the whole setup: it asks a few questions, shows you every file it is about to write, and writes nothing until you agree. This page walks through that command, what it leaves behind, and how to remove it.

Install the CLI

The CLI needs Node.js 18 or newer. You do not have to install it; run it straight from npm:

npx orbitmap init

If you would rather have the orbitmap command on your path, install it globally:

npm install -g orbitmap

After a global install, every command on this page works without the npx prefix, for example orbitmap init. Your agent calls the orbitmap command too; without a global install it runs it through npx orbitmap.

Where to run init

Run init where your code lives:

• One repository: run it inside that repository. The repository becomes one area.
• Several repositories: run it in the folder that contains them. That folder becomes your workspace root, and each repository becomes an area.

Workspaces and areas explains how folders map to a workspace in more detail.

What init asks

init asks its questions first and writes afterwards. You can press Enter at every question to take the default shown in brackets. Some questions appear only when there is something to choose.

1. Your agent's API key

❯ npx orbitmap init
OrbitMap CLI Setup

Agent API Key:

Validating credentials...

Paste the key that the app showed you on the Connect step of onboarding. The prompt hides what you type, so the key never shows up in your terminal or its history. If you no longer have the key, regenerate it in Settings in the app.

init checks the key with OrbitMap and reads the areas it can see. If the key is wrong, it stops here with Validation failed and writes nothing.

2. Which workspace

This question appears only when your key can see areas in more than one workspace. init lists each workspace with its areas and asks you to pick one by number. A brand-new account has one workspace, so you will not see it.

3. What this directory is

When your workspace already has areas, init asks what the current folder is:

  What is this directory?

  [1] A parent directory — the areas live in subdirectories here
      (2 matching subdirectories found)
  [2] One area's own directory
  [3] Neither — just record the workspace connection here

  Choice [1-3, Enter = 1]:

• A parent directory: the areas are in subfolders. init matches each area to a subfolder by its name or its git remote. For an area it cannot place, it asks for a path; press Enter to skip it.
• One area's own directory: this folder is a single area. init suggests which one it looks like and lets you pick.
• Neither: init only records the connection. Commands run at workspace scope until you map a folder later.

On a brand-new account there are no areas yet, so init skips this question. Instead it plans to create an area for each repository it finds: the current folder if it is a repository, otherwise each subfolder. Each new area is named after its folder and remembers the repository's git remote.

4. Which agent, and where its skills go

If the folder already has a CLAUDE.md or a .claude folder, init offers to install the OrbitMap skills for Claude Code and asks you to confirm with [Y/n]. Otherwise it asks which agent you use:

No coding agent config found in this directory.
OrbitMap can create one — the skills are what teach your agent the workflow.

Install the OrbitMap skills for:
  [1] Claude Code  (CLAUDE.md)
  [2] GPT Codex CLI  (AGENTS.md)
  [0] Skip — install later with `orbitmap setup-agent --agent <type>`

  Choice [0-2, Enter = 1]:

Then it asks where the skills should be installed:

• Global (the default): in your agent's own folder in your home directory, ~/.claude for Claude Code or ~/.codex for Codex. Every session and subagent can load them, whichever folder it starts in. This is the recommended choice, especially when your workspace spans several repositories.
• This directory only: only sessions started in this folder, or below it, can load them. Codex reads skills from ~/.codex only, so for Codex this choice puts the full instructions into ./AGENTS.md instead of installing skill files.

5. The confirmation

Last, init prints everything it is about to write, split into two lists, In this repository and On this machine. Each line starts with + for a new file or ~ for an edit to a file you already have. If it is about to create areas, it lists them too, with their git remotes. Then it asks once:

  Write them? [Y/n]

Press Enter to write. Any other answer cancels, and nothing is written, neither in the folder nor on your machine. Your workspace, areas and documents stay as they were.

What init writes

The confirmation lists the exact files for your folder and your answers. For the usual setup, Claude Code or Codex with the skills installed globally, it looks like this.

In this folder

On your machine

If you chose This directory only, the skills, the block and the Claude Code hook go into the current folder instead: .claude/skills/, CLAUDE.md or AGENTS.md, and .claude/settings.json.

For Codex, init writes the hook but two steps stay manual, and init prints them: enable hooks in ~/.codex/config.toml with [features] hooks = true, then approve the orbitmap emit-instructions hook inside Codex with /hooks.

The block in CLAUDE.md or AGENTS.md

The block sits between two marker comments, so init, setup-agent and uninstall can find it and leave the rest of your file alone:

<!-- ORBITMAP_START v0.15.0 -->
## OrbitMap

Work is tracked in OrbitMap via the `orbitmap` CLI. You work in a WORKSPACE, which can span
several repositories: each repo is an AREA, while missions, intents and documents belong to
the workspace itself, not to any one repo.
Load the OrbitMap skills whenever the user wants to build, add, change or fix something, in
whatever words they use — do not wait for OrbitMap vocabulary. Load them too when they talk
about tracking work (backlog, tasks, missions, intents, ideas, issues, documents, planning).
Load the core skill 'orbitmap' first, before any other orbitmap-* skill — they all build on it.
Nothing gets built before it is framed: a feature, component or behaviour change gets an intent
— outcome (brainstorm) → design → plan → build (execute), one gate at a time, written to the
intent as you go. Small self-contained work (a typo, an obvious one-file fix) is just a task.
NEVER finish a task, intent or mission without a final `orbitmap log` entry and a status update;
the final entry closes a record that already exists. Finished work defaults to `in_review`, not `done`.
OrbitMap tool responses may carry an Instructions section — act on it before continuing.
<!-- ORBITMAP_END -->

The block only tells your agent when to load the skills. The skills themselves load on demand, so they do not fill your agent's context in every session.

After the writes

init ends by reporting what it did and what to do next:

✓ Connected as My AI Agent on workspace Acme
Configuration saved to .orbitmap/config.json
API key saved to /home/you/.orbitmap/credentials.json (profile "my-ai-agent")

Area directories:
  api                      api  (created)
  web                      web  (created)
Marked api/.orbitmap/config.json → area api
Marked web/.orbitmap/config.json → area web
Added .orbitmap/docs/, .orbitmap/link.json to .gitignore.

Next: open your agent here — cd /home/you/code/acme && claude (or codex) — and ask: "what should we build first?"

Between the .gitignore line and the last line, init also lists each skill, block and hook it installed.

The six skills

The skills are what teach your agent the OrbitMap way of working. Each one is a folder with a SKILL.md file that your agent loads when the work calls for it.

• orbitmap: the entry point. How workspaces, areas, missions, intents and tasks fit together, and which command does what. Your agent loads it before any other OrbitMap skill.
• orbitmap-brainstorm: turns an idea into an agreed outcome, one question at a time, and writes it to the intent.
• orbitmap-design: turns the agreed outcome into an approach and a technical design.
• orbitmap-plan: breaks the design into tasks, each with its tests, and checks that together they cover the intent.
• orbitmap-execute: builds a planned intent, or works through a single task, and leaves the result in review for you.
• orbitmap-docs: reads and updates the documents in your workspace, such as specs, guides and decisions.

The intent flow shows how the brainstorm, design, plan and execute skills follow one another.

What init sends about your code

OrbitMap never sees your code. Before it finishes, init looks at the folder on your machine: whether there is a README, a CLAUDE.md, whether there are commits. It sends one thing upstream: a verdict on whether it found enough to work from. It does not send what it read.

When the verdict is that the folder is empty, OrbitMap prepares a demo workspace for you, and init prints a line that starts with Demo prepared:. Getting started describes what happens next.

Running init again

Running init again is safe. It merges into the existing .orbitmap/config.json instead of replacing it, rewrites the skills with the current version, and updates the OrbitMap block in place rather than adding a second one.

Run it again when:

• You clone another repository of the same workspace. Run init inside it; the new area joins the workspace config that already exists above it.
• A folder was skipped the first time. Run init inside that folder to map it to its area.
• You connect another machine. See Workspaces and areas.

If another workspace's root already sits above or below the current folder, init names it and asks before going on, because one folder holds one workspace.

Adding an agent or refreshing the skills

init installs the skills once. Use setup-agent when you want to change them later:

orbitmap setup-agent

It asks the same two questions as init, which agent and where, then writes the skills, the OrbitMap block and the hook again. It does not touch your workspace config or your API key. Use it to:

• Refresh the skills after upgrading the CLI. A new CLI version ships new skill text. If the installed block is older than your CLI, orbitmap context and init print a one-line reminder to run orbitmap setup-agent.
• Add a second agent, for example Codex next to Claude Code: orbitmap setup-agent --agent codex.
• Move the skills to the global install: orbitmap setup-agent --scope user.

--agent also accepts gemini, cursor, windsurf and generic. Those agents cannot load skills on demand, so they get the full instructions written into one file instead.

Removing OrbitMap

To undo everything init and setup-agent wrote, run:

orbitmap uninstall

It lists every file it would remove, in the same two halves as the confirmation of init, and asks once:

  [Enter] remove everything   [p] this repository only   [n] cancel

• Enter removes both halves: the .orbitmap/ folders and .gitignore lines in this folder, and ~/.orbitmap/, the skills, the OrbitMap block and the hook on your machine.
• p removes only this folder's files and keeps the install on your machine for your other folders.
• n cancels.

uninstall edits your files with care: it cuts only the OrbitMap block out of CLAUDE.md or AGENTS.md and only the OrbitMap entries out of settings.json, and deletes a file only when OrbitMap's part was all of it. To remove everything without the question, for example in a script, run orbitmap uninstall --all --yes.

Nothing on the server is touched. Your workspace, areas, missions, intents, tasks and documents stay in OrbitMap, and running init again reconnects to all of them. Your API key also stays valid until you regenerate it in Settings.