// cozyagents
the harness that runs your bots.
CozyAgents runs agents on your computer with a local or hosted model. Around the model loop, it adds execution policy, delivery records, and a path back from interruptions. It is early, with gains and limitations measured side by side.
release v0.2.16
bots you make in CozyChat run here.
CozyAgents pairs a computer to your gateway, keeps a runner alive in the background, and reconnects on its own after a network or service interruption. From the phone you follow the conversation, the tool activity, the approvals, and the results.
Before a tool batch runs, every call goes through preflight. A denied or duplicate sibling can block the whole batch before any sibling executes. Successful workspace mutations open a verification requirement; receipts tell the model what ran and what still needs checking. A failed verification stays open until a successful recheck.
check. act. verify.
- Check the whole batch.Policy validation happens before execution, so a blocked call does not quietly leave its siblings running.
- Record what happened.Tool receipts report execution state. Pending approvals are persisted before the request is shown.
- Keep verification live.Cacheable investigation reads may be reused. Mutations bypass the read cache and advance the workspace state epoch.
Execution-policy notes describe v0.2.16. Individual tools can explicitly opt out of opening a verification requirement.
What makes recurring delivery durable?
A scheduled occurrence carries a stable delivery ID, which maps to the same message identity on retry. That identity lets delivery recognize the same occurrence instead of producing a new message. Receipts are retained within a bounded history; this is delivery deduplication, not proof that a person read the result.
How does the read cache stay tied to the work?
Only explicitly cacheable investigation tools qualify. Cache identity includes the tool and schema, arguments, workspace fingerprint, and state epoch. Successful mutations advance that epoch. Mutation tools do not use the cache, and a cache failure falls back to a live read.
What still belongs to the operator?
Keep the computer available and preserve its pairing and data. A user service follows the operating system’s login and sleep behavior. Tool policy is not an operating-system sandbox, and a receipt is not independent proof of every external effect. General superiority over other harnesses has not been demonstrated.
a small start, and tools on request.
A turn opens with a one-line capabilities list, one line per tool set, and a single tool, attach. The model asks for a set; from the next step its tools are native in the request.
- capabilities listone line per set, at most 32 tokens
- attachthe always-on tool
- native toolsthe set from the next step
- dropafter eight quiet turns
Usually the model never asks.
| signal | sets attached |
|---|---|
| file path in the message | workspace |
| routine | sets it declared |
| four or more words on an empty thread | every line scored; specific matches rank above general |
| system prompt, cached | per-turn block, only when changed |
|---|---|
| identity, at most 400 tokens posture rules memory index | time who is in the room whether the phone is reachable |
The provider's prompt cache keeps hitting.
Partial development runs. Each finding names its report, model class and run count; figures stay in the report because setups differ. A standardized suite replaces these as the harness matures.
what the runs show
Seven development findings. Open a result for the evidence and its limits.
Smaller starting context
Fifty tool sets as cards open a turn on a fraction of the context eager schemas cost, and stay under the chat context ceiling at catalogue sizes where eager schemas do not.
- Report
- needle-at-scale
- Model
- hosted and local
- Coverage
- five catalogue sizes
- Date
A tradeoff in tool selection
On a fully specified task with fifty tool sets, cards pick the right tool slightly less often than an eager list, on both model classes, at a fraction of the context.
- Report
- needle-at-scale
- Model
- hosted and local
- Coverage
- fifty trials an arm
- Date
Hints help local models
The lexical pre-attach hint cuts steps, starting context and local-model turn time. The catalogue was built to suit it, so read its hit rate as a ceiling.
- Report
- needle-at-scale
- Model
- local
- Coverage
- fifty trials an arm
- Date
Skills with less context
Fifty skills as cards open a turn on a fraction of the context of spelled-out tiers. Named sections raise the hit rate on a hosted model; a local model also needs the pre-attach hint.
- Report
- needle-skills
- Model
- hosted and local
- Coverage
- twenty trials a variant
- Date
Faster warm reads
Cached tool reads make a warm call quicker than a cold one on a local model. The reliability gate never fired in that run, so no reliability claim.
- Report
- qualification
- Model
- local
- Coverage
- three trials an arm
- Date
Faster turns, slower starts
Against the build before the context work, today's CozyAgents finishes a greeting faster and answers a workspace question the old build mostly got wrong. Whole-turn time only: time to first token and setup got slower on most prompts.
- Report
- shootout section 7
- Model
- hosted and local
- Coverage
- five runs a prompt a build
- Date
Thirty scripted tool turns
Over thirty tool-bearing turns on the served-bot path against a local model, the scripted workload called the right tool with every required argument, every turn.
- Report
- live validation
- Model
- local
- Coverage
- thirty tool-bearing turns
- Date
Head to head, 2026-09-06
A separate run put CozyAgents, Hermes Agent and raw Pi on the same
prompts and models. Each line has model class and run count.
Figures: docs/benchmarks/2026-09-06-shootout-121.md in the private CozyAgents repo,
mirrored here.
Where it leads
- Plain greeting: CozyAgents opens the turn on a fraction of the context Hermes Agent or raw Pi use. hosted; three runs a cell
- 150-tool catalogue: an order of magnitude less starting context than raw Pi. hosted; seventy-five trials a cell
- Local model greeting: CozyAgents starts answering sooner than stock Hermes and finishes sooner; both clocks are in the report. local; three runs a cell
- Tasks all three can run: cost per success equals raw Pi and is below Hermes at the hosted list price frozen in the run. hosted; shared tasks
- Room turns: only CozyAgents can take one. hosted and local; every scored row
- No harness wrote outside its workspace in any of the 114 scored workspace rows. hosted and local; 114 workspace rows
Where it loses
- Fifty-set catalogue: it finds the right tool less often than raw Pi, on both model classes. hosted and local; seventy-five trials a cell
- Organising task, hosted model: the slowest harness in the run. hosted; three runs a cell
- Undo restored the workspace one turn in three; of four turns that reached for undo, one restored it. Too unreliable to claim. hosted and local; twelve scored rows
it comes with the gateway.
Run the CozyGateway installer on a computer with no Hermes Agent on it and the first thing it asks is which harness runs your bots.
Which harness runs your bots? [1] CozyAgents (recommended) [2] Hermes Agent [1]Enter installs CozyAgents beside the gateway, pairs it, and asks which provider or local endpoint and which model new bots use. A computer that already runs Hermes keeps it and skips the question.
macOS + Linux
curl -fsSL https://cozylabs.ai/setup | bashpin a specific release
Installs v0.8.2 instead of the newest release, for reproducing a bug report.
curl -fsSL https://cozylabs.ai/setup | COZYGATEWAY_INSTALL_TAG=v0.8.2 bashWindows PowerShell
irm https://cozylabs.ai/setup | iexpin a specific release
Installs v0.8.2 instead of the newest release, for reproducing a bug report.
$env:COZYGATEWAY_INSTALL_TAG='v0.8.2'; irm https://cozylabs.ai/setup | iexalready have a gateway? add this computer.
The harness alone. It asks for the pairing code from CozyChat (Settings > Computers > Add this computer), a name for the computer, and which gateway to join.
macOS + Linux
curl -fsSL https://cozylabs.ai/agents.sh | bashWindows PowerShell
irm https://cozylabs.ai/agents.ps1 | iexthe most performant local-model-first harness.
The goal. Local models expose harness quality: repeated calls, odd stopping points and swings with prompt shape. These are measurable execution problems, often fixable without touching the model.
We run every change three ways on the same model, prompts and tools: plain Pi, CozyAgents cold cache, CozyAgents warm cache. A change counts only when the paired run shows it; otherwise we mark it not demonstrated.
Measured so far: same success rate at a fraction of the starting context, fewer steps when the hint lands, faster tool time from safe caching. General tool-calling reliability: not yet demonstrated.
the fine print.
- source Private for now; the site mirrors each pinned release.
- isolation Process mode is no sandbox and a container shares the host kernel. Enable outside tools with care.
- Hermes A computer that already runs it keeps it.