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