agent-desk

AgentDesk

中文说明

AgentDesk is a local MCP and CLI orchestrator for Codex work. It turns an engineering goal into a markdown checklist task, lets agents claim work before they start, runs Codex subagents, and records the result as an auditable project session.

flowchart LR
    goal["Engineering goal"] --> entry{"MCP / CLI entry"}
    entry --> task["Markdown checklist<br/>task.md"]

    task -. "Need help?" .-> tools["list / read / claim<br/>task items"]
    tools -. "Write claim marker" .-> task

    task --> executable{"Executable<br/>checkbox tasks?"}
    executable -- "No" --> stop["Stop execution<br/>report why fanout is unavailable"]
    executable -- "Yes" --> session["Start session<br/>dispatch Codex workers"]
    session --> done{"Agent succeeded?"}
    done -- "Failed" --> error["Record lastError<br/>in session metadata"]
    done -- "Succeeded" --> finalize["Finalize<br/>worktree branch<br/>or configured integration"]
    error --> summary["Regenerate session.md<br/>latest execution summary"]
    finalize --> summary
    summary --> user["User reviews<br/>auditable status"]

What It Is

AgentDesk is built around three objects:

• Project: any local git repository.
• Task: a generated task.md with checkbox subtasks.
• Session: one execution run that fans out task items to Codex CLI workers or prepares a Codex App launch plan.

Agents can use claim_next_task_item before implementation; the visible marker records agent -> sessionId so people and other agents can see ownership. Before subagent execution, the coordinating model should review task complexity and concurrent-edit conflict risk, choose a recommended per-batch subagent count, and tell the user; the user can still choose a different concurrency value within the configured maximum.

The AgentDesk usage path is the bundled Codex skills plus MCP/CLI: generate or read a task.md, claim checklist work, run or prepare subagent sessions, and review session history through verunectl or the MCP stdio server.

AgentDesk is headless: it has no web UI, HTTP API, or browser surface. Subagents are launched through the Codex (codex-cli) and Claude (claude-code-cli) CLIs, or prepared as host-direct launch plans (codex-app / claude-direct / grok-direct) for in-session dispatch.

Local MCP Setup

AgentDesk currently runs from a local checkout. It requires Node.js 22.12 or newer and a working Codex CLI.

npm install
codex mcp add agent-desk -- node "$(pwd)/bin/agent-desk-mcp.mjs"
codex mcp get agent-desk

To bind the MCP server to a fixed project:

codex mcp add agent-desk-my-project \
  --env AGENT_DESK_PROJECT_ROOT=/absolute/path/to/your/project \
  -- node "$(pwd)/bin/agent-desk-mcp.mjs"

You can also start the same MCP server through the local CLI:

./scripts/verunectl.sh mcp --project /absolute/path/to/your/project

Overall Tasks (SQLite)

AgentDesk keeps a user-level day/week/month planning store backed by SQLite, exposed through the create_overall_task family of MCP tools and the verunectl overall-tasks CLI subcommands.

Key design principle: This Overall Tasks SQLite database lives only at the user root level (~/.agent-desk/tasks.sqlite). Individual project directories should not contain their own copy of this database. Each project's .agent-desk/ directory only holds traditional control-plane tasks (task.md, sessions, etc.). This design enables managing tasks across multiple projects plus user-level planning tasks from the user's home directory.

Pass --sqlite-path <file> to override it for a run.

Overall tasks can be user-level (projectRoot empty) or project-bound (projectRoot absolute). Coding tasks require a project root before dispatch. Task and session dispatch keeps the documented weakest-model defaults: Codex launchers use o4-mini + low, Claude launchers use haiku, Grok launchers use composer-2.5-fast, service tier unset by default, and launch batch size 6.

Common CLI

Create a task:

./scripts/verunectl.sh tasks create \
  --project /absolute/path/to/project \
  --title "Checkout flow" \
  --brief "Implement the checkout flow end to end"

List and inspect tasks:

./scripts/verunectl.sh tasks list --project /absolute/path/to/project
./scripts/verunectl.sh tasks show <taskId> --project /absolute/path/to/project

Start a session:

./scripts/verunectl.sh sessions start <taskId> \
  --project /absolute/path/to/project \
  --model o4-mini \
  --reasoning low \
  --parallel 6

Useful session commands:

./scripts/verunectl.sh sessions list --project /absolute/path/to/project
./scripts/verunectl.sh sessions show <sessionId> --project /absolute/path/to/project
./scripts/verunectl.sh sessions logs <sessionId> <agentId> --project /absolute/path/to/project

Defaults: Codex launchers use model o4-mini and reasoning low; Claude launchers use haiku; Grok launchers use composer-2.5-fast; service tier is unset by default; execution mode auto; launch batch size 6; maximum parallelism 6. External CLI launchers: codex-cli and claude-code-cli.

codex-cli subagents are launched as resumable interactive Codex CLI sessions. sessions show and session.md include each agent's primary codex resume <sessionId> command, plus codex resume --all <sessionId> for resuming from another working directory.

State Layout

Each project stores AgentDesk state inside the project, while persistent worktrees live under the user home directory.

<project>/task/
  <task-slug>.task.md

<project>/.agent-desk/
  tasks/
    <taskId>/
      brief.md
      prompt.md
      task.md
      memory.md
      meta.json
      stdout.log
      stderr.log
  sessions/
    <sessionId>/
      meta.json
      session.md
      stdout.log
      stderr.log
      agents/
        <agentId>/
          task.snapshot.md
          memory.snapshot.md
          prompt.md
          report.json
          stdout.log
          stderr.log

~/.agent-desk/worktrees/<project-key>/<sessionId>/<agentId>

taskId and sessionId are stable references for paths, commands, worktrees, and MCP lookups. memory.md preserves shared task context across sessions, and session.md is regenerated as agents finish.

Each CLI-run agent writes report.json when implementation and validation are complete. Agent metadata also records codexSessionId, codexSessionPath, codexResumeCommand, and codexResumeAllCommand for read-only inspection and manual continuation.

Detailed skills, MCP tools, task format, and verification notes are in docs/reference.md. Runtime behavior details are in docs/design.md.

License

AgentDesk is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for details.