PiCraft

An opinionated workflow suite for the Pi coding agent.

The published npm package is pi-craft.

Install

pi install npm:pi-craft

If Pi still lists the historical npm:@losomz/picraft identity, remove it before installing npm:pi-craft; Pi treats the two npm names as different packages.

Restart Pi after installation, or run /reload in an existing Pi session.

Included Workflows

• Plan: a persistent planning mode with guarded write tools and explicit execution handoff.
• Questionnaire: structured intent clarification with single-choice, multiple-choice, and free-form answers in the Pi TUI.
• Permission: project-boundary and sensitive-file approval with parent/child session authorization sharing.
• MCP: lightweight stdio and Streamable HTTP server/tool controls through the Pi TUI.
• Subagent: bundled General, Explore, and Scout agents with per-agent model and thinking configuration. Scout uses a controlled Git tool and deterministic checkouts under ~/.cache/picraft/scout/repos.
• Git: commit, pull, and branch workflows under /git.
• Init: repository-aware AGENTS.md initialization with reusable project templates.
• Blog: file-based product, technical, release, and work log workflows.

PiCraft requires Pi 0.80.4 or newer.

Plan Analysis Tools

Plan keeps a conservative built-in tool set. Add trusted read-only extension tools in ~/.pi/agent/picraft.json, or in a trusted project's .pi/picraft.json:

{
  "plan": {
    "tools": ["codegraph_explore", "codegraph_search", "memory_search"]
  }
}

Configured tools must already be registered and active. Do not list custom tools that can modify files or external state.

MCP

Add compatible mcpServers configuration to ~/.pi/agent/mcp.json or a trusted project's .mcp.json, then use /mcp to enable servers and individual tools. Servers are disabled by default and connect only when selected.

{
  "mcpServers": {
    "local": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": { "TOKEN": "${MCP_TOKEN}" }
    },
    "remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
    }
  }
}

Update

pi update npm:pi-craft

Pinned installs such as npm:pi-craft@0.1.9 do not update automatically. Install a newer explicit version to move a pinned package.

Uninstall

pi remove npm:pi-craft

Try From Source

From an AgentFramework checkout:

pi --no-extensions --no-skills --no-prompt-templates --no-themes -e ./packages/picraft

Do not enable npm, Git, project-local, or manually copied versions of the same PiCraft extensions at the same time. Duplicate sources register the same tools, commands, shortcuts, and event handlers.

Security

Pi extensions execute with the current user's system access. Review the source before installation. PiCraft Permission is a tool-call approval layer, not an operating-system sandbox; headless approval failures default to rejection. For external reads, an always grant uses a detected project, package, or engine manifest root so files in the same dependency tree do not prompt individually; external write grants remain limited to the direct parent directory. Existing regular files dragged or pasted into the Pi TUI receive exact, session-scoped read approval, including sensitive files the user explicitly supplies; parent directories, sibling files, and write operations remain restricted. PiCraft's exact Scout cache root is trusted for ordinary reads by all agents, while sensitive-file checks and write approval remain active. Only the bundled Scout receives the managed repository tool.

Credentials, model configuration, sessions, logs, and other machine-local Pi state are not distributed by this package.

Source and issue tracking: Losomz/AgentFramework