The quickest way to get started is to grab an API key for your preferred provider such as Anthropic, OpenAI, Groq, OpenRouter, or Vercel AI Gateway and just start Codeplane. You'll be prompted to enter your API key.

That said, you can also set environment variables for preferred providers.

If you prefer subscription-based usage, here are some plans that work well in Codeplane:

• Synthetic
• GLM Coding Plan
• Kimi Code
• MiniMax Coding Plan

Codeplane runs great with no configuration. That said, if you do need or want to customize Codeplane, configuration can be added either local to the project itself, or globally, with the following priority:

1. .codeplane.toon
2. codeplane.toon
3. $HOME/.config/codeplane/codeplane.toon

Configuration itself is stored as a TOON object:

As an additional note, Codeplane also stores ephemeral data, such as application state, in one additional location:

# Unix
$HOME/.local/share/codeplane/codeplane.json

# Windows
%LOCALAPPDATA%\codeplane\codeplane.json

Codeplane can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:

{
  "$schema": "https://charm.land/codeplane.json",
  "lsp": {
    "go": {
      "command": "gopls",
      "env": {
        "GOTOOLCHAIN": "go1.24.5"
      }
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "nix": {
      "command": "nil"
    }
  }
}

Codeplane also supports Model Context Protocol (MCP) servers through three transport types: stdio for command-line servers, http for HTTP endpoints, and sse for Server-Sent Events. Environment variable expansion is supported using $(echo $VAR) syntax.

{
  "$schema": "https://charm.land/codeplane.json",
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "timeout": 120,
      "disabled": false,
      "disabled_tools": ["some-tool-name"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "timeout": 120,
      "disabled": false,
      "disabled_tools": ["create_issue", "create_pull_request"],
      "headers": {
        "Authorization": "Bearer $GH_PAT"
      }
    },
    "streaming-service": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "timeout": 120,
      "disabled": false,
      "headers": {
        "API-Key": "$(echo $API_KEY)"
      }
    }
  }
}

Codeplane respects .gitignore files by default, but you can also create a .codeplaneignore file to specify additional files and directories that Codeplane should ignore. Legacy .crushignore and .smithersignore files are still honored during migration. This is useful for excluding files that you want in version control but don't want Codeplane to consider when providing context.

The .codeplaneignore file uses the same syntax as .gitignore and can be placed in the root of your project or in subdirectories.

By default, Codeplane will ask you for permission before running tool calls. If you'd like, you can allow tools to be executed without prompting you for permissions. Use this with care.

{
  "$schema": "https://charm.land/codeplane.json",
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep",
      "edit",
      "mcp_context7_get-library-doc"
    ]
  }
}

You can also skip all permission prompts entirely by running Codeplane with the --yolo flag. Be very, very careful with this feature.

If you'd like to prevent Codeplane from using certain built-in tools entirely, you can disable them via the options.disabled_tools list. Disabled tools are completely hidden from the agent.

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "disabled_tools": ["bash", "sourcegraph"]
  }
}

To disable tools from MCP servers, see the MCP config section.

If you'd like to prevent Codeplane from using certain skills entirely, you can disable them via the options.disabled_skills list. Disabled skills are hidden from the agent, including builtin skills and skills discovered from disk.

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "disabled_skills": ["codeplane-config"]
  }
}

Codeplane supports the Agent Skills open standard for extending agent capabilities with reusable skill packages. Skills are folders containing a SKILL.md file with instructions that Codeplane can discover and activate on demand.

The global paths we looks for skills are:

• $CODEPLANE_SKILLS_DIR
• $XDG_CONFIG_HOME/agents/skills or ~/.config/agents/skills/
• $XDG_CONFIG_HOME/codeplane/skills or ~/.config/codeplane/skills/
• On Windows, we also look at
  • %LOCALAPPDATA%\agents\skills\ or %USERPROFILE%\AppData\Local\agents\skills\
  • %LOCALAPPDATA%\codeplane\skills\ or %USERPROFILE%\AppData\Local\codeplane\skills\
• Additional paths configured via options.skills_paths

On top of that, we also load skills in your project from the following relative paths:

• .agents/skills
• .codeplane/skills
• .claude/skills
• .cursor/skills

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "skills_paths": [
      "~/.config/codeplane/skills", // Windows: "%LOCALAPPDATA%\\codeplane\\skills",
      "./project-skills",
    ],
  },
}

You can get started with example skills from anthropics/skills:

# Unix
mkdir -p ~/.config/codeplane/skills
cd ~/.config/codeplane/skills
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . && rm -rf _temp

# Windows (PowerShell)
mkdir -Force "$env:LOCALAPPDATA\codeplane\skills"
cd "$env:LOCALAPPDATA\codeplane\skills"
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . ; rm -r -force _temp

Codeplane sends desktop notifications when a tool call requires permission and when the agent finishes its turn. They're only sent when the terminal window isn't focused and your terminal supports reporting the focus state.

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "disable_notifications": false, // default
  },
}

To disable desktop notifications, set disable_notifications to true in your configuration. On macOS, notifications currently lack icons due to platform limitations.

When you initialize a project, Codeplane analyzes your codebase and creates a context file that helps it work more effectively in future sessions. By default, this file is named AGENTS.md, but you can customize the name and location with the initialize_as option:

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "initialize_as": "AGENTS.md"
  }
}

This is useful if you prefer a different naming convention or want to place the file in a specific directory (e.g., CODEPLANE.md or docs/LLMs.md). Codeplane will fill the file with project-specific context like build commands, code patterns, and conventions it discovered during initialization.

By default, Codeplane adds attribution information to Git commits and pull requests it creates. You can customize this behavior with the attribution option:

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "attribution": {
      "trailer_style": "co-authored-by",
      "generated_with": true
    }
  }
}

• trailer_style: Controls the attribution trailer added to commit messages (default: assisted-by)
  • assisted-by: Adds Assisted-by: [Model Name] via Codeplane <[email protected]> (includes the model name)
  • co-authored-by: Adds Co-Authored-By: Codeplane <[email protected]>
  • none: No attribution trailer
• generated_with: When true (default), adds 💘 Generated with Codeplane line to commit messages and PR descriptions

Codeplane supports custom provider configurations for both OpenAI-compatible and Anthropic-compatible APIs.

Here’s an example configuration for Deepseek, which uses an OpenAI-compatible API. Don't forget to set DEEPSEEK_API_KEY in your environment.

{
  "$schema": "https://charm.land/codeplane.json",
  "providers": {
    "deepseek": {
      "type": "openai-compat",
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-chat",
          "name": "Deepseek V3",
          "cost_per_1m_in": 0.27,
          "cost_per_1m_out": 1.1,
          "cost_per_1m_in_cached": 0.07,
          "cost_per_1m_out_cached": 1.1,
          "context_window": 64000,
          "default_max_tokens": 5000
        }
      ]
    }
  }
}

Custom Anthropic-compatible providers follow this format:

{
  "$schema": "https://charm.land/codeplane.json",
  "providers": {
    "custom-anthropic": {
      "type": "anthropic",
      "base_url": "https://api.anthropic.com/v1",
      "api_key": "$ANTHROPIC_API_KEY",
      "extra_headers": {
        "anthropic-version": "2023-06-01"
      },
      "models": [
        {
          "id": "claude-sonnet-4-20250514",
          "name": "Claude Sonnet 4",
          "cost_per_1m_in": 3,
          "cost_per_1m_out": 15,
          "cost_per_1m_in_cached": 3.75,
          "cost_per_1m_out_cached": 0.3,
          "context_window": 200000,
          "default_max_tokens": 50000,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}

Codeplane currently supports running Anthropic models through Bedrock, with caching disabled.

• A Bedrock provider will appear once you have AWS configured, i.e. aws configure
• Codeplane also expects the AWS_REGION or AWS_DEFAULT_REGION to be set
• To use a specific AWS profile set AWS_PROFILE in your environment, i.e. AWS_PROFILE=myprofile codeplane
• Alternatively to aws configure, you can also just set AWS_BEARER_TOKEN_BEDROCK

Vertex AI will appear in the list of available providers when VERTEXAI_PROJECT and VERTEXAI_LOCATION are set. You will also need to be authenticated:

gcloud auth application-default login

To add specific models to the configuration, configure as such:

{
  "$schema": "https://charm.land/codeplane.json",
  "providers": {
    "vertexai": {
      "models": [
        {
          "id": "claude-sonnet-4@20250514",
          "name": "VertexAI Sonnet 4",
          "cost_per_1m_in": 3,
          "cost_per_1m_out": 15,
          "cost_per_1m_in_cached": 3.75,
          "cost_per_1m_out_cached": 0.3,
          "context_window": 200000,
          "default_max_tokens": 50000,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}

Local models can also be configured via OpenAI-compatible API. Here are two common examples:

{
  "providers": {
    "ollama": {
      "name": "Ollama",
      "base_url": "http://localhost:11434/v1/",
      "type": "openai-compat",
      "models": [
        {
          "name": "Qwen 3 30B",
          "id": "qwen3:30b",
          "context_window": 256000,
          "default_max_tokens": 20000
        }
      ]
    }
  }
}

{
  "providers": {
    "lmstudio": {
      "name": "LM Studio",
      "base_url": "http://localhost:1234/v1/",
      "type": "openai-compat",
      "models": [
        {
          "name": "Qwen 3 30B",
          "id": "qwen/qwen3-30b-a3b-2507",
          "context_window": 256000,
          "default_max_tokens": 20000
        }
      ]
    }
  }
}

Sometimes you need to look at logs. Luckily, Codeplane logs all sorts of stuff. Logs are stored in ./.codeplane/logs/codeplane.log relative to the project.

The CLI also contains some helper commands to make perusing recent logs easier:

# Print the last 1000 lines
codeplane logs

# Print the last 500 lines
codeplane logs --tail 500

# Follow logs in real time
codeplane logs --follow

Want more logging? Run codeplane with the --debug flag, or enable it in the config:

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "debug": true,
    "debug_lsp": true
  }
}

For deep runtime debugging, Codeplane can also expose a local observability endpoint with Prometheus metrics, pprof, expvar, and an in-memory recent span buffer:

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "observability": {
      "address": "127.0.0.1:9464",
      "trace_buffer_size": 1024,
      "trace_sample_ratio": 1
    }
  }
}

When enabled, the process serves:

• /metrics
• /debug/pprof/
• /debug/vars
• /debug/traces
• /debug/observability

The recent-span buffer and HTTP debug logs redact common secrets (tokens, authorization headers, API keys, cookies, and sensitive query parameters) so they are safer to use during production debugging. The metrics surface also includes visibility into pubsub/SSE fanout, permission backlog and queueing, background job lifecycle, database connect/migration steps, retries, and workspace lifecycle events.

You can also configure trace export to an OTLP/HTTP backend:

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "observability": {
      "otlp_endpoint": "http://localhost:4318",
      "otlp_insecure": true,
      "otlp_headers": {
        "Authorization": "Bearer example-token"
      }
    }
  }
}

By default, Codeplane automatically checks for the latest and greatest list of providers and models from Catwalk, the open source Codeplane provider database. This means that when new providers and models are available, or when model metadata changes, Codeplane automatically updates your local configuration.

For those with restricted internet access, or those who prefer to work in air-gapped environments, this might not be want you want, and this feature can be disabled.

To disable automatic provider updates, set disable_provider_auto_update into your codeplane.json config:

{
  "$schema": "https://charm.land/codeplane.json",
  "options": {
    "disable_provider_auto_update": true
  }
}

Or set the CODEPLANE_DISABLE_PROVIDER_AUTO_UPDATE environment variable:

export CODEPLANE_DISABLE_PROVIDER_AUTO_UPDATE=1

Manually updating providers is possible with the codeplane update-providers command:

# Update providers remotely from Catwalk.
codeplane update-providers

# Update providers from a custom Catwalk base URL.
codeplane update-providers https://example.com/

# Update providers from a local file.
codeplane update-providers /path/to/local-providers.json

# Reset providers to the embedded version, embedded into Codeplane at build time.
codeplane update-providers embedded

# For more info:
codeplane update-providers --help

Codeplane records pseudonymous usage metrics (tied to a device-specific hash), which maintainers rely on to inform development and support priorities. The metrics include solely usage metadata; prompts and responses are NEVER collected.

Details on exactly what’s collected are in the source code (here and here).

You can opt out of metrics collection at any time by setting the environment variable by setting the following in your environment:

export CODEPLANE_DISABLE_METRICS=1

Or by setting the following in your config:

{
  "options": {
    "disable_metrics": true
  }
}

Codeplane also respects the DO_NOT_TRACK convention which can be enabled via export DO_NOT_TRACK=1.

Installing an extra tool might be needed on Unix-like environments.

FSL-1.1-MIT

Part of Charm.

This project was originally forked from Charm's Crush TUI.