User guide on ensō

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:

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.

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.

User guide on ensō

TUI

TUI#

Keybindings#

Slash commands#

Status bar#

Sessions

Sessions#

Persist-before-render#

Permissions

Permissions#

Modes#

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#

`$ENSO_*` env-var indirection#