@aaroncql/pim-agent 0.0.1 → 0.2.0

package/README.md

@@ -3,26 +3,29 @@
 
 _**Pim is to Pi what Vim is to Vi.**_
 
-An opinionated yet minimal, Bun-native extension pack for [Pi](https://pi.dev/): revamped tools, ANSI-compatible themes, fzf-style autocompletions, Telegram bot, and more. Scores up to [41.6% on Terminal-Bench 2.0](#terminal-bench-20) with locally hosted Qwen3.6-35B, matching Claude Code + Sonnet 4.5.
+A Bun-native extension pack for [Pi](https://pi.dev/): web access, subagents, revamped core tools, ANSI-compatible themes, fzf-style completions, Telegram mode, and more. Preliminary score of [37.8% on Terminal-Bench 2.0](#terminal-bench-20) with locally hosted Qwen3.6-35B, rivalling Claude Code + Sonnet 4.5.
 
 - [Quick Start](#quick-start)
+  - [Enabling/Disabling Extensions](#enablingdisabling-extensions)
   - [API Keys (Optional)](#api-keys-optional)
-  - [Recommended Settings (Optional)](#recommended-settings-optional)
+  - [Recommended Pi Settings (Optional)](#recommended-pi-settings-optional)
+- [Why Pim?](#why-pim)
+  - [Lean System Prompt](#lean-system-prompt)
+  - [Model-Aware Tools](#model-aware-tools)
+  - [Terminal-Bench 2.0](#terminal-bench-20)
 - [Agent Tools](#agent-tools)
 - [Terminal UI](#terminal-ui)
 - [Telegram Bot](#telegram-bot)
   - [Setup](#setup)
   - [Commands](#commands)
   - [Features](#features)
-- [Why Pim?](#why-pim)
-  - [Harness Design](#harness-design)
-  - [Terminal-Bench 2.0](#terminal-bench-20)
 - [Developing](#developing)
 
+![Pim Demo](https://raw.githubusercontent.com/AaronCQL/pim-agent/refs/heads/main/assets/demo.webp)
+
 ## Quick Start
 
-> [!IMPORTANT]
-> The following instructions assume you have [Pi](https://pi.dev/docs/latest/quickstart) and [Bun](https://bun.com/docs/installation) already installed. If not, install them first (_or ask your agent to do it for you_). For all things related to Pi, refer to [Pi's comprehensive docs](https://pi.dev/docs/latest).
+Ensure that you have [Pi](https://pi.dev/docs/latest/quickstart) and [Bun](https://bun.com/docs/installation) already installed. If not, install them first (_or ask your agent to do it for you_). For all things related to Pi, refer to [Pi's comprehensive docs](https://pi.dev/docs/latest).
 
 ```sh
 # First, install Pim as a Pi extension:
@@ -35,11 +38,24 @@ bun install -g @aaroncql/pim-agent
 pim
 ```
 
-The `pim` command is a [thin Bun launcher](./bin/pim.ts) that wraps around `pi` so that Bun-specific tooling and APIs can be used. Other Pi extensions should continue to work normally.
+> [!IMPORTANT]
+> **Use `pim` instead of `pi` after installing Pim.** The `pim` command is a drop-in replacement for `pi` that [runs Pi via Bun](./bin/pim.ts), enabling Bun-specific APIs. Existing Pi behaviour and extensions should continue to work normally.
+
+If `pim` cannot locate Pi, make sure `pi` is on your `PATH`, or set:
+
+```sh
+PIM_PI_CLI=/path/to/pi/dist/cli.js pim
+```
+
+### Enabling/Disabling Extensions
+
+Pim ships a collection of extensions which are all enabled by default. To disable specific ones that don't suit your needs, run `pim config` and toggle them there.
+
+Some Pim extensions can be toggled directly within the TUI as well: `/powerline` for the Git-aware powerline footer, `/tps` for inference speed reporting.
 
 ### API Keys (Optional)
 
-Pim's web tools use [Exa](https://exa.ai) for searching the web and [Jina](https://jina.ai/reader/) for fetching websites as Markdown. Without API keys, the tools are subject to the following rate limits (as of May 2026):
+Pim's web tools use [Exa](https://exa.ai) for searching the web and [Jina](https://jina.ai/reader/) for fetching websites as Markdown. These tools still work without API keys, but are subject to the following rate limits (as of May 2026):
 
 - Exa - 1,000 requests per month
 - Jina - 20 requests per minute
@@ -63,7 +79,7 @@ Environment variables override `settings.json` when present:
 EXA_API_KEY='api_key_here' JINA_API_KEY='api_key_here' pim
 ```
 
-### Recommended Settings (Optional)
+### Recommended Pi Settings (Optional)
 
 Add the following settings to your `~/.pi/agent/settings.json` for the best experience with Pim:
 
@@ -77,10 +93,69 @@ Add the following settings to your `~/.pi/agent/settings.json` for the best expe
 }
 ```
 
+## Why Pim?
+
+Pim's philosophy is **opinionated but minimal**. Its goal is to improve the out-of-the-box experience for both users and agents, without sacrificing composability with other Pi extensions.
+
+### Lean System Prompt
+
+Pim's system prompt is just **~3K tokens** despite exposing 10+ tools, far leaner than alternatives like OpenCode (~10K) or Hermes (~16K).
+
+This is achieved by having tool descriptions focus on _how_ to use each tool instead of prescribing _when_, since models already appear to internally encode when tools are needed, and prompting them to call tools can [suppress both necessary and unnecessary calls](https://arxiv.org/abs/2605.09252).
+
+### Model-Aware Tools
+
+LLMs are [increasingly post-trained](https://openai.com/index/introducing-codex) for specific agent harnesses, making tool schemas part of the model's learned interface. For text-file editing, Anthropic models are trained to use [string replacement operations](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool), while OpenAI models use [V4A patch operations](https://developers.openai.com/api/docs/guides/tools-apply-patch).
+
+Pim keeps the active toolset model-aware instead of assuming one tool fits every LLM. It dynamically exposes the tools best suited to the selected model, giving each model the interface that best matches its learned behaviour while keeping the prompt lean.
+
+### Terminal-Bench 2.0
+
+| ID | Pim Version | LLM / Model | Results |
+| --- | --- | --- | --- |
+| [r1](./benchmarks/terminal_bench_2/results/r1/) | [`21d084d1`](https://github.com/AaronCQL/pim-agent/tree/21d084d1) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **41.6%** (37/89) |
+| [r2](./benchmarks/terminal_bench_2/results/r2/) | [`bfd792cf`](https://github.com/AaronCQL/pim-agent/tree/bfd792cf) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **36.0%** (32/89) |
+| [r3](./benchmarks/terminal_bench_2/results/r3/) | [`cd52f3a4`](https://github.com/AaronCQL/pim-agent/tree/cd52f3a4) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **36.0%** (32/89) |
+
+Preliminary aggregate score of **37.8%** from 3 independent runs. Each ran on an incremental build of Pim, though changes between runs were minor and none were tuned to the benchmark. Pim's `subagent` tool was disabled for all runs to keep each trial single-agent.
+
+On average, Pim solves **~54% more tasks** than [little-coder](https://github.com/itayinbarr/little-coder) with the same Qwen3.6-35B model (37.8% vs 24.6%). This also places Pim in a similar tier to Claude Code + Sonnet 4.5 (40.1%), and above Codex + GPT-5-Mini (31.9%).
+
+The Qwen3.6-35B model is hosted via llama.cpp on an M4 Pro 48GB MacBook, with the following config:
+
+```sh
+llama-server \
+  -c 131072 \
+  -ngl 99 \
+  --slot-save-path /tmp/llama-slots \
+  --flash-attn on \
+  --cache-type-k q8_0 \
+  --cache-type-v q8_0 \
+  --jinja \
+  --temp 0.6 \
+  --top-p 0.95 \
+  --top-k 20 \
+  --min-p 0.0 \
+  --presence-penalty 0.0 \
+  --repeat-penalty 1.0 \
+  --reasoning-budget 16384 \
+  --reasoning-budget-message "Alright, I've thought enough. Let me take the next concrete step now — either a tool call or a final answer — and refine based on what I learn." \
+  -np 1
+```
+
+_Note 1_: results are preliminary as only 3 independent full runs were conducted; Terminal-Bench 2.0 requires 5 independent full runs under a fixed configuration for an official score.
+
+_Note 2_: the gap with little-coder may be partly explained by different inference configs (128K context vs 32K, Q6_K_XL vs Q4_K_M, higher thinking budget, etc.).
+
+_Note 3_: in r1 and r3, the `code-from-image` trial was counted as non-passing because Qwen autonomously searched for the answer online after legitimately trying for a while.
+
+_Note 4_: see the [`benchmarks/terminal_bench_2`](./benchmarks/terminal_bench_2/) dir for breakdown of results and reproduction steps.
+
 ## Agent Tools
 
-Pim revamps Pi's default tools (`bash`, `read`, `write`, `edit`) and adds the following:
+Pim revamps Pi's default tools (`bash`, `read`, `write`, `edit`) so they produce consistent behaviour and output, cross-reference each other where useful, and render uniformly in the TUI. It also adds:
 
+- **`apply_patch`** - V4A patch editing, dynamically exposed instead of `edit` for OpenAI models
 - **`glob`** - file enumeration by glob pattern, sorted newest-first, respects `.gitignore`
 - **`grep`** - regex search across files with context lines, multiline matching, respects `.gitignore`
 - **`web_search`** - search the web via [Exa](https://exa.ai) with ranked results and snippets
@@ -92,11 +167,11 @@ Pim revamps Pi's default tools (`bash`, `read`, `write`, `edit`) and adds the fo
 
 Pim also ships with quality of life improvements for the TUI:
 
-- **ANSI-compatible themes** - `pim-light` and `pim-dark` themes that match your terminal's colour scheme
+- **ANSI-compatible themes** - `pim-light` and `pim-dark` themes which adapt to your terminal's colour scheme
 - **fzf-style autocomplete** - `@path` file picker and `/command` picker with fuzzy search
-- **Git-aware powerline footer** - current dir, git branch and states, context usage, model and session cost (toggle with `/powerline`)
+- **Git-aware powerline footer** - cwd, git branch and states, context usage, model and session cost (toggle with `/powerline`)
 - **TPS reporting** - per-cycle decode/prefill rate, TTFT, and cache read tokens (toggle with `/tps`)
-- **Concise tool headers** - minimal one-liner title across all tool calls, `Ctrl+O` to toggle full details
+- **Concise tool UI** - minimal one-liner title across all tool calls, `Ctrl+O` to toggle full details
 
 ## Telegram Bot
 
@@ -149,58 +224,11 @@ For development, run standalone with `pim --mode telegram` instead.
 
 ### Features
 
-- **Scheduled tasks** - your bot can create one-time, interval, or cron-based tasks that fire automatically; ask your bot to schedule something.
-- **Rich media** - send photos, documents, videos, audio, and voice messages directly in chat; your bot can also send files back to you.
-- **Thread-specific prompts** - each chat (or thread) gets its own session and instructions; ask your bot to modify its instructions.
-
-## Why Pim?
-
-### Harness Design
-
-Pim overrides Pi's default tools (`bash`, `read`, `write`, `edit`) so that all tools produce consistent, structured output for the model, cross-reference each other where useful, and render uniformly in the TUI.
-
-The system prompt is also kept as minimal as possible: at just ~3K tokens despite having 10+ tools (vs OpenCode's ~10K, Hermes' ~16K), with tool descriptions focusing on _how_ to use each tool instead of prescribing _when_. The rationale is that models already appear to internally encode when tools are needed, and prompting them to call tools can [suppress both necessary and unnecessary calls](https://arxiv.org/abs/2605.09252).
-
-### Terminal-Bench 2.0
-
-Preliminary results from two full runs:
-
-| ID | Pim Version | LLM / Model | Results |
-| --- | --- | --- | --- |
-| [r1](./benchmarks/terminal_bench_2/results/r1/) | [`21d084d1`](https://github.com/AaronCQL/pim-agent/tree/21d084d1) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **41.6%** (37/89) |
-| [r2](./benchmarks/terminal_bench_2/results/r2/) | [`bfd792cf`](https://github.com/AaronCQL/pim-agent/tree/bfd792cf) | `Qwen3.6-35B-A3B-UD-Q6_K_XL.gguf` | **36.0%** (32/89) |
-
-Comparing against the same Qwen3.6-35B model, Pim solves up to **70% more tasks** than [little-coder](https://github.com/itayinbarr/little-coder) (41.6% vs 24.6%). This puts Pim, with a locally hosted model, in a similar tier to Claude Code + Sonnet 4.5 (40.1%) and above Codex + GPT-5-Mini (31.9%).
-
-The Qwen3.6-35B model is hosted via llama.cpp on an M4 Pro 48GB MacBook, with the following config:
-
-```sh
-llama-server \
-  -c 131072 \
-  -ngl 99 \
-  --slot-save-path /tmp/llama-slots \
-  --flash-attn on \
-  --cache-type-k q8_0 \
-  --cache-type-v q8_0 \
-  --jinja \
-  --temp 0.6 \
-  --top-p 0.95 \
-  --top-k 20 \
-  --min-p 0.0 \
-  --presence-penalty 0.0 \
-  --repeat-penalty 1.0 \
-  --reasoning-budget 16384 \
-  --reasoning-budget-message "Alright, I've thought enough. Let me take the next concrete step now — either a tool call or a final answer — and refine based on what I learn." \
-  -np 1
-```
-
-_Note 1_: results are preliminary as only 2 independent full runs were conducted; Terminal-Bench 2.0 requires 5 independent full runs for an official score.
-
-_Note 2_: the gap with little-coder may be partly explained by different inference configs (128K context vs 32K, Q6_K_XL vs Q4_K_M, higher thinking budget, etc.).
-
-_Note 3_: in r1, the recorded result is actually 1 higher at 38/89. However, the `code-from-image` trial was excluded because Qwen autonomously searched for the answer online after 27 legitimate turns (see line 822 in [trajectory.json](benchmarks/terminal_bench_2/results/r1/code-from-image/trajectory.json)).
-
-_Note 4_: see the [`benchmarks/terminal_bench_2`](./benchmarks/terminal_bench_2/) dir for breakdown of results and reproduction steps.
+- ⏰ **Scheduled tasks** - your bot can create one-time, interval, or cron-based tasks that fire automatically; ask your bot to schedule something.
+- 👀 **Live progress logs** - use `/logs` to choose what you see while the agent works: final replies, tool use, intermediate text, or thinking.
+- 📝 **Markdown formatting** - replies render Markdown out of the box, including tables converted to vertical lists for Telegram.
+- 📎 **Rich media** - send photos, documents, videos, audio, and voice messages directly in chat; your bot can also send files back to you.
+- 🧵 **Thread-specific prompts** - each chat (or thread) gets its own session and optional instructions; ask your bot to modify its instructions.
 
 ## Developing
 

package/bin/pim.ts

@@ -1,9 +1,20 @@
 #!/usr/bin/env bun
+import { realpath } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 const PI_PACKAGE = "@earendil-works/pi-coding-agent";
 
-function findPiCli(): string {
+async function findPiCli(): Promise<string> {
+  const envCli = await resolveEnvPiCli();
+  if (envCli) {
+    return envCli;
+  }
+
+  const pathCli = await resolvePathPiCli();
+  if (pathCli) {
+    return pathCli;
+  }
+
   const globalCli = resolveGlobalPiCli();
   if (globalCli) {
     return globalCli;
@@ -15,11 +26,52 @@ function findPiCli(): string {
   } catch {
     throw new Error(
       `Pim could not locate ${PI_PACKAGE}.\n` +
-        `Install it globally under Bun: bun install -g ${PI_PACKAGE}`
+        `Install Pi from https://pi.dev/docs/latest/quickstart, or set PIM_PI_CLI=/path/to/cli.js`
     );
   }
 }
 
+async function resolveEnvPiCli(): Promise<string | null> {
+  const candidate = process.env["PIM_PI_CLI"]?.trim();
+  if (!candidate) {
+    return null;
+  }
+  return (await isFile(candidate)) ? candidate : null;
+}
+
+async function resolvePathPiCli(): Promise<string | null> {
+  const piBin = Bun.which("pi");
+  if (!piBin) {
+    return null;
+  }
+
+  const cliPath = await resolveRealPath(piBin);
+  const pkgPath = join(dirname(cliPath), "..", "package.json");
+
+  try {
+    const pkg = (await Bun.file(pkgPath).json()) as { readonly name?: string };
+    return pkg.name === PI_PACKAGE ? cliPath : null;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveRealPath(path: string): Promise<string> {
+  try {
+    return await realpath(path);
+  } catch {
+    return path;
+  }
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await Bun.file(path).stat()).isFile();
+  } catch {
+    return false;
+  }
+}
+
 function resolveGlobalPiCli(): string | null {
   const result = Bun.spawnSync({ cmd: ["bun", "pm", "-g", "bin"] });
   if (result.exitCode !== 0) {
@@ -78,7 +130,7 @@ if (mode === "telegram") {
   process.exit(0);
 }
 
-const piCli = findPiCli();
+const piCli = await findPiCli();
 const proc = Bun.spawn({
   cmd: [process.execPath, piCli, ...cliArgs],
   stdio: [

package/package.json

@@ -1,14 +1,28 @@
 {
   "name": "@aaroncql/pim-agent",
-  "version": "0.0.1",
-  "description": "Pim is to Pi what Vim is to Vi.",
+  "version": "0.2.0",
+  "description": "A Bun-native extension pack for Pi: web access, subagents, revamped core tools, ANSI-compatible themes, fzf-style completions, Telegram mode, and more.",
+  "license": "MIT",
   "type": "module",
+  "keywords": [
+    "pi-package",
+    "agent"
+  ],
+  "homepage": "https://github.com/AaronCQL/pim-agent#readme",
+  "bugs": {
+    "url": "https://github.com/AaronCQL/pim-agent/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AaronCQL/pim-agent.git"
+  },
   "bin": {
     "pim": "bin/pim.ts"
   },
   "files": [
     "bin/",
-    "src/"
+    "src/",
+    "!src/**/*.test.ts"
   ],
   "engines": {
     "bun": ">=1.2.7"
@@ -19,14 +33,15 @@
     ],
     "themes": [
       "./src/themes"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/AaronCQL/pim-agent/refs/heads/main/assets/demo.webp"
   },
   "scripts": {
     "dev": "bun link && pim",
     "typecheck": "tsgo --noEmit",
     "test": "bun test src --only-failures",
     "lint": "oxlint . --fix",
-    "format": "prettier --write --list-different package.json tsconfig.json .oxlintrc.json .prettierrc.json \"src/**/*.ts\" \"bin/**/*.ts\" \"**/*.md\"",
+    "format": "prettier --write --list-different package.json tsconfig.json .oxlintrc.json .prettierrc.json \"src/**/*.ts\" \"bin/**/*.ts\"",
     "check": "bun run typecheck && bun run test && bun run lint && bun run format"
   },
   "peerDependencies": {

package/src/extensions/_init/index.ts

@@ -21,8 +21,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
   if (typeof Bun === "undefined") {
     throw new Error(
       "Pim requires the Bun runtime.\n" +
-        "Install pi via bun: bun install -g @earendil-works/pi-coding-agent\n" +
-        "Then run: pim"
+        "Install the Pim launcher: bun install -g @aaroncql/pim-agent\n" +
+        "Then run: pim\n" +
+        "If pim cannot locate Pi, ensure `pi` is on PATH or set PIM_PI_CLI=/path/to/cli.js"
     );
   }
 

package/src/extensions/apply-patch/coordinator.ts

@@ -0,0 +1,49 @@
+const EDIT_TOOL = "edit";
+const APPLY_PATCH_TOOL = "apply_patch";
+
+/**
+ * Pure reconcile over the active-tool list. Single-slot swap:
+ *  - If neither `edit` nor `apply_patch` is active, no-op (respect user opt-out).
+ *  - Otherwise keep exactly one in the same position: `apply_patch` when the
+ *    model is GPT/Codex-family, else `edit`. All other active tools are
+ *    preserved in order.
+ *
+ * Returns the same array reference when nothing changes so callers can skip the
+ * prompt-rebuilding `setActiveTools` call.
+ */
+export function computeActiveTools(
+  active: readonly string[],
+  isGpt: boolean
+): readonly string[] {
+  const hasEdit = active.includes(EDIT_TOOL);
+  const hasApplyPatch = active.includes(APPLY_PATCH_TOOL);
+
+  if (!hasEdit && !hasApplyPatch) {
+    return active;
+  }
+
+  const desired = isGpt ? APPLY_PATCH_TOOL : EDIT_TOOL;
+  const drop = isGpt ? EDIT_TOOL : APPLY_PATCH_TOOL;
+
+  if (active.includes(desired) && !active.includes(drop)) {
+    return active;
+  }
+
+  const result: string[] = [];
+  let placed = false;
+  for (const tool of active) {
+    if (tool === EDIT_TOOL || tool === APPLY_PATCH_TOOL) {
+      if (!placed) {
+        result.push(desired);
+        placed = true;
+      }
+      continue;
+    }
+    result.push(tool);
+  }
+  if (!placed) {
+    result.push(desired);
+  }
+
+  return result;
+}