cpk generate

cpk generate produces two coordination files inside .codepakt/ from your current project and agent state. These files are committed to git and travel with the project.

Usage

cpk generate

Generating coordination files...
  .codepakt/AGENTS.md written
  AGENTS.md exists — not modified (codepakt manages .codepakt/AGENTS.md)
  .codepakt/CLAUDE.md written
  CLAUDE.md created (imports .codepakt/CLAUDE.md)

No flags. It always generates both files.

What gets generated

.codepakt/AGENTS.md

The portable coordination file — readable by any AI coding agent (Claude Code, Codex, Cursor, Copilot).

Contains:

Session start — commands to run at the start of every session
Complete command reference — every cpk command with examples
Task lifecycle — status flow diagram
Rules — critical gotchas (e.g. “command is task add, NOT task create”)
Active agents — snapshot of who has interacted with the project

.codepakt/CLAUDE.md

Claude Code-specific instructions. Takes advantage of Claude Code’s @import feature for automatic loading. Same content as AGENTS.md — both are generated from the same templates.

Root file handling

Codepakt owns the files inside .codepakt/. Your root files are yours.

On first run (root files don’t exist):

File	Created with
`CLAUDE.md`	`@import .codepakt/CLAUDE.md` — Claude Code loads it automatically
`AGENTS.md`	A pointer comment: “See .codepakt/AGENTS.md for the agent protocol”

On subsequent runs (root files exist):

Codepakt regenerates .codepakt/AGENTS.md and .codepakt/CLAUDE.md. For root CLAUDE.md, it will prepend @import .codepakt/CLAUDE.md if not already present. Root AGENTS.md is never modified after creation.

This means you can add your own project-specific instructions to the root CLAUDE.md or AGENTS.md without codepakt overwriting them.

File ownership model

my-project/
├── CLAUDE.md                    ← YOU own this (add @import + your own rules)
├── AGENTS.md                    ← YOU own this (pointer or custom content)
└── .codepakt/
    ├── AGENTS.md                ← codepakt owns — safe to regenerate
    ├── CLAUDE.md                ← codepakt owns — safe to regenerate
    ├── config.json              ← git-ignored
    ├── data.db                  ← git-ignored
    └── .gitignore               ← only ignores config.json + *.db

.gitignore

cpk generate updates .codepakt/.gitignore to only ignore ephemeral files:

config.json
*.db
*.db-wal
*.db-shm

The .md files inside .codepakt/ are not ignored — they should be committed to git. They’re project documentation, not local state.

When to regenerate

Regenerate whenever:

A new agent starts interacting with the project
The CLI is updated to a new version
You set up the project for the first time

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

Backward compatibility

cpk agents-md generate still works — it calls cpk generate internally.

cpk agent list — see agents that have interacted with the project
AGENTS.md concept — what agents do with this file
Installation — file locations and data directory