how to contribute debugging

Debugging

This page points at where state and logs live and how to diagnose the failures most likely to block a contribution. It complements Testing, which covers how to reproduce with the faux provider.

Where state and logs live

• Agent config, sessions, and diagnostic logs live under the agent config directory ~/.prime/agent/. Logs are written to ~/.prime/agent/logs/ (for example agent.jsonl); the path is derived in packages/coding-agent/src/config.ts.
• The IPython kernel venv is ~/.prime/agent/kernel-venv by default, overridable with the PRIME_AGENT_KERNEL_VENV environment variable.
• Auth and provider configuration are read from environment variables and ~/.prime/config.json; see Getting started and the configuration reference (../reference/index.md).

Inspecting the daemon

• prime-agent status shows background service state (running, idle, and saved sessions).
• prime-agent doctor [--fix] inspects and, with --fix, repairs background services, including node version and kernel runtime problems.
• Use ps to find running daemon processes before killing or restarting anything; be careful not to disturb unrelated tmux sessions or background services.

Common failures

• Node version too old. Prime Agent requires Node >= 22.8.0, enforced by packages/coding-agent/src/cli/node-version-check.ts. If startup rejects the active node, install Node 22.8+ (for example nvm install 22 && nvm use 22).
• Missing Python or ipykernel. The kernel runtime needs Python >= 3.10. Install it and the prime-agent-runtime package (pip install -e prime-agent-runtime), or point at an existing environment with PRIME_AGENT_KERNEL_PYTHON. If the kernel venv is corrupt, remove ~/.prime/agent/kernel-venv so it is rebuilt.
• tsx resolution errors. Run tests from the package root and reference vitest through the root node_modules, as in npx tsx ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts. The ../../ assumes you are in a package directory under packages/.
• Port 3000 conflicts. The web dev server binds to 127.0.0.1:3000 by default. If another process owns the port, pass --host <host> --port <port> --cwd <directory> or stop the conflicting process.
• pnpm/npm workspace mixups. The root is the npm workspace (npm install); web/ is a separate pnpm workspace (pnpm install --dir web). Never npm install inside web/ and never pnpm install at the repo root. Mixing these produces resolution errors, especially for @earendil-works/* links.
• Protocol version mismatch. The daemon protocol version is DAEMON_PROTOCOL_VERSION = 8 in packages/coding-agent/src/modes/daemon/daemon-protocol.ts. Clients negotiate Math.min(hello.protocol.version, DAEMON_PROTOCOL_VERSION) on connect, so an old client and new daemon (or the reverse) may surface capability or command errors. Bumping the version for incompatible changes is governed by the policy in AGENTS.md; see Patterns and conventions and the wire protocol reference (../api/daemon-protocol.md).

Reproducing with the faux provider

For suite work in packages/coding-agent/test/suite/, drive scenarios through packages/coding-agent/test/suite/harness.ts plus the faux provider. This avoids real provider APIs, real API keys, and paid tokens. Use the harness to reproduce a reported bug before fixing it, then add a regression test under packages/coding-agent/test/suite/regressions/.

Related pages

• Testing, frameworks and how to run them
• Patterns and conventions, daemon protocol change policy
• Getting started, commands such as prime-agent status, doctor, shutdown
• Daemon protocol, wire protocol reference