# executus

> ⚠️ **This project is vibe-coded.**
> executus is written almost entirely by an AI coding agent (Claude), with a
> human steering at the design and review level rather than typing the code.
> That's a deliberate choice, stated up front — the same way [gadfly] is. Read
> the code before you depend on it, pin a version, and file issues if something
> looks off. It is offered as-is.

[gadfly]: https://gitea.stevedudenhoeffer.com/steve/gadfly

A **batteries-included base for building LLM agent harnesses in Go.** Import it,
do a little wiring, and you have agentic capabilities: a bounded run loop, a tool
registry with a suite of common tools, context compaction, config-driven model
tiering and failover, structured output, and parallel fan-out — with sensible
defaults so a brand-new project is agentic with almost no setup, and pluggable
seams so a serious host can swap in its own storage, config, delivery, and tools.

executus sits **strictly above** [majordomo] — the lean LLM substrate (agent
loop, canonical `llm` types, providers, media normalization, model parsing /
failover / tiering). majordomo stays the substrate; executus is the opinionated,
batteries-included layer on top. executus requires **no changes to majordomo**.

[majordomo]: https://gitea.stevedudenhoeffer.com/steve/majordomo

## Status

Early. Being extracted, phase by phase, from the agent layer of [mort] (a Discord
bot) — mort and gadfly are the first two consumers (heavy and light). See
`CLAUDE.md` for the architecture and the extraction roadmap (P0–P6).

[mort]: https://gitea.stevedudenhoeffer.com/steve/mort

**Available today:**

- `run/` — **executus is runnable.** `run.Executor` ties model resolution, the
  tool registry, majordomo's agent loop, context compaction, run-bounding, and
  step/audit instrumentation into one `Run(ctx, RunnableAgent, inv) Result`, with
  every host concern behind a nil-safe `run.Ports` (Audit/Budget/Critic/
  Checkpointer/PaletteSource/Delivery). See `examples/minimal`.
- `model/` — config-driven tier resolution + failover over majordomo, with
  pluggable `UsageSink`/`TraceSink` and `GenerateWith[T]` structured output.
- `tool/` — the tool registry + 3-stage permission model + SSRF guard.
- `compact/` — the per-run context compactor.
- `lane/` — bounded worker pool with fair-share queueing (run- and
  provider-concurrency).
- `fanout/` — programmatic N×M swarm with bounded global + per-key concurrency.
- `config/`, `deliver/`, `identity/` — host seams (config / output / identity),
  each with a shipped default.
- `dispatchguard/`, `pendingattach/` — run-safety primitives.
- `examples/reviewer` — a **gadfly-shaped PR reviewer on the core only** (env-config
  model fleet → `fanout` N×M swarm → `model.GenerateWith[T]` structured findings →
  consolidation), the light-tier canary; CI asserts it pulls in no battery.

## Design

Two tiers in one module (`go.mod` = majordomo + stdlib only):

- **Core** — everything a light host needs to be agentic: run loop, tool
  registry + common tools, model resolution, compaction, lanes, fan-out,
  structured output. No persistence, no scheduling.
- **Batteries** (opt-in sibling packages) — persona/agent nouns, saved skills,
  audit, run-critic, scheduling, budgets, checkpointing. Each is nil-safe and
  ships a default, so you add only what you use.

Persistence that needs a real database lives in a **separate** nested module
(`contrib/store`, pure-Go SQLite) so the core never drags in a DB driver — a
static-binary host (gadfly) stays static.

## License

TBD.