Getting started

After you sign up, OrbitMap walks you through four steps: Welcome, Agent, Connect and First mission. The progress bar at the top of the card shows where you are. This page follows the same steps, so you can keep it open next to the app.

You need a terminal on the machine where your code lives, Node.js, and Claude Code or Codex installed there.

1. Welcome

The first screen says Welcome to OrbitMap. Click Get Started.

If a teammate invited you into an existing workspace, the screen says Set Up Your AI Agent instead. The steps that follow are the same, except that you do not name a workspace.

2. Agent

On Customize Your Agent you give your AI agent its identity in OrbitMap. This is the name your agent works under in OrbitMap.

Avatar: click Choose file to upload an image, or skip it.
Avatar Color: pick one of the colour swatches. Without an image, the avatar shows the first two characters of the name, in capitals, on this colour.
Agent Name: pre-filled, for example Anna's Agent. Change it if you like.
Slug: filled in from the name as you type, for example my-ai-agent. You can edit it.

Click Continue.

3. Connect

Connect your machine: one command sets everything up, and your agent does the rest.

Name your workspace

Fill in Workspace name, for example your company or team name. A workspace is where your team's work lives, every repository, task and decision, in one place. One per team is usual; you can add more later.

Run the command where your code lives

Under Run it where your code lives, the app shows one command:

npx orbitmap init

Where you run it decides what gets connected:

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

Paste your agent's API key

The card Your agent's API key is marked Shown once. Click Show or Copy. The command asks for the key and hides what you type, so the key never appears in the command itself. If you lose it, you can regenerate it in Settings at any time.

init then asks a few more questions and writes its files. Install and init explains each question, every file it writes, and how to remove it all with orbitmap uninstall.

Wait for the connection

While the command runs, the app shows Waiting for your machine to connect…. Once your machine checks in, the line changes to Connected and lists the areas it created, for example Connected · 2 areas created: api, web. Click Continue.

The Common questions at the bottom of the step answer what the command changes on your machine, how to remove it, what your agent will do once connected, and whether your code is safe. In short: OrbitMap never sees your code. init looks at the folder locally and sends one thing upstream, whether it found enough to work from.

4. First mission

The last step shows what init built: your Workspace, its Areas, and your Agent marked as connected. Under Start your agent with the question, pick Claude Code or Codex and copy the command. Run it in the same folder where you ran init:

claude "what should we build first?"

With Codex, the command is codex "what should we build first?".

What happens next depends on what init found in the folder.

A real repository

The heading reads Your workspace is connected. Your agent reads the repository and its CLAUDE.md, tells you what it found, and offers two or three intents worth building. Nothing is created until you pick one. A first session looks like this:

terminal

❯ claude "what should we build first?"

I read the repository and CLAUDE.md. This is a booking API with a
React front end; the README lists email reminders as missing, and the
test suite does not cover cancellations yet.

Three intents worth building:

  1. Email reminders: a patient gets a reminder a day before the visit.
  2. Safe cancellations: cancelling a visit frees the slot and is covered by tests.
  3. Clinic calendar: staff see the whole day's bookings on one screen.

Which one should we start with? I recommend 2: it is small and makes
the next changes safer.

❯ Let's do 2.

Created the mission "First steps" and the intent "Safe cancellations".
Let's agree the outcome first. What should a patient see after
cancelling: a confirmation screen, an email, or both?

While you talk, the app shows Waiting for your first intent…. As soon as your agent creates it, the line changes to Your first mission: with the mission name and its number of intents (or Your first intent is in. if there is no mission yet), and Go to Missions view becomes active. Click it to follow the intent on the board.

An empty folder

If init found nothing to work from, and your workspace has no missions or intents yet, OrbitMap adds a demo to your workspace so you can see how building with OrbitMap works. The heading reads Let's build something: a demo area, a mission with three intents, and the documents that go with them. Your agent will build a tiny doctor-booking app on Node alone. Run the same command; your agent proposes working on the first intent and agrees its outcome with you. There is nothing to wait for: Go to Missions view is active right away and opens the demo mission on the board.

Not ready yet

Skip for now takes you straight to your workspace. You can start your agent with the question at any time later.

What next

Install and init: what init asks, what it writes, and how to undo it.
Missions: the focus your first intents belong to.