Getting started

The first run has three steps: complete onboarding in the app, connect the folder with your code, then start a conversation with your agent. Onboarding creates the workspace and agent identity once; init connects local files to that workspace.

1. Complete onboarding in the app

Sign up or accept your invitation and follow the onboarding flow until Orbitmap asks you to connect your machine. Choose a workspace name and copy the agent API key shown there. Leave the page open: it waits for the connection. To find the key again later, see Setup and troubleshooting.

2. Connect the code with init

No global install is needed; Node.js 18 or newer is enough:

npx orbitmap init

To open a terminal in the right folder:

• Mac: In Finder, right-click the folder → Services → New Terminal at Folder.
• Windows: Open the folder, click the address bar, type cmd and press Enter — a terminal opens in that folder.

If the terminal says "command not found: npx", see Setup and troubleshooting.

What the first run connects depends on the folder:

• A repository you cloned (git clone …), the standard path: one area named after the repository.
• A folder holding several repositories: one area per repository.
• A downloaded folder without git: the folder itself is one area.
• A subfolder of a repository: init offers to connect the repository instead.
• An empty folder in a new account: a demo playground, a mission with three intents for your agent to build. The terminal prints Demo ready: ….

init asks for the key from onboarding and which workspace the folder belongs to, then prepares both Claude Code and Codex to use Orbitmap. It lists the local changes before you confirm. Your source code stays on your machine.

When it succeeds, the onboarding card changes to Connected and may list the areas created. The agent uses this same connection; there is no second registration step.

A second project

Run npx orbitmap init in the new folder. With one key saved on this computer, it asks Agent API Key (Enter = use the saved key of …): press Enter and init reuses that key, or paste another. With several, it lists each as <agent> (all workspaces · <first workspace>) or <agent> (workspaces: a, b +N); type a number, or press Enter to paste a new key. A scripted npx orbitmap init --key <key> never reuses a saved key.

New workspace or an existing one

init then asks which workspace the project is part of: Create a new workspace or Use existing: <name>. Creating one is the default for a folder outside your connected workspaces, and it needs a name you type. Nothing is created until you confirm.

3. Start with Claude Code or Codex

init ends with a Next: block that names the command for this folder:

cd "<folder>" && claude "what should we build first?"

On Windows, run the two commands one after the other.

With Codex, run codex "what should we build first?" in the same folder.

Prefer a desktop app? Setup still runs once in a terminal. After that, open the same folder in the Claude app's Code tab, or in Codex in the ChatGPT app, and ask the same question. The skills and the connection are the same as in the terminal.

The agent reads the repository and its Orbitmap instructions, then proposes a few starting points. Choose one and answer its questions about the outcome. In the app you land on the Missions view after login; it shows the mission or intent as soon as the agent creates it. To skip the first conversation, choose Skip for now in onboarding.

When setup needs attention

Running init again is safe: it updates the existing connection and refreshes the instructions rather than creating a second one. For a wrong mapping, a lost key or removing the local setup, see Setup and troubleshooting.