andrew@thecoder:~$

$ Enchanter

View on GitHub → ·  Runs on Linux, macOS, and Windows.

A focused AI agent harness. Single Rust binary, any OpenAI-compatible provider, zero runtime dependencies. Reads your SOUL, loads your memory, finds your skills, talks to your model. Nothing more. Ships with a REPL, an optional web UI (enchanter serve), a daemon mode, and a Landlock security sandbox.

### download

Grab a prebuilt v0.8.0 binary directly — no GitHub account, no Rust toolchain required. Pick your platform:

Verify integrity with theSHA256SUMSfile:

ARM builds are cross-compiled (experimental). The same files are always available onGitHub Releases.

### features

• -Single Binary — No runtime dependencies. Build it, ship it, run it anywhere.
• -Any OpenAI-Compatible Provider — Works with OpenAI, Ollama, OpenRouter, Groq, or any provider that speaks the OpenAI API.
• -Named Providers — Define multiple providers in config.yaml and switch between them mid-session with /model.
• -SOUL-Driven Personas — Define your agent's personality, directives, and behavioral constraints in SOUL.md.
• -Knowledge Store — Structured key-value facts that persist across sessions. Unlike memory (narrative text), knowledge entries are typed, searchable, and organized by category. The agent learns once and never asks again.
• -Persistent Memory — Memories persist across sessions with automatic summarization when the store grows.
• -Session Summaries — On clean exit, Enchanter generates a concise session summary and saves it to memory so your next session picks up where you left off.
• -Session History — Every conversation is automatically logged to JSONL files. List and review past sessions with enchanter sessions or /sessions in the REPL.
• -Prompt Inspection — See exactly what the model receives. /prompt budget shows token/character counts per layer with bar charts and threshold warnings. enchanter prompt --budget does the same from the CLI.
• -Session Recording & Replay — Record sessions to JSONL with --record, then replay with enchanter replay. Swap models, verify determinism, or replay with stubbed tools. API keys are redacted by default.
• -Skill Discovery — Drop in SKILL.md files to teach your agent new capabilities. Compatible with the agentskills.io format.
• -MCP Integration — Connect local (stdio) and remote (HTTP) MCP servers for external tools and data.
• -Built-in Tools — exec_command, read_file, write_file, edit_file, search_files, list_directory, memory, knowledge.
• -Interactive REPL — Full readline-powered REPL with slash commands for soul, memory, skills, config, and more.
• -Daemon Mode — Background process keeps MCP servers warm, eliminating 3–15s cold starts. Linux & macOS only.
• -Web UI — Opt-in browser interface (enchanter serve) with streaming chat, tool-call side panel, session resume, model switching, and token/context display. Binds to 127.0.0.1 by default; optional bearer-token auth.
• -Tool Approval — Opt-in human-in-the-loop gate (security.require_tool_approval). Asks y/N in the REPL or Approve/Reject cards in the web UI before running dangerous tools.
• -Security Sandbox — On Linux,exec_commandruns under a Landlock kernel sandbox confined to allowed paths. File tools check the path allowlist on all platforms.
• -Context Compaction — Rolling compaction keeps long sessions within the model's context window. Older turns are summarized; recent turns are always preserved verbatim.

### philosophy

### platform support

Daemon mode requires Unix domain sockets and is only available on Linux and macOS. On Windows, Enchanter runs entirely in inline mode — no --no-daemon flag or daemon subcommand is available.

### getting started

### configuration

All config lives in ~/.enchanter/config.yaml. Environment variables override config values. First run creates sensible defaults.

### named providers

Define multiple providers in config.yamland switch between them mid-session. Each provider can set model,base_url, and api_key. Fields left blank inherit from the top-level model config or environment variables.

### soul, memory & skills

The system prompt is assembled in seven layers, each with a distinct role:

• 1.SOUL — Your agent's persona from SOUL.md. Stable across turns, defines identity and behavioral directives.
• 2.CONTEXT — Environment info: model, user, working directory, host, platform.
• 3.SKILLS — Discovered SKILL.md files index.
• 4.INSTRUCTIONS — Tool usage guidance, canonical tool descriptions, and knowledge capture directives.
• 5.KNOWLEDGE — Structured key-value facts from the knowledge store. Compact and searchable.
• 6.VOLATILE — Memory entries and user profile. Changes frequently, fully replaceable.
• 7.SESSION — Current date and session start timestamp.

### knowledge store

Unlike memory (free-form narrative text), the knowledge store captures discrete, typed facts that persist across sessions. Keys use dot-namespaced identifiers likeproject.rust_versionoruser.email. Values are short strings organized into five categories:

• -environment — Runtime and system facts (OS, shell, tool versions)
• -project — Project-specific details (language, framework, conventions)
• -preference — User preferences and style (code style, commit conventions)
• -decision — Architectural or design decisions (chosen approach, rationale)
• -fact — General facts that don't fit other categories

Each entry tracks its source:observed (detected from tool output),told (explicitly stated by the user), orinferred (concluded by the agent from context).

The agent proactively stores facts it discovers during conversation. When it learns a version number, a project path, a user preference, or a bug workaround, it stores it with theknowledgetool so it never has to ask again. The INSTRUCTIONS prompt layer directs this behavior automatically.

### session continuity

When you exit the REPL with /exit or Ctrl+D, Enchanter generates a concise summary of your session and saves it to memory. Your next session automatically loads this context so you can pick up where you left off.

• •Skipped for single-shot mode (-p flag)
• •Skipped if the session was too short (no real exchange)
• •10-second timeout; falls back to a simple message count on failure
• •Disable with summarize_on_exit: false in config.yaml

session history

Every conversation is automatically saved to ~/.enchanter/sessions/as a JSONL file. Each message is appended atomically — if the process crashes, everything written up to that point is preserved. Each session gets a unique ID and stores the model, timestamps, and full conversation including tool calls and results.

resuming a session

Pass --resume <id> at startup to reload a previous conversation and continue from where it left off. The session is reopened, its history is reconstructed (tool calls included), and the REPL starts with the conversation already loaded.

### prompt inspection

Enchanter assembles the system prompt in explicit layers: SOUL → CONTEXT → SKILLS → INSTRUCTIONS → KNOWLEDGE → VOLATILE → SESSION. You can inspect exactly what the model receives and how much each layer costs.

The budget view shows approximate token counts per layer (chars÷4 heuristic), visual bar charts, and threshold warnings when a layer exceeds ~4,000 estimated tokens. It is the fastest way to spot a layer that is quietly consuming your context window.

### recording & replay

Record full sessions to JSONL files for debugging, reproducibility, and model comparison. API keys and auth tokens are never included in recordings by default.

Each recorded event includes a schema version, monotonic sequence number, UTC timestamp, and a typed payload. Recordings capture config snapshots (with redacted API keys), prompt layer hashes, user messages, assistant responses, tool calls, model changes, and session summaries.

### mcp servers

Connect external tools and data sources via Model Context Protocol servers. Two transport types are supported:

• -stdio — Local processes spawned by Enchanter. Auto-restarted on crash (up to 3 attempts).
• -HTTP — Remote servers via Streamable HTTP with SSE support. Session tracking with Mcp-Session-Id headers.

Tools from MCP servers are namespaced as server_name:tool_name. Use /tools in the REPL to list all available tools.

### security sandbox

On Linux, exec_command(shell execution) runs under a Landlockkernel sandbox that confines the spawned shell to an allowlist of directories. The sandboxed process can read/write withinallowed_pathsand read/execute system directories (/usr, /bin, /lib, etc.), but write access to system dirs is denied.

File tools (read_file, write_file, edit_file, search_files, list_directory) check allowed_pathson all platforms.

### context compaction

For long sessions, the conversation window can grow beyond the model's context limit. Rolling compaction keeps the live context within bounds:

When the estimated token count exceeds max_tokens, older turns are summarized into a single compact message. The most recent keep_last_turnsmessages are always preserved verbatim. Both values are optional — without them, no compaction occurs and the full conversation is sent.

### web ui (optional)

The web UI is a self-hosted browser interface served by the Enchanter binary itself — no separate app, no deployment needed. It provides streaming chat, a left-side panel showing live tool calls, session resume, model switching, and a token/context status line.

By default the server binds 127.0.0.1 and opens your browser. Configure the port, host, and browser behavior with flags:

Endpoints under /api/* cover status, sessions, history, model switching, chat (SSE streaming), undo, clear, stop, and tool approval. Chat streams server-sent events, so tool calls and results appear live.

Token auth

On a shared machine, require a bearer token on all API routes:

When set, every /api/* route requires Authorization: Bearer <token>. SSE endpoints also accept ?token=. The frontend stores the token inlocalStorage (use the 🔑 button).

### tool approval (opt-in)

set security.require_tool_approval to true and the agent pauses before running dangerous tools —exec_command, write_file, edit_file, memory, knowledge, and all MCP tools. Read-only tools (read_file, search_files, list_directory) run freely.

The REPL prompts y/N; the web UI renders Approve/Reject cards. Calls are rejected (fail-closed) if no approval channel is connected — a timeout or rejection denies the call.

### daemon mode (Linux & macOS only)

### running

### repl commands

### environment variables

All optional. Environment variables override config.yaml values.

Provider api_key and base_url fields support ${VAR} expansion, so you can writeapi_key: ${OPENROUTER_API_KEY} instead of hardcoding.

### data directory

By default, all data lives in ~/.enchanter/. Set ENCHANTER_HOME to point it elsewhere. First run auto-creates the directory with defaults.