Docs Case Studies

Your First Project

This tutorial walks through both halves of codepakt — code intelligence and task coordination — on a real project. By the end you’ll have an indexed codebase that agents can query in ~200 tokens per call, plus a running board for multi-agent work.

1. Initialize a project

Navigate to the root of any repo and run:

cd your-project
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, writes .codepakt/config.json, registers it in the global index at ~/.codepakt/index.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.

2. Scan your codebase

Index all the symbols and imports so agents can query them in constant time:

cpk scan
{"files_scanned":230,"symbols":958,"imports":1223,"duration_ms":388,"languages":["typescript","javascript"],"incremental":false}

cpk scan parses every supported source file with tree-sitter WASM, extracts functions, classes, interfaces, types, methods, and imports, and stores them in .codepakt/data.db. It respects .gitignore automatically.

Install the git hook so the index stays fresh on every commit:

cpk scan --install-hook
Installed pre-commit hook at .git/hooks/pre-commit

3. Query the index

Now agents can answer structural questions in one CLI call:

# Project overview
cpk code summary

# Find a symbol
cpk code symbols --name AuthService

# All classes in a directory
cpk code symbols --kind class --file src/auth/

# What does this file import?
cpk code imports --file src/auth/guard.ts

# Who imports this file? (impact analysis)
cpk code dependents --file src/shared/types.ts

These commands work offline — no server daemon required. They read .codepakt/data.db directly.

4. Start the server (for task coordination)

Code intelligence is standalone. The server daemon is only needed for task coordination across concurrent agents:

cpk server start
Starting Codepakt server...
Server running on :41920 (PID: 34821)
  Version:  0.2.0

5. 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)

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

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

8. Open the dashboard

open http://localhost:41920

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

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

arrow_back
Previous
Installation
Next
cpk scan
arrow_forward