pi-claude-agent

Pi extension that delegates work to the local Claude Code CLI.

It adds one tool, claude_agent, that can run Claude in either:

• backend: "tmux" — interactive Claude in a tmux session or pane, with artifacts written to disk.
• backend: "print" — claude --print --output-format stream-json, streamed back to Pi.

The tmux backend is the main feature: it uses the same working directory as Pi, writes an inspectable artifact directory, and can run hidden or in a visible split pane.

Install

Prerequisites:

• Pi
• Claude Code available as claude
• tmux for the default backend: "tmux". If you do not use tmux, set backend: "print".

Install from GitHub:

pi install git:github.com/liamvinberg/pi-claude-agent@v0.1.1

For a local checkout:

pi install /path/to/pi-claude-agent

Usage

Ask Pi to delegate to Claude:

Use claude_agent to inspect this repository and suggest one cleanup.

Explicit tmux run:

{
  "backend": "tmux",
  "task": "Inspect this repository and summarize the package structure."
}

Watch Claude in a visible tmux split:

{
  "backend": "tmux",
  "tmux_display": "pane",
  "task": "Review the current diff."
}

Leave the tmux session or pane open after completion:

{
  "backend": "tmux",
  "tmux_display": "pane",
  "autoclose": false,
  "task": "Investigate this failing test."
}

Resume a previous Claude session:

{
  "backend": "tmux",
  "resume_session_id": "00000000-0000-0000-0000-000000000000",
  "task": "Continue from the previous investigation."
}

Use a custom MCP config:

{
  "backend": "tmux",
  "mcp_config": "./claude-mcp.json",
  "strict_mcp_config": true,
  "allowed_tools": ["mcp__example__tool"],
  "task": "Use the configured MCP server to answer the question."
}

Options

Common options:

• task — delegated task for Claude.
• backend — "tmux" or "print". Default: tmux.
• cwd — working directory. Default: Pi's current cwd.
• model — Claude model or alias. Omitted by default, so Claude CLI chooses its default.
• resume_session_id — Claude session id returned by a prior run.
• timeout_seconds — run timeout. Default: 300.
• sandbox_mode — "read-only" or "default". Default: read-only.
• permission_mode, tools, allowed_tools — forwarded to Claude permission/tool flags.
• mcp_config, strict_mcp_config — generic Claude MCP config. No MCP profiles are built in.

Tmux options:

• tmux_display — "detached" or "pane". Default: detached.
• autoclose — close the tmux target when done. Default: true.
• output_dir — artifact directory. Default: a temporary pi-claude-agent-* directory.
• tmux_session_name — optional name for detached sessions.

Optional environment overrides:

export PI_CLAUDE_COMMAND=claude
export PI_CLAUDE_AGENT_BACKEND=print
export PI_CLAUDE_AGENT_TMUX_DISPLAY=pane
export PI_CLAUDE_AGENT_MODEL=sonnet
export PI_CLAUDE_AGENT_TIMEOUT_SECONDS=600

Artifacts

Tmux runs write files such as:

• task.md — delegated task
• instructions.md — run instructions for Claude
• final.md — final assistant message captured by the Stop hook
• ready.json, done.json — lifecycle markers
• hook-events.jsonl — Claude hook events
• tmux-capture.txt — recent tmux pane capture

Pi returns the artifact directory path in the tool result. Artifacts may contain prompts, local paths, Claude transcript paths, and hook event metadata. Treat them as local debugging output, not sanitized logs.

Security

This extension runs your local claude CLI with your local Claude credentials and filesystem access. The default sandbox_mode: "read-only" limits Claude's built-in tools, but it is not an OS sandbox. Review requested permissions before enabling write tools or bypass permissions.

License

MIT