Agents & Coordination

An agent is any autonomous entity that self-serves from the task board using the cpk CLI. It could be a Claude Code session, a Codex API call, a Cursor agent, a shell script, or a human. The server doesn’t care — it just tracks who is working on what.

No registration needed

Agents don’t need to be pre-registered. The first time an agent name appears in a pickup, done, or block command, the server creates an agent record automatically.

# This creates the "claude" agent record on first use
cpk task pickup --agent claude

No ceremony. No config. The agent shows up, claims work, and the server starts tracking it.

Agent identity

Agent names are passed via the --agent flag or the CPK_AGENT environment variable:

# Option 1: flag on every command
cpk task pickup --agent claude
cpk task done T-001 --agent claude --notes "done"

# Option 2: set once per session
export CPK_AGENT=claude
cpk task pickup
cpk task done T-001 --notes "done"

The --agent flag takes precedence over CPK_AGENT. If neither is set, commands that require agent identity will fail with an error message.

Commands that require agent identity: task pickup, task done, task block, task mine.

Commands that don’t: task add, task list, task show, task unblock, board status, docs *.

How pickup works

When an agent calls cpk task pickup, the server:

Finds the highest-priority open task with all dependencies met
Assigns the task to the agent (atomically — BEGIN IMMEDIATE transaction)
Creates or updates the agent record

No capability matching. No filtering. The human is the orchestrator — you already know which agent is good at what. If you want a specific agent on a specific task, use --id:

cpk task pickup --agent claude --id T-003

The human-in-the-loop model

codepakt is semi-autonomous. Agents self-serve from the board, but the human is always aware:

Dashboard at http://localhost:41920 shows who is working on what
cpk board status gives a CLI summary
You can redirect at any time — reassign tasks, block/unblock, add new work

The system works because:

The human creates tasks (or directs an agent to decompose a PRD into tasks)
Agents pick up work and report back
The human watches the dashboard and steers when needed

Agent statuses

Status	Meaning
`idle`	Not currently working on any task
`working`	Has an `in-progress` task assigned

Status is derived from the task board. When an agent picks up a task, it becomes working. When the task is completed or blocked, the agent returns to idle.

Listing agents

cpk agent list

NAME       STATUS    CURRENT TASK
backend    working   T-002
frontend   idle      —

The agent list is auto-populated from interactions — no registration needed.

AGENTS.md — the generated coordination file agents read on startup
cpk agent list — CLI reference
cpk task pickup — atomic pickup mechanics