architecture

Architecture

Overkill is a single Go binary with an Ink (React) terminal UI running in a sidecar Node.js process.

High-level

┌─────────────────────────────────────────┐
│  cmd/overkill/  — CLI entrypoint (Cobra) │
├─────────────────────────────────────────┤
│  internal/agent/    — ReAct loop        │
│  internal/providers/— LLM adapters      │
│  internal/tools/    — Built-in tools     │
│  internal/session/  — Postgres store     │
│  internal/config/   — TOML config       │
│  internal/compaction/— Context mgmt     │
│  internal/security/  — Injection scan   │
│  internal/cron/     — Scheduler         │
│  internal/doctor/   — Health checks     │
├─────────────────────────────────────────┤
│  tui/               — Ink/React TUI     │
│  bridge/            — Python gRPC bridge │
├─────────────────────────────────────────┤
│  Postgres           — Session + memory   │
│  MCP servers        — Optional tools     │
│  LSP servers        — Optional code intel│
└─────────────────────────────────────────┘

Core loop

User prompt → ReAct loop
  ├─ Think: classify complexity, select model, build messages
  ├─ Act: dispatch tool calls (shell, fs, git, web, etc.)
  ├─ Observe: capture output, check for errors
  └─ Repeat until done or max iterations

Key interfaces

• Provider: Complete(ctx, req) → (Response, error) + Stream(ctx, req) → (<-chan Chunk, error)
• Tool: Name() string, Execute(ctx, input) → (output, error)
• Session: Postgres-backed CRUD with per-folder isolation

Storage

All state lives in PostgreSQL under ~/.overkill/sessions/ keyed by working directory. No embedded KV stores.