little-coder 1.8.4 → 1.9.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to little-coder are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and little-coder's public interface (CLI, providers, tools, skills) follows semver starting at `v0.0.1` post-rename.
 
+## [v1.9.1] — 2026-06-08
+
+### Fixed
+- **Plan Mode shortcut moved to `alt+p` so `shift+tab` stays pi's thinking-level cycle** ([#47](https://github.com/itayinbarr/little-coder/issues/47)). v1.9.0 claimed `shift+tab` for Plan Mode by rebinding pi's built-in `app.thinking.cycle` to `alt+t` in `~/.pi/agent/keybindings.json`. That collided with the muscle memory of every existing pi user — `shift+tab` is the documented thinking cycle — and pi (≥ 0.79) also surfaced an `[Extension issues]` warning whenever the rebind hadn't taken yet. Plan Mode now registers on **`alt+p`** instead (unbound by pi, so the extension claims it cleanly with no shadowing), and `shift+tab` returns to pi's default behavior. The launcher also performs a **one-time cleanup**: on first run after upgrade, if `~/.pi/agent/keybindings.json` still has the v1.9.0 rewrite (`app.thinking.cycle: "alt+t"` exactly), it is removed; any binding you set yourself is preserved untouched. README and the Plan-Mode indicator (`(alt+p to exit)`) updated to match.
+
+### Notes for upgraders
+- No CLI-flag or public-API changes. **Plan Mode is now `alt+p`** (was `shift+tab` in v1.9.0). `shift+tab` is again pi's thinking-level cycle. If you customized `app.thinking.cycle` yourself in `~/.pi/agent/keybindings.json`, your binding is left alone.
+
+---
+
+## [v1.9.0] — 2026-06-15
+
+### Added
+- **Plan Mode (shift+tab).** A Claude-Code-style "research → ask → plan" flow, built as the new `plan-mode` extension. Press **shift+tab** to toggle it (an honey `◆ PLAN MODE` indicator appears below the input). When it's on, submitting a request does *not* run a normal coding turn — instead little-coder: (1) decomposes the request into 1-4 exploration tasks, (2) dispatches read-only explorer sub-coders to gather information (their transcripts never enter the main context — only their concise reports survive), (3) generates 1-3 clarifying questions, each with suggested answers plus a free-text "Other" option, asked via the UI, and (4) synthesizes the findings + your answers into a written plan in the chat. Each reasoning phase ("deciding what to explore…", "preparing clarifying questions…") shows an animated spinner with a running m:ss timer. The planning instructions + research are injected into the synthesis turn's system prompt, so the chat shows only your original request and the plan — never the internal scaffolding. A single continuous m:ss timer runs for the whole process (not just the per-sub-coder timers). When the plan is presented, an **Approve & implement / Keep planning** prompt (arrow keys + enter) gates implementation — only on approval does little-coder start making the changes. **Esc** (or Ctrl+C) cancels a plan in progress.
+- **Up-arrow prompt history** (`prompt-history` extension), **persisted across sessions**. pi's default editor has no prompt recall; from an empty prompt, **↑** now walks back through your recent prompts (most-recent first) and **↓** walks forward. History is saved to `<agentDir>/little-coder-prompt-history.json`, so even a brand-new session can recall prompts from earlier runs. Implemented as a `CustomEditor` subclass (pi copies its keybindings/autocomplete/submit wiring onto it) using `keybindings.matches` for ↑/↓ detection — robust to pi's Kitty keyboard protocol and key-release events — and scoped to recall-from-empty so it never interferes with multi-line cursor movement or the autocomplete dropdown. Edits/writes are blocked during the synthesis turn so plan mode produces a plan, not changes. shift+tab previously cycled the thinking level; pi (≥ 0.79) reserves built-in shortcuts and won't let an extension claim a colliding one, so the launcher rebinds the thinking-level cycle to **alt+t** in `~/.pi/agent/keybindings.json` (non-destructively — only when you haven't set your own binding for it), freeing shift+tab for Plan Mode.
+- **Sub-coders (`dispatch` tool).** little-coder can now spawn isolated child little-coder sessions to research a focused question — single (`{ task }`) or parallel (`{ tasks: [{ label, task }] }`, up to 4, concurrency 2 by default, override with `LITTLE_CODER_SUBCODER_CONCURRENCY`). Children run with the **same local-model provider and extensions** as the parent (spawned through the launcher headless, not bare `pi`) but are constrained to **read + browse-online** tools (read, grep, glob, webfetch, websearch, browser, read-only bash) — no edit/write and no recursive dispatch, enforced via the existing `tool-gating` + `permission-gate` env gates. Each child returns a **concise report**; its full transcript lives in the tool's UI-only `details` and never enters the parent model's context, keeping the main window clean. New `subagent` extension (`spawn.ts` engine, importable by plan mode).
+- **Live sub-coder tracker.** A small animated panel above the input shows each running/finished sub-coder with a spinner, status (✓/✗), elapsed time, and current activity (the latest tool call or report snippet), with a diff-guarded ~120 ms repaint. Hidden on non-interactive (benchmark/RPC) runs.
+- **Session naming + terminal title sync.** The session is auto-named from your first prompt (overridable any time with pi's `/name`), and the terminal tab title now shows the session name (`little-coder · <name>`), updating when you switch sessions with `/resume`. pi's built-in `/resume` already lists past sessions for the current directory.
+- **Read-before-edit guard.** New `read-guard-edit` extension: a file must be **Read** in the current session before it can be **Edited** — an edit to an unread file is blocked with "File must be read first before edit" and a nudge to Read it (so `old_string` matches exactly). Files you just wrote count as read. Mirrors the `write-guard` enforcement pattern.
+
+### Changed
+- **`glob` match cap lowered 500 → 100** (`extra-tools/glob.ts`) to keep results focused for small models. (`grep` was already capped at 100.)
+- **Default thinking level is now `medium`** for interactive sessions (pi's default is `minimal`) — the launcher passes `--thinking medium` unless you set a level yourself (`--thinking`, or a `--model …:<level>` shorthand) or run headless (`--mode`/`-p`).
+- **Auto-named session titles are capped at 4 words**, cut on word boundaries (no more mid-word truncation) with a trailing `…` when the prompt was longer.
+
+### Dependencies
+- **Bumped bundled pi `@earendil-works/pi-coding-agent` 0.75.3 → 0.79.4.** The "Operation aborted" marker patch (`scripts/patch-pi.mjs`) still applies cleanly to the new source (verified by `patch-pi.test.mjs`). pi 0.79 no longer hoists `@earendil-works/pi-tui` to the top level, so the `dispatch` tool's result renderers now build their lines as duck-typed components via the theme (the same pattern `branding` already uses) instead of importing pi-tui primitives — no behavior change.
+
+### Notes for upgraders
+- No breaking CLI-flag or public-API changes. **shift+tab now toggles Plan Mode** instead of cycling the thinking level — use **alt+t** for the thinking-level cycle (the launcher writes this rebinding into `~/.pi/agent/keybindings.json`, preserving any binding you've already set). New env var `LITTLE_CODER_SUBCODER_CONCURRENCY` (default 2) tunes how many sub-coders run at once against your local backend.
+
+---
+
 ## [v1.8.4] — 2026-06-08
 
 ### Added

package/README.md

@@ -60,6 +60,14 @@ little-coder --list-models                      # see everything pi knows about
 
 The agent uses the directory you launched it from as its working directory — `Read` / `Write` / `Edit` / `Bash` operate on your project, not on little-coder's install path.
 
+### Interactive features
+
+- **Plan Mode** — press **alt+p** to toggle (a `◆ PLAN MODE` indicator shows below the input). Submit a request and little-coder researches it with sub-coders, asks you 1-3 clarifying questions (each with suggested answers and a free-text option), then writes a plan in the chat instead of editing anything. **Esc** cancels a plan mid-run. (**shift+tab** stays pi's thinking-level cycle.)
+- **Prompt history** — from an empty input, **↑** recalls your recent prompts (most-recent first), **↓** walks forward. History persists across sessions, so a fresh session can recall prompts from earlier runs.
+- **Sub-coders (`dispatch`)** — little-coder can spawn isolated child sessions to research a question (read the repo + browse online, read-only) and report back concisely, without cluttering the main conversation. A live panel above the input tracks them. Tune parallelism with `LITTLE_CODER_SUBCODER_CONCURRENCY` (default 2).
+- **Sessions** — each session is auto-named from your first prompt (rename with `/name`) and shown in the terminal tab title. Use `/resume` to list and reopen past sessions for the current directory.
+- **Read-before-edit** — editing a file requires reading it first, so edits match the file's exact current text.
+
 For local providers (llama.cpp, Ollama, LM Studio) pi expects *some* value in the API-key env even though local servers ignore it:
 
 ```bash
@@ -99,12 +107,14 @@ build/bin/llama-server -m ~/models/Qwen3.6-35B-A3B-UD-Q4_K_M.gguf \
 
 If you only need text and want to skip the projector download, drop the second `hf download` line and the `--mmproj` flag — little-coder still works text-only, but the TUI's image attachment will be rejected by the server with a 4xx.
 
+**Context window.** `-c` sets the server's context (`-c 16384` = 16K above — a conservative default for 8 GB VRAM). little-coder **auto-detects the live `n_ctx`** from llama.cpp's `/props` at startup and registers the model with it, so whatever you pass to `-c` is what the TUI shows and budgets against — no `models.json` edit needed. To run larger, relaunch the server with e.g. `-c 131072` (128K) or `-c 262144` (256K); the KV cache grows with it, so size it to your RAM/VRAM. (`--list-models` reflects the detected window.)
+
 **Option B — Ollama** (simpler, but slower on MoE):
 
 ```bash
 curl -fsSL https://ollama.com/install.sh | sh
 ollama pull qwen3.5        # 9.7B — the paper's model
-# or: ollama pull qwen3.6-35b-a3b
+# or: ollama pull qwen3.6:35b-a3b
 ```
 
 **Option C — LM Studio** (GUI; OpenAI-compatible server on port 1234):
@@ -330,11 +340,15 @@ The benchmarks harness (`benchmarks/`) is dev-only and not shipped with the npm
 little-coder/
 ├── .pi/
 │   ├── settings.json               # per-model profiles + benchmark_overrides (terminal_bench, gaia)
-│   └── extensions/                 # 23 TypeScript extensions, auto-discovered by pi
-│       ├── branding/               # little-coder startup header + terminal title (replaces pi's built-in)
+│   └── extensions/                 # 27 TypeScript extensions, auto-discovered by pi
+│       ├── branding/               # little-coder startup header + terminal title + session auto-naming
+│       ├── plan-mode/              # alt+p "research → ask → plan" flow (sub-coders + clarifying questions → written plan)
+│       ├── subagent/              # `dispatch` tool: isolated read/browse-only sub-coders + live tracker (spawn.ts engine)
+│       ├── prompt-history/         # up-arrow recall of recent prompts (from an empty input)
 │       ├── llama-cpp-provider/     # data-driven provider registration from models.json — ships llamacpp, ollama, lmstudio (+ user override file)
 │       ├── write-guard/            # Write refuses on existing files; rewrites root-bare /foo.md paths to cwd
 │       ├── read-guard/             # trims a Read that would overflow the context window to its first 30 lines + a search-instead directive
+│       ├── read-guard-edit/        # Edit refuses until the file has been Read this session
 │       ├── extra-tools/            # glob, webfetch, websearch (pi ships grep/find)
 │       ├── skill-inject/           # per-turn tool-skill selection (error > recency > intent)
 │       ├── knowledge-inject/       # algorithm cheat-sheet scoring (word=1.0, bigram=2.0, threshold=2.0)

package/bin/little-coder.mjs

@@ -9,6 +9,7 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
@@ -36,6 +37,13 @@ if (tooOld) {
 const here = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(here, "..");
 
+// Headless sub-coder fast-path. When the subagent extension re-invokes this
+// launcher to spawn a child little-coder (--mode json -p), the update check and
+// the global-settings merge below are pointless per-child overhead (network +
+// disk) — and we want children to start fast. The env flag is set by
+// .pi/extensions/subagent/spawn.ts::buildChildEnv.
+const isSubagent = process.env.LITTLE_CODER_SUBAGENT === "1";
+
 // ---- 3. Resolve the bundled pi CLI entry point ----
 // We invoke pi's JS entry directly under the current Node binary instead of
 // the `node_modules/.bin/pi` shim. Two reasons:
@@ -110,10 +118,12 @@ try {
 } catch {
   // ignore — update-check just won't fire if we can't read the version
 }
-const exitAfterCheck = await checkForUpdate(currentVersion);
-if (exitAfterCheck) {
-  // Successful update happened; user needs to re-run the new binary.
-  process.exit(0);
+if (!isSubagent) {
+  const exitAfterCheck = await checkForUpdate(currentVersion);
+  if (exitAfterCheck) {
+    // Successful update happened; user needs to re-run the new binary.
+    process.exit(0);
+  }
 }
 
 // ---- 6. Compose pi argv ----
@@ -124,10 +134,22 @@ if (exitAfterCheck) {
 // Strip our own flags before forwarding to pi so it doesn't reject them.
 const userArgs = process.argv.slice(2).filter((a) => a !== "--no-update-check");
 const agentsMd = join(pkgRoot, "AGENTS.md");
+
+// Default the thinking level to "medium" for interactive sessions (pi's own
+// default is "minimal"). Only when the user hasn't asked for a level themselves
+// (--thinking, or the --model "provider/id:level" shorthand) and this isn't a
+// headless/sub-coder run (--mode rpc/json) where the caller controls thinking.
+const userPickedThinking =
+  userArgs.includes("--thinking") ||
+  userArgs.some((a, i) => a === "--model" && /:/.test(userArgs[i + 1] || ""));
+const headless = isSubagent || userArgs.includes("--mode") || userArgs.includes("-p");
+const thinkingArgs = !userPickedThinking && !headless ? ["--thinking", "medium"] : [];
+
 const piArgs = [
   "--no-context-files",
   "--no-extensions",
   ...(existsSync(agentsMd) ? ["--system-prompt", agentsMd] : []),
+  ...thinkingArgs,
   ...extArgs,
   ...userArgs,
 ];
@@ -167,7 +189,10 @@ if (process.env.PI_SKIP_VERSION_CHECK === undefined) {
 //
 // Existing keys are preserved. We only write when the desired value differs
 // from what's already on disk, so this is a no-op on warm launches.
-try {
+//
+// Skipped for headless sub-coders: they share the user's settings (already
+// written by the interactive parent) and shouldn't each re-do the merge.
+if (!isSubagent) try {
   const agentDirEnv = process.env.PI_CODING_AGENT_DIR;
   let agentDir;
   if (agentDirEnv && agentDirEnv.trim().length > 0) {
@@ -219,6 +244,32 @@ try {
   if (mutated) {
     writeFileSync(globalSettingsPath, JSON.stringify(globalSettings, null, 2));
   }
+
+  // ---- 8b. One-time cleanup of the v1.9.0 keybinding rewrite ----
+  // v1.9.0 wrote `app.thinking.cycle: "alt+t"` into ~/.pi/agent/keybindings.json
+  // so the plan-mode extension could claim shift+tab (issue #47). Plan mode now
+  // lives on alt+p, so shift+tab should go back to pi's default thinking-cycle
+  // binding — but only if the value is *exactly* the one we wrote. A user who
+  // chose their own binding (anything ≠ "alt+t") wins.
+  const keybindingsPath = join(agentDir, "keybindings.json");
+  if (existsSync(keybindingsPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(keybindingsPath, "utf-8"));
+      if (parsed && typeof parsed === "object" && parsed["app.thinking.cycle"] === "alt+t") {
+        delete parsed["app.thinking.cycle"];
+        if (Object.keys(parsed).length === 0) {
+          // Don't leave an empty {} sitting around — remove the file so pi
+          // reads its defaults cleanly.
+          rmSync(keybindingsPath);
+        } else {
+          writeFileSync(keybindingsPath, JSON.stringify(parsed, null, 2));
+        }
+      }
+    } catch {
+      // Corrupted JSON or unreadable — leave it alone; pi will surface its own error.
+    }
+  }
+
 } catch {
   // Best-effort. If we can't write the settings (read-only HOME, etc.) pi
   // falls back to its built-in defaults — the [Extensions] block will show

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "little-coder",
-  "version": "1.8.4",
+  "version": "1.9.1",
   "description": "A pi-based coding agent optimized for small local language models. Reproduces the whitepaper's scaffold-model-fit adaptations as pi extensions.",
   "homepage": "https://github.com/itayinbarr/little-coder",
   "repository": {
@@ -38,7 +38,7 @@
     "postinstall": "node scripts/patch-pi.mjs"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^0.75.3",
+    "@earendil-works/pi-coding-agent": "^0.79.4",
     "@sinclair/typebox": "^0.34.49",
     "playwright": "^1.59.1"
   },

package/skills/tools/dispatch.md

@@ -0,0 +1,38 @@
+---
+name: dispatch-guidance
+type: tool-guidance
+target_tool: dispatch
+priority: 6
+token_cost: 140
+user-invocable: false
+---
+## Dispatch Tool (sub-coders)
+Delegate focused research to isolated child little-coder sessions ("sub-coders").
+Each runs in its own context window, can READ the repo and BROWSE online
+(read, grep, glob, webfetch, websearch, browser, read-only bash) but CANNOT
+edit or write files. Each returns a concise report. Use this to gather
+information without filling your own context with raw file dumps or web pages.
+
+SINGLE: `task` (string) — one research question.
+PARALLEL: `tasks` — array of `{label, task}`, up to 4, run concurrently.
+OPTIONAL: `cwd` (defaults to the current working directory).
+
+RULES:
+- Give each parallel task a short, distinct `label` — it shows in the live tracker.
+- Ask narrow, answerable questions ("how does auth work in this repo?", not "do everything").
+- You receive only each sub-coder's short report; the full transcript stays in the
+  tool's details (not in your context). Act on the reports.
+- Sub-coders can't change files — do the editing yourself after they report back.
+
+EXAMPLE (single):
+```tool
+{"name": "dispatch", "input": {"task": "Find where sessions are persisted in this repo and summarize the format."}}
+```
+
+EXAMPLE (parallel):
+```tool
+{"name": "dispatch", "input": {"tasks": [
+  {"label": "repo auth", "task": "How does authentication work in this codebase? Cite files."},
+  {"label": "lib docs", "task": "Look up the current recommended API for the jose JWT library online."}
+]}}
+```