---
status: community
title: Pi Coding Agent
description: Install the native PowerContext package for Pi and control recall, capture, and durable tool writes.
---

# Pi Coding Agent

`community`

## Install or refresh the package

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

```bash
powercontext setup pi
```

A local checkout works as well:

```bash
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:

```bash
powercontext server run
pi
```

If an older PowerContext package at another path has Pi resource filters, setup stops before changing the host.
Move that package entry to the managed path reported in the error, keeping its filters, then rerun setup.
Refreshes at the managed path preserve existing filters.

## 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.

### Pre-compaction checkpoint

The package implements **best-effort** checkpointing on Pi's public `session_before_compact` event. Eligible prompts
are captured with deterministic Source IDs before the agent turn, and the event flushes their accepted journal
positions. A position is removed from the pending set only after a complete, valid flush response reports
`current_cursor` at or beyond that exact position. A 2xx response, malformed cursor, or cursor from another Scope
cannot acknowledge it.

Each lifecycle boundary makes at most `POWERCONTEXT_PI_FLUSH_MAX_CALLS` calls (default `4`, valid range `1`–`16`)
within its own one-second budget. Queue waiting, all pending Scopes, and retry calls share that boundary budget. A
behind cursor or `remaining_work` consumes another bounded call.
Failures and cancellation before acknowledgement retain pending work; cancellation after acknowledgement does not
revoke it. A boundary that exhausts its budget while queued emits a content-free `deadline_exceeded` diagnostic and
retains its pending positions. `session_before_switch` and `session_shutdown` flush only already accepted pending
positions.

Pi's real `ExtensionRunner` continues after thrown handler errors unless a handler explicitly returns
`{ cancel: true }`. This package never returns that result, so checkpoint failure does not block compaction and the
integration is not `required_capable`. Optional diagnostics are content-free and use a hashed Scope correlation,
target and observed positions, lifecycle event, host, and stable failure class.

## Control prompt capture

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

```bash
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:

```bash
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:

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

Start Pi with the complete matching header:

```bash
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](../operate/connect-remote-server.md) for setup and saved consent.

## Verify the installation

```bash
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

| Variable | Default | Meaning |
| --- | --- | --- |
| `POWERCONTEXT_PI_BASE_URL` | `http://127.0.0.1:8000` | Server base URL |
| `POWERCONTEXT_PI_ALLOW_INSECURE_HTTP` | `false` | Explicitly permit non-loopback plaintext HTTP |
| `POWERCONTEXT_PI_SCOPE_ID` | unset | Explicit existing Scope before workspace binding and Server default |
| `POWERCONTEXT_PI_AUTHORIZATION` | unset | Complete `Bearer <token>` header for package HTTP requests |
| `POWERCONTEXT_PI_CAPTURE_PROMPTS` | `true` | Capture eligible user prompts as Source evidence |
| `POWERCONTEXT_PI_REQUEST_TIMEOUT_MS` | `3000` | Per-request timeout in milliseconds |
| `POWERCONTEXT_PI_HTTP_BUDGET_MS` | `6000` | Shared recall/capture HTTP budget in milliseconds |
| `POWERCONTEXT_PI_MAX_BYTES` | `8000` | Requested and validated PreparedContext byte limit (`512`–`32768`) |
| `POWERCONTEXT_PI_FLUSH_ON_CAPTURE` | `false` | Wait for captured Source processing during the prompt hook |
| `POWERCONTEXT_PI_FLUSH_MAX_CALLS` | `4` | Maximum flush calls shared by all pending Scopes at one lifecycle boundary |
| `POWERCONTEXT_PI_DIAGNOSTICS` | `off` | Failure diagnostics sink: `off`, `stderr`, or an absolute file path (`~/` expanded) for JSON lines |

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.

## Automatic input privacy

See [Automatic prompt privacy](index.md#automatic-prompt-privacy) for this host's capture default, disable control, credential recognition limits and independent read-only query handling. Recognized inputs are skipped for capture; accepted Source content and event identity are not rewritten.