clankr

Run coding agents in isolated Docker containers.

Supports multiple agent harnesses:

• claude — Claude Code (--dangerously-skip-permissions without the danger)
• pi — pi coding agent (badlogic/pi-mono)

install

uv tool install clankr

setup

clankr init
# prompts for: github username, bot username, PAT, default harness

Create a classic PAT on the bot account with repo scope.

per-repo setup (recommended)

clankr setup-repo user/project
# then accept the invitation (log in as bot → github.com/notifications)

This adds the bot as a collaborator and configures the repo with:

• Branch protection: PRs required for main, owner bypasses
• Squash merge only, auto-delete branch on merge

This step is optional — agents work without it, but branch protection prevents them from pushing directly to main.

pi auth

Pi authenticates via ~/.pi/agent/auth.json (OAuth or API key). Options:

• API key: set ANTHROPIC_API_KEY in your environment — pi reads it directly
• pi OAuth: run pi → /login to authenticate with a provider
• clankr auth: convert Claude CLI OAuth tokens to pi format (use at your own risk)

usage

clankr launch user/project                        # interactive, bare profile, default harness
clankr launch -H pi user/project                  # use pi harness
clankr launch -p my-profile user/project          # custom configuration profile
clankr launch -d user/project                     # detached (tmux)
clankr launch -d -s auth-fix user/project         # named slot
clankr launch /path/to/local/repo                 # local repo

clankr run user/project -- -p "prompt"                # non-interactive, stdout capture
clankr run /path/to/repo -p ./profile -- -p "prompt"  # local repo, custom profile path

clankr sync user/project /path/to/host/repo       # register session sync mapping
clankr sync                                       # list sync mappings

clankr resume project-1                           # relaunch a stopped slot
clankr attach project-1                           # reattach to detached agent
clankr save project-1 /path/to/host/repo          # export sessions to host
clankr ls                                         # list slots
clankr rm project-1                               # remove (warns if unpushed)
clankr clean                                      # remove all stopped clean slots

$ clankr ls
SLOT                 HARNESS  PROFILE  STATUS       SYNC   REPO
hello-world-1        claude   bare     detached     yes    /home/max/.local/share/clankr/repos/hello-world-1
project-2            pi       bare     running      -      /home/max/.local/share/clankr/repos/project-2
project-1            claude   bare     stopped      -      /home/max/.local/share/clankr/repos/project-1

profiles

Each profile is an agent config — settings, init scripts, host mounts. Clankr ships with one profile (bare); for a real-life example see e.g. MaxWolf-01/agents.

-p takes a profile name (looked up in ~/.config/clankr/profiles/) or a path to a profile directory. Each profile is a directory with any of:

• CLAUDE.md — context file for Claude Code harness
• AGENTS.md — context file for pi (and other) harnesses. If only one exists, it's used for both.
• claude.settings.json — Claude Code settings
• pi.settings.json — pi settings. An env key here is extracted by clankr and passed as docker --env (pi ignores unknown keys; this is how we get env vars in since pi's schema has no native env field)
• pi.SYSTEM.md — pi system prompt override (pi's default prompt triggers Anthropic's subscription-blocking detection; see agent/knowledge/pi-auth.md)
• init — executable script that runs inside the container before the agent starts
• mounts — bind-mount host paths into the container (one per line: source:destination[:ro|rw], default rw, ~ expanded, ./ relative to profile dir)

clankr profiles                                   # list available profiles
cp -r ~/.config/clankr/profiles/bare ~/.config/clankr/profiles/my-custom
vim ~/.config/clankr/profiles/my-custom/CLAUDE.md

how it works

• each slot gets its own repo clone and agent config
• harness: -H selects the agent runtime (claude, pi). Default configurable via clankr init
• session sync: sessions bind-mounted to the host for the active harness's session layout — synced slots mirror the host repo path inside the container, so sessions show up natively in claude --resume from that path on the host
• session preservation: rm/clean auto-archive sessions before deleting (--purge to skip)
• credentials copied fresh from host on each launch (Claude: ~/.claude/.credentials.json, pi: ~/.pi/agent/auth.json)
• -d wraps the container in a tmux session — survives SSH disconnects
• git identity: configurable bot account with scoped PAT
• branch protection via setup-repo: require PR + approval for main, owner bypasses, squash-only merges

commands

paths