edgar

The agent harness you can read in an afternoon. Any model. No hidden calls. Nothing is done until it's verified.

uvx edgar-harness                                # interactive
git diff | edgar -p "review this" --mode read-only
edgar -p "bump httpx and fix what breaks" --mode auto --verify "just check"

Status: design complete (spec v0.4). Implementation has started with milestone M0, the package skeleton; nothing runs yet beyond edgar --version. The documents in docs/ are the spec being built against.

Why edgar

• Small enough to read. The core is under 5,000 lines, with a size budget enforced in CI. Fork it and change it without first learning 40,000 lines.
• Any model. OpenAI, Azure, Anthropic, OpenRouter, Ollama, or any OpenAI-compatible server as a config block. API keys, not a vendor's subscription. Works with small local models too.
• No hidden calls. edgar never contacts a host you did not configure, has no telemetry, and its system prompt is a short file you can read and replace.
• Done means verified. A turn that changed something ends when your check passes, not when the model says it is finished.

What it is

edgar runs an LLM in a tool-using loop, in the directory you launched it from, against OpenAI, Azure, Anthropic, OpenRouter, Ollama or any OpenAI-compatible server. It has permissions, a verify-before-done gate, context compression, custom tools for CLIs and APIs, skills, subagents, memory, MCP and extensions.

It ships in three tiers, each with a size budget:

None of that is unusual. What is unusual is that the whole thing is small enough to read in an afternoon, and the parts usually hidden behind an SDK are written out plainly: how tool calls differ between providers, how compaction avoids corrupting a transcript, how a permission decision is actually made.

It is a teaching artifact first and a usable tool second. Where those two goals conflict, teaching wins. That trade is why some things are simpler than they could be (SQLite FTS instead of embeddings) and some are stricter than they need to be (a 150 ms startup budget enforced in CI).

Why it exists

Agent harnesses come in two sizes. Toys that teach you nothing beyond a while loop and a function call, and production systems whose complexity buries the interesting parts. There is a gap in the middle: a harness that implements the genuinely hard bits honestly, at a size a person can hold in their head.

What it does

Terminal-native. Interactive REPL for daily use, -p for one-shot and pipes. Result on stdout, status on stderr, real exit codes. Composes with the rest of your shell.

Five providers, two adapters, any compatible server. OpenAI, Azure, OpenRouter and Ollama share one OpenAI-compatible adapter driven by a quirks table; Anthropic has its own. Any other OpenAI-compatible server is a config block. Anything else is one module and one registry entry, or a provider plugin package.

Subagents with their own models. Declared in markdown, not code. Run a cheap local model for exploration and an expensive one for review, in parallel, each with its own tool allowlist and budget.

Model routing that isn't magic. Declarative rules pick the model before the turn, as a pure function with zero model calls. Escalation and fallback are kept separate from routing and from each other, because "not capable enough" and "not reachable" want different responses. Every switch is announced.

Extend it without Python. Give the agent a CLI with a command tool (an argv template, never a shell) or an API with an HTTP tool (a request template with the host fixed and secrets from the environment). Add MCP servers, skills in Claude's SKILL.md format, subagents in markdown, and hooks that can veto a tool call. Bundle any of it into an extension folder and share it by copying.

Long sessions that stay valid. Context is compressed in stages, cheapest first: big outputs spill to disk, old tool results become stubs, old turns fold into one summary. It never splits a tool call from its result, and the full record stays on disk.

Memory that stays trustworthy. Hand-authored instructions and machine-learned facts live in separate places, on purpose. Only what you type, or an error the harness classified itself, becomes a fact. When the model wants to remember something, it asks you first. Tool output and web pages never reach memory.

Safe to point at a repo you just cloned. Project hooks, MCP servers and tools run only after you trust the project. The agent cannot edit its own config without asking, and auto mode tightens after it reads untrusted content.

A controller that cannot hurt you (v2). Deterministic checks after each turn; a cheap model runs only when one trips. It returns typed proposals from a fixed whitelist, dry-run by default, fully logged, and it can only ever tighten policy. It cannot write your instruction files — it proposes a diff and you apply it.

Scheduling without a daemon (v2). One tick command plus one host cron entry. Agents can schedule themselves, with guardrails.

Easy to build on. -p --json for one result, -p --events for the live event stream as JSON Lines, and edgar.run() from Python. No daemon, no HTTP API.

What it deliberately is not

No MCP server mode. No daemon or HTTP API. No vector store. No multi-user. No GUI. No race to support fifty providers. The full list with reasoning is in PRD §5.2, written down so scope creep has something to argue with.

Documentation

Reading the source

Once it exists, in this order:

1. core/message.py and core/units.py — the vocabulary and the invariant
2. core/loop.py — the whole thing in 200 lines
3. tools/base.py and tools/execute.py — the contract and its pipeline
4. permissions/policy.py — one pure function
5. context/compact.py — where the subtlety is
6. tools/custom.py — command and HTTP tools
7. providers/routing.py — the same shape as permissions, deciding models instead of access

Licence

AGPL-3.0-or-later. Use it, fork it and change it freely. If you distribute a modified edgar, or run one as a service for others, you share your changes under the same licence. The reasoning is in ADR-0026.