Installation — codepakt docs

Prerequisites

Node.js 20+ — codepakt uses modern Node APIs. Check your version with node --version.
macOS or Linux — Windows is not supported. WSL2 on Windows works but is untested.
npm — used only for the global install. The server itself uses no npm at runtime.

Install

npm i -g codepakt

Verify the install:

cpk --version

Expected output:

0.1.1

Start the server

cpk server start

The server forks and detaches — your terminal returns immediately. It runs on port 41920 by default.

Verify it’s running:

cpk server status

Expected output:

Server running on :41920 (PID: 12345)
  Version:  0.1.1

Data directory

codepakt stores everything in ~/.codepakt/:

File	Purpose
`~/.codepakt/index.json`	Global project index — lists all registered projects, their paths, and schema versions
`~/.codepakt/server.pid`	PID file for the running daemon
`~/.codepakt/server.log`	Server access and error logs. View with `cpk server logs` or `cpk server logs -f` to follow.

Each project also has its own database:

File	Purpose
`<project>/.codepakt/data.db`	Per-project SQLite database (WAL mode) — tasks, agents, events, docs
`<project>/.codepakt/config.json`	Project-specific CLI configuration (server URL, project ID)
`<project>/.codepakt/AGENTS.md`	Generated agent protocol + roster — committed to git
`<project>/.codepakt/CLAUDE.md`	Generated Claude Code coordination instructions — committed to git

This directory is created automatically on first cpk server start. You do not need to create it manually.

Project configuration

When you run cpk init inside a project, codepakt creates .codepakt/config.json in your project root. This file tells the CLI where the server is and which project is active:

{
  "url": "http://localhost:41920",
  "project_id": "proj_abc123"
}

Port configuration

If port 41920 conflicts with something else, override it:

CPK_PORT=8080 cpk server start

Or set it permanently in your shell profile:

export CPK_PORT=8080

All cpk commands respect CPK_PORT automatically, so you don’t need to update .codepakt/config.json.

View server logs

cpk server logs           # Last 50 lines
cpk server logs -f        # Follow in real time
cpk server logs -n 200    # Last 200 lines

Stop the server

cpk server stop

Next steps

Your First Project — create tasks, coordinate agents, run the full loop
cpk server reference — full flag documentation