AgentDesk

Session status and outcomes

Session status remains independent of accomplishments: Stopped · PR created still means stopped, not approved or complete. Confirmed PRs and substantive tracker replies appear as separate links in the sidebar and status panel. Outcomes are saved immediately, survive later session updates and server restarts, and are deduplicated on replay. Archived sessions retain them; explicit session deletion removes the associated records.

Capture currently recognizes successful, standalone gh pr create commands with an explicit repository and head branch; marked final gh issue comment calls; and marked Jira/Linear comment-creation responses from standalone curl calls using literal JSON payloads. The engine supplies instructions for a session-specific [AgentDesk reply:…] marker in the final task reply, not startup/progress comments. Jira responses must include the created comment's ID/body/self URL; Linear mutations must return success and comment { id url body issue { identifier } }. Provider receipts must match the session's task/repository. Raw command output and credentials are not stored with outcomes.

Arbitrary shell scripts, pipelines, redirected output, file-based comment payloads, unsupported providers/hosts, and unconfirmed responses remain unknown rather than being guessed from chat or a PR lookup. A crash before the receipt reaches durable storage can still lose an outcome. There is no background recovery or historical backfill in this release.

The sidebar initially shows 12 past sessions across its date groups. More reveals older loaded sessions; an explicitly selected older session is revealed automatically. Active sessions are not limited.

Parallel sessions with Git worktrees

New team and solo sessions create a separate Git worktree and branch by default. Agents, their shell commands, file tools, and Git operations use that session directory. Multiple sessions can work on the same repository concurrently. Existing sessions keep their original directories.

The daemon runs at most 3 sessions concurrently by default, including sessions awaiting confirmation or completing teardown. Set AGENTDESK_MAX_SESSIONS=5 agentdesk daemon to change the limit (1–32). Excess requests wait in a cancellable in-memory daemon queue (up to 100); non-worktree sessions sharing a repository are serialized. The limit applies to daemon-managed sessions, not independently launched agentdesk team processes. Queued requests survive a network reconnect but not a daemon process restart.

agentdesk team -d "Add search" --base-branch main --branch feature/search
agentdesk team -d "Fix navigation" --base-branch main
agentdesk team TASK-123 --existing-branch feature/unfinished --base-branch main
agentdesk team TASK-123 --no-worktree
agentdesk team TASK-123 --resume-worktree SESSION-ID

The dashboard's Run Team dialog offers the same choices. Git refuses an existing branch that is already checked out elsewhere. A starting branch must exist locally (fetch remote branches first); an unborn or detached HEAD requires selecting a valid starting branch. Opting out uses the current directory and allows one AgentDesk session in that directory at a time.

Worktrees start from committed files. Uncommitted source files, dependencies, and ignored files are not copied or symlinked. Project configuration and environment values are loaded from the registered project, while commands run in the worktree. Install dependencies within each worktree as needed. Worktrees and retained runtime notes live under ~/.agentdesk/workspaces/; the CLI prints the working directory when a session starts.

Agents use private Git refs, configuration, hooks, and an index, borrowing existing objects read-only. The shared Git database is read-only inside the kernel sandbox. When a session exits, AgentDesk validates new objects and publishes only its branch and index; it refuses to overwrite a branch that moved independently. Private Git state is retained if publication fails and can be resumed when the shared branch has not moved. Worktree sessions require strict kernel isolation (macOS sandbox-exec or Linux bubblewrap); disabling it or selecting the legacy policy will prevent the session from starting. --resume-worktree cannot be combined with branch-selection flags.

Cancellation waits at most 30 seconds for process teardown. If processes still remain, the session ends but its worktree is quarantined: no Git publication, resume, or deletion until those processes exit. Other worktrees remain usable. The daemon checks stale locks on startup and every 15 seconds, preserving locks held by surviving agent PIDs or process groups even if the previous daemon crashed. Recovery removes only stale locks, never unfinished files or branches; unpublished private Git state remains available for recovery on resume. Inaccessible or unidentifiable processes require manual review rather than automatic unlocking.

The same live-process check applies after a successful session. Quarantine is recorded separately from the session result and survives server restart; the dashboard reports quarantine at shutdown, while Worktrees shows the current recovery state. Handoff and queued sessions remain open for display and are excluded from bulk inactive-session deletion; only active/stale sessions count as running.

Use Worktrees in the dashboard to inspect retained directories, resume work, or remove them. Archiving or deleting a session requests cleanup, including when the daemon is temporarily offline. Automatic removal requires a clean directory (including no untracked or ignored files) and commits reachable from the selected starting branch. Branches are kept. Merge checks use local refs; fetch first if a merge happened remotely. Squash merges do not prove commit ancestry and require manual review.

Unfinished work is retained, with a review reminder after 14 days of session inactivity. Age never triggers deletion. Discard files requires typing the branch name and permanently removes uncommitted, untracked, and ignored files; committed branch history remains. Automatic cleanup is retried while the daemon and dashboard are connected. Update both the server and daemon to use this feature.

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 | Team Lead — owns priorities and delivery, assigns work, challenges evidence, and resolves disagreements | | 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.

Before the reviewers are asked, the engine runs the project's own checks itself — commands.test, commands.build and commands.lint from project settings, or the test/build/lint scripts in package.json when those are unset — inside the session sandbox, at the current commit. A failing check goes straight back to EXECUTION with the real output as findings; the reviewers are only asked once the checks pass. An approval is pinned to that commit: if the code changes afterwards, the approval no longer counts and the session ends for human review instead of reporting success. In a session worktree, uncommitted changes block review too — an approval refers to a committed revision. Publishing is verified the same way, on the spot: when the team runs git push or gh pr create — however the command is spelled (git -C . push, env git push, on a later line, inside sh -c) — the engine runs the checks at the revision being published and refuses with the failing output until a new commit passes. A passing run is evidence for one tree only: the same commit with a clean working tree, then and now. It is reused by the review that follows only while that still holds; uncommitted changes force a fresh run. Publishing also needs Sam's explicit verdict: he ends his audit with AUDIT: APPROVED or AUDIT: REJECTED, the engine reads that line and ties an approval to the commit he read — a rejection, a report without the line, or a commit made after his approval keeps publishing closed until he audits again. REVIEW and SUMMARY cannot commit, move HEAD, or push; they read and write messages only.

The team follows the task. INTAKE assesses the scope — small or standard, and which areas the change touches (ui, copy, docs, api, data). A small task skips PLAN (Dennis states the approach at the start of EXECUTION) and is reviewed by Bart and Vera; Sam's architecture audit still gates the PR inside EXECUTION. Luna, Mark and Nora join only when the task touches UI, user-facing copy or docs respectively. Set "teamProfile": "small" or "standard" in .agentdesk.json to force it ("auto", the default, lets INTAKE decide).

Every phase run is also recorded by the engine in .agentdesk/handoffs.jsonl (revision before and after, the phase's structured output, the verification evidence, and what is still open). Unresolved findings and deferred items are carried into the next phase's prompt as open items, and an EXECUTION that reports work without making a commit is flagged to the reviewers.

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

The phase lead submits each handoff through the SDK's StructuredOutput tool. It must be included in both the selected agent's tool list and the unattended tool permissions; chat text alone cannot advance the phase. To check this against the real SDK after changes to tool configuration, run npm run test:sdk-handoff. This opt-in diagnostic requires a Claude login and uses model tokens. It checks every phase, solo mode, and handoff repair with fixed fixtures and execution tools blocked.

Run npm run test:sdk-leadership to check Jane's decisions against supplied reports: a superseded scope deferral, a completion claim missing visual evidence, and a failed Jira comment. This opt-in behavioral check also requires a Claude login and uses model tokens; delegation and external actions are blocked. It checks decisions and named follow-up owners using the production prompts.

Sessions started from the dashboard with an updated daemon can be paused and resumed in the same conversation and workspace. Use Pause / check workers, or enter a correction and choose Pause & save. Instructions are saved immediately; Verify & resume becomes available after the previous workers have stopped and released the workspace. A quarantined workspace remains blocked until its workers exit.

Resume restores the original task, discovered tracker task ID, pending phase, saved findings, user corrections, token totals, and recorded external actions. Corrections trigger replanning against the existing work. Access is checked again before continuing; a failed login check preserves both the checkpoint and the pending correction. For a revoked model login, reconnect Claude on the daemon computer using the same account profile, then choose Verify & resume. Before every session the engine checks that login with one tiny real request; an expired or revoked login stops the session before intake and names the profile to reconnect. Session controls require the session owner and a connected daemon that supports recovery; older sessions need a separate continuation.

A missing phase handoff gets one repair attempt using the preserved findings with execution tools disabled. If repair fails, or required tracker access is denied during intake or planning, work pauses for intervention. Recognized external write commands are fingerprinted before dispatch and exact repeats are blocked. An uncertain result must be reconciled with the provider before continuing. This is a conservative replay guard, not general deduplication of equivalent commands or arbitrary scripts.

The recovery checkpoint lives on the daemon computer. The dashboard retains instructions and recovery status across server restarts, but cannot resume without the local checkpoint and workspace. It never silently creates a new task when a required checkpoint is missing.

Terminal sessions also save a resume snapshot (.agentdesk-resume.md) when interrupted. To start a continuation from the terminal, use the command printed in that snapshot, including --resume-worktree when present:

# Session hits limit → "HANDOFF" shown in terminal
# Continue in the retained workspace:
agentdesk team KEN-517 --resume-worktree SESSION-ID

Project lessons

The team's cross-session memory is an engine-owned ledger, .agentdesk/lessons.json in the project directory (local, gitignored, shared by every session worktree). At the end of a session the SUMMARY handoff (or the solo agent's) may propose lessons — a setup step, seed data, an environment quirk — each with evidence and a scope (project, area:<ui|copy|docs|api|data>, or path:<prefix>). The engine records them with where they came from (session, task, phase, agent, revision). A lesson from a session that ended complete (verified approval) is active immediately; one from a session that ended in handoff stays proposed until a later complete session proposes the same lesson. Solo sessions have no review gate, so their lessons stay proposed until a team session that ends complete confirms them. Every phase prompt receives the active lessons in scope, newest first (at most 30). A team that finds a lesson wrong or obsolete retires it by id in the same handoff; retired lessons are kept for the record and never shown again.

.agentdesk/memory.md, the hand-written notes file from earlier versions, is still shown to the team as read-only legacy notes but is no longer written.

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 — spawns Claude with a fixed set of allowed tools, plus the project's own configured test/build/lint commands (run inside the same sandbox, before each review) — nothing the server can push
• 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