Niffler

A self-extending agent harness

Simple and fast harness.
Batteries included.

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.

Install GitHub ↗
curl -fsSL https://raw.githubusercontent.com/gokr/niffler/main/scripts/bootstrap.sh | bash

v0.5.0 — Fleet, one settings surface, vector search

niffler-tui, the terminal chat client: a conversation with tool calls, an approval prompt and per-turn cache statistics
niffler-tui — one client of a shared, local instance. Cache hit rate reported on every turn.

01 Fast & cache-effective

Strict cache regime,
token efficient.

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.

Benchmark full31 — 31 small coding tasks, one round each, first‑party DeepSeek (Oct 2026)
HarnessPassWall / taskTurnsTool callsTokens / task (in / cache / out)Cost / taskCache hit
Pi 1.1.031/3113.4s5.35.53.7k / 18.1k / 2.0k$0.003783%
Niffler 0.4.031/3115.4s6.17.84.0k / 31.6k / 2.1k$0.003989%
Maki 0.6.031/3112.1s6.38.09.7k / 53.2k / 1.5k$0.005085%
DSH 0.2.1 (sdk, out of the box)31/3117.9s6.17.18.3k / 45.6k / 2.7k$0.006185%
Opencode 1.18.3531/3123.3s5.45.718.2k / 87.9k / 1.1k$0.007383%
OpenHands 1.2431/3125.7s0.96.68.8k / 84.6k / 3.9k$0.007891%

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.

Benchmark full31 — the same 31 tasks through a hosted gateway (DeepSeek V4.1 Flash, low effort, Nov 2026)
HarnessPassWall / taskTurnsTool callsTokens / task (in / cache / out)Cost / taskCache hit
Pi31/3124.4s5.35.03.8k / 17.4k / 2.1k$0.008382%
Niffler31/3129.5s6.57.67.0k / 31.3k / 2.3k$0.013482%
Droid v0.251.0 (BYOK)31/3130.2s1.98.33.4k / 65.6k / 2.4k$0.016195%
Claude Code 2.1.31831/3133.7s14.17.00 / 45.0k (+18.1k w) / 1.2k$0.0231100%

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.

Direct tools & fixed prompt — what each harness puts in front of the model
HarnessDirect toolsWhichBase promptBase prompt + tools
Pi4 (+3 optional)read · bash · edit · write (grep · find · ls off by default)≈0.68k≈1.4k
Niffler8discover · invoke · bash · read · write · edit · replace_across · grep (whole component catalog behind discover/invoke)≈0.28k≈2.1k
Maki19index · 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)25bash · 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
OpenHands3 (+3 system)terminal · file_editor · task_tracker (finish · think · switch_llm)generated per request≈12–16k
Opencode10bash · edit · glob · grep · read · skill · task · todowrite · webfetch · write≈10.7k≈16k
Claude Code23Agent · 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

Not one of a kind —
rarely all together.

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:

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.

Fleet — remote workers

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.

Isolated Git worktrees

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.

Write arbitration

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.

Background processes

Servers, watchers and builds run under the harness: start, poll, kill. No second terminal, no tmux discipline.

Permission gate

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.

Self-extension

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.

Programmable tool calling

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.

Compaction as a projection

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.

One conversation = one process

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.

Any language

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

The table stakes,
all of them.

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:

Providers, no JSON

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.

MCP in, tools out

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.

LSP for your language

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

  • File toolsbatched windowed reads, locate-and-fetch select reads, exact-match edit with a guarded fallback, literal bulk replace across a file set, atomic write, persistent undo
  • Searchgitignore-aware grep and file finding — stateless replicas so parallel calls really run in parallel
  • Gitstatus, diff, log, show, blame — read-only and approval-free
  • Web fetchreal HTML extraction, SSRF-validated, oversized bodies spill to disk
  • Imagesscreenshot in, multimodal turn out — MIME checks, caps and pixel budgets included
  • Repo mapranked symbols auto-appended where a repo earns it

Conversations & context

  • Steeringcourse-correct mid-turn without cancelling the work in flight
  • Full recalltrimmed or compacted-away messages stay searchable through context_recall
  • Durable resumecanonical append-only history in the store — restart mid-task and continue, attachments included
  • Per-conversation controlstool allowlists, budgets, workspace pin plus human-granted extra roots, provider/model/effort pins
  • Introspection/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/logs
  • Slash commandsbuilt in — plus ones contributed by installed plugins and MCP servers

Trust & safety

  • Approvals everywhereany gated caller, sub-agents included — routed to the human driving the turn; denied when none is reachable, with an opt-in per-conversation default for unattended instances
  • Sub-agent limitshard budgets that cannot be talked around; soft limits negotiate over the approval channel
  • Concurrent-write conflictsoverlapping writes refuse and name the holder; cancellation releases a confirmed-stopped writer's claim, leases bound crash recovery, and disjoint paths stay parallel — coordination, not filesystem fencing
  • Remembered grantsper-tool “don't ask again”, digest-keyed for program-shaped calls
  • Fail closedtimeouts deny, unknown limits refuse, a missing component degrades explicitly — never silently
  • Least privilegeMCP environment allowlists and guard processes, no bus access or secrets in fabric's executor, redacted listings
  • First-open trustopening a cloned harness home runs only the core bootstrap set — 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 component
  • Opt-in shell guardLinux only and off by default: one bash command gets a read-only host view, private /tmp, no network and no bus — and read masks hide operator-named paths from reads and writes whether or not the guard is on. A mask is not a confidentiality boundary.

Ecosystem & extension

  • Agent SkillsSKILL.md skills: list, search, install and audit — interop with the wider skills ecosystem
  • PluginsGitHub packages cloned and built from source, approval-gated, manifest v1 or v2 recipes
  • Three SDKsNim, Go and TypeScript around one tiny portable codec — or no SDK at all, a shell script speaks the wire
  • Tool profilesnamed toolset selectors resolved once per conversation, or sticky tools promoted on demand
  • One settings surfaceevery component publishes a discoverable config domain: list, inspect and patch with schema validation, compare-and-set revisions and approval — secrets redacted, human-only keys writable only by a person
  • A store that answersserver-side full-text search, plus nearest-neighbour search over embeddings on SQLite — one contract; TiDB reports vectors unsupported

04 Clients, not containers

The harness
isn't a UI.

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.

Service 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

Small programs,
one wire.

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.

minimal profile · 6 processes nats-server · core · store · bash · llm · systemprompt
stock boot · +23 above minimal builder · plugins · config · skills · recall · compaction · fetch · jev · models · provider · grep ×4 · mcp · edit · locks · lsp · repomap · processes · git · observe · logfile · agent · expert · fabric
+10 more ship in the box fleet · remote workers, opt-in — store-tidb · alternate store engine — llm-openai · example adapter — mcp-bridge · one per MCP server — fabric-exec · fabric's executor — hooks · event hooks, off by default — von · optional decision-runtime launcher — cli · console · scripting · live bus viewer — dialog · SDK-free bash demo, now in examples/dialog
envelope.json
{
  "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

Credit where
credit is due.

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:

Pi

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.

DSH

The more advanced component model, and the serious techniques most harnesses never attempt: projection-based compaction and the sub-agent model.

Opencode

Simplicity of use — the standing reminder that a powerful harness can still be obvious to drive.

Reasonix

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

Two minutes in.

terminal
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 ↗.