Architecture
Huginn is a single Go binary built around a TUI, an orchestrator, and a local Ollama backend.
High-level overview
┌─────────────────────────────────┐
│ TUI (Bubble Tea) │
│ Input → Viewport → Wizard │
└──────────────┬──────────────────┘
│
┌──────────────▼──────────────────┐
│ Orchestrator │
│ Plan→Approve→Implement Loop │
└───┬──────────────────────┬──────┘
│ │
┌───▼────────┐ ┌────────▼──────┐
│ Planner │ │ Coder │
│ (model) │ │ (model) │
└───┬────────┘ └────────┬──────┘
│ │
┌───▼──────────────────────▼──────┐
│ Ollama REST API │
│ (local inference) │
└──────────────┬──────────────────┘
│
┌──────────────▼──────────────────┐
│ Repo Indexer │
│ git ls-files → chunking → BM25 │
│ + HNSW vectors (optional) │
└─────────────────────────────────┘Key components
| Component | Location | Purpose |
|---|---|---|
| TUI | internal/tui/ | Bubble Tea terminal interface |
| Orchestrator | internal/agent/ | Plan→Approve→Implement state machine |
| Named Agents | internal/agents/ | Persistent personas + tiered memory |
| Tools | internal/tools/ | File, git, bash, test tools |
| Repo Indexer | internal/repo/ | git ls-files + BM25 context |
| Semantic Search | internal/search/ | BM25 + HNSW + RRF |
| Storage | internal/storage/ | Pebble KV (history, summaries, symbols) |
| MCP | internal/mcp/ | Model Context Protocol client |
| Skills | internal/skills/ | Prompt + rules loading |
Architecture Decision Records
Full ADRs are in the GitHub repository: