Hyperextensible runtime for composing tools, plugins, and interfaces in Lua.
Small core. User-owned config. Replaceable everything else.
Think Neovim as a runtime: a programmable core, process plugins, and a Lua
config you own. The engine spawns processes, routes lines, hosts Lua, and stamps
identity. Your init.lua decides what exists, how it talks, what gets
persisted, and which interface sits on top.
Nefor does not require LLMs. Models, scripts, tools, agents, orchestrators, and plain interfaces are composable units when you wire them in. The bundled agent example is one distribution, not the product boundary.
Most tools expose selected extension points. Eventually you hit the wall: this part is configurable, that part is not.
Nefor moves the wall into Lua. Plugins are independent OS processes. Interfaces are another composition. Routing, persistence, orchestration, approvals, protocol semantics, session roots, and process-lifecycle policy live where you can read and rewrite them. The engine executes the exact plugin commands Lua registers; it has no plugin-directory discovery or installation-provenance model.
The example proves the shape with a chat surface, providers, tool gates, sessions, and a MAG-based agentic loop. MAG itself is a pure, namespaced typed language; shipped libraries declare foreign capabilities, validate graph data, and lower it to a generic runtime artifact. The lead composes work by writing tiny MAG programs the runtime folds into live actor constellations. Keep it, strip it down, or use it as a reference for your own distribution.
- Tools: spawn them as plugins, gate them, wrap them, translate them, or replace them.
- Plugins: run independent binaries over stdio. Rust is common here; the boundary is process + lines.
- Interfaces: put a TUI, CLI, bridge, or custom surface on the same runtime.
- Reasoners: compose LLM calls, scripts, tool calls, agents, orchestrators, or any unit that reads context and produces work.
- Policies: own approval, routing, persistence, replay, provider choice, and dispatch behavior in Lua.
- Distributions: ship a complete
init.luawith plugins and defaults, or keep a private config that only fits your machine.
From source:
git clone https://github.com/amenocturne/nefor
cd nefor
just installjust install builds the engine and plugin binaries, then copies the starter
composition to ~/.config/nefor. Use lower-level targets when needed:
just install-nefor source # source | latest | nightly
just install-example safe # safe | forceinstall-example refuses to overwrite an existing config unless you pass
force.
Or install the engine with brew:
brew install amenocturne/tap/nefor
mkdir -p ~/.config/nefor
cp -r $(brew --prefix)/share/nefor/examples/nefor-agent/* ~/.config/nefor/The example ships with a deterministic offline mock provider, plus
openai-provider for OpenAI-compatible APIs and chatgpt-provider for the
ChatGPT Responses API.
The starter's permission modes are documented in
examples/nefor-agent/docs/permissions.md.
Run the example:
neforThe example defaults to the deterministic mock-plugin / mock-model, so no
credentials are needed. Edit the copied config to use a real provider, different
tools, or different wiring:
$EDITOR ~/.config/nefor/config/init.lua
$EDITOR ~/.config/nefor/init.luaA Nefor composition is an init.lua. Use the example as the concrete reference
for provider setup, tool gating, session replay, workflow actors, and TUI
wiring.
The engine spawns processes and routes lines through Lua. Everything else is composition.
| Layer | What it owns |
|---|---|
| Engine / bus | Executes plugin commands registered by Lua, routes lines, hosts Lua, stamps identity/time, and reports typed process termination. It owns no sessions, plugin discovery, or shutdown policy. |
Plugins (plugins/) |
Self-contained work over stdio. Each plugin owns one scoped task. |
Lua config / example (init.lua, examples/nefor-agent/) |
Dispatch hooks, actor spawning, policies, persistence, provider/tool wiring, and interfaces. |
| Interfaces | User surfaces composed over the same bus. The example uses nefor-tui; you can wire another. |
Bash-tool test: a plugin should feel like a self-contained utility you could run from a shell, then compose elsewhere. Plugins should not know their neighbors; composition belongs in Lua.
All commands live in the justfile. Run just to see the full list.
Use just test for the fast default checks and just test-integration for the
release-bundle and deterministic TUI daily-path suites.
- Nefor Manifesto
- Architecture and writing principles
- Plugin authoring guide
- Documentation index
- Glossary
- Current protocol
- Plugins
- Starter composition
- Lua core
Do whatever you want, i.e. MIT.