fen documentation #
fen is a small Fennel→Lua coding-agent CLI. It is built as a reloadable microkernel: a tiny core (agent loop, canonical types, provider dispatch, extension registry) with providers, the UI, session storage, and even the built-in tools all shipped as first-party extensions. It mirrors pi-mono's interface shapes in simplified form and targets Lua 5.4 on ARMv7/Raspberry-Pi-class hardware.
For a project overview, install instructions, and a quick start, see the repository README.
Which doc should I read? #
These guides are the primary, hand-written docs; each one has a single main audience. Read these first — the generated reference below is for lookup, not onboarding.
| If you are… | Start with |
|---|---|
| running fen | the repository README |
| understanding the TUI design | TUI design guide |
| contributing code | Development workflow |
| understanding the internals | Architecture notes |
| writing an extension | Extensions |
| configuring a provider | Providers |
Guides #
- Development workflow — dev workflow, hot reload, checks, TUI stall diagnostics, statistical profiling, and Nix result symlinks.
- TUI design guide — terminal UI spatial model, affordances, extension surfaces, recovery, and testing direction.
- Architecture notes — module map, canonical types, reloadable microkernel, design principles.
- Extensions — extension discovery, manifests, API surface, reload, packaging, skills, examples.
- Providers — provider interface, auth/wire differences,
models.jsoncustom providers. - Tools — built-in tool contracts and deliberate omissions.
- Sessions — JSONL session format and flags.
- Wire protocol — versioned JSONL events and controls between a parent and a live child agent.
- Scripts — portable Lua/Fennel script runner.
- Distribution — Nix artifacts, single-file binary format,
package.searchersprecedence, dev overlays, releases.
Generated reference #
The generated site is reference material scanned directly from source — reach for it to look up a specific contract, not to get oriented. It includes contracts, API, registries, and graphs pages. Use the sitemap for a dense index of every page and the machine-readable artifacts. It is part of the published documentation site rather than the repository.