pi-agent-kernel

Coding agents waste context when they read entire files to inspect one function, dump thousands of lines of terminal output, or rewrite whole files for small edits. pi-agent-kernel is an extension for Pi that keeps sessions compact by clamping command outputs, capping file reads, and verifying edits before saving.

Benchmarks

Evaluating 6 coding agent harnesses across 8 bug fixes (hono, ky, zod, ufo, picomatch, fastify, uuid, p-limit) with cx/gpt-5.6-luna:high:

Prompts describe symptoms and expected behavior without providing the fix. Token totals reflect each tool's reported telemetry. In Claude Code, 1 additional task passed test verification after timing out.

Quick start

1. Install

Install the extension through Pi's package manager:

# Global install
pi install npm:@floydous/pi-agent-kernel

# Local install for the current workspace only
pi install -l npm:@floydous/pi-agent-kernel

Restart Pi or start a new session.

The instructions in AGENT_KERNEL_SYS_PROMPT.md are added to the agent system prompt automatically. To turn them off, set [instructions] enabled = false in .pi/config.toml or run /agent-kernel set guidance off.

2. Configure the retrieval engine (/engine)

pi-agent-kernel includes an in-memory retrieval engine for keyword and vector search:

/engine status

• auto: Selects lean on remote servers, hybrid on laptops, or full on desktops based on available hardware.
• lean (default): AST-indexed BM25 keyword search (🌿 retrieval:bm25) with no extra memory footprint.
• hybrid: BM25 search combined with 256-dimension Matryoshka embeddings (◈ retrieval:hybrid-256d).
• full: 768-dimension dense semantic search (🧠 retrieval:dense-768d).
• off: Disables local indexing completely.

When indexing runs in the background, the status line shows chunk progress:

🧠 retrieval:dense-768d ⇢ 45% (22/48 • 14.2 chunk/s)

Switch profiles directly:

/engine hybrid
/engine full

3. Settings and configuration (/agent-kernel)

Run /agent-kernel to open the settings interface:

/agent-kernel

Key controls in the settings modal:

• Tab / Shift+Tab: Switch categories (Retrieval, Safety, Editing, UI).
• G (or Ctrl+G): Toggle whether a setting applies globally (~/.pi/agent/config.toml) or locally (.pi/config.toml). Global settings show in yellow.
• Esc or q: Save changes and close. Changes stay in memory and save together when you close the modal, so browsing options will not trigger extra re-indexing runs.

You can also manage settings from the command line:

/agent-kernel status             # Print current configuration and file locations
/agent-kernel set <key> <val>    # Update a setting globally
/agent-kernel reset              # Reset global configuration to defaults

4. Language servers (/lsp)

Run /lsp to check detected languages, connection states, and installation status:

/lsp

To install a server directly:

/lsp install <language>    # e.g. python, typescript, rust, go, csharp

5. Disable Pi documentation for external projects

Pi injects reference documentation for building Pi extensions into every session. When working on ordinary codebases, you can hide those docs to save prompt space:

/pi-docs off

Use /pi-docs on when returning to work on Pi extensions.

Tool reference

[!NOTE] Exploratory tools (ast_search, get_repo_map, lsp) are disabled by default (enable_tools = false) to reduce per-turn token overhead. You can enable them with /agent-kernel set tools all or by setting PI_ENABLE_ALL_RETRIEVAL_TOOLS=1.

License

ISC