Nerva

The local-first agent runtime for developers who want to own the whole stack.

Nerva is a terminal AI coding agent written in Rust. That undersells it.

Most coding agents are a chat loop with tools attached. Nerva is built like a workspace runtime: local state, durable memory, code structure, extensions, skills, browser automation, MCP, subagents, and the prompts that govern the agent are all visible parts of the system.

If you want the shortest possible AI terminal toy, this is not the pitch.

If you want an agent you can inspect, reshape, extend, and run as part of a real repository, Nerva is the pitch.

git clone https://github.com/hannes-wan/nerva.git
cd nerva
cargo install --path .
nerva

Why Nerva Exists

Coding agents are becoming infrastructure, but too many of them still hide the parts that matter:

• how context is shaped
• how older work is compacted
• how code structure is discovered
• what memory survives across turns
• how tools are selected
• how models and providers are normalized
• how extensions hook into the runtime
• how a team can make the agent behave differently per repository

Nerva makes those pieces first-class.

The Five Systems

1. Compaction That Behaves Like Architecture

Nerva treats context as working capital. It keeps the model focused by shaping history, tool results, system fragments, memory recall, and recent work instead of blindly stuffing the transcript back into the next request.

Useful when a task takes twenty turns and the agent still needs to remember the actual objective.

2. AST-Backed Code Structure

Nerva does not stop at string search. The public structure surface is Graphic: an AST-backed workspace code graph with graphic_inspect and graphic_query.

It can answer questions like:

• what owns this file
• what calls this symbol
• what does this function depend on
• what might a change impact
• what path connects these two nodes

The graph lives locally in .nerva/graphic.db. AST caches remain an internal implementation detail in .nerva/ast.db.

3. Durable Workspace Memory

Nerva memory is for facts that should compound:

• user preferences
• project conventions
• architectural decisions
• root causes
• environment facts
• prior learnings

The model-facing tools are deliberately small: memory_add, memory_search, and memory_delete. Session ids are provenance, not the memory model.

4. Native Extensibility

Nerva can be changed without forking the app.

You can add:

• project-local extensions
• slash commands
• external tools backed by shell or Python
• event hooks
• skills
• prompt fragments
• themes
• MCP servers
• custom providers

Extensions are process-based today: if a language can read stdin, write stdout, and run from the command line, it can participate.

5. Exposed Orchestration

The prompt stack, role tools, memory policy, code-structure discipline, verification posture, recovery behavior, subagent surface, and extension hooks are not hidden magic.

Nerva exposes them because serious agent systems should be owned, not merely used.

What You Get

• Rust terminal coding agent
• TUI, print mode, and JSON output mode
• Local project state under ./.nerva/
• User defaults under ~/.nerva/ or NERVA_AGENT_DIR
• Branchable, resumable sessions
• Automatic context compaction
• Durable workspace memory
• AST-backed Graphic code graph
• Built-in file, edit, bash, web, browser, memory, role, and subagent tools
• Browser automation through local Chrome/Chromium over CDP
• OpenAI, Anthropic, Google, Groq, Mistral, Moonshot, Azure OpenAI, Ollama, and custom OpenAI-compatible providers
• MCP stdio server support
• Project-local extensions, skills, prompts, and themes
• Provider/model switching from inside the TUI
• Tool filtering and output shaping

Install

Requirements:

• Rust toolchain
• a model provider credential, local model endpoint, or custom provider config
• Chrome/Chromium only if you want browser tools

Build and install:

git clone https://github.com/hannes-wan/nerva.git
cd nerva
cargo install --path .

Run:

nerva

Build without installing:

cargo build --release
./target/release/nerva

Connect a Model

Inside Nerva:

/connect
/connect codex
/connect anthropic
/models
/model <provider>/<model>

From the shell:

nerva --provider openai --model <model>
nerva --list-models

Credentials are stored in ~/.nerva/auth.json by default. Project-specific settings live in ./.nerva/settings.json.

Quick Start

Interactive mode:

nerva

One-shot text output:

nerva -p "summarize this repository"
nerva --print "review the public API"

Structured JSON output:

nerva --mode json "summarize this repository"

Pass files directly:

nerva "review these files" @Cargo.toml @src/main.rs

Continue or resume work:

nerva --continue
nerva --resume
nerva --session ./path/to/session.session
nerva --no-session -p "answer without storing a session"

Useful in-app controls:

/help
/status
/context full
/compact
/history
/session list
/tools
/extensions
/skills
/mcp

The Local Control Plane

Project-local state:

./.nerva/
  settings.json
  auth.json
  mcp.json
  runtime.db
  memory.db
  ast.db
  graphic.db
  browser/
  sessions/
  queues/
  extensions/
  skills/
  prompts/
  themes/

User-level defaults:

~/.nerva/
  settings.json
  auth.json
  mcp.json
  filters/
  extensions/
  skills/
  prompts/
  themes/
  sessions/

Set NERVA_AGENT_DIR to move user-level state somewhere else.

Extend It

Create a project-local extension:

/extensions new repo-tools
/extensions reload

Minimal extension:

./.nerva/extensions/repo-tools/
  extension.json
  scripts/
    repo_map.py

{
  "name": "repo-tools",
  "version": "1.0.0",
  "tools": [
    {
      "name": "repo_map",
      "description": "Return a concise repository map.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" }
        },
        "required": ["path"]
      },
      "command": "scripts/repo_map.py"
    }
  ]
}

Extensions can also ship slash commands, lifecycle hooks, event hooks, skills, prompt fragments, and built-in native tool activation.

Documentation

• Quick Start
• Configuration
• Providers
• Code Graph
• Skills
• Orchestration
• Python Integration
• Extension Authoring
• Extension SDK

Source Map

src/
  agent/        turn loop, model requests, tool routing, memory recall
  app/          application-level command/session orchestration
  bootstrap/    runtime assembly and built-in resource installation
  browser/      local Chrome/Chromium CDP tools
  cli/          terminal UI, print mode, JSON mode, controls
  context/      compaction and context shaping
  control/      slash-command control surface
  extensions/   extension loading, commands, hooks, native tool registry
  graphic/      AST-backed code graph model and tools
  mapper/       SQLite persistence for runtime, memory, sessions, graph
  mcp/          MCP stdio runtime
  memory/       durable workspace memory
  providers/    model provider adapters and normalization
  skills/       reusable reasoning workflows
  tools/        built-in file/edit/bash/human/model tools

Development

Run checks:

cargo test
cargo test --test config_docs_test
cargo test --test extension_test
cargo test --test skills_test
cargo test --test graphic_test
cargo test --test memory_test

Status

Nerva is a source-first, hackable agent runtime. It is real code, not a design mockup, but it is intentionally closer to a power-user system than a polished consumer product.

That is the point: every important layer is close enough to touch.

Star Nerva

Star this repository if you want coding agents with:

• local project identity
• durable memory
• structural code understanding
• visible orchestration
• serious extensibility
• fewer black boxes

The next generation of agents should be something developers can own.