little-coder Agent工作流

Install

One-line install (Node.js 22.19+ required):

curl -fsSL https://raw.githubusercontent.com/itayinbarr/little-coder/main/install.sh | bash

Or with npm directly:

npm install -g little-coder

Or with bun:

bun add -g little-coder

That's the whole install. No clone, no npm install in a workspace, no PATH fiddling. little-coder is now on your PATH and works from any directory.

Note for bun add -g users. The launcher (bin/little-coder.mjs) is a Node.js script with #!/usr/bin/env node at the top, so Node ≥ 22.19 still has to be on your PATH for the binary to start — bun is fine for installing/updating the package, but the runtime is Node. If you want a fully node-less setup, replace the shebang in $(bun pm bin -g)/little-coder with #!/usr/bin/env bun.

Local model setup (optional)

Skip this section if you're using a cloud model.

Option A — llama.cpp (fastest for local; supports Qwen3.6-35B-A3B MoE):

```bash

One-time: build llama.cpp with CUDA (sm_XXX = your GPU arch; Blackwell = 120)

git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp cmake -B build -DGGML_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES=120 -DLLAMA_CURL=ON cmake --build build --config Release -j

Add 'make' (with word-boundary) and 'docker compose ps' on top of the defaults

export LITTLE_CODER_BASH_ALLOW="make ,docker compose ps"

Follow that version's README for its Python setup (pip install -e .)

```

The paper ran ollama/qwen3.5 through the Python little-coder at commit 1d62bde (tag v0.0.2). The 45.56 % mean figure is the average of two full 225-exercise runs on that exact codebase. For the 78.67 % headline, check out tag v0.0.5 — both are pre-pi Python and follow the pre-pi setup.

---

The mmproj (~900 MB) is what lets the model see attached screenshots.

pip install -U "huggingface_hub[cli]" hf download unsloth/Qwen3.6-35B-A3B-GGUF Qwen3.6-35B-A3B-UD-Q4_K_M.gguf --local-dir ~/models hf download unsloth/Qwen3.6-35B-A3B-GGUF mmproj-F16.gguf --local-dir ~/models

Pick the env vars matching whichever provider is running on the server

export LLAMACPP_API_KEY=noop export LLAMACPP_BASE_URL=http://<server-lan-ip>:8888/v1

Configuring models

The shipped model list lives in models.json at the package root. The llama-cpp-provider extension reads it at startup and registers each provider via pi's registerProvider(). Editing this file in your global install does take effect — but it's overwritten on npm install -g little-coder@latest, so for anything you want to keep, use a user override file instead.

User override resolution (first match wins):

1. $LITTLE_CODER_MODELS_FILE — explicit path, useful for ad-hoc tests.
2. $XDG_CONFIG_HOME/little-coder/models.json
3. ~/.config/little-coder/models.json

Merge semantics: each top-level provider key in your override file fully replaces the same key in the shipped models.json. Providers only in your file are added; providers only in the shipped file are kept. (We don't deep-merge per-model fields — you redeclare the whole provider entry, which avoids "your override silently inherited new fields from a future package release" surprises.)

Default model. A top-level "default": "provider/id" key names the model bare little-coder launches when you don't pass --model and pi has no saved selection yet (shipped default: llamacpp/qwen3.6-35b-a3b). Your override file's default wins over the shipped one, so {"default": "llamacpp/qwen3.6-27b"} in ~/.config/little-coder/models.json makes the dense 27B your first-run default. It's first-run-only: once you switch models in-session, pi remembers that and the default stops applying.

Per-phase models. /plan-model and /action-model let planning and implementation run on different models — see Per-phase model selection below.

Qwen3.8-27B (dense + MTP). Added to the shipped registry in v1.17.0. It's the quality option on a small card, not the fast one — measured on an RTX 5070 Laptop (8GB) with UD-Q4_K_XL:

Compare ~44 tok/s for Qwen3.6-35B-A3B (MoE) on the same box: the MoE is roughly 7× faster because its experts live in RAM (--n-cpu-moe), a trick a dense model has no equivalent for. Its NextN head is in the GGUF (qwen35.nextn_predict_layers=1, blk.64), so MTP speculative decoding works — measured draft acceptance ~0.87. The one caution worth repeating: at 32k, -ngl 20 passes /health and then produces zero tokens. It fits in VRAM but has no room left to compute, so "the server started" is not evidence the config works. Raise the context and you must lower -ngl.

Community-recommended models. The shipped models.json stays intentionally small and stable — it doesn't track the fast-moving world of community fine-tunes (which get re-uploaded and disappear from Hugging Face constantly). If you want to try one that's doing well in the community — e.g. Qwen3.6-35B-A3B-REAM-192, which topped both a community tournament and a little-coder pilot (#63) — add it to your own override file rather than waiting for it to ship. Load the GGUF on your llama.cpp server, then drop an entry in ~/.config/little-coder/models.json:

{
  "providers": {
    "llamacpp": {
      "api": "openai-completions",
      "baseUrl": "http://127.0.0.1:8888/v1",
      "apiKey": "LLAMACPP_API_KEY",
      "models": [
        { "id": "ream-192", "name": "Qwen3.6-35B-A3B REAM-192 (community)", "reasoning": true, "input": ["text"] }
      ]
    }
  }
}

Then pick it with little-coder --model llamacpp/ream-192. (llama.cpp serves whichever GGUF you loaded regardless of the id, so the id is just your handle for it.)

Example — switch the llama.cpp port and bump qwen3.6-35b-a3b to a 150K context, leave ollama untouched:

{
  "providers": {
    "llamacpp": {
      "api": "openai-completions",
      "baseUrl": "http://127.0.0.1:1234/v1",
      "apiKey": "LLAMACPP_API_KEY",
      "models": [
        {
          "id": "qwen3.6-35b-a3b",
          "name": "Qwen3.6-35B-A3B (local llama.cpp, 150K)",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 150000,
          "maxTokens": 4096,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

Then verify with little-coder --list-models — you should see your overridden entry.

LLAMACPP_BASE_URL, OLLAMA_BASE_URL, and LMSTUDIO_BASE_URL env vars still beat both files for those three providers.

Skip the gate entirely (use this only inside controlled environments)

export LITTLE_CODER_PERMISSION_MODE=accept-all ```

Write/Edit confirmations are pi's responsibility; little-coder doesn't intercept those.

---

Troubleshooting

--update flag — pass little-coder --update to force an immediate version check, bypassing the 12-hour cache. Useful right after a release. The flag is stripped before pi sees argv so it won't produce an "Unknown option" error.

Auto-update fails on Windows (≤ v1.9.5): npm exit null — the updater in those versions can't locate npm.cmd. Fixed in v1.9.6, but the broken updater can't deliver its own fix — run npm install -g little-coder@latest once to get there, then auto-update works normally.

little-coder: command not found — npm's global bin directory isn't on your PATH. Run npm config get prefix to see where it installed; add <prefix>/bin to your PATH. Or reinstall with sudo if your prefix needs root.

ECONNREFUSED 127.0.0.1:8888 — llama.cpp isn't running. Start llama-server first, or switch --model to an Ollama/cloud ID.

LAN client times out (no RST, just hangs) — the inference box's firewall is dropping the SYN. The usual cause is ufw with a default-deny policy that allow-lists only SSH / a few dev ports. From the server: sudo ufw status verbose to confirm; sudo ufw allow from <your-lan-subnet>/24 to any port 8888 proto tcp to fix (scoped to the LAN so you're not exposing the box). Docker-published ports bypass ufw via PREROUTING NAT, which is why a Docker container can be reachable while a plain llama-server on the same host isn't.

Image attachment is accepted but the request returns 4xx — your llama-server is running without a vision projector. Re-launch it with --mmproj ~/models/mmproj-F16.gguf (or another mmproj variant from the same GGUF repo). The --list-models images column reflects what the client will attempt to send, not what the server can answer; the projector is what gives the model eyes.

Failed to parse input at pos N: SomeTool(arg='…')]<|tool_call_end|> (LFM2 / Liquid models) — the model is emitting its native Pythonic tool calls (<|tool_call_start|>[Read(path='…')]<|tool_call_end|>), but llama.cpp's tool-call parser is choking on them — usually because the chat template doesn't match the parser. The GGUF's embedded template often renders tools as a plain List of tools: […] blob without the <|tool_list_start|> / <|tool_call_start|> special tokens the parser expects. Fix: serve with --jinja and the model's proper chat template, e.g. llama-server -m LFM2.5-8B-A1B-Q4_K_M.gguf --jinja --chat-template-file LFM2-8B-A1B.jinja (templates ship under llama.cpp/models/templates/). With the matching template, llama.cpp parses the calls into native tool_calls and tools execute normally — verified end-to-end with LFM2.5-8B-A1B. If your build still leaks the calls as plain text, little-coder's output-parser recognizes the format and surfaces this same diagnostic instead of a cryptic error (issue #42).

Context overflows on a long task before compaction kicks in — fixed in v1.9.12. pi only re-checks compaction when the model goes idle at the end of a turn sequence, so a single long autonomous run (dozens of tool calls) could grow context all the way to an overflow error before that check ever ran (issue #59). little-coder now watches context usage at every turn boundary and triggers pi's compaction mid-run once usage crosses 80 % of the window. Tune the trigger with LITTLE_CODER_COMPACT_AT_PERCENT=<n> (e.g. 70 to compact earlier; values ≤0 or ≥100, or LITTLE_CODER_NO_COMPACT_WATCHDOG=1, disable it and fall back to pi's end-of-run behavior). This is independent of pi's own reserveTokens / keepRecentTokens, which still govern how much is summarized vs. kept. As of v1.11.0 the watchdog also guards against a compaction loop (issue #68): if a mid-run compaction frees too little (usage stays near the threshold, e.g. a context window too small for the task), it pauses automatic compaction with a notice instead of firing a doomed second compaction that pi would reject with Nothing to compact — which previously left the session unrecoverable. It re-arms once usage drops back below the threshold (a /clear, /compact, or a smaller turn). If you hit the pause a lot, the real fix is a larger-context model or -c window.

No API key env var warning — pi expects some key even for local providers. Export LLAMACPP_API_KEY=noop (or OLLAMA_API_KEY=noop) before launching.

Update prompt hangs on launch / want it in the UI instead — when a new version is published the launcher asks Update now? [Y/n] before starting. As of v1.9.12 it auto-continues without updating after 10 s so an unattended terminal is never blocked; tune with LITTLE_CODER_UPDATE_PROMPT_TIMEOUT=<seconds> (0/off waits forever). If you dismiss or time out of the prompt, little-coder still shows a one-line "update available" notice inside the TUI, and you can run /update any time to install the latest and end the session for a clean restart (issue #64). As of v1.11.0, answering Y at the launcher prompt auto-relaunches into the new version with your original arguments (issue #66) — no manual re-run — printing Relaunching little-coder… (with a manual-relaunch fallback if the re-exec can't start). The in-app /update still ends the session for a manual restart, since it runs inside the pi child process where an in-place re-exec isn't safe.

No pi "Update Available" banner — that's intentional. little-coder defaults PI_SKIP_VERSION_CHECK=1 so the bundled pi runtime doesn't nag about updating itself; little-coder pins pi to a known-good version per release. If you actually want the banner back, export PI_SKIP_VERSION_CHECK=0 before launching.

Running little-coder from Zed's agent panel — there's no built-in ACP server, but a community pi-acp bridge works well; see docs/zed-acp.md for the full setup (issue #58).

Extension load failures on startup — run /extensions inside the TUI: it lists what loaded, where each one came from, and anything that failed. A user extension that can't be resolved also raises a notification at session start. little-coder --list-models --verbose surfaces pi's own load errors. If the install looks corrupt: npm uninstall -g little-coder && npm install -g little-coder.

My pi extensions / themes don't load — themes do load; extensions don't, by default. --no-extensions gates extensions only, so pi themes in ~/.pi/agent/themes work as normal. For extensions, relaunch with --with-pi-extensions, or put your own in ~/.config/little-coder/extensions/. See docs/extensions.md (issue #67).

A malware alert on npm install -g little-coder — Socket's AI scanner flagged the postinstall script in v1.10.0/v1.11.0 as suspicious. It was a false positive on a visible, dependency-free patcher, but as of v1.12.0 little-coder ships no install scripts at all — the launcher does that work at launch time instead, which is also the only path that ever ran for upgrading users, since /update installs with --ignore-scripts (issues #75, #50).

ctrl+r does nothing — it isn't bound at the prompt; pi binds "expand / more" to ctrl+o. Versions up to v1.11.0 advertised ctrl-r in the startup header, which was simply wrong (issue #74). Press ctrl+h for the current key list, or /hotkeys for the full reference. Note that during a Deep Research run there is nothing for ctrl+o to expand: research sub-coders are separate child processes, so their tool output never enters this session's transcript — the progress bar is the view of that work. While a dialog is open (the max-agents or clarifying-question prompts), keys belong to the dialog.

llama.cpp reprocesses the whole conversation every turn — fixed in v1.12.0. little-coder's per-turn skill and knowledge blocks used to be appended to the system prompt, which sits at the front of every request, so changing them invalidated the entire cached prefix and your server re-read the full history (issue #73). Those blocks now arrive as a message at the end of the conversation instead, leaving the prefix byte-identical. Watch the CH field in the status line to confirm cache reuse. LITTLE_CODER_INJECT_MODE=system restores the old placement, which is what the whitepaper scaffold numbers were measured against.

Node version too old — little-coder needs Node ≥ 22.19.0 (matching the minimum of the bundled @earendil-works/pi-coding-agent v0.75+). Check with node --version. Easiest fix: nvm install 22 && nvm use 22.

---