Hexa-native AI coding agent — plugin-first · LLM-bypass cost-routing · multi-provider · agents.md SSOT
Minimal core · everything-else-is-a-plugin · raw-mode TUI · streaming render · plugin-bundle · ai-native dispatch
wilson is a hexa-native AI coding agent. The whole thing is one statically-linked multi-call binary (busybox-style): a minimal core (agent loop + event bus + plugin loader + provider interface + TUI primitives) plus a default 28-plugin bundle that's everything-else (harness · tools · providers · governance · memory · recap · cost · permissions · hooks · MCP · slash commands · bridges). Heavy / dangerous / session-less plugins run as separate processes via JSONL IPC. hexa-lang only — no TypeScript, no dual-twin.
Note
AI agent harness file is AGENTS.md (agents.md standard). CLAUDE.md is a symlink to it; wilson reads AGENTS.md directly via the agents-md plugin (walk-up from cwd, prepended to system_prompt at session_start). Read AGENTS.md first for build state, conventions, traps, session protocol. Sister format .tape lives at dancinlab/tape — wilson's runtime traces, identity, and domain ledgers all use it.
$ wilson "investigate flaky test_concurrent_writes — fails 1/20 runs"
⏺ analyzing — provider=claude-cli model=opus-4-7
[⚙ grep] tests/test_io.rs:412
[⚙ read] tests/test_io.rs:400-440
[⚙ edit] tests/test_io.rs ⎿ Added 1 · Removed 0
+ barrier.wait(); # race: shared mutex dropped before second writer joins
⏺ fixed race in tests/test_io.rs:421 — added barrier sync before second writer.
$ wilson tool git --subcmd diff --args HEAD~1 HEAD # LLM-bypass — same plugin path, no token cost
$ wilson task add "verify 100 reruns stay green" # persistent task list
$ wilson session list # session transcripts (per-sid .tape)
$ wilson -p "summarise the fix in 1 sentence" # one-shot print mode (no TUI)wilson(==ws) launches the raw-mode TUI;-p "..."prints one turn and exits;--harness rpcruns as a swarm-cell over JSONL stdin/stdout.- Every registered tool is callable from the shell without going through the LLM — same plugin-dispatch path, byte-identical args + ToolResult. That's wilson's cost-routing design pillar.
- Multi-provider out of the box:
provider-claude-cli(default · OAuth viaclaude -p),provider-anthropic(API key fallback),provider-openai-compat(MLX-LM / vLLM / HF Inference / FastAPI-shim).
See AGENTS.md for the full surface; docs/wilson-cli-argv-modes.md for argv modes.
Most AI coding agents are baked-in monoliths — every feature wired into the core, expensive to swap, impossible to slim. The opposite pattern: everything-else-is-a-plugin, irreducible core (agent loop + event bus + provider interface + TUI primitives + plugin loader). 28 plugins ship as the default static-linked bundle; heavy / dangerous / session-less ones run as separate processes; wilson build --with X --without Y lets you assemble your wilson at compile time.
The second pillar is LLM-bypass cost-routing — the LLM is the most expensive resource in the loop, so deterministic tools (file I/O, git, web, hexa build, image probe, task / memory / session / recap state) get a CLI shortcut that hits the same plugin-dispatch path the agent loop uses, byte-identical. wilson <noun> <verb> from a shell, a CI script, a swarm cell, or another agent's child-tool produces the same result the LLM would — without paying for it.
Third: hexa-lang only. The whole codebase is hexa — no TypeScript, no dual-twin. When something blocks in hexa-lang itself (a stdlib gap, a toolchain bug), wilson files an upstream patch (update || PR) and waits — not work around. The atlas (proven constants + formulas) is the long-term knowledge base.
- v0.0.1 alpha (2026-05-14) — interactive TUI ships, multi-turn tool calls work,
wilson test --e2epasses end-to-end on Darwin-arm64 - 28-plugin default bundle:
hello · harness-{cli,print,rpc} · tool-core · provider-{claude-cli,anthropic,openai-compat} · endpoint-registry · agents-md · sysprompt · prefs · governance · bridge-{hexa,git,gh} · tool-web · tool-task · tool-image · recap · swarm · pool · cost · permissions · hooks · notebook · mcp · slash-core - 35 tools · 22 slash commands · 3 providers
- TUI: raw-mode + alt-screen · cell-grid diff renderer · char-boundary line editor · streaming render · multimodal v2 (image / vision) · 5 Hz spinner · Shift+Enter multi-line input
wilson test17/17 PASS ·wilson test --e2e19/19 PASS ·hexa build core/main.hexa -o build/<host>/wilsonsucceeds on Mac- Sister formats:
.tapev1.1 (agent-execution trace) wired into_identity_block+ root<DOMAIN>.tape(HCX / ORIGIN / POOL / TEST / TAPE)
Important
Project-level governance lives in AGENTS.md ## Governance (deny / allow / ssot-lock / note prefixes). The governance plugin enforces those at tool_call_pre @ validate BEFORE the global ~/.wilson/governance/rules.jsonl. Same source for plugin enforcement + LLM context — they cannot diverge.
┌─ wilson (static-linked multi-call hexa binary, busybox-style) ──────────┐
│ │
│ core/ = vocabulary + skeleton + the wire + loader + provider iface + TUI │
│ types.hexa host.hexa event_bus.hexa loader.hexa │
│ agent_loop.hexa main.hexa test_fixture.hexa │
│ core knows nothing about what any plugin does — it loads + pumps events │
│ │
│ + static-linked default bundle (plugins/_bundle): │
│ harness-cli · harness-print · harness-rpc · tool-core · providers · …│
└──────────────────────────────────────────────────────────────────────────┘
separate processes (heavy / risky / session-less): wilson plugin-daemon <id>
swarm cell: wilson --harness rpc (= same binary, different mode)
external-repo dep (large): bedrock · resource · tape
- core = irreducible — message types (
Message/ToolCall/AsmEventpayload-enum/HookEvent) + agent-loop skeleton + event bus (fire_hook: validate short-circuit → transform fold → observe) + plugin loader (@pluginmanifest parsing + 9-step validation + dispatch routing) + provider interface (handle-basedstream_open/next/close) + TUI primitives. That's it. - everything else = plugin — one
pub fn <id>_dispatch(action, payload) -> any+@plugin(...)manifest. Providers / tools / hooks / commands / views / governance / memory / compaction / resource-mgmt / swarm / bridges — all of it. Hot-path plugins static-link into the binary; heavy / risky / session-less ones run as separate processes with JSONL IPC; large governance / resource modules live in external repos (bedrock/resource) as plugin deps. - hexa-lang RULES.md compliance — no
>=/<=operators,exec(...)requires a policy comment, no silent catch / silent exit.PORT_PITFALLS.mdtraps avoided.
2-axis classification — family (4 + misc) × category (10). SSOT is core/loader.hexa (plugin_family / plugin_category); wilson plugin list renders grouped. Full table + members in plugins/README.md.
| family | meaning | categories | members |
|---|---|---|---|
| io | in and out | harness · provider · bridge |
harness-{cli,print,rpc} · provider-{claude-cli,anthropic,openai-compat} · bridge-{hexa,git,gh} |
| tools | what to do | tool |
tool-core · tool-web · tool-task · tool-image |
| policy | how to wrap | context · guardrail · telemetry |
agents-md · sysprompt · prefs · memory · compaction-{local,llm} · governance · permissions · hooks · cost · resource-management · statusline · recap |
| orchestration | many together | orchestration |
swarm · pool · endpoint-registry · mcp · slash-core · notebook |
| misc | the rest | example · meta |
hello · _bundle · _bundle_cell |
Bridge = adapter that wraps an external CLI / system as a structured tool (graceful absence — if the peer CLI is missing, returns ok=true · is_error=false instead of crashing). Common ones bundled by default (bridge-{hexa,git,gh}, ~200 LoC each, opt-out WILSON_NO_BRIDGE_{HEXA,GIT,GH}=1).
.tape is wilson's runtime trace format — typed events + provenance edges + delivery grade + append-only + KV-cache-stable. Wilson uses it across 5 placements (canonical matrix from tape v1.1 spec):
| Placement | What | Wired in wilson |
|---|---|---|
~/.wilson/identity.tape |
agent identity SSOT (singleton) | core/main.hexa::_identity_block() reads it → renders ## Identity system-prompt slot #1 |
~/.wilson/harness-cli/sessions/<sid>.tape |
per-session conversation events | harness-cli plugin persists messages here (transcripts) |
~/.wilson/recap/index.tape |
session pointer index | recap plugin appends on session_start |
~/core/wilson/<DOMAIN>.tape |
per-domain history (governance #4 sibling of <DOMAIN>.md) |
root HCX / ORIGIN / POOL / TEST / TAPE.tape track per-topic events |
~/core/atlas/<PROJ>::<DOMAIN>.tape |
cross-project federated history | atlas-housed — e.g. wilson::governance.tape |
.tape content is read-write via the tape CLI (installed by hx install tape — see dancinlab/tape):
tape from-md TAPE.md TAPE.tape tape # .md → .tape (one-shot migration)
tape to-md TAPE.tape /tmp/TAPE.md # .tape → .md (whole-tape projection)
tape query-table HCX.tape --section=Inventory # adjacent @D rows → markdown table
tape render-identity ~/.wilson/identity.tape # → ## Identity prompt block
tape domain-status ~/core/wilson # walk repo, status matrix
tape grep <sid>.tape --type=T --grade=denied # what did governance blockDesign SSOT: TAPE.md — adoption design + 7-content-type matrix + 6-Phase path. Sibling formats: n6 (semantic atoms) · hxc (byte-canonical wire) · n12 (multidimensional cube).
# 1. Install hexa-lang (gives you `hexa` + `hx` package manager)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/dancinlab/hexa-lang/main/install.sh)"
# 2. Install wilson
hx install wilson
# 3. Optional — short alias `ws` (symlinks ws → wilson on PATH)
ln -sf wilson ~/.hx/bin/wshx install picks up bin/wilson and symlinks it into ~/.hx/bin/. The launcher runs the compiled build/<host>/wilson if present and runnable on the host, else build/wilson (legacy single-path), else hexa run core/main.hexa (interpreter fallback — slower start).
wilson # interactive TUI (== `ws`)
wilson "first message" # interactive, seeded
wilson -p "..." # print one turn, exit
wilson --harness rpc # JSONL RPC (swarm cell)
wilson --model <id> ... # override host_config("model") for this run
# LLM-bypass direct tool access — cost-routing core pillar
wilson tool <name> [--key V]... [--json '{...}'] # call any registered tool
wilson tool --list # all registered tool names
wilson tool read --path /etc/hosts # = tool-core read
wilson tool web_fetch --url https://anthropic.com # = tool-web web_fetch
wilson tool git --subcmd log --args -3 --args --oneline # bridge-git
wilson tool image_info --path screenshot.png # tool-image
# noun-verb family shortcuts
wilson task <add|list|done|in_progress|delete|clear> # task list (~/.wilson/tool-task/tasks.jsonl)
wilson memory <list|add [<tier>] <text>|forget <slug>> # 4-tier memory (~/.wilson/memory/*.jsonl)
wilson recap [show [<sid>] | list] # previous-session handoff capsule
wilson session <list | resume <sid> | rm <sid>> # session transcripts (per-sid .tape)
wilson pool <list|propose|on|probe|mount|doctor|mesh> # host pool router
wilson endpoint <list|show|test|resolve> # ~/.wilson/providers.json
wilson web <fetch|search> # tool-web
wilson image <info> # tool-image
# single-tool shortcuts
wilson git <subcmd> [args] [--cwd D] # bridge-git
wilson gh <subcmd> [args] # bridge-gh
wilson hexa <parse|build|cc|run> <file> [--out X] [<args>...] # bridge-hexa
wilson bash "<cmd>" [--timeout-ms N] # tool-core bash
wilson read | write | edit | glob | grep # tool-core
wilson hello [<name>] # trivial example
wilson subagent "<prompt>" [--tools T]... # swarm
# domain conventions (governance #4 + #N+2 readme-format)
wilson domain <list | show <NAME>> # root <UPPERCASE>(+<UPPERCASE>)*.{md,tape} inventory
wilson doctor # runtime / bundle / providers / tools status
wilson plugin list # the loaded plugin set
wilson build [--with a,b] [--without c] # compile this wilson's variantOutput convention: default is tr.content text; --result adds full ToolResult JSON; exit codes 0=ok / 1=tool error / 2=bad argv / 3=plugin not loaded.
Full surface: wilson --help · docs/wilson-cli-argv-modes.md · AGENTS.md.
wilson/
├── README.md
├── AGENTS.md AI agent harness file (agents.md standard) + governance section
├── CLAUDE.md symlink → AGENTS.md
├── BACKLOG.md core open-work backlog (P-tagged)
├── TAPE.md .tape adoption design SSOT
├── HCX / ORIGIN / POOL / TEST.tape root domain ledgers (governance #4)
├── project.hexa @project(...) + non-goals + .hexa convention notes
├── core/ irreducible core — 7 .hexa modules
├── plugins/ 28 default-bundle + opt-in plugins
│ ├── _bundle/ default-bundle meta-package
│ ├── _bundle_cell/ swarm-cell minimal bundle
│ └── <id>/{plugin.hexa, main.hexa, test_<id>.hexa}
├── bin/
│ ├── wilson launcher (hx install entry point)
│ └── ws symlink → wilson
├── docs/ ROADMAP / plugin-architecture / wilson-cli-argv-modes / writing-plugins / sessions
├── state/ gitignored runtime markers
├── build/ gitignored hexa build artifacts (per-host)
└── tests/ e2e shell scripts (tmux multi-turn)
Full doc index: AGENTS.md §"Repo layout" + docs/.
MIT — Copyright (c) 2026 dancinlab. Use, modify, sublicense, sell freely; include the notice; no warranty.