# 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:

```bash
npx orbitmap init
```

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

```bash
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](/docs/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

```terminal
❯ 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:

```terminal
  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:

```terminal
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:

```terminal
  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

| File | What it holds |
|---|---|
| `.orbitmap/config.json` | The workspace connection: which workspace this folder belongs to, which agent profile to use, and which subfolder is which area. No secret. **Commit it.** |
| `<area>/.orbitmap/config.json` | A small marker in each area's folder naming its area. Not written when the root folder is itself the area. |
| `.gitignore` | Two lines added: `.orbitmap/docs/` (a local cache of your workspace's documents) and `.orbitmap/link.json` (paths that only make sense on this machine). |
| `.claude/settings.json` | Claude Code only. Lets your agent run `orbitmap` commands without asking you each time, through the permission entry `Bash(orbitmap *)`. |

### On your machine

| File | What it holds |
|---|---|
| `~/.orbitmap/credentials.json` | Your agent's API key, stored under the agent's name. It never goes into a file in your repository. |
| `~/.claude/skills/orbitmap*` or `~/.codex/skills/orbitmap*` | The six OrbitMap skills, one folder each. |
| `~/.claude/CLAUDE.md` or `~/.codex/AGENTS.md` | A short OrbitMap block, 17 lines, added to the file or created with it. |
| `~/.claude/settings.json` or `~/.codex/hooks.json` | A hook entry that passes OrbitMap's instructions from command output back to your agent. |

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:

```markdown
<!-- 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:

```terminal
✓ 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](/docs/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](/docs/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](/docs/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:

```bash
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:

```bash
orbitmap uninstall
```

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

```terminal
  [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.