nash is an agentic harness implemented as a single compiled binary. It connects to any OpenAI-compatible LLM server (llama.cpp, OpenAI, Anthropic, Vertex AI) and executes multi-step coding tasks through a ReAct (Reason + Act) loop with persistent memory, a TUI interface, and research-grounded cognitive architecture.
Unlike wrapper-based agents, nash has minimal runtime dependencies. It runs locally with local models, maintains long-term memory across sessions, and learns from every task it completes.
- 20 built-in tools - file I/O, search, web fetch, memory, image analysis, subtask spawning
- ncurses TUI - markdown rendering, step expansion, streaming output, in-page search
- 4 LLM providers - local (llama.cpp), OpenAI, Anthropic, Vertex AI
- Persistent memory - Bayesian-validated, git-backed, workspace-isolated
- ONNX embeddings - local semantic search with no API calls
- Playbook system - YAML-defined multi-pass workflows (dream, health, reflect, etc.)
- Agent scheduler - cron-scheduled autonomous tasks with workspace binding, sensitivity gating, three-tier discovery
- Self-improvement - postmortem analysis, regression testing, prompt optimization
- Session journaling - checkpoint/resume, episodic search, full audit trail
- Context management - importance-tagged eviction, BM25 compression, lossless breadcrumbs
- Plugin system -
libnash.so+ external.soplugins for custom tool development - Research-grounded - papers were driving the design (see Research Foundations)
+-----------------------------------------------------------+
| TUI (ncurses) |
| Markdown rendering - Step expansion - Keyboard nav |
+-----------------------------------------------------------+
| React Loop (react.c) |
| Plan -> Tool Call -> Observe -> Reflect -> Done |
+----------+----------+-----------+-------------------------+
| Provider | Memory | Tools | Journal + Store |
| local | semantic | 20 tools | content-addressed |
| openai | Bayesian | registry | full audit trail |
| anthropic| event- | dispatch | checkpoint/resume |
| vertex | driven | filtering | episodic recall |
+----------+----------+-----------+-------------------------+
| Agents - Playbooks - Self-Harness - Model Profiles |
+-----------------------------------------------------------+
| LLM Server (llama.cpp / API) |
+-----------------------------------------------------------+
# Build
make
# First-time setup wizard
./nash --setup
# Interactive TUI mode
./nash
# Single query (headless)
./nash -p "fix the memory leak in tools.c"
# Run a playbook
./nash --play dream
# Run all due agents
./nash --agent --due
# Resume a session
./nash --session ~/.nash/sessions/my-projectSee Building & Usage for full build instructions, dependencies, and CLI reference.
| Document | Description |
|---|---|
| Memory Architecture | Four-tier memory system, Bayesian scoring, embeddings, pruning, dreaming, reactive retrieval, workspaces |
| ReAct Loop & Tools | ReAct loop, 20 built-in tools, plugin registry, error recovery |
| Custom Tool Plugins | External .so plugin API, ABI versioning, lifecycle hooks, examples |
| Multi-Provider Support | Local, OpenAI, Anthropic, Vertex AI provider configuration |
| Context Management | Thinking mode, Harness-1 eviction, scratchpad architecture |
| TUI | Terminal interface, slash commands, tree branching, SearXNG search |
| Playbooks | YAML multi-pass workflows, standalone mode, custom system prompts |
| Agents | Cron-scheduled autonomous tasks, three-tier discovery, sensitivity gating, workspace binding |
| Self-Harness | Postmortem analysis, regression testing, prompt optimization |
| Model Profiles & Spec | Per-model overrides, unified spec export/import |
| Configuration & Sessions | config.toml reference, session structure, checkpoint/resume |
| Building & Usage | Dependencies, build, run, CLI reference, testing |
| Research Foundations | papers influencing the design |
| Session Threading (Design) | Matrix/Telegram bridge session threading design |
Nash runs a ReAct loop - the agent reasons about what to do, executes a tool, observes the result, and repeats until the task is done:
User Query -> [Plan] -> Tool Call -> Observe Result -> [Reflect] -> ... -> Done
Memory persists across sessions in four tiers: context window (volatile), scratchpad (session-persistent), session history (searchable journals), and curated memory (git-backed, Bayesian-validated). The agent learns from every task through post-task reflection and consolidation.
Context management uses importance-tagged messages with multi-pass progressive eviction - recoverable content (files, memory) is evicted before irreplaceable observations. Sentence-BM25 compression keeps the most relevant sentences when context pressure hits.
Self-improvement closes the loop: postmortem analysis mines failure patterns from session history, regression tests validate changes, and --optimize automatically tunes the system prompt for your model.
See the documentation for deep dives into each subsystem.
Nash uses TOML configuration at ~/.nash/config.toml. Run nash --setup for an interactive wizard:
# Switch providers by changing one line
[routing]
default = "my-local"
#default = "vertex-opus"
# Named providers (define once, reference by name)
[providers.my-local]
type = "local"
api_base = "http://192.168.1.18:8080" # llama.cpp server
[providers.vertex-opus]
type = "vertex"
model_id = "claude-opus-4-6"
project_id = "my-gcp-project"
region = "global"
[thinking]
mode = "yes" # yes | no | on | off
[embedding]
type = "onnx" # onnx | ollama | openai | none
model_path = "~/models/all-MiniLM-L6-v2"Per-model profiles in ~/.nash/models/*.toml override any config field per model. See Configuration & Sessions for the full reference and Model Profiles for profile examples.
Nash is a project focused on exploring what's possible with local LLMs as autonomous coding agents. The codebase is intentionally compact and self-contained.
Key design principles:
- Minimal runtime dependencies - single compiled binary
- Local-first - works with llama.cpp, no cloud required
- Research-grounded - every major design decision cites its research basis
- Self-improving - the agent learns from every task via persistent memory
- Full audit trail - every action is stored, referenced, and inspectable
MIT