chaff v0.4

Open-source TypeScript agent harness

Agents that live in real conversations, without the harness tax.

Most agent frameworks assume one developer, a local terminal, and a stack of config files. chaff is built for agents that behave like humans digitally: multi-party group threads, real-time voice calls, passage of time, and knowing when to stay quiet.

Dynamic skill loading, per-turn thinking routing, and three-tier compaction happen automatically, cutting output tokens by up to 89% on the exact same model with no knobs to tune.

Read the source
Node 20+ Bun Deno Cloudflare Workers Gemini / Claude / Kimi
Asia/Jerusalem · 3 speakers
The premise

A harness is not neutral plumbing. It shapes the tool schemas, formats the history, decides what stays in context, and determines whether your prompt cache hits 55% or 0%. You do not need to wait for the next frontier model to cut your token bill in half.

Architecture

Built for how people actually communicate

01

Multi-party first, not user/assistant ping-pong

Real messaging is not an alternating two-role array. chaff tracks named participant_utterance turns, message edits, emoji reactions, and out-of-band external_event webhooks separately from the model's own thoughts. When two humans are talking to each other in a group chat, the agent emits do_nothing and stays silent instead of chiming in on every message.

participant_utterance do_nothing external_event edits & reactions
02

Time is part of the state

Every turn carries timestamps and an IANA timezone. Long threads segment naturally on 30-minute conversation gaps, idle skills unlearn themselves once the topic moves on, and each turn respects a wall-clock execution budget alongside iteration caps.

timezoneIANA gap segmentation turn time budgets
03

One harness for IM and real-time voice

Pass the same AgentSpec, tools, skills, and event log to text channels (Gemini, Anthropic, Kimi with automatic safety-block fallback) or switch to transport: { kind: "audio" } for full-duplex Gemini Live calls with barge-in interruption handling.

Gemini / Claude / Kimi Gemini Live duplex barge-in flush
04

Economical and dynamic, with no knobs to babysit

Instead of asking you to hand-wire static tool subsets, reasoning budgets, and summary schedules, chaff adapts per turn. A lightweight decision model activates only the skills needed now and picks thinking depth (LOW, MEDIUM, HIGH). Large tool outputs spill to a scratchpad, settled sessions compact into structured summaries, and deterministic guards catch repetition floods, truncation, and unbacked claims at zero happy-path token cost.

on-demand skills thinking-level routing 3-tier compaction zero happy-path tax

Same-model benchmarks

Holding the model constant (gemini-3.8-flash)

Identical repositories, identical tasks, identical model. Every task passed on both sides. The only variable was the harness.

ClawBench · t2-config-loader
-89.2%
fewer output tokens vs. Pi
chaff
944
Pi
8,711
Turn-1 startup overhead
~800
initial tokens vs. 4,239 for Pi
chaff
~800
Pi
4,239
τ-bench Retail · 5/5 passed
55.2%
prompt cache hit rate vs. 0%
chaff
55.2%
LLMAgent
0%
Benchmark Metric chaff Baseline Delta
ClawBench t2-config-loader vs. Pi Output tokens 944 8,711 -89.2%
ClawBench t2-config-loader vs. Pi Total tokens 120,857 248,755 -51.4%
ClawBench t2-config-loader vs. Pi LLM calls 16 36 -55.5%
ClawBench t1-bugfix-discount vs. Pi Output tokens 1,239 7,600 -83.7%
τ-bench Retail (5/5) vs. reference LLMAgent Output tokens 1,137 3,406 -66.6%
τ-bench Retail (5/5) vs. reference LLMAgent Total API cost -22.1% 1.0x 55.2% cache hit

Deterministic history prefixes keep provider caches warm across multi-turn sessions, and preserving thoughtSignature + tool_call turn pairing eliminates the infinite limit-cycle loops Gemini thinking models otherwise hit. Read the full benchmark writeup →

API surface

Typed, composable, no framework lock-in