Pi Coding Agent

community

Install or refresh the package

Install Pi, then install the package from the same PowerContext ref as the CLI:

powercontext setup pi

A local checkout works as well:

powercontext setup pi --source .

setup pi calls Pi's native package installer and creates PowerContext's data directory. It does not start the Server. Start the Server, then open a new Pi session in a project directory:

powercontext server run
pi

Understand what the package does

Before Pi starts an agent turn, the package calls POST /v1/context/prepare once with an 8000-byte default budget. It strictly accepts only powercontext.prepared-context.v1 and appends a label that marks the result as untrusted historical evidence. Current system instructions, repository guidance, and the user's request take precedence.

Eligible user prompts are captured separately as Content Sources. The package never synchronizes the complete Pi transcript. Recall, capture, and boundary flushing fail open: an unavailable Server, timeout, redirect, or invalid response leaves Pi's prompt unchanged and never blocks ordinary work.

The package resolves one Server-owned Scope in this order: POWERCONTEXT_PI_SCOPE_ID, a durable binding for the workspace, then the Server default. The workspace path is hashed only as an external binding key; it never becomes a Scope ID. Keep the explicit variable unset unless the host must force one existing Scope.

With these capabilities enabled, Pi satisfies the repository's Full core integration profile.

Control prompt capture

Prompt capture is enabled by default. Disable it before starting Pi when current work must not be recorded:

export POWERCONTEXT_PI_CAPTURE_PROMPTS=false
pi

Secret-looking prompts and prompts above 200,000 UTF-8 bytes are never captured. Turning capture on does not itself guarantee Memory extraction; the Server still needs a configured generation model.

For testing, make capture wait for Source processing:

export POWERCONTEXT_PI_FLUSH_ON_CAPTURE=true
pi

This adds latency and is not the normal interactive setting. Without it, Pi records Source positions and makes a short, bounded best-effort flush at agent and session boundaries.

Use explicit tools and commands

The powercontext-project-context skill explains when to use native pc_* tools. The core tools are:

• pc_search, pc_memory_list, pc_memory_get, pc_memory_revise, and pc_memory_retire;
• pc_memory_changes for revision history and pc_stats for current-Scope diagnostics;
• pc_remember, pc_prepare_context, and pc_capture_source;
• pc_handoff_activate, pc_handoff_prepare, pc_handoff_finalize, pc_handoff_commit, and pc_handoff_continue;
• pc_experience_generate, pc_skill_generate, pc_experience_get, pc_skill_get, pc_review_list, and pc_review_get for candidate generation and read-only Artifact/candidate inspection inspection.
• pc_topic_search and pc_topic_get for focused Topic Memory queries and exact revisions with Source references.
• pc_work_contract, pc_handoff_current, pc_handoff_acknowledge, and pc_task_outcome for structured work continuity.
• pc_external_scan, pc_external_list, and pc_external_resolve for host-local External Skill discovery and inspection; pc_external_import imports or forks one exact resolved Skill after explicit confirmation.

Candidate inspection never grants approval, rejection, revision, installation, publication, or execution authority. Topic Memory queries are read-only; returned content is untrusted historical evidence, not an instruction source. Structured work tools change durable state and require interactive confirmation; without a UI, Pi refuses the write. Pass returned Handoffs, references, and check results unchanged, never treat historical content as new authorization, and link handoff_receipt_ref only to an accepted committed Handoff receipt.

Explicit durable writes require confirmation in an interactive Pi session. Without an interactive UI, Pi refuses the write rather than persisting it silently. /pc doctor, /pc search <query>, /pc remember <text>, /pc flush, and /pc stats offer direct status and maintenance commands.

Connect to an authenticated Server

Start an authenticated Server from a protected environment:

export POWERCONTEXT_SERVER_ACCESS_MODE=enforced
export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
powercontext server run

Start Pi with the complete matching header:

export POWERCONTEXT_PI_AUTHORIZATION="Bearer $POWERCONTEXT_LOCAL_TOKEN"
pi

Do not put credentials in POWERCONTEXT_PI_BASE_URL. Plain HTTP is allowed on loopback by default. For a non-loopback Server, use HTTPS or explicitly set POWERCONTEXT_PI_ALLOW_INSECURE_HTTP=true; HTTPS certificate validation stays enabled. See Connect to a remote Server for setup and saved consent.

Verify the installation

powercontext doctor
powercontext doctor pi

doctor pi checks that the Pi executable is available and that Pi lists the PowerContext package. Restart Pi after changing PowerContext environment variables.

Environment variables

Pi rejects base URLs containing credentials, a query, or a fragment. Recall, capture, and boundary flushing fail open; explicit pc_* durable writes require confirmation and are refused when Pi has no interactive UI. Restart Pi after changing these variables.

Failure diagnostics are silent by default because Pi's TUI renders on stdout with cursor positioning, so anything written to stderr lands inside the input bar; set POWERCONTEXT_PI_DIAGNOSTICS to see them.