Your First Project — codepakt docs

This tutorial walks through the complete codepakt workflow with two agents dividing work on a real project. By the end you’ll have a running server, a populated task board, agents claiming work atomically, and a dashboard showing live state.

1. Start the server

cpk server start

Starting Codepakt server...
Server running on :41920 (PID: 34821)
  Version:  0.1.1

2. Initialize a project

Navigate to your project root and initialize:

cpk init --name "my-app"

Project "my-app" created (proj_abc123)
.codepakt/config.json created

Generating coordination files...
  .codepakt/AGENTS.md written
  AGENTS.md created (references .codepakt/AGENTS.md)
  .codepakt/CLAUDE.md written
  CLAUDE.md created (imports .codepakt/CLAUDE.md)

cpk init creates the project record on the server, writes .codepakt/config.json, and generates coordination files that agents read on startup.

If you have a PRD document, pass it directly:

cpk init --name "my-app" --prd ./PRD.md

This stores the PRD as a reference doc in the knowledge base, giving all agents access via cpk docs search.

3. Add tasks

Add tasks with dependencies. Tasks with unmet dependencies stay in backlog until their deps reach review or done.

cpk task add \
  --title "Set up database schema" \
  --priority P0 \
  --verify "pnpm db:migrate && pnpm typecheck"

Task created: T-001 (open)

cpk task add \
  --title "Build auth API endpoints" \
  --priority P0 \
  --depends-on T-001 \
  --verify "pnpm test src/auth" \
  --acceptance-criteria "JWT login, refresh, logout. All endpoints have integration tests."

Task created: T-002 (backlog — waiting on T-001)

cpk task add \
  --title "Build login UI" \
  --priority P1 \
  --depends-on T-002 \
  --epic "auth-flow"

Task created: T-003 (backlog — waiting on T-002)

4. Agent workflow

Each agent runs this loop. No registration needed — agents identify themselves via the --agent flag.

Terminal 1 — backend agent:

# Pick up the highest-priority available task
cpk task pickup --agent backend

Picked up T-001: "Set up database schema" (P0)
Status: in-progress

The pickup is atomic. If two agents call cpk task pickup simultaneously, exactly one gets the task. The other gets an empty result and can call again.

Do the work, then mark it done:

cpk task done T-001 --agent backend --notes "Created users, sessions, and refresh_tokens tables."

T-001 moved to review
T-002 deps_met: true (unblocked)

When T-001 moves to review, the server automatically updates deps_met on T-002, making it available for pickup. Dependencies resolve on review — no need to wait for human approval.

# Pick up the next task
cpk task pickup --agent backend

Picked up T-002: "Build auth API endpoints" (P0)

Terminal 2 — frontend agent:

cpk task pickup --agent frontend

At this point, T-003 is still in backlog (waiting on T-002). If nothing is available:

No open tasks available

Once T-002 is done, T-003 becomes available and the frontend agent can pick it up.

5. Check board status

cpk board status --human

Project: my-app

Tasks by status:
  open:        0
  in-progress: 1 (T-002 → backend)
  review:      1 (T-001)
  backlog:     1 (T-003)

Agents:
  backend   working  (T-002)

6. Open the dashboard

open http://localhost:41920

The dashboard shows a live kanban with the same state. It polls every 30 seconds.

7. Generate coordination files

When you want any new agent to know how to participate:

cpk generate

This creates .codepakt/AGENTS.md and .codepakt/CLAUDE.md — coordination files that agents read on startup. Commit them to git.

What’s next

Tasks & Lifecycle — all task fields, status transitions, verification
Agents & Coordination — how agents interact with the board
Knowledge Base — storing and retrieving project knowledge
Dashboard — what you can do from the web UI