Negan Agent

What it is

Negan Agent is a next-generation AI agent for developers — but unlike a thin wrapper around an API, it’s a full cognitive system written in Rust: it plans, reflects on its own output, judges code quality, criticizes itself, remembers learned skills, and can replay entire sessions. It runs completely offline against local models, or exposes a WebSocket API for a browser-based UI.

The whole agent is ~2,830 lines of Rust across 30+ modules, and the release profile is tuned for production: opt-level=3, full LTO, codegen-units=1, panic=abort and stripped binaries.

Cognitive capabilities

Capability	What it does
📋 Planner	Breaks a goal into small executable steps
🔍 Reflection	Analyzes the output of every step before moving on
⚖️ Judge	Scores code quality on a 1–10 scale
💬 Self-Critique	Reviews its own work and learns from mistakes
🧠 Skill Memory	Stores reusable experiences as .toml skill files
🧹 Memory Hygiene	Keeps the context window clean and focused
🎥 Replay Engine	Re-runs past sessions for verification & debugging
🛡️ Sandbox	Blocks dangerous commands and restricts file access

Architecture

┌──────────────────────────────────────────────────────────┐
│                    USER INTERFACES                        │
│   🖥️ TUI (Ratatui)            🌐 Web UI (HTML/CSS/JS)     │
└────────────┬──────────────────────────────┬──────────────┘
             │                              │
┌────────────▼──────────────────────────────▼──────────────┐
│            API SERVER  (Axum + WebSocket)                 │
│   POST /api/chat  •  GET /api/health  •  WS /ws          │
└───────────────────────────┬──────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────┐
│                    COGNITIVE CORE                         │
│   🎯 Tool Selector → 📋 Planner → 🔄 Executor            │
│   🔍 Reflection → ⚖️ Judge → 💬 Self-Critique            │
│   🛑 Stop conditions (max_steps=10, max_retries=3)        │
└───────────────────────────┬──────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────┐
│                      MEMORY LAYER                         │
│   Context • Tasks • Project Memory • Skills • Hygiene     │
│   Trace (decisions) • Replay (sessions)                   │
└───────────────────────────┬──────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────┐
│                       TOOL LAYER                          │
│   Shell (20+ cmds) • File Ops • Auto-debugger • Sandbox   │
└───────────────────────────┬──────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────┐
│                    AI PROVIDERS (local)                   │
│   Ollama • DeepSeek Coder • Qwen Coder • Local GGUF       │
└──────────────────────────────────────────────────────────┘

How it thinks — one request end to end

User: "Fix the bug in main.rs"
  → [Tool Selector]  debug task detected
  → [Planner]        1. run tests → see errors  2. read log
                     3. AI-debug the file       4. apply fix
                     5. re-run tests
  → [Executor]       step 1 → [Reflection] 2 errors found
  → [Planner]        step 2 → [Reflection] error at line 42
  → [Judge]          code quality 7/10
  → [Stop check]     continue (step 5/10)
  → [Memory]         save decision to trace
  → [Self-Critique]  "I could have read the errors first"

Safety sandbox

The sandbox.rs module is a real guardrail, not a promise:

• Blocked commands (deny-list): rm -rf /, sudo, chmod 777, mkfs, dd if=, fork bombs (:(){ :|:& };:)
• Allowed paths — an explicit whitelist of directories the agent may touch
• Network control — allow_network flag toggles connectivity

Learned skills (Skill Memory)

Skills persist as structured .toml files that get re-applied when the same problem type shows up:

skills/
├── rust_borrow_checker.toml        # fixing borrow-checker errors
├── git_conflict_resolution.toml    # resolving git conflicts
└── performance_optimization.toml   # perf improvement patterns

Project structure

negan-agent/
├── src/
│   ├── main.rs                  # entry point
│   ├── api/                     # Axum server, REST routes, WebSocket handler
│   ├── core/                    # orchestrator, planner, reflection, judge,
│   │                            #   tool_selector, task_tracker, context,
│   │                            #   model_router, project_memory, skill_memory,
│   │                            #   memory_hygiene, trace, replay, sandbox
│   ├── tools/                   # shell_exec, file_ops, auto_debugger
│   ├── optimizations/           # zero_copy, memory_pool, async_executor
│   └── tui/                     # Ratatui terminal interface
├── static/index.html            # browser Web UI (talks over WebSocket)
├── skills/                      # learned skills (.toml)
└── benchmarks/                  # fix_rust_bug / refactor_small / add_feature

Benchmarks

The benchmarks/ folder turns agent quality into something measurable — three standardized tasks (fixing a Rust bug, refactoring a small module, adding a feature) are run and scored, so improvements to the agent are validated instead of guessed.

Why it stands out

Most “AI agents” are API wrappers with a prompt. Negan Agent is a genuine systems project: an agent that plans, reflects, judges and criticizes itself, with durable memory and a real security sandbox — all in ~2,800 lines of dependency-light Rust that runs offline on local models. It shows the discipline of building cognitive machinery you can actually reason about and benchmark.