ensō

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Architecture#

A single Go binary with subcommands tui (default), run, daemon, attach, config, trust, fork, export, stats, sandbox. ~26,000 lines of Go (~32% test).

Big picture#

Inside one process the agent goroutine runs the chat→tool loop (internal/agent), publishes typed events on a fan-out bus (internal/bus), and persists state synchronously through a session writer (internal/session) before the UI sees anything (persist-before-render invariant). The TUI (internal/tui over tview/tcell) subscribes for rendering, the permissions checker (internal/permissions) gates tool calls with three-tier patterns, MCP servers (internal/mcp via mark3labs/mcp-go) plug their tools into the same registry as built-ins (internal/tools), subagents (spawn_agent tool + internal/workflow runner) construct child agents that share the parent’s bus/provider/permissions but get their own filtered tool registry. The daemon (internal/daemon) hosts the same agent over a unix socket; attach is a TUI variant that reads events from the socket and proxies user input + permission decisions back. Slash commands (internal/slash) layer built-ins + file-loaded skills on top of the input handler. LSP (internal/lsp) is a hand-rolled JSON-RPC client that exposes language-server features as lsp_* tools. Sandbox (internal/sandbox) runs bash inside a per-project podman/docker container.

Install

Mon, 01 Jan 0001 00:00:00 +0000

Install#

ensō is a single static Go binary (named enso). No CGO, no runtime dependencies on the host beyond a POSIX shell (and optionally podman or docker if you turn the bash sandbox on).

Prerequisites#

Go 1.23+ (only if building from source).
An OpenAI-compatible chat endpoint — llama.cpp’s llama-server is the reference target; vLLM, Ollama, OpenAI itself, anything that speaks Chat Completions with SSE streaming will work.
POSIX OS (Linux/macOS/BSD). Windows builds compile but the daemon path is unsupported there; run via WSL.

Build from source#

git clone https://github.com/TaraTheStar/enso.git
cd enso
make build # produces ./bin/enso

Common Make targets:

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Configuration reference#

ensō reads layered TOML files. Lowest → highest precedence:

/etc/enso/config.toml — system.
$XDG_CONFIG_HOME/enso/config.toml (≈ ~/.config/enso/) — user.
<cwd>/.enso/config.toml — project, committed.
<cwd>/.enso/config.local.toml — project, gitignored. The “Allow + Remember” target.
-c <path> — one-off override.

Each file is map-merged into the previous. Lists concatenate; nested tables merge key-by-key.

enso config init # write the default to the user path
enso config init --print # dump to stdout
enso config init --force # overwrite an existing file
enso config show # list search paths and which exist

The default config below is also embedded in the binary — enso config init --print prints it verbatim.

TUI

Mon, 01 Jan 0001 00:00:00 +0000

TUI#

The default enso command launches a tview-based terminal UI: a chat pane, an input area at the bottom, an optional agents pane on the right, and a status bar.

Keybindings#

Key	Action
`Enter`	Submit the current input.
`Shift+Enter` / `Alt+Enter` / `Ctrl+J`	Newline. `Ctrl+J` is the cross-terminal-reliable one.
`Ctrl+C`	Cancel the current turn (no-op when idle).
`Ctrl+D`	Quit (cancels in-flight turn first).
`Ctrl+A`	Toggle the right-side agents pane.
`Ctrl+T`	Toggle visibility of completed reasoning blocks.
`Ctrl+R`	Open the recent-sessions overlay (Enter switches via `syscall.Exec`).
`@` (at token start)	Open the file picker — type to filter, Enter inserts the path.
`Esc`	Close any modal (= Deny on a permission prompt).

Slash commands#

Command	What it does
`/help`	List all available commands.
`/yolo on\|off`	Toggle auto-allow for the rest of the session.
`/tools`	List tools currently registered (built-ins + MCP + LSP).
`/sessions`	Recent sessions, inline. Ctrl-R opens the overlay version.
`/grep <pattern>`	One-shot project-wide grep, results inline.
`/permissions`	Inspect and remove project-local permission rules in `config.local.toml`.
`/model [<name>]`	List configured providers (no arg) or switch the active one (with arg).
`/compact`	Force a context-compaction pass.
`/init [target]`	Survey the project and write `ENSO.md` (or any other filename).
`/agents`	List declarative agent profiles (built-in + user + project).
`/loop <interval> <prompt>`	Re-submit a prompt every interval (≥5s); `/loop off` stops.
`/workflow <name> <args>`	Run a declarative workflow.
`/<skill-name> <args>`	Any user-defined skill (project shadows user).
`/quit`	Exit.

Status bar#

Two halves:

JSON event schema

Mon, 01 Jan 0001 00:00:00 +0000

JSON event schema#

enso run --format json emits one JSON object per line on stdout — newline-delimited JSON, parseable with any streaming JSON tool (jq -c ., python -m json.tool --json-lines, etc.).

The schema mirrors the internal bus events 1:1, with a leading session_start and trailing session_end for boundaries.

Example#

$ enso run --yolo --format json "list .go files in cmd/" | head
{"type":"session_start","cwd":"/home/me/proj","id":"4d8b2e9a-…","model":"qwen3.6-35b-a3b","resumed":false}
{"type":"user_message","content":"list .go files in cmd/"}
{"type":"reasoning_delta","text":"The user wants…"}
{"type":"reasoning_delta","text":" to enumerate…"}
{"type":"tool_call_start","args":{"pattern":"**/*.go"},"id":"call_1","name":"glob"}
{"type":"tool_call_end","error":null,"id":"call_1","name":"glob","result":"cmd/enso/main.go\ncmd/enso/run.go\n…"}
{"type":"assistant_delta","text":"There are five Go files in cmd/:\n"}
…
{"type":"assistant_done"}
{"type":"session_end","tool_errors":false}

Event types#

Every line has a "type" field. Other fields depend on the type.

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Quickstart#

Five minutes from “I cloned the repo” to “the agent is editing my code.”

1. Build#

make build # → ./bin/enso

2. Start your model#

If you’re running llama.cpp’s llama-server:

llama-server -m <model.gguf> --port 8080

If you’ve configured a different backend, point your config there. See Install for the full command line.

3. First run#

./bin/enso

The first time ensō runs, it writes a default config to ~/.config/enso/config.toml and creates ~/.enso/enso.db for session storage. The TUI boots, talks to your model, and you can start typing.

Sessions

Mon, 01 Jan 0001 00:00:00 +0000

Sessions#

Every conversation is a session — a row in ~/.enso/enso.db with its messages, tool calls, and bus events. Sessions persist automatically (use --ephemeral to skip), survive crashes, and can be resumed, branched, or exported.

Persist-before-render#

Every user message, assistant reply, and tool call is written to SQLite before the UI renders it. If you kill -9 enso mid-tool-call and resume, the interrupted call comes back as a synthetic tool result with the message “tool call interrupted (process exited before completion); user has resumed the session” so the model can react.

Permissions

Mon, 01 Jan 0001 00:00:00 +0000

Permissions#

The permission system gates every tool call by matching it against patterns in [permissions]. Three rule lists, evaluated in deny → ask → allow → mode default order.

Modes#

[permissions]
mode = "prompt" # "prompt" | "allow" | "deny"

"prompt" — for unmatched calls, ask the user via a modal.
"allow" — for unmatched calls, auto-allow.
"deny" — for unmatched calls, auto-deny.

--yolo (or /yolo on) overrides the mode and auto-allows everything except patterns explicitly listed in deny. Use it for unattended runs.

Worktree mode

Mon, 01 Jan 0001 00:00:00 +0000

Worktree mode#

--worktree creates a fresh git worktree at ~/.enso/worktrees/<repo>-<rand> on a new enso/<rand> branch off your current HEAD, chdirs into it, and runs the session from there. The agent operates in the worktree; your main checkout stays untouched.

Useful when:

You want a sacrificial branch for a speculative refactor without contaminating your working tree.
You’re running multiple agents in parallel — each on their own worktree, so they can’t step on each other’s edits.
You want to keep git diff and git status clean while the agent experiments.

Usage#

enso --worktree # in-process TUI
enso run --worktree --yolo "do thing" # single-shot

Both enso (default tui) and enso run honour the flag. The daemon and attach paths don’t — they target an existing process that might span multiple repos.

Sandbox

Mon, 01 Jan 0001 00:00:00 +0000

Sandbox#

By default the bash tool runs as your user on the host. With [bash] sandbox = "auto" (or "podman" / "docker"), every bash call instead runs inside a per-project container with the project cwd bind-mounted at /work. The agent’s shell can’t see ~, ~/.ssh, sibling repos, or anything else outside the project.

The sandbox is off by default. Turn it on per project (or globally in your user config) when you want the safety.

LSP

Mon, 01 Jan 0001 00:00:00 +0000

LSP integration#

Configure language servers under [lsp.<name>] and four tools become available to the agent:

lsp_hover(file, line, column) — type / signature / doc at a position.
lsp_definition(file, line, column) — where the symbol is defined.
lsp_references(file, line, column, include_declaration?) — every reference.
lsp_diagnostics(file) — errors / warnings the server has published.

Servers are spawned lazily on first use, scoped by file extension, and reused for the rest of the session. ensō’s LSP client is hand-rolled JSON-RPC over stdio (no new dependencies; ~600 lines of pure Go), so anything that speaks standard LSP works.

Agents

Mon, 01 Jan 0001 00:00:00 +0000

Declarative agents#

A declarative agent is a reusable bundle of (system-prompt addition, tool restrictions, sampler overrides, max-turns) that replaces the default top-level configuration for a session. Pick one with --agent <name> at startup; list them with /agents in the TUI.

Built-in: plan mode#

enso --agent plan

The plan agent is read-only. bash, write, and edit are removed from the registry; only read, grep, glob, web_fetch, and todo remain. The system prompt explicitly tells the model: investigate and produce a plan; do not modify files. Use it for “tell me what this codebase does” or “design a fix” sessions where you don’t want the model touching anything.

Memory

Mon, 01 Jan 0001 00:00:00 +0000

Auto-memory#

Sessions don’t share state by default — each new session sees the same system prompt and starts cold. Auto-memory is the mechanism for making certain facts persistent across sessions.

How it works#

Two things, working together:

The memory_save tool. The agent calls it with a name and content; ensō writes a markdown file at <cwd>/.enso/memory/<slug>.md.
The instruction loader. At session start, every *.md under ~/.enso/memory/ (user) and <cwd>/.enso/memory/ (project) is concatenated and appended to the system prompt under a ## Auto-memory header. Project files shadow user files on name collision.

A future session in the same project automatically inherits everything the agent saved. No re-explaining the database constraints, no re-stating the team’s lint policy.

Skills

Mon, 01 Jan 0001 00:00:00 +0000

Skills#

A skill is a user-defined slash command. Drop a frontmatter-headed markdown file at ~/.enso/skills/<name>.md (user) or <cwd>/.enso/skills/<name>.md (project), and /<name> becomes a slash command in the TUI that injects the rendered body as the next user message.

Project shadows user on name collision.

File format#

---
name: explain-this
description: read-only summariser — explains a file, function, or area of the codebase
allowed-tools: [read, grep, glob, lsp_hover, lsp_definition, lsp_references]
---

You are about to explain a piece of this codebase to the user. The
target is:

{{ .Args }}

Investigate read-only first — use `glob` / `grep` to find relevant
files, `read` to inspect them, and `lsp_*` if a language server is
available for richer signal. Then write a concise explanation in this
shape:

1. **What it is** — one paragraph, plain language. No code.
2. **How it fits in** — what calls it, what it depends on.
3. **Subtleties** — anything non-obvious.
4. **Where to look next** — 1–2 next files worth reading.

The body is a Go text/template. Available variables:

Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Workflows#

A workflow is a declarative agent pipeline — multiple roles with their own prompts and tool restrictions, wired together by edges. The canonical example is planner → coder → reviewer: one agent investigates and produces a plan, the next implements it, the third critiques the result.

File format#

~/.enso/workflows/<name>.md (user) or <cwd>/.enso/workflows/<name>.md (project), frontmatter + body. One ## <role> section per agent.

---
roles:
 planner:
 tools: [read, grep, glob]
 coder:
 tools: [read, write, edit, bash, grep, glob]
 reviewer:
 tools: [read, grep, glob]
edges:
 - planner -> coder
 - coder -> reviewer
---

## planner

You are the planner. Read the relevant code and produce a concrete,
file-scoped plan for the following request:

{{ .Args }}

Output a numbered list of changes, each naming the file and the
specific modification. Do not write code yet. End with a short list
of risks and open questions.

## coder

You are the coder. Implement the plan below using read/write/edit/bash:

{{ .planner }}

Do not deviate from the plan; if you find the plan is wrong, stop and
explain rather than improvise.

## reviewer

You are the reviewer. The implementation is below; the original plan
preceded it:

Plan:
{{ .planner }}

Implementation summary:
{{ .coder }}

Read the actual changed files and report:
- What's correct.
- What's wrong (severity-ordered).
- What tests would catch regressions.

Frontmatter fields#

roles: # role-name → role config
 <name>:
 tools: [...]  # registry filter; empty = full registry
 model: <name>  # provider name from [providers.X]; empty = inherit default
edges: # explicit dependencies — runner topo-sorts
 - planner -> coder
 - coder -> reviewer

edges declares dependency direction (a -> b means b waits for a). Roles with no incoming edges run first. Sibling roles (no dependency between them) run in parallel.

MCP servers

Mon, 01 Jan 0001 00:00:00 +0000

MCP servers#

Model Context Protocol servers expose tools to the agent over a JSON-RPC transport. ensō’s MCP client (built on mark3labs/mcp-go) connects to as many servers as you configure and merges their tools into the same registry as the built-ins.

Configuration#

# Stdio transport — server is a subprocess.
# Only $ENSO_*-prefixed env vars expand here; everything else collapses
# to "" (logged once). See [Secrets](/enso/docs/secrets/) for why.
[mcp.gitea]
command = "gitea-mcp-server"
args = ["--token", "$ENSO_GITEA_TOKEN"]

# HTTP transport (Streamable-HTTP, falls back to SSE).
[mcp.notion]
url = "https://mcp.notion.com/v1"
headers = { Authorization = "Bearer $ENSO_NOTION_TOKEN" }

Field	Description
`command`	Stdio transport: the binary to spawn. Mutually exclusive with `url`.
`args`	CLI args. `$VAR` / `${VAR}` resolve against the process env at startup.
`url`	HTTP transport: the server’s base URL. Mutually exclusive with `command`.
`headers`	HTTP transport only. Static map of header name → value, applied to every request. `$VAR` expanded.

Each block becomes one connection. ensō connects with a 10-second per-server timeout and proceeds with whichever connect; failures are logged but don’t abort startup.

Daemon

Mon, 01 Jan 0001 00:00:00 +0000

Daemon mode#

enso daemon runs a long-lived agent server on a unix socket (~/.enso/daemon.sock). enso run --detach submits a fire-and-forget prompt to it and exits with the new session id. enso attach <id> opens an interactive TUI driven by the live event stream.

The daemon is POSIX-only — Linux, macOS, BSD. Windows users run via WSL.

When to use the daemon#

Long-running prompts you want to leave going while you do other work. enso run --detach "audit the whole repo for X" returns immediately with a session id.
Agent operations from automation / cron / CI that need to outlive the invoking script.

For interactive day-to-day work, enso (the in-process TUI) is the right tool. The daemon path is intentionally narrower.

Secrets

Mon, 01 Jan 0001 00:00:00 +0000

Secrets#

ensō is local-first; there’s no central secret store. The patterns below cover provider API keys, MCP server tokens, and per-repo secrets without paying for an OS keyring integration nobody asked for.

The three surfaces#

Where	What	How to set
`[providers.<name>] api_key`	LLM endpoint bearer token	TOML literal or `$ENSO_FOO` reference
`[mcp.<name>] headers` / `args`	Per-server auth (token, header)	`$ENSO_FOO` reference (literal also works)
`<cwd>/.enso/config.local.toml`	Per-repo overrides (gitignored)	Free-form TOML; same expansion rules apply

`$ENSO_*` env-var indirection#

Any $VAR or ${VAR} reference inside the fields above is expanded against the process environment, but only for variables whose name starts with ENSO_. A reference to anything else (e.g. $AWS_SECRET_ACCESS_KEY) collapses to the empty string and logs one WARN to ~/.enso/enso.log.

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Contributing#

ensō is small enough that the contributor flow is mostly “read AGENTS.md, run make check, send a patch.”

Operating instructions for agents (and humans)#

AGENTS.md at the repo root is the source of truth. Highlights:

Always run make check before sending a patch — gofmt + vet + test + build. CI runs the same target.
No CGO. Every dependency must build with CGO_ENABLED=0. SQLite uses modernc.org/sqlite, not mattn/go-sqlite3.
No new dependencies without surfacing the choice. ensō is deliberately minimal; we have a documented short list in AGENTS.md.
Follow AGENTS.md. It’s the architectural source of truth. Anything that contradicts its conventions or non-goals (package layout change, dep substitution, new abstraction) needs to be discussed first.
Don’t git push or git commit unless asked. Stage and report what’s ready; let the reviewer commit.
Don’t run destructive commands (rm -rf, git reset --hard, git push --force) without confirmation in the same turn.

Repo layout#

See Architecture for the full package map. Quick orientation:

ensō

Architecture

Architecture#

Big picture#

Install

Install#

Prerequisites#

Build from source#

Reference

Configuration reference#

TUI

TUI#

Keybindings#

Slash commands#

Status bar#

JSON event schema

JSON event schema#

Example#

Event types#

Quickstart

Quickstart#

1. Build#

2. Start your model#

3. First run#

Sessions

Sessions#

Persist-before-render#

Permissions

Permissions#

Modes#

Worktree mode

Worktree mode#

Usage#

Sandbox

Sandbox#

LSP

LSP integration#

Agents

Declarative agents#

Built-in: plan mode#

Memory

Auto-memory#

How it works#

Skills

Skills#

File format#

Workflows

Workflows#

File format#

Frontmatter fields#

MCP servers

MCP servers#

Configuration#

Daemon

Daemon mode#

When to use the daemon#

Secrets

Secrets#

The three surfaces#

$ENSO_* env-var indirection#

Contributing

Contributing#

Operating instructions for agents (and humans)#

Repo layout#

`$ENSO_*` env-var indirection#