pcode

pcode is a terminal-native coding agent built for long-running and parallel work. Background commands wake the agent when they finish, every session can use its own git worktree, conversations can be rewound and forked, and every tool call stays inspectable.

• Slow work doesn't block you. Long commands become background jobs, and a finished job wakes the agent, so it can watch tests or CI and fix what fails.
• Agents in parallel. A git worktree per session lets several agents work on one repo at once.
• Rewind and fork. /tree returns to any point in a conversation and branches from there. Every session is kept, so you can resume or search it.
• Nothing hidden. /tools shows every command the agent ran and its full output, and scrollback re-renders to show or fold every command and diff.

It runs on any model Pydantic AI supports, or on your Claude or ChatGPT subscription.

Documentation: cruxwell.github.io/pcode

Install

With Homebrew:

brew tap cruxwell/pcode https://github.com/cruxwell/pcode.git
brew install cruxwell/pcode/pcode

Or from PyPI with uv:

uv tool install 'pcode[claude]'

brew install --HEAD tracks master instead of the latest release.

Quick start

codex login                                  # or /login [claude|openai-codex] inside pcode, or export a provider API key
pcode -m openai-codex:gpt-5.6-luna           # interactive; /model (Ctrl+L) saves a default
pcode                                        # reuses the saved model, or opens the offline preview
pcode -C /path/to/repo "Summarize the open TODOs"
git diff | pcode -p --no-save                # non-interactive: reply to stdout
pcode --continue                             # resume this directory's newest session
pcode --theme-preview                        # offline sample output and the style gallery

Live mode edits files and runs shell commands with your permissions and no approval prompt. Read tool permissions before pointing it at anything you care about.

More

• Your subscription: Claude runs through Anthropic's own Agent SDK and Claude Code login, the way Anthropic supports, and ChatGPT through a Codex login. See providers.
• Email remote control: send a task from Gmail on your phone, reply to keep going, and take the session over at a terminal with pcode --attach.
• Custom keybindings and Vim editing: map keys to commands with arguments, add a Space leader in normal mode, or use jj to leave insert mode.
• /btw side questions, background sessions, recall of past sessions, a browser the agent can drive, and Python extensions.
• Pydantic AI's Harness coder capabilities, with the rest of a finished agent on top: MCP with OAuth and tool search, searchable sessions, jobs, worktrees. Extensions are plain Pydantic AI capabilities. The conversation tree follows pi's.

See PLAN.md for the longer-term direction.

Documentation

The same pages build into a browsable site with make docs-serve; make docs checks every page and anchor link.

Contributing

Bugs: open an issue. Security problems: see SECURITY.md. Setup and checks are in CONTRIBUTING.md.

make test        # fast suite; real-tmux regressions skipped
make test-all    # everything, before touching layout, streaming, the editor, or the prompt

AGENTS.md has the worktree workflow and the traps worth knowing before editing. Contributor notes (architecture, dependencies, profiling, prompt caching, provider design) live in dev/, outside the published docs.