agentkit-pi-port

One-shot port of ALL AgentKit assets (~/.claude/) → Pi agent (~/.pi/agent/).

Hard constraint: AgentKit MUST be installed at ~/.claude/ before running. This tool is a local bridge — it never downloads AgentKit content from the internet, and it never modifies ~/.claude/.

Quick Start

# 1. Install AgentKit on your machine (prerequisite)
# 2. Install this tool
npm install -g agentkit-pi-port

# 3. Run the port
agentkit-pi-port

# 4. Use Pi with full AgentKit capabilities
pi
/ak-cook

What It Ports

| Asset | Action | |-------|--------| | Skills | Added to Pi's native skills path + registered as /ak-* commands via a generated extension | | Agents | Copied to ~/.pi/agent/agents/ for pi-sub-agent (tools:/model: frontmatter stripped — see below) | | Hooks | Bridged to Pi lifecycle events via generated hooks-bridge.ts, or documented as skipped | | Rules | Merged into ~/.pi/agent/AGENTS.md (a user-owned AGENTS.md is never overwritten) | | Settings | effortLevel → defaultThinkingLevel (Claude model aliases are not valid Pi model IDs and are not ported) |

MCP configs are not ported. Pi has first-class MCP support: pi install npm:pi-mcp-adapter, then /mcp setup imports existing host configs (including Claude Code's).

Options

agentkit-pi-port              # Full port
agentkit-pi-port --dry-run    # Preview only
agentkit-pi-port --force      # Overwrite existing (incl. user-owned AGENTS.md)
agentkit-pi-port --uninstall  # Remove everything
agentkit-pi-port --verbose    # Detailed output

How It Works

1. Prerequisite check — verifies ~/.claude/ exists with skills and agents
2. Discovery — catalogs all skills, agents, hooks, rules, settings
3. Install deps — pi install npm:pi-sub-agent for subagent support (skipped if a local subagent extension is already present)
4. Copy agents — agent .md files → ~/.pi/agent/agents/, stripping tools: and model: frontmatter (Claude tool names would intersect to an empty Pi tool allowlist; Claude model aliases are invalid Pi model IDs)
5. Create AGENTS.md — merges all rules with Pi adaptations; refuses to overwrite a file it didn't create
6. Setup skills — adds ~/.claude/skills to Pi's skills setting (Pi's documented pattern for Claude Code skills)
7. Install skill overrides — Pi-compatible SKILL.md variants → ~/.pi/agent/ak-skill-overrides/ (never into ~/.claude/)
8. Install extensions — three self-contained extensions into ~/.pi/agent/extensions/:
   • ak-commands.ts — discovers skills at session start, registers /ak-* commands (overrides take precedence)
   • ask-user.ts — ask_user tool for AgentKit's "ask_user capability"
   • hooks-bridge.ts — runs Claude Code .cjs hooks on Pi events + 3 native guards (sensitive-file blocking, descriptive filenames, exploration rate-limiting)
9. Port settings — effort level only, never overwriting existing Pi settings
10. Generate report — ~/.pi/agent/docs/agentkit-port-report.md
11. Verify — checks every artifact above; a failed check fails the port

Idempotent

Safe to re-run. Only rewrites files that changed (SHA-256 hash checked). Use --force to overwrite everything. New skills in ~/.claude/skills/ are picked up automatically at the next Pi session — the command extension discovers them at session start.

Uninstall

agentkit-pi-port --uninstall

Removes everything the tool created: extensions, ported agents, AGENTS.md (only if created by this tool), skill overrides, settings references, and pi-sub-agent. Also restores any SKILL.md.ak-original backups left in ~/.claude/skills/ by versions ≤1.0.0 (which incorrectly modified AgentKit skills in place — running any ≥1.1.0 command heals this automatically).

Testing

npm test

Runs the integration suite against a throwaway HOME fixture: full port, idempotent re-run, user-owned AGENTS.md guard, legacy-damage healing, and uninstall.

Requirements

• Node.js >= 18
• AgentKit installed at ~/.claude/
• Pi CLI installed (npm install -g --ignore-scripts @earendil-works/pi-coding-agent)