Set up a coding agent

Configure Claude Code, Cursor, or Codex to use Affitor's local tracking MCP server in your project. CLI 0.4.5 adds a preview, an explicit apply step, and a read-only static check.

This uses a program API key for integration work. To read account reports through the hosted server with Affitor sign-in, use Connect your AI app instead.

1. Preview the selected clientCopy Anchor Link

Run from your app's project root. This example selects Claude Code; replace claude_code with cursor or codex for your client.

npx affitor@0.4.5 agent setup --client claude_code --dry-run --json

The output has status: "planned", file paths, operations, backup paths, and any manual instructions. It does not include existing config contents or write files. Repeat --client to select multiple clients from your own terminal.

When a coding agent invokes setup, it can configure only itself. Without --client, a detected caller selects itself; otherwise an interactive terminal asks you to select clients. Finding a client directory alone never selects it.

2. Apply the reviewed planCopy Anchor Link

After reviewing the preview, run:

npx affitor@0.4.5 agent setup --client claude_code --yes --json

Unlike onboard --json, agent setup --yes --json writes files. Without --yes or --auto-confirm, an interactive run asks before applying; a JSON or non-interactive run returns needs_confirmation and exits 1.

Setup writes .affitor/agent-mcp.cjs and Git ignore rules for local credentials and backups. For Claude Code and Cursor, it preserves other MCP entries and sets the entry named affitor. Existing files it changes get a private first snapshot under .affitor/backups/; an earlier snapshot is kept on later runs.

The generated MCP entry contains this machine's absolute project path. Keep it local or regenerate it on each teammate's machine. A successful apply reports needs_human, not a verified connection.

For Codex, follow the printed manual MCP instructions after applying. On Windows, the output gives a command and exact argument for Codex MCP settings instead of a shell command. Setup does not edit Codex's MCP settings for you.

3. Configure the program key privatelyCopy Anchor Link

Make the program's AFFITOR_API_KEY available to the agent process, or keep one AFFITOR_API_KEY assignment in this project's .affitor/.env. Use a program API key, not your account login token. Never paste the key into a prompt, MCP JSON, or Git.

The launcher reads the environment first, then .affitor/.env. It starts the pinned @affitor/mcp@0.2.2 server when your client launches it and keeps sale/refund tools disabled. Setup itself does not start an agent session or call the Affitor API.

4. Check the local filesCopy Anchor Link

npx affitor@0.4.5 doctor --client claude_code --json

doctor reads local configuration without editing files or calling Affitor. It checks AFFITOR_API_KEY in the environment or .affitor/.env; the global --api-key and --api-url flags do not change this check.

The top-level result is aligned with exit 0 only when every checked client has aligned files, a present_unverified credential, and no warnings. Otherwise it reports needs_attention and exits 1. Codex stays manual in this static check, including after you configure it yourself.

5. Check the restarted agentCopy Anchor Link

Restart the selected coding agent so it loads the new configuration, then ask it:

Call affitor_readiness. Confirm the program identity and report the returned checks.
Do not run synthetic verification or other writes without asking me first.

doctor always reports mode: "static" and liveSession: "not_checked". File alignment, a working agent connection, and integration_verified are separate results. Follow the readiness checks before claiming the integration works.

RelatedCopy Anchor Link

• CLI command reference: flags, JSON statuses, and exit codes.
• Program API keys: obtain and replace the program credential.
• Testing integration: verify tracking after deployment.
• Hosted MCP server: account sign-in and read-only reporting.