@aaroncql/pim-agent 0.0.1 → 0.1.0

package/README.md

@@ -3,7 +3,7 @@
 
 _**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)
   - [API Keys (Optional)](#api-keys-optional)
@@ -19,6 +19,8 @@ An opinionated yet minimal, Bun-native extension pack for [Pi](https://pi.dev/):
   - [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]
@@ -37,6 +39,12 @@ 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.
 
+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
+```
+
 ### 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):
@@ -96,7 +104,7 @@ Pim also ships with quality of life improvements for the TUI:
 - **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`)
 - **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
 
@@ -155,22 +163,25 @@ For development, run standalone with `pim --mode telegram` instead.
 
 ## 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.
+
 ### 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.
+Pim overrides Pi's default tools (`bash`, `read`, `write`, `edit`) so that all tools produce consistent behaviour and 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) |
+| [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.
 
-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%).
+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:
 
@@ -194,11 +205,11 @@ llama-server \
   -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 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, 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 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.
 

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.1.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/bash/capture.test.ts

@@ -1,126 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { concat, StreamCapture } from "./capture";
-import { STREAM_HEAD_BYTES, STREAM_TAIL_BYTES } from "./schema";
-
-const enc = new TextEncoder();
-const u8 = (s: string) => enc.encode(s);
-
-describe("concat", () => {
-  test("merges multiple chunks in order", () => {
-    const out = concat([u8("foo"), u8("bar")], 6);
-    expect(new TextDecoder().decode(out)).toBe("foobar");
-  });
-
-  test("returns empty array when total is 0", () => {
-    expect(concat([], 0).byteLength).toBe(0);
-  });
-});
-
-describe("StreamCapture", () => {
-  test("empty capture", () => {
-    const c = new StreamCapture();
-    expect(c.snapshot()).toEqual({
-      text: "",
-      totalBytes: 0,
-      truncated: false,
-      path: null,
-      nextStart: null,
-    });
-  });
-
-  test("ignores zero-byte chunks", () => {
-    const c = new StreamCapture();
-    c.push(new Uint8Array(0));
-    c.push(u8("hi"));
-    expect(c.snapshot()).toEqual({
-      text: "hi",
-      totalBytes: 2,
-      truncated: false,
-      path: null,
-      nextStart: null,
-    });
-  });
-
-  test("does not truncate when within head+tail budget", () => {
-    const c = new StreamCapture();
-    c.push(u8("hello"));
-    c.push(u8(" world"));
-    expect(c.snapshot()).toEqual({
-      text: "hello world",
-      totalBytes: 11,
-      truncated: false,
-      path: null,
-      nextStart: null,
-    });
-  });
-
-  test("truncates middle when over budget", () => {
-    const c = new StreamCapture();
-    const headChunk = "A".repeat(STREAM_HEAD_BYTES);
-    const middleChunk = "X".repeat(1000);
-    const tailChunk = "B".repeat(STREAM_TAIL_BYTES);
-    c.push(u8(headChunk));
-    c.push(u8(middleChunk));
-    c.push(u8(tailChunk));
-
-    const snap = c.snapshot();
-    expect(snap.truncated).toBe(true);
-    expect(snap.totalBytes).toBe(STREAM_HEAD_BYTES + 1000 + STREAM_TAIL_BYTES);
-    expect(snap.text.startsWith(headChunk)).toBe(true);
-    expect(snap.text.endsWith(tailChunk)).toBe(true);
-    expect(snap.text).toContain(`... ${1000} bytes truncated ...`);
-    expect(snap.nextStart).toBe(1);
-  });
-
-  test("reports the resume line at the end of the head when truncated", () => {
-    const c = new StreamCapture();
-    const lineBytes = STREAM_HEAD_BYTES / 4;
-    const headChunk = `${"A".repeat(lineBytes - 1)}\n`.repeat(4);
-    c.push(u8(headChunk));
-    c.push(u8("X".repeat(1000)));
-    c.push(u8("B".repeat(STREAM_TAIL_BYTES)));
-
-    const snap = c.snapshot();
-    expect(snap.truncated).toBe(true);
-    // Head holds exactly 4 newline-terminated lines, so reading resumes at 5.
-    expect(snap.nextStart).toBe(5);
-  });
-
-  test("splits a single chunk between head and tail when needed", () => {
-    const c = new StreamCapture();
-    const big = "Z".repeat(STREAM_HEAD_BYTES + STREAM_TAIL_BYTES + 500);
-    c.push(u8(big));
-
-    const snap = c.snapshot();
-    expect(snap.truncated).toBe(true);
-    expect(snap.totalBytes).toBe(big.length);
-    expect(snap.text.startsWith("Z".repeat(STREAM_HEAD_BYTES))).toBe(true);
-    expect(snap.text.endsWith("Z".repeat(STREAM_TAIL_BYTES))).toBe(true);
-    expect(snap.text).toContain(`... ${500} bytes truncated ...`);
-  });
-
-  test("keeps head and final tail when many middle chunks arrive", () => {
-    const c = new StreamCapture();
-    const HEAD_FILL = "A".repeat(STREAM_HEAD_BYTES);
-    c.push(u8(HEAD_FILL));
-    for (let i = 0; i < 100; i++) {
-      c.push(u8("M".repeat(STREAM_TAIL_BYTES)));
-    }
-    const finalTail = "B".repeat(STREAM_TAIL_BYTES);
-    c.push(u8(finalTail));
-
-    const snap = c.snapshot();
-    expect(snap.truncated).toBe(true);
-    expect(snap.text.startsWith(HEAD_FILL)).toBe(true);
-    expect(snap.text.endsWith(finalTail)).toBe(true);
-  });
-
-  test("at exact head+tail boundary is not truncated", () => {
-    const c = new StreamCapture();
-    c.push(u8("A".repeat(STREAM_HEAD_BYTES)));
-    c.push(u8("B".repeat(STREAM_TAIL_BYTES)));
-    const snap = c.snapshot();
-    expect(snap.truncated).toBe(false);
-    expect(snap.totalBytes).toBe(STREAM_HEAD_BYTES + STREAM_TAIL_BYTES);
-  });
-});

package/src/extensions/bash/format.test.ts

@@ -1,240 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import {
-  detailsOf,
-  formatResult,
-  formatTruncationAffordance,
-  isErrorResult,
-  stripTrailingNewline,
-} from "./format";
-import {
-  type BashCommandResult,
-  STREAM_HEAD_BYTES,
-  STREAM_TAIL_BYTES,
-} from "./schema";
-
-function makeResult(
-  overrides: Partial<BashCommandResult> = {}
-): BashCommandResult {
-  return {
-    exitCode: 0,
-    signal: null,
-    stdout: {
-      text: "",
-      totalBytes: 0,
-      truncated: false,
-      path: null,
-      nextStart: null,
-    },
-    stderr: {
-      text: "",
-      totalBytes: 0,
-      truncated: false,
-      path: null,
-      nextStart: null,
-    },
-    timedOut: false,
-    aborted: false,
-    durationMs: 1,
-    ...overrides,
-  };
-}
-
-describe("stripTrailingNewline", () => {
-  test("removes one trailing newline", () => {
-    expect(stripTrailingNewline("foo\n")).toBe("foo");
-  });
-  test("leaves no-newline strings alone", () => {
-    expect(stripTrailingNewline("foo")).toBe("foo");
-  });
-  test("only strips one", () => {
-    expect(stripTrailingNewline("foo\n\n")).toBe("foo\n");
-  });
-});
-
-describe("formatTruncationAffordance", () => {
-  test("emits bracketed affordance with byte counts and next-step", () => {
-    const out = formatTruncationAffordance("stderr", {
-      text: "x",
-      totalBytes: 12345,
-      truncated: true,
-      path: null,
-      nextStart: 1,
-    });
-    expect(out.startsWith("[bash tool:")).toBe(true);
-    expect(out.endsWith("]")).toBe(true);
-    expect(out).toContain("stderr showing first");
-    expect(out).toContain(`first ${STREAM_HEAD_BYTES} bytes`);
-    expect(out).toContain(`last ${STREAM_TAIL_BYTES} bytes`);
-    expect(out).toContain("of 12345");
-    expect(out).toContain("redirect to a file");
-    expect(out).toContain("read");
-  });
-
-  test("points to spill path with a resume line when one is provided", () => {
-    const out = formatTruncationAffordance("stdout", {
-      text: "x",
-      totalBytes: 99999,
-      truncated: true,
-      path: "/tmp/pim-bash-abc.out",
-      nextStart: 42,
-    });
-    expect(out).toContain(
-      "use read with path=/tmp/pim-bash-abc.out and start=42 for the rest."
-    );
-    expect(out).not.toContain("redirect to a file");
-  });
-});
-
-describe("formatResult", () => {
-  test("happy path with stdout only", () => {
-    const out = formatResult(
-      makeResult({
-        stdout: {
-          text: "hello\n",
-          totalBytes: 6,
-          truncated: false,
-          path: null,
-          nextStart: null,
-        },
-      }),
-      30_000
-    );
-    expect(out).toBe("Exit code: 0\nstdout:\nhello");
-  });
-
-  test("includes signal line when signal present", () => {
-    const out = formatResult(
-      makeResult({ exitCode: null, signal: "SIGTERM" }),
-      30_000
-    );
-    expect(out).toContain("Exit code: none");
-    expect(out).toContain("Signal: SIGTERM");
-  });
-
-  test("aborted overrides timed out message", () => {
-    const out = formatResult(
-      makeResult({ aborted: true, timedOut: true }),
-      30_000
-    );
-    expect(out).toContain("Aborted.");
-    expect(out).not.toContain("Timed out");
-  });
-
-  test("timed out adds duration message", () => {
-    const out = formatResult(makeResult({ timedOut: true }), 5000);
-    expect(out).toContain("Timed out after 5000 ms.");
-  });
-
-  test("includes both stdout and stderr when both have bytes", () => {
-    const out = formatResult(
-      makeResult({
-        exitCode: 1,
-        stdout: {
-          text: "out",
-          totalBytes: 3,
-          truncated: false,
-          path: null,
-          nextStart: null,
-        },
-        stderr: {
-          text: "err",
-          totalBytes: 3,
-          truncated: false,
-          path: null,
-          nextStart: null,
-        },
-      }),
-      30_000
-    );
-    expect(out).toBe("Exit code: 1\nstdout:\nout\nstderr:\nerr");
-  });
-
-  test("appends bracket affordance after a truncated stream body", () => {
-    const out = formatResult(
-      makeResult({
-        stdout: {
-          text: "head…tail",
-          totalBytes: 99999,
-          truncated: true,
-          path: null,
-          nextStart: 1,
-        },
-      }),
-      30_000
-    );
-    const lines = out.split("\n");
-    expect(lines[0]).toBe("Exit code: 0");
-    expect(lines[1]).toBe("stdout:");
-    expect(lines[2]).toBe("head…tail");
-    expect(lines[3]?.startsWith("[bash tool: stdout showing first")).toBe(true);
-    expect(lines[3]?.endsWith("]")).toBe(true);
-  });
-
-  test("does not append affordance when stream is not truncated", () => {
-    const out = formatResult(
-      makeResult({
-        stdout: {
-          text: "ok",
-          totalBytes: 2,
-          truncated: false,
-          path: null,
-          nextStart: null,
-        },
-      }),
-      30_000
-    );
-    expect(out).not.toContain("[bash tool:");
-  });
-});
-
-describe("detailsOf", () => {
-  test("mirrors per-stream truncation and byte counts", () => {
-    const details = detailsOf(
-      makeResult({
-        exitCode: 1,
-        durationMs: 42,
-        stdout: {
-          text: "x",
-          totalBytes: 99999,
-          truncated: true,
-          path: null,
-          nextStart: 1,
-        },
-        stderr: {
-          text: "y",
-          totalBytes: 5,
-          truncated: false,
-          path: null,
-          nextStart: null,
-        },
-      })
-    );
-    expect(details).toEqual({
-      exitCode: 1,
-      signal: null,
-      durationMs: 42,
-      timedOut: false,
-      aborted: false,
-      stdout: { totalBytes: 99999, truncated: true, path: null },
-      stderr: { totalBytes: 5, truncated: false, path: null },
-    });
-  });
-});
-
-describe("isErrorResult", () => {
-  test("zero exit code is not an error", () => {
-    expect(isErrorResult(makeResult({ exitCode: 0 }))).toBe(false);
-  });
-  test("non-zero exit code is an error", () => {
-    expect(isErrorResult(makeResult({ exitCode: 1 }))).toBe(true);
-  });
-  test("null exit code is an error", () => {
-    expect(isErrorResult(makeResult({ exitCode: null }))).toBe(true);
-  });
-  test("aborted is an error", () => {
-    expect(isErrorResult(makeResult({ aborted: true }))).toBe(true);
-  });
-  test("timed out is an error", () => {
-    expect(isErrorResult(makeResult({ timedOut: true }))).toBe(true);
-  });
-});