newt-agent 0.7.3

Newt-Agent — small, fast, local-first agentic coder (vi to Hermes's emacs)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

# Newt-Agent

<p align="center">
  <img src="docs/logos/newt-agent-logo_source.png" alt="Newt-Agent logo" width="256" />
</p>

> Small, fast, local-first agentic coder.
> **vi to Hermes-Agent's emacs.**

A single Rust binary with a sharp, minimal tool set. It runs against your
local hardware by default — no cloud bytes leave your machine unless you
deliberately install a provider plugin. Opinionated, not extensible.

## Why — the bridle, not just the harness

An agent *harness* helps the model do work; a **bridle** lets the operator
*steer* — and prove, after the fact, exactly where the horse went. Newt is an
experiment in making Object Capability (OCAP) security — long considered
theoretically correct but practically unimplementable — pragmatic inside an
agent loop, as a reusable concept
([`agent-bridle`](https://github.com/Gilamonster-Foundation/agent-bridle))
intended to be pluggable into other harnesses, not just this one.

OCAP's algebraic construction means some questions are answered
*structurally*, not by audit-log archaeology:

- Who acted on what, and when?
- Who granted the authority for this to do that?
- Did what they permitted actually happen — and did **only** what they
  permitted happen?

For anyone whose work lives on provenance, authority, integrity, and data
sovereignty — lawyers, clinicians, data scientists — those answers have to be
properties of the system, not promises in a policy document.

If it doesn't find its day in the sun, it was fun anyway.

## Quick start

```bash
git clone https://github.com/Gilamonster-Foundation/newt-agent
cd newt-agent
just install          # release binaries → ~/bin/newt, ~/bin/newt-mcp-server
newt code             # TUI coder in the current directory
```

Run `newt --help` for every mode (worker, MCP server, doctor, config, …) —
the binary is the authority on its own surface, this file is not. Python
bindings live in [`newt-agent-py/`](./newt-agent-py/) (`pip install
newt-agent-py`, import path `newt_agent`).

## Design laws

The invariants. Each links to the decision record that argues it.

- **Local-first inference.** The default binary speaks only to local
  backends. Cloud providers are opt-in subprocess plugins speaking the
  JSON-RPC schema in [`plugins-protocol/`](./plugins-protocol/) — the opt-in
  is enforced at the **build** level, not a runtime flag.
- **Fail-closed OCAP.** Authority is a caveat lattice, not a denylist; a
  fixed safety floor no mode or grant can unlock. See
  [`docs/decisions/agentic_object_capability_security.md`](./docs/decisions/agentic_object_capability_security.md)
  and [`docs/decisions/ocap_confinement_model.md`](./docs/decisions/ocap_confinement_model.md).
- **Small crates, zero warnings, coverage-gated.** `just check` mirrors CI;
  the pre-push hook runs it. One operator's leverage *is* this discipline.
- **Patch, not prose.** Delegated work is verified by the harness (real
  diffs, real test runs — [`newt-eval/`](./newt-eval/)), never by trusting a
  model's summary of itself.
- **Skills are on-demand context.** The prompt carries an index; bodies load
  when used. See [`docs/decisions/agent-skills.md`](./docs/decisions/agent-skills.md)
  and the bundled skills in [`.newt/bundled-skills/`](./.newt/bundled-skills/).
- **Issues are ground truth.** [`ROADMAP.md`](./ROADMAP.md) sequences
  delivery, but GitHub issue state is authoritative — the document is only
  the map.
- **Causal ordering, not wall-clock.** Timestamps are display *claims*; the
  conversation store orders on signed per-writer ticks + content hashes. See
  [`docs/decisions/conversation_context_architecture.md`](./docs/decisions/conversation_context_architecture.md).

## Field notes

The durable output of this experiment is what building it teaches about how
LLMs behave inside a harness:

- **[Summarization-induced hallucination](./docs/notes/2026-06-13-summarization-induced-hallucination.md)**
  — context compression that *summarizes* a session can make the model
  hallucinate APIs it had already read. A confident summary is worse than a
  labelled absence: absence routes the model to re-read; a summary suppresses
  recovery.
- **[Truncation honesty](./docs/testing/results/context-baseline-f0f4f6e.md)**
  — silent context truncation yields *silently wrong* answers; every fix
  moves the failure, it doesn't always remove it.
- **[Coder-driving sweet spots](./docs/notes/2026-05-31-newt-coder-driving-sweet-spots.md)**
  — where small local models are and aren't reliable at agentic coding.
- **[Hermes learnings](./docs/design/context-memory-hermes-learnings.md)**
  — take the algorithms, refuse the architecture.

## Where things live

| What | Where |
|---|---|
| Forward plan | [`ROADMAP.md`](./ROADMAP.md) (issue numbers are the live state) |
| Release history | [`CHANGELOG.md`](./CHANGELOG.md) |
| Design docs & studies | [`docs/design/`](./docs/design/) |
| Decision records | [`docs/decisions/`](./docs/decisions/) |
| Evaluation harness | [`newt-eval/README.md`](./newt-eval/README.md) |
| Local gate | `just check` (see [`justfile`](./justfile)) |

## License

Apache-2.0. See [LICENSE](./LICENSE).