Sub-agents
Delegate and walk away — a background child job runs, and when it settles it wakes your conversation with the result. Steer, continue or fork it later.
A self-extending agent harness
Niffler is built from small Unix-style processes — every capability is a component on one NATS wire — so the agent can write, compile and spawn its own tools mid-conversation.
Niffler is as simple and efficient to drive as the leanest coding agents — cache-stable prompts, a tiny toolset, measured low token use. Sub-agents, background processes, a permission gate, MCP, LSP? In the box as well.
curl -fsSL https://raw.githubusercontent.com/gokr/niffler/main/scripts/bootstrap.sh | bash
v0.5.0 — Fleet, one settings surface, vector search
01 Fast & cache-effective
The request prefix is tiny and stays byte-stable for the
conversation's lifetime: a very small base prompt and a deliberately
small frozen direct toolset, so provider caches stay hot turn after
turn. Everything else is progressive discovery — one
discover/invoke away, entering as history
instead of prompt bloat. Fewer tokens per turn, quicker round trips —
and the numbers are measured in bench/ against Pi,
Opencode, DeepSeek Harness, CodeWhale, Droid and Claude Code, not
asserted.
What this measures. Numbers gathered with
DeepSeek‑V4.1‑Flash (deepseek-v4-flash) at
low thinking effort, called directly through DeepSeek's
first‑party API — no gateway, no proxy; the same key and endpoint for every
harness. The tasks are deliberately simple, well‑specified coding
exercises: this is not a capability benchmark. It measures the
three things that dominate real daily cost — tokens per task, wall‑clock per
task, and price per task — for normal work.
| Harness | Pass | Wall / task | Turns | Tool calls | Tokens / task (in / cache / out) | Cost / task | Cache hit |
|---|---|---|---|---|---|---|---|
| Pi 1.1.0 | 31/31 | 13.4s | 5.3 | 5.5 | 3.7k / 18.1k / 2.0k | $0.0037 | 83% |
| Niffler 0.4.0 | 31/31 | 15.4s | 6.1 | 7.8 | 4.0k / 31.6k / 2.1k | $0.0039 | 89% |
| Maki 0.6.0 | 31/31 | 12.1s | 6.3 | 8.0 | 9.7k / 53.2k / 1.5k | $0.0050 | 85% |
DSH 0.2.1 (sdk, out of the box) | 31/31 | 17.9s | 6.1 | 7.1 | 8.3k / 45.6k / 2.7k | $0.0061 | 85% |
| Opencode 1.18.35 | 31/31 | 23.3s | 5.4 | 5.7 | 18.2k / 87.9k / 1.1k | $0.0073 | 83% |
| OpenHands 1.24 | 31/31 | 25.7s | 0.9 | 6.6 | 8.8k / 84.6k / 3.9k | $0.0078 | 91% |
Scroll sideways to explore →
Full record and methodology: bench/reports/ in the repository.
Cache hit = cached read ÷ (cached read + uncached input) over the whole run.
All lanes run one cell at a time (jobs‑1), so wall times are uncontended.
Niffler = the average of two runs.
| Harness | Pass | Wall / task | Turns | Tool calls | Tokens / task (in / cache / out) | Cost / task | Cache hit |
|---|---|---|---|---|---|---|---|
| Pi | 31/31 | 24.4s | 5.3 | 5.0 | 3.8k / 17.4k / 2.1k | $0.0083 | 82% |
| Niffler | 31/31 | 29.5s | 6.5 | 7.6 | 7.0k / 31.3k / 2.3k | $0.0134 | 82% |
| Droid v0.251.0 (BYOK) | 31/31 | 30.2s | 1.9 | 8.3 | 3.4k / 65.6k / 2.4k | $0.0161 | 95% |
| Claude Code 2.1.318 | 31/31 | 33.7s | 14.1 | 7.0 | 0 / 45.0k (+18.1k w) / 1.2k | $0.0231 | 100% |
Scroll sideways to explore →
A second gateway, so a second table: these rows are not
comparable with the first-party numbers above. Claude Code is one uncontended run
(2.1.318, 5 Nov 2026; 2.1.286 measured the same suite at $0.0271/task and a
10 855-token first call), Pi/Niffler/Droid come from the 29 Oct 2026
three‑lane run; every cell in either set passed in round 1.
Read “in” with care: Synthetic's Anthropic endpoint reports each prompt
token as a cache write (18.1k per task here — the w figure) and none as fresh input, which is why
the hit column reads 100% while the lane is the most expensive — writes bill at the prompt
rate. Claude Code is also the busiest caller (14.1 messages per task, ~0.5 tool calls each,
against Droid's 1.9 messages at ~4.4 calls), so it re-bills its prefix seven times as often:
prefix size sets the per-call price, round trips set how often you pay it.
| Harness | Direct tools | Which | Base prompt | Base prompt + tools |
|---|---|---|---|---|
| Pi | 4 (+3 optional) | read · bash · edit · write (grep · find · ls off by default) | ≈0.68k | ≈1.4k |
| Niffler | 8 | discover · invoke · bash · read · write · edit · replace_across · grep (whole component catalog behind discover/invoke) | ≈0.28k | ≈2.1k |
| Maki | 19 | index · code_execution · task · bash · batch · read · write · edit · multiedit · edit_lines · grep · glob · list · webfetch · websearch · skill · todo_write · memory · view_image | — | ≈7.4k |
| DSH (out of the box) | 25 | bash · create_goal · edit · exit_plan_mode · get_goal · glob · grep · interrupt_agent · job_kill · job_list · job_output · list_agents · read · read_image · run_code · send_message · skill · subagent · subagent_fork · todo_write · update_goal · web_fetch · web_search · workflow · write | ≈6.5k | ≈11.7k |
| OpenHands | 3 (+3 system) | terminal · file_editor · task_tracker (finish · think · switch_llm) | generated per request | ≈12–16k |
| Opencode | 10 | bash · edit · glob · grep · read · skill · task · todowrite · webfetch · write | ≈10.7k | ≈16k |
| Claude Code | 23 | Agent · Bash · CronCreate · CronDelete · CronList · DesignSync · Edit · EnterWorktree · ExitWorktree · ListAgents · Monitor · NotebookEdit · PushNotification · Read · ReportFindings · ScheduleWakeup · SendMessage · Skill · TaskStop · WebFetch · WebSearch · Workflow · Write | ≈1.5k | ≈18k |
Scroll sideways to explore →
≈ k tokens (chars/4) from the exact first‑request bytes each harness sends into
an empty workspace — captured from live wire requests, Oct 2026. User content excluded (Pi lists
your installed skills in its prompt by default, Niffler adds the repo's AGENTS.md chain, Claude Code
the CLAUDE.md) — all captured the same way. Maki's figure is the measured first request of a
three‑word prompt in an empty git-rooted workspace (system + all 19 tool schemas; split
not exposed) — a probe run outside a git root silently adds the enclosing repo's AGENTS.md chain
(~8.4k tokens) to the request, which is where an earlier ≈15.9k figure came from. OpenHands generates its
system prompt at request time (not stored server‑side); the range is the observed first‑request
budget including its tool schemas. Claude Code's row lists the interactive tool surface; the
bench lane drives headless claude -p, whose system/init frame names a
different set (Task, Monitor, ToolSearch in place of
Agent, DesignSync, PushNotification), and whose measured
first call on these tasks is ≈9.2k tokens — the figure the gateway table above reports.
02 Interesting features, relatively rare
None of the following is exclusive to Niffler. But the lean harnesses make you give most of it up, and the big ones hide it behind their UI. Here it is all in one small box:
Delegate and walk away — a background child job runs, and when it settles it wakes your conversation with the result. Steer, continue or fork it later.
Delegate a goal to a registered worker — an Incus container, Lima VM or SSH host. In delegate mode it plans its own steps under the ceiling its operator set for that machine: tools, roots and round/call/token budgets, off until enabled. Containers and VMs run the worker in a separate guest; a human inbox lists settled work with its artifact. Continue delegated work in the same worker conversation, inspect its receipts or cancel it; durable admission stops a retry from blindly replaying the job.
Give an agent its own checkout for risky or parallel work.
With git mutations enabled, /worktree add NAME [--fork]
starts a branch beside the primary — optionally with a peer
conversation that has its own permissions. Preview the merge with
git_merge_preview (computed by
merge-tree, no working tree touched) and use
/worktree merge to land it cleanly; the fork's origin
conversation then gets a durable notice. Removal guards foreign
trees, dirty work and unmerged changes.
Worktrees are in the development version, not the current v0.5.0 release. See the unreleased changes and worktree manual.
Two conversations can share a checkout without silently
overwriting each other. Declared writes take bounded leases:
overlapping writes refuse with E_WRITE_BUSY and name
the holder, disjoint files stay parallel, and cancellation or
lease expiry recovers after a writer dies. Cooperative
coordination, not OS fencing.
Servers, watchers and builds run under the harness: start, poll, kill. No second terminal, no tmux discipline.
A tool can ask first. You answer y/N per call —
sub-agents included: their gated calls route to you, their budgets
are hard-wired. With no human reachable, the call is denied by
default; a resident instance can opt into a loud per-conversation
approval default for unattended work. Never silently allowed.
The agent writes a source file, compiles it, spawns it as a process and calls the new tool — mid-conversation, in any language. Community packages install the same way, always built from source.
fabric compiles a small guest program the agent
writes: typed wrappers over pinned tool schemas turn a dozen tool
calls into one native loop — effect-aware batching, budgets,
approvals by content digest.
Context pressure walks a visible ladder — a byte-exact prune that also drops tool results a later write made stale, then a checkpointed projection compactor (a replaceable seam), then eliding results the tool declares re-obtainable, then a proportional trim as a last resort. Only the compactor needs a model or a component; every other rung is deterministic and cannot fail. Nothing degrades silently, a trim is durable, and everything dropped stays recallable.
Each conversation gets its own session runner, so conversations run
truly in parallel and one dead runner loses only its in-flight turn.
An advisory peer (expert) can watch a session and
advise — turn-bound, never steering by itself.
Components are plain processes: Nim, Go, TypeScript — or a shell script with no SDK at all. The language is a preference.
03 Everything you take for granted
None of this is exotic — you expect it in a serious harness. Some minimal ones make you give it up. Niffler ships all of it:
Add a backend with one call and hop with /model and
/effort — no config files to hand-edit. OpenAI-compatible,
Anthropic and Codex lanes, or log in with your ChatGPT/Claude
subscription over OAuth. Pins are per-conversation. A
provider can name a separate embedModel, so chat and
embeddings can live on different backends.
Register any MCP server once (stdio, http or sse): a supervised bridge process per server announces its tools and prompts as ordinary catalog tools — same discovery, same approval gate, same call path.
Diagnostics, definitions, references, hover over real language
servers: Go, Nim, TypeScript/JavaScript, Python, Rust, C/C++, Bash,
Java, PHP, Ruby, C# ship configured. Yours missing? One entry in
servers.json — the agent can add it itself.
Code, files & the web
Conversations & context
context_recall/export the exact provider request, prompt_preview, context_status for context health and loss attribution, per-role counts, /compact now — --log=debug logs per-model-call timing to var/logsTrust & safety
store, bash, builder, llm, systemprompt — until NIF_TRUST or a recorded var/home-trust answer trusts it; an already-run home keeps working, and the boot log names each skipped componentEcosystem & extension
04 Clients, not containers
Niffler runs headless as a shared local service: the agent, its tools, background jobs and history live in the instance — not in a window. Clients are thin attachers over the bus; several can share one running instance at once. A client boots the harness on demand, an autostarted core turns itself off when the last client leaves — and closing your terminal mid-task loses nothing: background jobs keep running and wake the conversation when they settle. Completion receipts are durable per conversation, so a client reconnecting after a gap reconciles the finishes it missed — a turn with no receipt reads as unknown, never as success.
nats subgokr/niffler-ui) — same wire, its own repoService mode runs with no terminal at all
(niffler < /dev/null) — and niffler in a
terminal is an admin shell (status, catalog, sessions), not a chat.
05 Unix-style architecture
Every capability is a separate process that does one thing —
its own lifecycle, its own failures, isolated from the agent's mind. One
wire connects them all: JSON envelopes over NATS. So the agent can write,
compile and spawn a new tool mid-conversation, and teardown is
just exit(). The OS is the disposer.
the agent extends itself, in any language, while you talk to it
{
"v": 1,
"id": "1760825…-4242-1",
"kind": "call",
"tool": "bash",
"args": { "command": "uname -a" },
"caller": "cli"
}
Calls land on svc.<component>.call (core serves
svc.core.call), events fan out on ev.* —
four kinds: call · result ·
event · error. That is the whole bus
contract.
The codec is ~77 lines of pure std/json, mirrored 1:1
by the Nim, Go and TypeScript SDKs — spec:
docs/WIRE.md ·
rationale:
research/REBOOT.md
06 Sources of inspiration
Niffler is meant to be easily extended — a trait it shares with Pi, its biggest influence. It wears its sources on its sleeve. What we took, and from where:
Token efficiency, a small initial toolset and self-aware extendability — a harness meant to be easily extended. Niffler is built the same way and pushes a variant architecture: loosely coupled components, replaceable at runtime.
The more advanced component model, and the serious techniques most harnesses never attempt: projection-based compaction and the sub-agent model.
Simplicity of use — the standing reminder that a powerful harness can still be obvious to drive.
The strict cache regime, working especially well for models with cheap cached tokens like DeepSeek — where cache hits are the economics of the turn.
07 Install
curl -fsSL https://raw.githubusercontent.com/gokr/niffler/main/scripts/bootstrap.sh | bash
# asks: stable release or main, where to create ~/niffler (or | bash -s -- /your/dir), then offers the optional extras one by one
# or manually, from a clone:
git clone https://github.com/gokr/niffler.git && cd niffler
make setup && make build
cp .env.example .env # add a model API key
make install-tui # the terminal client (a plugin)
niffler-tui # boots the harness on demand
Niffler is built from source and distributed that way —
there are no prebuilt binaries. The one-line installer brings in
everything missing (git, make, curl, Go, then the Nim toolchain,
nimble packages and ripgrep via make setup); Node.js and npm are
optional and it asks first; at the end it offers the optional extras
one by one — language servers (make install-lsp), the
agent CLI toolkit for bash (make install-tools) and jev
(make install-jev) — each defaulting to no. Building by
hand, make doctor reports what is missing. The bus is
bundled and built from this repo — core spawns its own nats-server,
never an external install.
The desktop UI is an experimental spin-off — install it like any
package: cli install gokr/niffler-ui. Full story in the
manual ↗.