@anthara/pi-claude

A pi package that runs Claude Code configuration in pi: Claude Code plugins (installed with /plugin, or by Claude Code), their skills and agents, Claude's tool names (Agent, Task, AskUserQuestion, Skill, TodoWrite, ToolSearch), and the env block of Claude's settings.json.

pi install npm:@anthara/pi-claude

Claude configuration is read from CLAUDE_CONFIG_DIR, else ~/.claude. The package is self-contained: it needs no other pi package.

If another pi package also registers Agent, AskUserQuestion, TodoWrite or Skill, pi refuses to start, whichever package is listed first, and names both extension files (Tool "TodoWrite" conflicts with …); remove one of the two with pi remove. A package that registers pi-code's tools (subagent, question, todo, slash_command) does the same jobs under other names, so the session warns once, naming the package and the pi remove command that removes it.

Not carried over from pi-code

The package replaces pi-code, and these pi-code features have no replacement here: --add-dir and the add-dir memory loading, the context usage readout, the status line, session titles, git checkpoints, /goal, /init, plan mode, pi-code's own memory (Anthara's memory is Fabric, through the plugin's MCP server), desktop notifications, settings flags, the thinking controls and the version floor check.

Plugins

/plugin add <github:owner/repo[@ref] | git URL[@ref] | local git checkout>, /plugin update <name>[@ref], /plugin remove <name>, /plugin enable <name>, /plugin disable <name> and /plugin list. Installs go under the pi agent folder, pi-claude/plugins/<name>/<full commit SHA>/, recorded with their source, ref and enabled state in pi-claude/plugins/index.json; the package never writes into the Claude config folder. A ref is a tag or a full SHA, never a branch; without one the latest tag is used. .claude-plugin/plugin.json is optional (the plugin is then named after its repository or folder), and top-level fields Claude does not define are reported when the plugin is added. Changes apply after /reload or in the next session.

Plugins Claude Code installed in the Claude config folder load read-only, enabled as Claude Code's enabledPlugins says; /plugin list shows them, and removing, updating, enabling or disabling one is refused. When a plugin installed with /plugin has the same name, it wins and the session says the other one does not load.

Settings env

The env block of the user settings.json is applied as pi loads the package. A project's .claude/settings.json and .claude/settings.local.json (at the repository root) are applied only once the project is trusted. pi itself asks about trust only for .pi/ and .agents/skills content, so the package asks once more for a project that ships Claude Code configuration (.mcp.json, .claude/settings*.json, .claude/commands, skills, agents or output-styles) and keeps the answer in pi's own trust.json. A session with no UI does not trust such a project until that answer exists.

Skills load from enabled plugins (skills/, the directories the manifest's skills names, or a root SKILL.md), from <Claude config>/skills and from each .claude/skills between the working folder and the repository root. /<plugin>:<skill> <args>, /skill:<name> <args> and the Skill tool expand the skill the way Claude does ($ARGUMENTS, $0, named arguments:, ${CLAUDE_SKILL_DIR} and the other ${CLAUDE_*} variables, @file inside the project, and !`cmd` spans with a 2-minute limit). Frontmatter that Claude accepts and pi's YAML rejects still loads. A project skill's spans run only in a project you trusted; in any other they are replaced by a line saying they were not run, and the skill is not listed to the model. disableSkillShellExecution: true in your settings refuses every span.

A settings file may not set a variable that decides where files go or how pi or Claude Code run: HOME, TMPDIR, TMP, TEMP, CLAUDE_CONFIG_DIR, PI_CODING_AGENT_DIR, Claude's tracing switches, and anything starting with CLAUDE_CODE_, XDG_, PI_CODE_ or PI_CLAUDE_. A host that starts pi can reserve more names by listing them, comma separated, in PI_CLAUDE_RESERVED_ENV_KEYS. Such a key is never applied; the session warns once, naming the key and the file, never the value.

Output styles, plugin executables and a plugin's main agent

/output-style lists Claude's built-in styles (Concise, Explanatory, Learning, Proactive), enabled plugins' styles as <plugin>:<name>, <Claude config>/output-styles and, in a trusted project, .claude/output-styles. The choice is kept per project under the pi agent folder (pi-claude/output-style.json), never in the project. A style replaces pi's default instructions unless its frontmatter sets keep-coding-instructions: true.

Files in an enabled plugin's bin/ run by bare name from the Bash tool. They are added after your own PATH, for that tool only, so a plugin cannot shadow a system command and hooks and MCP servers do not see them.

A plugin's settings.json (or the manifest's settings) agent runs the main session as that plugin's agent: its prompt, tools and model. An agent in your own Claude settings wins. Other keys in a plugin's settings are ignored, and the session says so once.

MCP servers' headersHelper

An http MCP server's headersHelper runs for an enabled plugin's server, for an agent's inline server and, in a project you trusted, for the project's .mcp.json server; an untrusted project's servers are not connected at all. The command runs through /bin/sh in the project folder with CLAUDE_CODE_MCP_SERVER_NAME, CLAUDE_CODE_MCP_SERVER_URL (without user info, query or fragment, and without a path that names a variable), CLAUDE_PROJECT_DIR and, for a plugin's server, CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA. Variables whose names contain TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL, API_KEY, PRIVATE_KEY or AUTH are removed from its environment, and so are the reserved names above except HOME, TMPDIR, TMP, TEMP and XDG_*. It has 10 seconds, and must print one JSON object of header names and text values, which replace static headers of the same name. It runs once when the session starts to learn the header names, then again on every connect and reconnect, with nothing cached; the values are kept out of every file, notice and log. ${user_config.*} in the command is refused, naming the server.

When the helper fails, times out or prints something else as the session starts, the server connects with its static headers and the session says so once, naming the server and never the output. Limits:

• A helper that fails on a later connect or reconnect fails that connect, because pi runs the header command itself; /mcp shows the error, which names pi-claude's runner and never a header value.
• The helper is not rerun after a 401 or 403 answer: pi gives a package nothing to hook there.
• ws and sse servers stay disabled, with or without a headersHelper.
• pi resolves each header on its own, so the helper runs once per header it printed on each connect; headers that must come from the same run, such as a signature over a timestamp, can disagree.
• A trusted project's settings env block does not reach the helper, as it does not reach hooks.

Agents' hooks and MCP servers

Your own agents (<Claude config>/agents and the pi agent folder's agents/) and, in a project you trusted, its .claude/agents can declare hooks and mcpServers. Plugin agents ignore both, and permissionMode and initialPrompt too, as Claude Code's plugin agents do; the session says so once.

• hooks run on the agent's own tool calls while a run started through Agent or Task lasts, and are released when it ends. PreToolUse, PostToolUse and PostToolUseFailure run; a Stop hook fires as SubagentStop when the run ends. Hooks on other events are not run, and an agent that a forked skill starts gets no hooks.
• mcpServers lists server names and inline { <name>: <config> } servers. A name gives the agent the session's server of that name, through the session's connection. An inline stdio or http server connects when the agent starts, is offered to that agent alone, and disconnects when the run ends. A server that cannot connect leaves the agent running without it, and the session warns once, naming the agent and the server.
• Calls to an agent's inline MCP servers happen inside the agent's own session, so neither the session's hooks nor the agent's own hooks see them.
• permissionMode has no effect in pi; the session says so once per agent.

Worktree agents

An agent with isolation: worktree runs in its own git worktree under the pi agent folder (pi-claude/worktrees/<run id>), and every one of its bash commands starts there. Claude Code's three checks keep it out of the main checkout, the repository git names as the top level of your working folder:

• a write or edit whose path, followed through links, lies in the main checkout is refused (a relative path is read against the worktree; the worktree itself, /tmp and other folders are allowed);
• a bash command that changes into the main checkout and then runs git is refused;
• git pointed elsewhere is refused: git -C a folder outside the worktree, --git-dir, --work-tree, -c core.worktree, GIT_DIR= and GIT_WORK_TREE=; env -C <dir> and env --chdir=<dir> count as a cd for the git that follows.

A refused call is blocked after the session's PreToolUse hooks have seen it, and the agent gets the reason, which names its worktree. Limits:

Hooks

Hooks from the user's settings.json, a trusted project's .claude/settings*.json, enabled plugins and skill frontmatter run as in Claude Code. Handler types: command, http, prompt and agent (a read-only sub-agent that answers {"ok": ...}). An mcp_tool handler is reported once and not run, because pi gives a hook no way to call a tool on an MCP server it connects.

Supported events, with the pi event or announcement each rides:

Setup runs once, at the start of a session that began with --init or --maintenance (the matcher and the payload's trigger are init or maintenance). Only command hooks run, and their answers are discarded. Put the flag after the prompt, because pi gives the token after a flag to the flag as its value: anthara -p "<prompt>" --init.

FileChanged watches each |-separated name of the matcher as a literal file name in the working directory, and an add, change or unlink fires the hook with file_path and event. A hook's watchPaths (absolute paths) replaces the extra watch list, and its systemMessage is shown; the event cannot block. No watcher is opened when no FileChanged hook exists, and a project's hooks are watched only in a trusted project.

SubagentStart runs before the child's first prompt and its additionalContext is added to that prompt. UserPromptExpansion, WorktreeCreate and WorktreeRemove are notifications: a hook cannot block or replace the expansion or the worktree.

Events this package does not support are listed with their reasons under Not supported.

Not supported

This section lists every Claude Code behaviour that pi-claude does not provide, with its reason. A row that names a feature described elsewhere in this README links to it. A difference that is not listed here is a bug.

Hook events

A plugin or settings file that declares one of these events is warned about once per session, naming the event and where it came from.

Hook handlers and behaviour

MCP servers

The other headersHelper limits are listed in MCP servers' headersHelper.

Marketplace sources

A marketplace entry can name an npm package, a zip archive or a command that prints a folder. Each limit below applies to one of them, or to all of them.

Worktree agents

The other limits of isolation: worktree are listed in Worktree agents.

Agents

Skills and commands

Tools and sessions

Licence

Apache-2.0. Parts are adapted from pi-code (MIT); see NOTICE.