Docs Case Studies

Agent Setup

AI coding agents sometimes overwrite project files — including CLAUDE.md and AGENTS.md. When this happens, the agent loses visibility into the codepakt protocol and stops coordinating. This page covers how to set up each agent so the protocol survives.

The problem

When you run cpk generate, codepakt creates:

my-project/
├── CLAUDE.md                ← @import .codepakt/CLAUDE.md (your file)
├── AGENTS.md                ← pointer to .codepakt/AGENTS.md (your file)
└── .codepakt/
    ├── CLAUDE.md             ← full protocol (codepakt owns this)
    ├── AGENTS.md             ← full protocol (codepakt owns this)
    ├── config.json           ← git-ignored
    └── data.db               ← git-ignored

The files inside .codepakt/ are safe — codepakt manages them and cpk generate regenerates them. The risk is with the root files:

  • An agent rewrites CLAUDE.md and drops the @import .codepakt/CLAUDE.md line
  • An agent deletes AGENTS.md or replaces it with unrelated content
  • A tool (formatter, linter, template generator) overwrites root markdown files

Once the @import line is gone, the agent can no longer see the codepakt protocol.

Recovery

If coordination files get overwritten, run:

cpk generate

This regenerates .codepakt/AGENTS.md and .codepakt/CLAUDE.md. If root CLAUDE.md exists but is missing the @import line, cpk generate automatically prepends it.

If root CLAUDE.md was deleted entirely, cpk generate recreates it with the @import line.

Prevention: per-agent setup

Claude Code

Claude Code reads CLAUDE.md from the project root and supports @import directives. The @import .codepakt/CLAUDE.md line loads the full codepakt protocol automatically.

To protect it:

Add this rule to the top of your root CLAUDE.md:

@import .codepakt/CLAUDE.md

# Project Instructions

> IMPORTANT: Never remove or modify the @import line above.
> It loads the codepakt coordination protocol.
> If you need to update coordination files, run `cpk generate`.

Claude Code respects instructions in CLAUDE.md — telling it not to remove the import line is usually sufficient.

Alternative: use project-level Claude settings

If you use .claude/settings.json in your project, you can add the codepakt protocol as a system instruction that can’t be overwritten by agents:

{
  "permissions": {
    "deny": [".codepakt/*"]
  }
}

This prevents Claude Code from modifying files inside .codepakt/, ensuring the protocol source stays intact.

OpenAI Codex

Codex reads AGENTS.md from the project root. It does not support @import, so it needs the full protocol in a file it can see.

Option 1: Direct reference in AGENTS.md

Edit your root AGENTS.md to include the full protocol rather than a pointer:

# Copy the generated protocol to root AGENTS.md
cp .codepakt/AGENTS.md AGENTS.md

Run this after every cpk generate. The downside: if Codex overwrites AGENTS.md, you lose the protocol until you copy again.

Option 2: Include protocol in the system prompt

When launching Codex, include the codepakt protocol in the task instructions:

Before starting, read .codepakt/AGENTS.md for the task coordination protocol.
Follow it exactly. Use `cpk` commands to pick up and complete tasks.
Set your agent name: export CPK_AGENT=codex

This is resilient to file overwrites because the instruction lives in the prompt, not the filesystem.

Cursor

Cursor reads .cursorrules or .cursor/rules for project instructions.

Setup:

Create .cursorrules in your project root:

# Codepakt Coordination

This project uses codepakt for task coordination. Before starting work:

1. Read `.codepakt/AGENTS.md` for the full protocol
2. Set your agent name: `export CPK_AGENT=cursor`
3. Check existing work: `cpk task mine --agent cursor`
4. Pick up a task: `cpk task pickup --agent cursor`
5. When done: `cpk task done <id> --agent cursor --notes "..."`
6. If blocked: `cpk task block <id> --agent cursor --reason "..."`

Never modify files inside `.codepakt/` directly. Run `cpk generate` to update.

Cursor does not modify .cursorrules, so this is safe from overwrites.

Generic agents (scripts, custom tools)

For any agent that runs bash commands, add the protocol to the agent’s startup script:

#!/bin/bash
export CPK_AGENT="my-agent"

# Ensure coordination files are current
cpk generate

# Check for existing work
cpk task mine --agent "$CPK_AGENT"

# Main agent loop
while true; do
  TASK=$(cpk task pickup --agent "$CPK_AGENT")
  if [ -z "$TASK" ]; then
    echo "No tasks available"
    break
  fi

  TASK_ID=$(echo "$TASK" | jq -r '.task_number')
  echo "Working on $TASK_ID"

  # ... do the work ...

  cpk task done "$TASK_ID" --agent "$CPK_AGENT" --notes "completed"
done

Git protection

Commit the codepakt coordination files to git so they can be restored:

git add .codepakt/AGENTS.md .codepakt/CLAUDE.md AGENTS.md CLAUDE.md
git commit -m "chore: add codepakt coordination files"

If an agent overwrites them, git checkout restores them instantly:

git checkout -- CLAUDE.md AGENTS.md

The .codepakt/.gitignore already ensures config.json and *.db are excluded while .md files are committed.

Session start checklist

Every agent session should begin with:

cpk server status                    # Ensure server is running
cpk generate                         # Refresh coordination files
cpk task mine --agent <name>         # Check assigned tasks
cpk task list --status open          # See available work

Including cpk generate at session start ensures the protocol is always current, even if files were overwritten in a previous session.

arrow_back
Previous
Dashboard
Next
Architecture
arrow_forward