Skip to content

Quick Start

Get CodePlane running and complete your first supervised agent job. No editor required — just a terminal and a browser.

Install

pip install codeplane

Verify the installation:

cpl doctor

This checks that Python, Git, and your agent CLIs are installed and authenticated.

Prerequisites
Requirement Details
Python 3.11 or later
Git Any recent version
Agent CLI At least one installed and authenticated: GitHub Copilot CLI or Claude Code CLI

You also need a local Git repository to run jobs against.

Start the Server

cpl up

Open http://localhost:8080 in your browser.

For remote access (phone, tablet, another machine):

cpl up --remote                    # auto-generates a password
cpl info                           # prints URL + QR code

A password is always required for remote access — one is generated automatically unless you set it with --password or the CPL_PASSWORD env var. See Configuration > Remote Access for Cloudflare Tunnels and other options.

Security

CodePlane is secure by default — localhost-only binding, password-protected remote access, and agents isolated in dedicated worktrees. See Security for the full threat model and best practices.

First-time setup

The first time cpl up is run, cpl setup will be triggered automatically — it walks you through registering your first repository and setting preferences.

Register a Repository

Go to Settings (Ctrl+,) and add a local Git repository path. This tells CodePlane which codebases it can work against.

Create Your First Job

  1. Press Alt+N or click New Job
  2. Write a prompt — e.g., "Add input validation to the user registration endpoint"
  3. Select the repository, agent CLI, and model
  4. Click Create Job

The agent starts working in an isolated Git worktree. Your working directory is never modified.

Watch It Run

The job detail view shows live updates:

  • Activity panel — hierarchical view of what the agent is doing, grouped by task
  • Transcript — the agent's reasoning and tool calls with per-turn intent
  • Plan — the agent's planned steps and progress
  • Metrics — token usage, live cost badge, and activity-based cost breakdown

Handle Approvals

Whether the agent pauses for approval depends on the action policy preset:

Preset Behavior
autonomous Most actions proceed — only non-contained operations require approval
supervised Contained, reversible actions proceed; writes and mutations require approval (default)
locked All actions checkpoint or gate — maximum oversight

You can set the preset per-job, globally in Settings → Policy, or via the API — see Configuration.

When an approval prompt appears, choose:

  • Approve — allow this action
  • Reject — block it; the agent may try an alternative
  • Trust Session — auto-approve all remaining actions for this job

Review & Merge

When the agent finishes, review the diff:

Then resolve the job:

Option What it does
Merge Cherry-pick only the agent's meaningful commits onto the base branch, skipping setup noise
Create PR Push the branch and open a pull request
Discard Delete the worktree and discard all changes

Remote Access

Access CodePlane from your phone or any other device:

cpl up --remote                              # Dev Tunnels (default)
cpl up --remote --provider cloudflare        # Cloudflare Tunnels
cpl up --phone                               # shortcut for --remote

The UI is fully responsive — monitor jobs, approve actions, and send messages from anywhere.

CodePlane is a Progressive Web App — on mobile browsers you can "Add to Home Screen" for a native-like experience with push notifications.

What's Next