codebyplan

CLI for CodeByPlan — AI-powered development planning and tracking.

Installation

npx codebyplan setup

This will:

1. Sign you in via OAuth (a browser window opens automatically; no API key needed)
2. Configure Claude Code to connect via remote MCP
3. Optionally link a repository

Commands

codebyplan setup

Interactive setup wizard. Authenticates via OAuth and configures the MCP server connection.

codebyplan config

Sync repo configuration from the CodeByPlan database to .codebyplan.json. Updates server_port, server_type, branch_config, and port_allocations. Also runs the worktree self-heal to cache the active worktree ID in memory.

Options:

| Flag | Description | | ------------------ | ------------------------------------------------ | | --path <dir> | Project root directory (default: cwd) | | --repo-id <uuid> | Repository ID (default: from .codebyplan.json) | | --dry-run | Preview changes without writing |

Example:

codebyplan config
codebyplan config --dry-run

codebyplan ports

Verify port allocations match local package.json dev scripts. Reports mismatches and unallocated apps. With --fix, auto-creates missing port allocations in the database.

Options:

| Flag | Description | | ------------------ | ------------------------------------------------ | | --path <dir> | Project root directory (default: cwd) | | --repo-id <uuid> | Repository ID (default: from .codebyplan.json) | | --dry-run | Preview changes without writing | | --fix | Auto-create missing port allocations |

Example:

codebyplan ports
codebyplan ports --fix
codebyplan ports --fix --dry-run

codebyplan tech-stack

Detect and sync tech stack dependencies from all package.json files in the project. Also runs the local config migration to move any legacy worktree_id from .codebyplan.json to the gitignored .codebyplan.local.json.

Options:

| Flag | Description | | ------------------ | ------------------------------------------------ | | --path <dir> | Project root directory (default: cwd) | | --repo-id <uuid> | Repository ID (default: from .codebyplan.json) | | --dry-run | Preview changes without writing |

Example:

codebyplan tech-stack
codebyplan tech-stack --dry-run

codebyplan help

Show help message.

codebyplan --version

Print the CLI version.

MCP Server

Claude Code connects to CodeByPlan via a remote MCP server. The setup command configures this automatically:

{
  "mcpServers": {
    "codebyplan": {
      "type": "http",
      "url": "https://mcp.codebyplan.com/mcp"
    }
  }
}

Authentication is handled via OAuth Bearer — no API key is stored in this file.

Learn More

• codebyplan.com