# Orbitmap Documentation

> Complete documentation for the Orbitmap agentic project management platform.

# Introduction

> Your agent's memory, across every session.

Orbitmap is an agentic project management platform that gives your AI coding agents persistent context - tasks, documents, decisions, and history - so they never start from scratch.

---

Orbitmap connects your AI coding agents (Claude Code, Cursor, Windsurf, Codex, Gemini) to a structured project management layer. Instead of losing context every time you start a new session, your agents read tasks, log decisions, track issues, and share documents - all through the MCP (Model Context Protocol) or CLI.

**What Orbitmap gives your agents:**

- **Persistent task memory** - agents pick up where they left off, reading prior logs and decisions
- **Structured documentation** - project specs, API docs, and guidelines available on demand
- **Issue and idea tracking** - bugs get reported and resolved in context, ideas get captured before they're forgotten
- **Work logging** - every code change, decision, and blocker is recorded for future sessions
- **Cross-session continuity** - agents resume work from task logs instead of re-exploring code

**Who is it for:**

- Solo developers using AI agents for coding
- Small teams (2–5 people) coordinating agent-assisted development
- Technical leads managing multiple agents across projects


---

# Quick Start

Get up and running in 5 steps.

## Step 1: Create an Account

Go to [orbitmap.ai](https://orbitmap.ai) and sign up.

## Step 2: Create Your First Project

After signing in, the onboarding wizard guides you through creating your first project. A project represents a codebase - an app, a service, a library, or a mobile version.

Give it a name and optional description. Orbitmap generates a slug (e.g., `my-saas-app`) used for MCP configuration.

## Step 3: Create Your AI Agent

Orbitmap automatically creates an agent for your user account. The agent gets a unique API key - this is shown only once during onboarding, so copy it immediately.

Your agent is the identity your AI tool uses to authenticate with Orbitmap. It can read tasks, log work, manage documents, and more.

## Step 4: Connect Your Tool via MCP

Add Orbitmap as an MCP server in your AI coding tool. The onboarding wizard shows the exact configuration for your setup.

**Claude Code** - add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "orbitmap": {
      "type": "http",
      "url": "https://mcp.orbitmap.ai",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-OrbitMap-Project": "your-project-slug"
      }
    }
  }
}
```

**Or run one command in your project directory:**

```bash
npx orbitmap setup-mcp --token YOUR_API_KEY --project your-project-slug
```

This writes the same MCP configuration to `.mcp.json` in the current directory (merging with an existing file). It's a shortcut for the manual JSON paste above — pick whichever you prefer.

> Using Codex CLI, Gemini CLI, Cursor, or another IDE? See the [Integration Guide](/docs/integration-guide) for setup instructions.

## Step 5: Start Working

That's it — your agent now has access to Orbitmap. Try it:

```terminal
~/my-project

❯ HAL, create a task: "Add password reset
  flow with email verification"

HAL: Creating task...
✓ create_task()

Task created:
TS-k2so77 - Add password reset flow with
email verification
Status: todo

Want me to start working on it now?
```


---

# Integration Guide

You'll see your agent's API key right after creating an agent account. You can always view it later in the **Members** tab of your project (click the key icon next to your agent) or in **Settings > Agents**. The project slug is available in **Project > Settings**. Pasting these two values into your configuration is the fastest way to get started. If you choose OAuth authorization instead, the keys will be saved automatically after you select your agent and project from the dropdown.

## MCP Overview

Orbitmap communicates with AI agents via the **Model Context Protocol (MCP)** - an open standard for connecting AI tools to external services. MCP provides your agent with 26 tools for managing tasks, documents, issues, ideas, vibes, orbits, and dependencies.

The MCP server runs at `https://mcp.orbitmap.ai` and accepts HTTP connections with bearer token authentication or OAuth.

### Claude Code (.mcp.json)

Claude Code reads MCP configuration from a `.mcp.json` file in your project root.

**With API Key (recommended for getting started):**

```json
{
  "mcpServers": {
    "orbitmap": {
      "type": "http",
      "url": "https://mcp.orbitmap.ai",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-OrbitMap-Project": "your-project-slug"
      }
    }
  }
}
```

**With OAuth (no API key needed):**

```json
{
  "mcpServers": {
    "orbitmap": {
      "type": "http",
      "url": "https://mcp.orbitmap.ai"
    }
  }
}
```

After adding the OAuth config, run `/mcp` in Claude Code to start the authorization flow. You'll select your agent and project during authorization.

> **Tip:** API key auth is simpler and faster. OAuth is useful when you don't want to store keys in files or when sharing configurations across teams.

#### CLI one-liner (alternative to manual JSON paste)

Instead of editing `.mcp.json` by hand, you can run a single command from your project directory. It writes the same configuration and merges it with an existing `.mcp.json` if one is present.

**With API Key:**

```bash
npx orbitmap setup-mcp --token YOUR_API_KEY --project your-project-slug
```

**With OAuth:**

```bash
npx orbitmap setup-mcp --oauth --project your-project-slug
```

**Optional flags:**

- `--profile lite` — install the Lite profile (developer workflow, 13 tools).
- `--profile manager` — install the Manager profile (project coordination, 22 tools).
- Default (no flag) — Full profile with all 26 tools.

The command uses the [`orbitmap`](https://github.com/BTA-Systems/orbitmap-cli) package from npm. It currently configures Claude Code's `.mcp.json` only — for Codex, Gemini, or IDE setups, follow the manual instructions below.

### Codex CLI (.codex/config.toml)

Codex CLI reads MCP configuration from a `.codex/config.toml` file in your project root.

**With API Key (recommended for getting started):**

Create or open `.codex/config.toml` in your project root and add:

```toml
[mcp_servers.orbitmap]
url = "https://mcp.orbitmap.ai/"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY", "X-OrbitMap-Project" = "your-project-slug" }
```

Then start Codex from your terminal:

```bash
codex
```

**With OAuth (no API key needed):**

Create or open `.codex/config.toml` in your project root and add:

```toml
[mcp_servers.orbitmap]
url = "https://mcp.orbitmap.ai/"
```

Then run the login command to authorize:

```bash
codex mcp login orbitmap
```

This opens a browser window where you select your agent and project, then authorize the connection. Once authorized, return to the terminal and start working:

```bash
codex
```

### Gemini CLI (~/.gemini/settings.json)

Gemini CLI reads MCP configuration from `~/.gemini/settings.json` (global) or `.gemini/settings.json` in your project root.

**With API Key (recommended for getting started):**

Add the Orbitmap server to your `settings.json`:

```json
{
  "mcpServers": {
    "orbitmap": {
      "httpUrl": "https://mcp.orbitmap.ai",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-OrbitMap-Project": "your-project-slug"
      }
    }
  }
}
```

Then start Gemini from your terminal:

```bash
gemini
```

**With OAuth (no API key needed):**

Gemini CLI supports Dynamic OAuth Discovery - it auto-detects OAuth requirements and discovers endpoints from server metadata without explicit configuration. The config is minimal:

```json
{
  "mcpServers": {
    "orbitmap": {
      "httpUrl": "https://mcp.orbitmap.ai"
    }
  }
}
```

When you run `gemini`, the CLI automatically detects that the server requires authorization, opens a browser window for the OAuth flow, and stores the token for future sessions. You'll select your agent and project during authorization.

### IDE Integration (Cursor / Windsurf)

In your IDE settings, add Orbitmap as an MCP server with these parameters:

```
Server URL: https://mcp.orbitmap.ai
Headers:
  Authorization: Bearer YOUR_API_KEY
  X-OrbitMap-Project: your-project-slug
```

Each IDE has its own MCP settings panel - consult your IDE documentation for the exact location. The values are the same across all IDEs.

### Claude.ai / Connectors (OAuth)

For Claude.ai web interface:

1. Go to **Settings → Customize → Connectors**
2. Click **Add Connector** and paste this URL: `https://mcp.orbitmap.ai/`
3. Follow the authorization flow - select your agent and project

### Authentication Methods

| Method | How it works | Best for |
|--------|-------------|----------|
| **API Key** | Bearer token in headers + project slug | CLI tools, quick setup, solo devs |
| **OAuth** | Browser-based authorization flow | Teams, shared configs, Claude.ai |

**API Key authentication** requires two headers:
- `Authorization: Bearer YOUR_API_KEY` - identifies your agent
- `X-OrbitMap-Project: your-project-slug` - scopes requests to a project

**OAuth authentication** handles both identity and project selection during the authorization flow. No headers needed in the config.

> **Security note:** API keys are shown only once during agent creation. Store them securely. You can regenerate a key in Settings → Agents, but the old key is immediately invalidated.

### MCP Modes

Orbitmap offers different MCP modes for different use cases:

| Mode | URL | Tools | Best for |
|------|-----|-------|----------|
| **Full** | `https://mcp.orbitmap.ai` | 26 | Everything - tasks, docs, issues, ideas, vibes, orbits, dependencies |
| **Lite** | `https://mcp.orbitmap.ai/lite` | 13 | Developer workflow - tasks, work logging, issues, docs, vibes |
| **Manager** | `https://mcp.orbitmap.ai/manager` | 22 | Project management - task planning, assignments, subtasks, docs, dependencies |

Use **Full** mode by default. Switch to **Lite** for agents focused purely on development work - executing tasks, logging progress, reading docs, and reporting issues without the overhead of planning and management tools. Use **Manager** for agents handling project coordination - creating and assigning tasks, managing dependencies, organizing ideas, and maintaining documentation.

## CLI Integration (Codex / Gemini)

If your AI tool doesn't support MCP or you prefer a simpler setup, you can use the Orbitmap CLI as an alternative.

```bash
npx orbitmap init \
  --key="YOUR_API_KEY" \
  --project="your-project-slug"
```

This saves your credentials to `~/.orbitmap/config.json`. After setup, agents can use `npx orbitmap` commands directly — no MCP needed.

> **Recommendation:** We recommend using MCP when possible. With MCP, the agent understands Orbitmap's workflow natively and can use tools contextually — the CLI requires explicit commands, which limits how well the agent can integrate Orbitmap into its reasoning.


---

# Working with Tasks

Tasks are the core unit of work in Orbitmap. Each task has a title, description, status, optional agent instructions, and a log of all work performed.

## Creating Tasks

Create tasks from the Orbitmap web UI or directly via your agent.

**Via agent:**

```terminal
~/my-project

❯ HAL, create a task: "Add password reset
  flow with email verification"

HAL: Creating task...
✓ create_task()

Task created:
TS-k2so77 - Add password reset flow with
email verification
Status: todo

Want me to start working on it now?
```

**Via web UI:** Navigate to your project → Tasks → click "New Task". Fill in the title, description, and optionally assign it to an agent and add agent instructions.

**Agent instructions** are special - they're read by your AI agent before starting work on the task. Use them to specify implementation details, constraints, or references the agent should follow.

## Executing Tasks

The agent workflow for executing tasks follows a structured lifecycle:

1. **Check for in-progress work** - the agent looks for tasks already started
2. **Start a task** - picks the first `todo` task, reads its context, sets status to `in_progress`
3. **Do the work** - implements code, reads docs, makes decisions
4. **Log everything** - records code changes, decisions, blockers
5. **Finish** - sets status to `in_review` (default) or `done`

**Starting a task:**

```terminal
~/my-project

❯ run task TS-r2d2, HAL

HAL: Starting task TS-r2d2...
✓ start_task(task_id='TS-r2d2')

Task: Set up authentication flow
Description: Implement login/register using
Supabase Auth with email+password.

Agent instructions:
- Use the SupabaseAuth middleware pattern
- Follow the existing Items module as
  reference for controller structure
- Include Form Request validation

Reading project docs for auth context...
✓ get_document(id='doc-auth-spec')

Starting implementation...
```

**Picking the next available task automatically:**

```terminal
~/my-project

❯ what's my next task, HAL?
  Pick it up and start working.

HAL: Checking your queue...
✓ get_tasks(status='in_progress') → empty
✓ start_task()

Started: TS-c3po42 - Add user profile page
Reading task context and logs...
```

## Reviewing and Closing Tasks

When the agent finishes work, it logs a summary and sets the status:

```terminal
~/my-project

❯ make a commit and close this task, HAL

HAL: Committing changes...
✓ git add app/Http/Controllers/...
✓ git commit -m "[TS-c3po42] Add user
  profile page with avatar upload"

Logging work summary...
✓ log_work(task_id, type='code_change',
  content='Added ProfileController,
  profile Livewire component, avatar
  upload with S3 storage')

Setting task to review...
✓ update_task_status(task_id, 'in_review',
  delivery_status='on_branch')

Task TS-c3po42 is ready for review.
Branch: feature/user-profile
```

**Task statuses:**

| Status | Meaning |
|--------|---------|
| `backlog` | Planned but not prioritized |
| `todo` | Ready to be picked up |
| `in_progress` | Currently being worked on |
| `in_review` | Work complete, awaiting human verification |
| `review_changes` | Reviewer requested changes |
| `done` | Verified and closed |
| `blocked` | Cannot proceed - external dependency |

## Checking Your Backlog

```terminal
~/my-project

❯ what do I have to do, HAL?

HAL: Checking your task queue...
✓ get_tasks(status='todo,in_progress')

In Progress:
• TS-r2d2x1 - Set up authentication flow

Todo:
• TS-c3po42 - Add user profile page
• TS-walle3 - Write API documentation

❯ check the backlog too, HAL

✓ get_tasks(status='backlog')

Backlog (5 tasks):
• TS-neo001 - Dark mode support
• TS-neo002 - Export to CSV
• TS-neo003 - Email notification prefs
• TS-neo004 - Admin dashboard widgets
• TS-neo005 - Mobile responsive fixes
```


---

# Project Documentation

Orbitmap stores and serves Markdown documents to your agents. Documents can be project-level (specific to one project) or workspace-level (shared across projects).

## Importing Documents

Upload documents to Orbitmap via the web UI or via your agent.

**Via agent:**

```terminal
~/my-project

❯ JARVIS, upload docs/api-spec.md to
  Orbitmap as "API Specification"

JARVIS: Importing document...
✓ import_document(title='API Specification',
  content=<file contents>)

Document imported: "API Specification"
ID: doc-7x8y9z
Sections: 12
```

**Via web UI:** Navigate to your project → Documents → click "New Document". Paste or upload your Markdown content.

## Sharing Documents

Documents can be shared across projects within your workspace.

**Via agent:**

```terminal
~/my-project

❯ JARVIS, share the API Specification with
  the mobile-app project

JARVIS: Sharing document...
✓ manage_document_sharing(doc_id,
  action='share',
  project_id='mobile-app')

"API Specification" is now shared with
project mobile-app.
```

## Reading Documents via Agent

Agents read documents efficiently using a tiered approach to minimize token usage:

1. **TOC first** - `get_document(id)` returns context + table of contents (~200 tokens)
2. **Section** - `get_document(id, section="## Auth")` returns just that section (~500 tokens)
3. **Full content** - `get_document(id, full=True)` downloads the complete document

```terminal
~/my-project

❯ check the docs on authentication, JARVIS

JARVIS: Reading project documentation...
✓ get_project_docs()
✓ get_document(id='doc-auth',
  section='## Authentication Flow')

From "Architecture Guide", section
"Authentication Flow":

The app uses Supabase Auth with email+
password. The SupabaseAuth middleware
validates JWT tokens on every request...

Want me to read the full document?
```

**Workspace-level documents:** When a task is started via `start_task()`, the response includes `workspace_knowledge` - documents shared at the workspace level. These contain cross-project guidelines, coding standards, or architectural decisions that apply to all projects.


---

# Bugs and Issues

Issues track bugs, errors, and problems discovered during development.

## Reporting Issues

```terminal
~/my-project

❯ Houston, register this issue: the login
  form throws a 500 error when the email
  field contains a plus sign

HOUSTON: Registering issue...
✓ register_issue(title='Login 500 error
  with plus sign in email',
  content='The login form returns a 500
  when email contains +. Likely a
  validation or encoding issue.')

Issue registered: IS-bug42z
Status: open
```

## Working on Issues

```terminal
~/my-project

❯ Houston, what issues do we have open?
  Pick up IS-bug42z and fix it.

HOUSTON: Checking issues...
✓ get_issues()

Open issues (3):
• IS-bug42z - Login 500 error with + in email
• IS-glitch7 - Avatar not loading on Safari
• IS-err99x - Timeout on large CSV export

Taking IS-bug42z...
✓ update_issue_status('IS-bug42z',
  'investigating')

Investigating the login form validation...
The email validation regex doesn't handle
the + character. Fixing now...
```

## Converting Issues to Tasks

When an issue requires structured work (multiple steps, agent instructions, tracking), convert it to a task:

```terminal
~/my-project

❯ Houston, make a task from issue IS-glitch7

HOUSTON: Reading issue details...
✓ get_issues(issue_id='IS-glitch7')

Creating task from issue...
✓ create_task(title='Fix avatar loading on
  Safari', description='Avatar images fail
  to load on Safari due to WebP format
  not being supported on older versions.
  Ref: IS-glitch7')

Task created: TS-fix7sa
Linked to issue: IS-glitch7
```


---

# Ideas

Ideas capture feature concepts, improvements, and future possibilities. They're not problems (use Issues for those) - they're opportunities.

## Capturing Ideas

```terminal
~/my-project

❯ store my idea in the Matrix project:
  "Add AI-powered search that understands
  natural language queries over project
  documents"

MORPHEUS: Logging idea...
✓ log_idea(title='AI-powered natural
  language search over docs',
  content='Implement semantic search that
  lets users query project documents in
  natural language instead of keyword
  matching.')

Idea saved: ID-search9
Status: new
```

## Analyzing and Converting Ideas

```terminal
~/my-project

❯ JARVIS, look at idea ID-search9, analyze
  the codebase and create a task for it

JARVIS: Reading idea...
✓ get_ideas(idea_id='ID-search9')

Analyzing codebase for search
implementation points...
Found: Document model, existing keyword
search in DocumentController, Supabase
pgvector extension available.

Creating task...
✓ create_task(title='Implement semantic
  search for project documents',
  description='Use pgvector + embeddings
  to enable NL queries. Build on existing
  DocumentController search. Ref: ID-search9
  ')
✓ update_idea_status('ID-search9', 'used')

Task created: TS-nlp42x
Idea ID-search9 marked as used.
```


---

# Work Logging

Orbitmap records two types of work logs: **task logs** (within a task) and **vibes** (ad-hoc work outside tasks).

## Task Logs

Every task accumulates a log of work entries. These are written by agents during task execution and serve as persistent memory for future sessions.

**Log types:**

| Type | Purpose |
|------|---------|
| `code_change` | What code was written or modified |
| `decision` | Why a particular approach was chosen |
| `note` | General observations, resume points |
| `blocker` | Something preventing progress |

```terminal
~/my-project

❯ HAL, log that we decided to use Redis
  for session caching instead of the
  database driver

HAL: Logging decision...
✓ log_work(task_id='TS-r2d2x1',
  type='decision',
  content='Chose Redis over DB session
  driver for caching - better performance
  under concurrent connections, and Laravel
  Cloud recommends it for production.')

Decision logged on TS-r2d2x1.
```

When an agent resumes a task, it reads all prior logs - so it immediately knows what was done, what was decided, and where work left off.

## Vibes - Ad-hoc Work Logs

Vibes capture work that happens outside the structured task system: exploration, discovery, quick fixes, experiments.

```terminal
~/my-project

❯ vibe log, stardate 2026.3: explored the
  Supabase Edge Functions as an alternative
  to Laravel queues for webhook processing.
  Promising but not mature enough yet.

DATA: Recording vibe...
✓ log_work(type='discovery',
  content='Explored Supabase Edge Functions
  for webhook processing. Promising
  alternative to Laravel queues but too
  immature - missing retry logic and DLQ.
  Revisit in Q3.')

Vibe recorded. Stardate 2026.3 logged.
```

**Vibe use cases:**
- Discovery sessions ("tried X, learned Y")
- Quick fixes not tied to any task
- Exploration of new tools or libraries
- Notes from debugging sessions


---

# Context Management

Orbitmap's core value is **persistent context**. Your agents don't start from scratch - they access the history of prior work, decisions, and documentation.

## Using Task History

When you reference a previous task, the agent loads its full context - logs, decisions, code changes, and status.

```terminal
~/my-project

❯ HAL, we need to change how the auth
  middleware works. You implemented it in
  task TS-r2d2x1 - check what you did.

HAL: Loading task context...
✓ get_tasks(task_id='TS-r2d2x1')

Task TS-r2d2x1 - Set up authentication flow
Status: done

Work logs (4 entries):
1. [code_change] Created SupabaseAuth
   middleware, AuthController, login/register
   views with Livewire components
2. [decision] Used JWT validation via
   firebase/php-jwt instead of Sanctum
3. [decision] Chose Redis session driver
4. [note] Ready for review - all auth tests
   pass

I see the original implementation. The
middleware validates JWT tokens using
firebase/php-jwt. What change do you need?
```

## Cross-entity Context

The same pattern works across all entity types - issues, vibes, documents, and ideas:

```terminal
~/my-project

❯ JARVIS, remember that vibe where we
  explored Edge Functions? Check the vibes
  from last week.

JARVIS: Searching vibes...
✓ get_vibes()

Found vibe from 2026-03-11:
"Explored Supabase Edge Functions for
webhook processing. Promising but too
immature - missing retry logic and DLQ."

❯ Also check issue IS-err99x, it might be
  related

✓ get_issues(issue_id='IS-err99x')

IS-err99x - Timeout on large CSV export
Status: open
These could be related - both involve async
processing bottlenecks...
```

## Token-Efficient Document Access

AI agents have limited context windows - every token counts. Orbitmap's document system is designed to minimize how much an agent needs to read before finding the right information.

Every document has a short **context** field (a few sentences) visible in document listings. This lets the agent decide which document is relevant *without opening it*. Once the right document is identified, the agent fetches only its **table of contents** (~200 tokens) - not the full content. From the TOC, the agent pinpoints the exact section it needs and fetches *just that section* (~500 tokens).

The result: an agent working with a 5,000-token document typically consumes only ~700 tokens - the context field, the TOC, and one section. The full document is never loaded unless explicitly needed.

This three-tier reading flow works like this:

```terminal
~/my-project

❯ CORTANA, how does our auth middleware
  validate tokens?

CORTANA: Let me find the right document...

✓ get_project_docs()
  → 8 documents found
  → "Architecture Guide" context says:
    "Covers auth, middleware, DB schema..."
  → This is the one.

✓ get_document('arch-guide')
  → TOC: 14 sections
  → "## Authentication Flow" looks right

✓ get_document('arch-guide',
  section='## Authentication Flow')
  → 480 tokens loaded (not 5,200)

The SupabaseAuth middleware validates JWT
tokens using firebase/php-jwt on every
request. Tokens are checked for expiry and
signature validity against the Supabase
JWT secret...
```

This approach has three key benefits:

- **Context window efficiency** - agents preserve their limited context for reasoning and code, not for reading documentation they don't need
- **Faster responses** - less data to process means the agent responds quicker
- **Scales with project size** - whether your project has 3 documents or 30, the agent's token cost stays roughly the same per lookup

The same efficiency applies to **editing** - agents can patch a single section without downloading or re-uploading the entire document.

For details on how documents are imported, shared, and read, see [Project Documentation](/docs/project-documentation).

## Orbit - Contextual Grouping

Orbits let you group related tasks, issues, ideas, and documents into a thematic collection. Think of an Orbit as a "feature area" or "initiative" that spans multiple entities.

For example, an Orbit called "Authentication Overhaul" might contain:
- 3 tasks (implement, test, document)
- 1 issue (the bug that triggered the overhaul)
- 2 documents (auth spec, migration guide)
- 1 idea (future SSO support)

Agents can query orbits to get the full picture of an initiative, including all related entities and their current state.


---

# Token Savings

> Less context burned, more context for reasoning.

AI coding agents operate within fixed context windows. Every token spent on loading instructions, reading documentation, or fetching task details is a token not available for reasoning and writing code. Orbitmap is designed from the ground up to minimize token overhead - so your agents spend their context budget on what matters.

---

## How Much Does Orbitmap MCP Cost?

Orbitmap connects to your agent via MCP (Model Context Protocol). Here's the actual token cost per conversation:

| What loads | Tokens | When |
|------------|--------|------|
| Server instructions + tool names | ~2,500 | Every conversation start |
| Each tool schema (on first use) | ~300–500 | Only when the agent calls that tool |
| Typical session (5–8 tools used) | ~4,500–6,000 | After active work |

That's **less than 3% of a 200K context window** even during intensive use.

### Deferred Tool Loading

Orbitmap doesn't dump all 26 tool definitions into your agent's context at once. Instead, it registers only tool **names** on startup (~225 tokens). Full schemas are loaded on-demand when the agent actually needs a specific tool.

This means:

- **Start of conversation**: ~2,500 tokens (instructions + names only)
- **After using 3 tools**: ~3,500 tokens (instructions + 3 schemas)
- **After context compression**: back to ~2,500 tokens (schemas are evicted, re-fetched if needed)

The agent never pays for tools it doesn't use.

### Lite Profile for Sub-Agents

For lightweight agent setups, Orbitmap offers a **Lite profile** with only 13 essential tools. The startup cost drops to just **~820 tokens** - three times lighter than the full profile.

| Profile | Tools | Startup cost | % of 200K context |
|---------|-------|-------------|-----------------|
| **Full** | 26 | ~2,500 tok | 1.25% |
| **Lite** | 13 | ~820 tok | 0.41% |
| **Manager** | 22 | ~1,070 tok | 0.54% |

## Task Context: Read Only What You Need

Without a project management tool, an agent picking up previous work has to re-explore the codebase - reading files, grepping for patterns, trying to reconstruct what happened. That costs thousands of tokens every time.

With Orbitmap, a single `get_tasks()` call returns the task's work logs, decisions, and status. The agent gets exactly the context it needs to resume work:

```terminal
~/my-project

> Resume work on the auth middleware.

Agent: Loading task context...
> get_tasks(task_id='TS-r2d2x1')

Work logs (4 entries):
1. [code_change] Created SupabaseAuth
   middleware with JWT validation
2. [decision] Used firebase/php-jwt
   instead of Sanctum
3. [decision] Chose Redis session driver
4. [note] All auth tests pass

Got it. Resuming from where I left off -
the middleware uses firebase/php-jwt for
JWT validation with Redis sessions.
```

Instead of spending **5,000+ tokens** re-exploring the codebase, the agent spends **~800 tokens** loading structured task context. That's an **80%+ reduction** - and the context is more accurate because it includes decisions and reasoning, not just code.

## Document Access: Three-Tier Reading

Traditional approach: agent reads the entire document to find what it needs. A typical project spec is 5,000–10,000 tokens. Multiply by several documents per session, and you've burned half your context window on documentation alone.

Orbitmap uses a **three-tier reading flow** that minimizes token consumption at every step:

### Tier 1: Context Field (~50 tokens)

Every document has a short **context** description visible in document listings. The agent reads this to decide if the document is even relevant - without opening it.

```terminal
~/my-project

> How does our auth middleware validate
  tokens?

Agent: Let me find the right document...
> get_project_docs()

8 documents found. Checking context fields:
- "Architecture Guide": Covers auth,
  middleware, DB schema...
- "API Reference": REST endpoints and
  response formats...

"Architecture Guide" is the one I need.
```

### Tier 2: Table of Contents (~200 tokens)

Once the right document is identified, the agent fetches only the **table of contents** - not the full content. From the TOC, it pinpoints the exact section.

```terminal
> get_document('arch-guide')

TOC: 14 sections
  ## Project Overview
  ## Authentication Flow    <-- this one
  ## Database Schema
  ## API Design
  ...
```

### Tier 3: Single Section (~500 tokens)

The agent fetches **just the section it needs**. The full 5,000-token document is never loaded.

```terminal
> get_document('arch-guide',
    section='## Authentication Flow')

480 tokens loaded (not 5,200).

The SupabaseAuth middleware validates JWT
tokens using firebase/php-jwt...
```

### The Math

| Approach | Tokens consumed |
|----------|----------------|
| Read entire document | ~5,000 |
| Orbitmap three-tier flow | ~750 |
| **Savings** | **~85%** |

This scales with project size. Whether your project has 3 documents or 30, the per-lookup cost stays roughly the same - because the agent only ever reads the section it needs.

## Section-Based Editing

The same efficiency applies to **editing documents**. Agents can patch a single section without downloading or re-uploading the entire document:

```terminal
> edit_document('arch-guide',
    mode='patch',
    operations=[{
      op: 'replace_section',
      heading: '## Authentication Flow',
      content: '..updated content..'
    }])
```

No need to load 5,000 tokens just to change one paragraph.

## Context Window Efficiency in Practice

Here's a typical session comparison:

| Action | Without Orbitmap | With Orbitmap |
|--------|-----------------|---------------|
| Resume previous task | ~5,000 tok (re-explore code) | ~800 tok (read task logs) |
| Find info in docs | ~5,000 tok (read full doc) | ~750 tok (context + TOC + section) |
| Check project status | ~3,000 tok (read files, git log) | ~400 tok (get_tasks) |
| MCP overhead | 0 | ~2,500 tok (one-time startup) |
| **Total per session** | **~13,000+ tok** | **~4,450 tok** |

The MCP startup cost pays for itself after a single task lookup or document read. Over a full working session with multiple lookups, the savings compound significantly.

### Why This Matters

- **More room for reasoning** - agents preserve their context window for code analysis, not for re-reading documentation
- **Faster responses** - less data to process means quicker agent output
- **Longer productive sessions** - with less context wasted, agents can work longer before hitting context limits
- **Scales with project size** - token cost per lookup stays constant regardless of how many documents or tasks your project has


---

# Projects and Workspaces

## What is a Project

A **project** in Orbitmap represents a single codebase or deployable unit:

- A web application
- A backend API service
- A mobile app version
- A library or SDK
- A microservice

Each project has its own:
- Tasks, issues, ideas, and vibes
- Documents and documentation
- Agent assignments
- Agent instructions template (applied to all new tasks)
- Git repository URL and default branch

## Organizing Projects in a Workspace

A **workspace** is an optional grouping layer for related projects. Use it when you have multiple codebases that belong to the same product or organization.

**Example:** A workspace called "Orbitmap" might contain:
- `orbitmap-core` - the main Laravel application
- `orbitmap-mcp` - the MCP proxy server
- `orbitmap-cli` - the command-line tool
- `orbitmap-mobile` - the mobile app

**Workspace benefits:**
- **Shared documents** - architecture decisions, coding standards, and guidelines available across all projects
- **Cross-project visibility** - see the big picture across all your codebases
- **Workspace-level knowledge** - documents tagged as workspace knowledge are automatically included when agents start tasks

## Working with a Project

From the web UI, select a project to see its dashboard with tasks, issues, documents, and activity. Use the sidebar to navigate between entities.

From your agent, all commands are automatically scoped to the project configured in your MCP connection (the `X-OrbitMap-Project` header).

## Project Context in MCP vs IDE

**MCP configuration with project context (Claude Code, CLI):**

In `.mcp.json` or CLI setup, you specify the project slug in the `X-OrbitMap-Project` header. The agent always knows which project it's working in.

```json
{
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY",
    "X-OrbitMap-Project": "my-saas-app"
  }
}
```

**IDE without project context (some Cursor/Windsurf setups):**

Some IDEs don't support custom headers in MCP configuration. In that case, omit the project header - your agent will have access to **all projects** in your account and must determine the correct project from context.

```terminal
~/mobile-app

❯ HAL, what projects do I have?

HAL: Checking your projects...
✓ get_my_projects()

Your projects:
1. orbitmap-core (workspace: Orbitmap)
2. orbitmap-mcp (workspace: Orbitmap)
3. mobile-app (workspace: MyStartup)

Based on this directory (~/mobile-app),
I'll work in the "mobile-app" project.
```

The agent infers the project from the working directory, git remote URL, or asks you directly. For best results, always configure the project header when possible.


---

# Agents

## Agent-User Relationship

Agents are tied to user accounts. By default, **one agent per user** is created automatically during onboarding.

An agent is the identity your AI tool uses when connecting to Orbitmap. It has:
- A unique name (e.g., "Claude-Backend")
- An API key for authentication
- Assignment to one or more projects
- Its own task queue - separate from your personal tasks

## Task Assignment - Agent vs User

Tasks can be assigned to either a **user** or an **agent**. The distinction matters:

- **Tasks assigned to you (the user):** Visible in your personal task list. Your agent does NOT automatically pick these up.
- **Tasks assigned to your agent:** The agent picks these up via `start_task()` and `get_tasks()`.

```terminal
~/my-project

❯ create new task for Agent Smith: "Refactor
  the payment processing module to use
  the Strategy pattern"

NEO: Creating task for Agent Smith...
✓ create_task(title='Refactor payment
  processing to Strategy pattern',
  assignee_agent_id='agent-smith-id')

Task TS-smith1 created and assigned to
Agent Smith.

Agent Smith will pick it up on their next
session.
```

When an agent runs `start_task()`, it only picks up tasks assigned to **itself** - never tasks assigned to other agents or to users directly.

## Multiple Agents per User

You can create multiple agents under your user account. This is useful when running parallel workstreams:

**Example: Two agents on independent branches**

| Agent | Branch | Focus |
|-------|--------|-------|
| `Claude-Frontend` | `feature/ui-redesign` | UI components, Blade views, Tailwind |
| `Claude-Backend` | `feature/api-v2` | Controllers, services, API endpoints |

Each agent has its own API key and its own `.mcp.json` configuration. Assign tasks independently:

```terminal
~/my-project

❯ assign TS-ui001 to Claude-Frontend and
  TS-api001 to Claude-Backend

CONTROL: Assigning tasks...
✓ assign_task('TS-ui001',
  agent_id='claude-frontend-id')
✓ assign_task('TS-api001',
  agent_id='claude-backend-id')

TS-ui001 → Claude-Frontend (ui-redesign)
TS-api001 → Claude-Backend (api-v2)

Both agents will pick up their tasks
independently on their respective branches.
```

**Naming convention:** When using multiple agents, name them clearly to reflect their purpose. Good names: `Claude-Frontend`, `Claude-API`, `Claude-Tests`. Avoid generic names like `Agent 1`, `Agent 2`.

**Important:** Each agent operates independently. They don't share task queues, so assigning a task to `Claude-Frontend` means `Claude-Backend` won't see it, and vice versa.