AgentDesk

AI team orchestrator for Claude Code. Run collaborative agent sessions from your terminal and watch them live on agentdesk.live.

AgentDesk spawns a team of AI agents inside Claude Code that collaborate on your tasks. The default team includes 8 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 | | Nora | Documentation Steward — README, /docs, setup guides, npm metadata, website docs |

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

Getting Started

The fastest way to try AgentDesk is the Claude Code plugin. It runs the phased loop (intake → plan → execute → review → summary) entirely inside your existing Claude Code session — no signup, no daemon, no extra install.

Quickstart — Claude Code plugin

Inside any Claude Code session:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install agentdesk@claude-community
/agentdesk <your task or tracker URL>

Five sub-agents run in sequence with a dedicated review pass before SUMMARY produces the final report. State persists in .agentdesk/session-memory.md.

What the plugin covers: the phased workflow, one task at a time, in your terminal. Zero-account, in-process.

What needs the full CLI + dashboard (below): session history, dashboard visibility, multi-session parallelism, team coordination, tracker integration (Jira/Linear/GitHub write-back), and the long-running daemon.

Full setup — CLI + dashboard

For session history, team workflows, and tracker integration, install the AgentDesk CLI and connect it to your agentdesk.live account.

1. Install

npm i -g @kendoo.agentdesk/agentdesk

Requires Claude Code and Node.js 18+.

2. Sign in

agentdesk login

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

3. Set up your project

agentdesk init

agentdesk init is a single mode-aware wizard. It detects whether this clone maps to an existing project on your account and picks a mode accordingly:

• Existing mode — local .agentdesk.json has a projectKey, or the git remote matches a project on your account. The wizard walks every step, but project-wide steps (repo, tracker type/location/team, signature) are shown as read-only with a "change in agentdesk.live" hint. Only per-machine credential steps (GitHub token, tracker credentials) are interactive. Rationale: tracker/repo/team are shared state — changing them in one CLI would desync teammates and the dashboard, so those changes belong in project settings on agentdesk.live.
• New mode — no match found. Every step is interactive. On save, the new project row is POSTed to agentdesk.live and its settings are pushed.

When there's no local config and no unique auto-match but the account has other projects, init shows a picker of your projects plus "Set up as a new project" and "Cancel" so you can't accidentally create a duplicate.

The wizard is ten tiny steps, each doing one thing:

1. Detect git repo in cwd.
2. GitHub repo (prompted in new mode; locked-display in existing mode).
3. GitHub token — per-machine, always editable. If present, offers Keep/Replace; if new, prompts. @login is fetched from the GitHub API and echoed.
4. git clone the repo into ./<repo> when cwd isn't already that repo.
5. Tracker type (locked in existing mode).
6. Tracker location — Linear workspace / Jira tenant URL (locked in existing mode).
7. Tracker credentials — per-machine, always editable with Keep/Replace.
8. "How should the AI team sign its work?" (locked in existing mode).
9. Verify tracker + (new mode) pick team/project from the fetched list.
10. Review, access-check checklist (agentdesk.live ✓, GitHub ✓, tracker ✓), confirm save.

Legacy .agentdesk.json files (without projectKey) are auto-migrated: init matches your account's projects by github.repo / git remote / tracker team, writes the projectKey back, and enters existing mode.

Use agentdesk init --force-full to bypass detection and always run the new-mode wizard (useful when the auto-match is wrong or you're intentionally re-pushing settings). agentdesk bootstrap is a compatibility alias.

All menus use arrow-key navigation with color highlighting; Ctrl-C exits cleanly.

.agentdesk.json is kept in sync with the server: every CLI run fetches the authoritative config and rewrites the local file as a credential-free snapshot. Credentials live only on the server, encrypted. If a local edit disagreed with the server's value, a one-line warning lists the overridden fields.

4. Run a team session

Work on an existing task:

agentdesk team KEN-517

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

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. Each session gets a deep link you can share — the session ID is visible in the header and sidebar with a one-click copy, alongside the tracker task ID. Teammates who don't have access yet see a friendly "private session" page with a one-click request-access button, and you can grant them viewer access for that session or the whole project from the dashboard.

Commands

agentdesk login                        Sign in to AgentDesk
agentdesk logout                       Sign out and remove credentials
agentdesk init [--force-full]          Guided setup — auto-detects new vs existing, clones if needed
agentdesk bootstrap                    Alias for the connect-to-existing-project flow
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, nora)
agentdesk daemon                       Start daemon for remote sessions
agentdesk security-check [-d <dir>]    Multi-surface security audit (server / CLI / UI / prompts)
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 → REVIEW → SUMMARY) — 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, 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. Acts as a credential-free cache of the server config, rewritten on every CLI run. If the server is unreachable, .agentdesk.json is used as-is (and never mutated).

The server is the source of truth. If you edit .agentdesk.json directly while the server has a different value for the same field, the server wins and the CLI prints a one-line warning listing the overridden fields so you notice. To push local edits back up, re-run agentdesk init (the wizard writes to the server).

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:

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:

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:

{
  "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).

Screenshots

Screenshots are captured by default for UI-related tasks. Bart captures desktop and mobile screenshots before creating the PR and attaches them to the task tracker.

To disable, set screenshots to false in .agentdesk.json or toggle it off in project settings:

{
  "screenshots": false
}

You can also toggle screenshots per session when starting a task from the Web UI.

Model per phase

In phased mode (INTAKE → PLAN → EXECUTION → REVIEW → SUMMARY), you can pick a different Claude model per phase from project settings. Useful when you want a stronger model for planning and implementation but a cheaper one for the lighter phases.

{
  "phaseModels": {
    "INTAKE": "sonnet",
    "PLAN": "opus",
    "EXECUTION": "opus",
    "REVIEW": "haiku",
    "SUMMARY": "haiku"
  }
}

Valid values: "default", "opus", "sonnet", "haiku". "default" resolves to Claude Code's default for INTAKE/PLAN/EXECUTION and to haiku for REVIEW/SUMMARY. Non-phased runs use the EXECUTION model.

The REVIEW phase is a read-only completeness check (no code changes) — it verifies the implementation meets requirements, flags missed documentation updates or silently-deferred scope. If gaps are found, the orchestrator loops back to EXECUTION once before moving on. The SUMMARY phase writes the final tracker comments and session protocol.

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 > Plan > Execution > Review > Summary
4. Agents discuss, disagree, and build on each other's ideas within a shared context
5. The session streams live to 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.

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

agentdesk daemon

Once running, a "Run Team" button appears on 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

• Per-session identity isolation — every session runs with HOME / GH_CONFIG_DIR / XDG_CONFIG_HOME pointed at a private scratch dir containing only this project's tracker credentials and commit identity. gh, git, and ssh inside the session cannot see your global accounts, other projects' tokens, or keys elsewhere on disk.
• Kernel-enforced sandbox when available — on macOS (sandbox-exec) and Linux (bwrap / bubblewrap), sessions run with a strict allowlist policy: full read/write on the project cwd, the per-session scratch HOME, /tmp, and common tool caches (~/.nvm, ~/.npm, ~/.cache, ~/.pyenv, ~/.rbenv, ~/.rvm, ~/.cargo, ~/.rustup, ~/.gem, ~/.local). Read-only on system paths (/usr, /etc, /System, etc.). Everything else under your real $HOME is unreadable from inside the session — ~/Documents, browser cookie stores, other projects' .env files, SSH keys, cloud-provider creds. Network stays open so agents can reach the Anthropic API, tracker APIs, package registries, and remote git. If sandbox-exec / bwrap isn't installed, sessions fall back to scoped-env isolation with a one-line notice.
  • Opt out for debugging: AGENTDESK_NO_SANDBOX=1 (no kernel sandbox at all).
  • If the strict allowlist breaks a tool you need, fall back to the pre-allowlist denylist policy with AGENTDESK_SANDBOX_LEGACY=1 and please file an issue so we can extend the allowlist.
• Credentials prerequisite — scoped sessions push code over HTTPS using a per-project GitHub token. agentdesk init saves it to the project's .env as GITHUB_TOKEN; if you skip that step, the session refuses to start with an actionable message. SSH-only remotes ([email protected]:...) are also rejected — the sandbox intentionally isolates ~/.ssh. Switch the origin to https://github.com/<owner>/<repo>.git or run without scoped isolation.
• 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; teammates without access can request it in one click and be granted viewer access per-session or project-wide
• Access requests inbox — pending requests from teammates appear in the dashboard header for quick approval
• 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 installed and configured
• Node.js 18+
• An AgentDesk account at agentdesk.live