Plandex v2.2.1: Terminal AI Coding Setup Guide

Two ways to get started with terminal AI coding using Plandex: sign up for Plandex Cloud, or self-host with Docker. Every tutorial written before October 2025 tells you to pick Cloud. That advice is dead – the README is unambiguous: Plandex Cloud is winding down as of 10/3/2025 and no longer accepting new users. Self-host with Docker Compose, bring your own OpenRouter key. That’s the only working path right now, and it’s what this guide covers.

What Plandex actually does differently

2M tokens of direct context. Another 20M indexed via tree-sitter project maps. That’s not a marketing figure – it means Plandex can hold an entire mid-size codebase in working memory while it plans a change, not just the three files you manually fed it. The other thing: AI changes land in a sandbox first. Nothing touches your project files until you approve the diff. If you’ve ever had Aider partially rewrite a file and leave it in a broken state mid-session, you know why that matters.

System requirements for v2.2.1

The CLI is a single Go binary – no runtime, no dependencies. The server is a different story.

Install the CLI

curl -sL https://plandex.ai/install.sh | bash

30 seconds. The script detects your architecture, pulls the matching tarball from GitHub releases, and drops the binary in your PATH.

Here’s the gotcha: if you had Plandex v1, the installer renames the old plandex command to plandex1 and pdx to pdx1. The v2 binary takes over the original names. Any shell scripts, Makefiles, or CI jobs that call plandex will now silently run v2. Grep your repo before you install – grep -r "plandex" .github/ Makefile scripts/ is a good start.

Prefer no piped bash? Download the binary for your platform directly from the releases page and drop it in /usr/local/bin. Same result.

Stand up the server with Docker Compose

git clone https://github.com/plandex-ai/plandex.git
cd plandex/app
docker compose up

That gives you a Postgres + server pair on the default local port. Leave it running. Second terminal:

plandex sign-in
# Choose "Local mode host" when prompted
# Confirm the default local address

Apple Silicon note: If you’re on an M-series Mac and the server container gets killed shortly after launch, the symptom is usually Docker Desktop hitting its memory ceiling. The server plus Postgres plus a warm tree-sitter cache needs headroom – bump Docker Desktop’s memory allocation up from the default if you’re seeing OOM kills.

First-time configuration: bring your own key

OpenRouter is the simplest path – one key, access to Claude, GPT-4o, Gemini, and open-source models.

export OPENROUTER_API_KEY=sk-or-v1-...
cd your-project
plandex

That’s the BYO key variable the quick-start docs specify. Not OPENAI_API_KEY – every older tutorial uses that and it won’t work for the multi-model setup.

Claude Pro/Max subscriber? As of v2.2.1, Plandex can pull from your Anthropic subscription when calling Claude models. The first time you run Plandex with a default model pack that uses Anthropic, it asks if you want to connect your subscription. Worth it if you’re already paying Anthropic $20/month and don’t want the API bill on top.

One cost trap: configure both a direct provider (OpenAI or Anthropic) and OpenRouter, and Plandex will fail over to OpenRouter if the direct call fails – that’s a v2.2.0 behavior documented in the release notes. Good for uptime. But check your OpenRouter dashboard occasionally. You can be spending there without realizing the direct calls were silently failing.

Verify the install

CLI version first:

plandex version
# Expected: 2.2.1 (or newer)

Server health? The advanced self-hosting docs document a /health endpoint – a GET request returns 200 when the server is ready:

curl -i http://localhost:8099/health

Then actually run something. Drop into a small project, launch plandex, ask it to “add a README section explaining how to run tests.” If you get a plan and a diff appears in the sandbox – you’re set.

Common errors

• “exec format error” after curl install: Architecture mismatch. Force the version: PLANDEX_VERSION=2.2.1 curl -sL https://plandex.ai/install.sh | bash, or grab the correct tarball manually from releases.
• “tree-sitter build error” (source builds only): Missing C toolchain. Debian/Ubuntu: apt install build-essential. Alpine: apk add gcc g++ make musl-dev.
• “connection refused” on the health endpoint: Postgres wasn’t ready when the server started. Wait 10 seconds, retry. Or: docker compose logs plandex-server to see what actually happened.
• Plandex hangs on Windows: You’re in PowerShell or CMD. There’s no workaround – move into WSL.
• REPL says “no model configured”: The OPENROUTER_API_KEY export didn’t persist across shell reloads. Add it to ~/.bashrc or ~/.zshrc.

There’s an open question the docs don’t answer clearly: what happens to in-progress plans if the server container restarts mid-task? The sandbox model suggests they’re stored in Postgres and survive a restart, but this isn’t explicitly confirmed anywhere in the self-hosting documentation as of mid-2025. Worth testing before you run Plandex against anything you can’t easily recover.

Upgrade and uninstall

Upgrade: re-run the install curl. It pulls the latest release and replaces the binary in place. Server: git pull, then docker compose up --build.

Uninstall is two steps. Binary: sudo rm /usr/local/bin/plandex. Server: docker compose down -v – the -v flag drops the Postgres volume, which wipes all stored plans and history. That’s permanent. If you kept the v1 binary as plandex1, remove that separately.

FAQ

Is Plandex still viable now that Cloud is shutting down?

Yes. v2.2.1 shipped after the Cloud sunset announcement. The open-source CLI and server are the maintained path forward.

How does Plandex compare to Aider for large codebases?

Say you’re refactoring auth across 40 files in a monorepo. Aider handles individual file edits well, but you’re manually feeding it context file by file. Plandex indexes the whole directory via tree-sitter maps, builds a multi-step plan, and stages every diff in the sandbox before touching anything. If your task fits in one or two files, Aider is lighter and faster to set up. Span a dozen files, and Plandex’s overhead starts paying for itself. The sandbox alone is worth it for risky refactors – you can review the full changeset before a single file is modified.

Can I use local models instead of paying OpenRouter?

Built-in Ollama support landed in v2.2.0 – so technically yes. The catch: multi-step planning is where model quality shows up most, and smaller local models (under ~30B parameters) tend to produce noticeably worse plans than Claude Sonnet or GPT-4o. The practical split that works for some setups: OpenRouter for the planning role, Ollama for the codegen role. Plandex supports assigning different models to different roles, which makes that combination possible without switching tools.

Next step: Clone the repo, run docker compose up, and give it a real task from your backlog – something you’ve been deferring for two weeks. That’s the fastest honest test of whether terminal AI coding fits how you work.