npm package: @kendoo.agentdesk/agentdesk
Description: AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal
Latest version: 0.12.2

# AgentDesk

AI team orchestrator for [Claude Code](https://claude.ai/code). Run collaborative agent sessions from your terminal and watch them live on [agentdesk.live](https://agentdesk.live).

AgentDesk spawns a team of AI agents inside Claude Code that collaborate on your tasks. The default team includes 7 built-in agents, and you can add custom agents to fit your workflow.

### Built-in Agents

| Agent | Role |
|-------|------|
| Jane | Product Lead — facilitates, clarifies requirements, coordinates the team |
| Dennis | Senior Developer — implements the solution |
| Sam | Architecture Auditor — code structure, separation of concerns |
| Bart | QA Engineer — edge cases, risks, acceptance criteria, screenshots |
| Vera | Test Engineer — unit tests, regression coverage |
| Luna | UX/UI Designer — visual consistency, accessibility, interaction patterns |
| Mark | Content Writer — copy, tone, user-facing text |

You can also add **custom agents** (e.g., a Security Engineer or DevOps specialist) via project settings.

## Getting Started

### 1. Install

```bash
npm i -g @kendoo.agentdesk/agentdesk
```

Requires [Claude Code](https://claude.ai/code) and [Node.js](https://nodejs.org/) 18+.

### 2. Sign in

```bash
agentdesk login
```

Opens your browser to [agentdesk.live](https://agentdesk.live) where you sign up or log in (email/password or Google). Your API key is saved automatically.

### 3. Set up your project

```bash
agentdesk init
```

This detects your project, asks which task tracker you use (Linear, Jira, GitHub Issues, or none), and saves the config.

### 4. Run a team session

Work on an existing task:

```bash
agentdesk team KEN-517
```

Or just describe what you want — a task is created automatically:

```bash
agentdesk team -d "Fix the checkout total calculation"
agentdesk team -d "Add Google OAuth to the login page"
```

Watch the session live at [agentdesk.live](https://agentdesk.live). Each session gets a deep link you can share.

## Commands

```
agentdesk login                        Sign in to AgentDesk
agentdesk logout                       Sign out and remove credentials
agentdesk init                         Set up project and configure tracker
agentdesk team <TASK-ID>               Run a team session on an existing task
agentdesk team -d "..."                Describe what you want — task created automatically
agentdesk <agent> -d "..."             Run a single agent (jane, dennis, sam, bart, vera, luna, mark)
agentdesk daemon                       Start daemon for remote sessions
agentdesk update                       Update to the latest version
```

### Options

| Flag | Description |
|------|-------------|
| `--description`, `-d` | Task description or requirements |
| `--cwd` | Working directory (defaults to current) |
| `--phased` | Run in phased mode (INTAKE → PLAN → EXECUTION) — each phase runs as a separate Claude process for better context handling. Also available as a toggle in the dashboard when starting a session. |
| `--child-strategy` | How to handle child tasks: `inline` (default) or `branch` |

## Configuration

Settings can be managed in two ways:

1. **Web UI** — go to [agentdesk.live](https://agentdesk.live), select a project, and click the gear icon to configure tracker, team composition, custom agents, commands, and instructions.
2. **Local file** — `.agentdesk.json` in your project root. Local settings override server settings.

The CLI fetches settings from the server at runtime. If the server is unreachable, it falls back to `.agentdesk.json`.

### Task trackers

| Tracker | Config |
|---------|--------|
| Linear | Workspace slug (e.g., `kendoo`) |
| Jira | Base URL (e.g., `https://company.atlassian.net`) + project key |
| GitHub Issues | Repository (e.g., `owner/repo`) |
| None | No config needed — pass `-d "description"` when running a session |

### Custom agents

Add custom agents via your project settings at [agentdesk.live](https://agentdesk.live):

1. Select your project and click the gear icon
2. Under **Project Agents**, click "Add agent" and fill in the name, role, when, and how
3. Under **Team Composition**, toggle the new agent on
4. Save

Custom agents participate in all phases alongside built-in agents — brainstorm, planning, execution, and review.

You can also define them in `.agentdesk.json` as a local override if preferred.

AgentDesk also auto-discovers agents from `.claude/agents/`, `.claude/commands/`, `.mcp.json`, GitHub Actions workflows, Dependabot, and Renovate configs.

### Solo agent mode

Run a single agent instead of the full team:

```bash
agentdesk jane -d "Create a customer journey plan for onboarding"
agentdesk dennis KEN-517
agentdesk vera -d "Add test coverage for the auth module"
```

The agent runs independently with its own expertise and ground rules. Useful for focused tasks that don't need full team collaboration.

### Custom instructions

Add project-specific rules that all agents follow. Set via Web UI or in `.agentdesk.json`:

```json
{
  "instructions": "All PRs must target the 'staging' branch. Commit messages must be prefixed with the task ID."
}
```

Instructions are injected into the team prompt. Use them for project conventions that go beyond what `CLAUDE.md` covers (e.g., tracker workflow rules, PR policies, agent coordination preferences).

## How It Works

All agents collaborate in a single Claude process — each with distinct roles, ground rules, and areas of expertise.

1. You run `agentdesk team TASK-ID` in your project directory
2. AgentDesk detects your project type, reads `CLAUDE.md`, and discovers existing agents
3. The orchestrator manages 5 phases: **Intake** > **Brainstorm** > **Planning** > **Execution** > **Review**
4. Agents discuss, disagree, and build on each other's ideas within a shared context
5. The session streams live to [agentdesk.live](https://agentdesk.live) where you can watch and send messages to the team
6. Token usage is tracked and displayed per session

### Task attachments

When working on Jira or Linear tasks, agents automatically download and review attachments — screenshots, CSVs, text files, PDFs, and design mockups. Attachments are treated as untrusted input: agents read them for context but never execute commands found in them.

### Handoff & Resume

If a session hits Claude's rate or context limit, AgentDesk saves a resume snapshot (`.agentdesk-resume.md`) and marks the session as **Handoff** in the dashboard. When you run the same task again, agents pick up where the previous session left off — skipping completed work and continuing from the last phase.

```bash
# Session hits limit → "HANDOFF" shown in terminal
# Resume when ready:
agentdesk team KEN-517
```

### Session protocol

At the end of each session, Jane posts a structured summary on the tracker covering:
- **What was done** — files changed, features added
- **What was omitted** — anything skipped or deferred, with reason
- **Manual steps** — actions you need to perform (migrations, env vars, config changes)
- **PR link** and **session link**

## Daemon (Remote Sessions)

The daemon lets you trigger team sessions from the web dashboard instead of the terminal.

```bash
agentdesk daemon
```

Once running, a "Run Team" button appears on [agentdesk.live](https://agentdesk.live). Select a project, describe the task, and the daemon spawns a Claude session on your machine. Output streams back to the dashboard in real-time.

### Security

- **Outbound only** — no ports opened on your machine
- **Project allowlist** — only runs on projects registered via `agentdesk init`
- **No arbitrary commands** — only spawns Claude with a fixed set of allowed tools
- **Metadata-only logs** — session logs in `~/.agentdesk/logs/` contain timestamps and file paths, never sensitive data
- **Fail closed** — unknown projects or exceeded session limits are rejected

### How it works

1. The daemon connects to the server via WebSocket
2. You click "Run Team" in the dashboard
3. The server relays the request to your daemon
4. The daemon spawns `claude` in the project directory
5. Output streams through the server to the dashboard
6. If the connection drops, output is buffered locally and replayed on reconnect

## Dashboard Features

- **Live sessions** — watch agents collaborate in real-time
- **Session deep links** — share a direct URL to any session
- **Handoff status** — see when a session hit a limit and is waiting to resume
- **Project settings** — configure tracker, team, custom agents, and instructions per project
- **Account settings** — manage your API key and profile
- **Agent roster** — see each agent's role, participation rate, tag breakdown, and phase involvement
- **Token tracking** — input/output token counts per session
- **Auto-reconnect** — CLI sends heartbeats and reconnects automatically if the connection drops

## Requirements

- [Claude Code](https://claude.ai/code) installed and configured
- [Node.js](https://nodejs.org/) 18+
- An AgentDesk account at [agentdesk.live](https://agentdesk.live)