run-claude-code

A small Python library to launch isolated Claude Code instances — an instance's only config is what you hand it. Nothing from ~/.claude (settings, hooks, CLAUDE.md, history, permissions) and no project .mcp.json leaks in. Login is the one thing carried across.

How the isolation works

| ambient config | lever (set for you) | |---|---| | MCP servers | --strict-mcp-config + an inline --mcp-config written per launch | | user ~/.claude (settings/hooks/CLAUDE.md/history/permissions) | CLAUDE_CONFIG_DIR=fresh throwaway dir | | project files | launch in a fresh/neutral work folder | | built-in tools (Bash/Edit/Write/Read/…) | per-instance settings.json permissions.deny — because --strict-mcp-config scopes MCP only, not the built-ins | | login | macOS Keychain is shared; if a ~/.claude/.credentials.json exists, only that file is copied in |

Fully-gated profiles. crankfix ships settings.permissions = {allow: ["mcp__gate"], deny: [built-ins]} so the instance can act only through the gate. That matters for telemetry: the gate forwards every {session,tool,intent} to congruency, so denying the built-ins is what makes "all its actions are logged" actually true (otherwise the agent could Bash/Edit around the gate, untelemetered).

Use

from runclaude import launch, build, get, render

launch(get("crankfix"))                       # interactive, fully isolated (exec-replaces this process)
launch(get("crankfix"), workdir="~/work/x")   # in a chosen folder
launch(get("crankfix"), headless_prompt="fix the auth bug")   # headless one-shot
print(render(build(get("crankfix"))))          # inspect the exact command + env, run nothing

CLI:

python -m runclaude crankfix                  # isolated interactive instance
python -m runclaude crankfix ~/work/fix1      # in a chosen work folder
python -m runclaude crankfix --print          # dry-run: show the command + env
python -m runclaude crankfix -p "fix bug X"   # headless
python -m runclaude list                       # list profiles

Profiles (runclaude/profiles.py)

- crankfix — the single-purpose "fix congruency, then crank" agent: the intent-gate scoped to registry.crankfix.json (crankfix-only) + the crankfix.md task brief. Every action is gated by memory and streamed to congruency (?route=agent.trail on :8899) for live monitoring. - suite — the full gate (crankimg + crankfix + bash decoy), unscoped.

Add your own: a Profile(name, mcp_servers=…, brief_path=…) registered in PROFILES.

Notes

- Needs the claude CLI on PATH (native installer: curl -fsSL https://claude.ai/install.sh | bash). - test_runclaude.py proves the isolation with build() alone — no claude needed to run it. - Flag spellings for settings/permissions can shift across Claude Code versions; confirm with claude --help. The isolation core (CLAUDE_CONFIG_DIR, --strict-mcp-config, --mcp-config) is stable.