pi-rtk

Pi coding agent extension that uses rtk to reduce LLM token usage for shell command execution.

When pi-rtk is loaded, it participates in two Pi shell paths:

• agent-initiated bash tool calls
• user-issued !<cmd> shell commands whose output is included in model context

In both cases, pi-rtk first attempts to rewrite the command with:

rtk rewrite "<original command>"

If rewrite succeeds, Pi executes the rewritten command. If rewrite fails for any reason, pi-rtk falls back silently so normal Pi shell behavior continues.

Commands entered with !!<cmd> are intentionally not intercepted. They continue through Pi's normal context-excluded shell execution path unchanged.

Prerequisites

• Pi v0.60.0 or later
• rtk, installed and available on your PATH

If rtk is unavailable, pi-rtk still preserves normal shell behavior by falling back to the original command.

Install

Make sure your Pi installation is v0.60.0 or later before installing this package.

pi install npm:@sherif-fanous/pi-rtk

Or try without installing:

pi -e npm:@sherif-fanous/pi-rtk

To uninstall:

pi remove npm:@sherif-fanous/pi-rtk

How It Works

Agent bash tool calls

pi-rtk registers a replacement bash tool for Pi. Before the tool executes a command, the extension attempts an rtk rewrite and uses the rewritten command when available.

This preserves the normal bash tool interface while routing supported commands through rtk, which can filter and compress output before it reaches the model.

If rtk is unavailable, times out, or cannot rewrite the command, the original command runs unchanged.

Behavior summary

Agent bash tool call
        │
        ▼
pi-rtk replacement bash tool
        │
        ├─ try: rtk rewrite "<command>"
        │      │
        │      ├─ success -> execute rewritten command
        │      └─ failure -> execute original command unchanged
        │
        ▼
    same bash tool interface to Pi

User !<cmd> shell commands

pi-rtk also hooks Pi's user_bash event for context-visible user shell commands entered with !<cmd>.

For these commands, the extension probes rewrite eligibility before claiming the event. If rewrite succeeds, it returns custom bash operations so Pi can keep owning the normal execution lifecycle and UI behavior. If rewrite does not succeed, the extension falls through and Pi handles the command normally.

This keeps optimization best-effort, silent, and non-disruptive during normal operation.

Behavior summary

User !<cmd>
        │
        ├─ try: rtk rewrite "<command>"
        │      │
        │      ├─ success -> return custom bash operations
        │      └─ failure -> fall through to normal Pi user_bash handling
        │
        ▼
    same user shell experience in Pi

User !!<cmd> shell commands

Commands entered with !!<cmd> are excluded from model context by design, so pi-rtk does not intercept them.

They bypass pi-rtk completely and continue through Pi's normal context-excluded shell handling.

Behavior summary

User !!<cmd>
        │
        ▼
    bypass pi-rtk and use normal Pi context-excluded shell handling

/rtk Slash Command

pi-rtk registers a /rtk slash command for session-scoped control:

• /rtk enable turns command rewriting on for the current Pi session.
• /rtk disable turns command rewriting off for the current Pi session.
• /rtk status shows the current toggle state, detected rtk binary details, and a bypass tip.
• /rtk opens an overlay where you can choose the same actions interactively.

The footer includes a persistent pi-rtk status indicator: rtk ✓ in green when rewriting is enabled, rtk ✗ in red when disabled.

The toggle is in-memory only. It resets to enabled every time Pi restarts and is not written to disk. For a single-command bypass while leaving the session toggle enabled, use rtk's per-command form:

!RTK_DISABLED=1 <cmd>

What pi-rtk Does Not Do

pi-rtk is a rewrite shim. It does not gate, prompt for, sandbox, or deny commands based on their content, including when rtk rewrite surfaces a deny verdict.

That scope is intentional. rtk's deny verdict comes from a permission source that does not match Pi's permission model, and Pi's built-in approval flow plus Pi's extension ecosystem cover command gating better as composable layers.

If you want command-level permissions, guardrails, or shields, install a dedicated Pi extension for that. Browse pi.dev/packages filtered by extension and search for terms like permission, guardrail, or shield.

Those extensions compose with pi-rtk: they block disallowed commands at execution time, whether or not pi-rtk has rewritten the command.