overkill

Overview ¶

Package main — alarm fire dispatcher.

When an alarm fires inside the daemon, this is what runs. The design intent (master plan §7.1 Layer 2): a cheap sub-agent reads the alarm's prompt, decides whether there's real work, and either does it or quick-exits without burning a turn on the main model.

Today's implementation is lean — no tool-use, no multi-step reasoning. The cheap model gets one shot: "look at this prompt and summarise what should happen next". The output is recorded into the ledger so the user sees "alarm fired, here's the AI's take" in `overkill task list`. A future iteration can promote this into a full sub-agent run with shell access; for now the conservative shape keeps token spend predictable.

Package main — alarm RPC. Exposes the daemon's in-process alarm clock to TUI / CLI clients over the daemon socket. Three ops: alarm.set, alarm.list, alarm.cancel.

The daemon owns the Badger-backed AlarmClock; clients can't open the same Badger dir simultaneously (single-process constraint). Routing writes + reads through the socket keeps the constraint honest and lets the daemon be the single timing authority.

Package main — `overkill daemon` boots background services: cron scheduler, automation alarm clock, routine engine. Foreground process by default; runs until SIGINT/SIGTERM. PID file at ~/.overkill/daemon.pid for `stop`/ `status` to find a running instance.

Package main — `overkill estop` (master plan §7.1) is the emergency stop.

Two-phase escalation:

1. Graceful RPC: dial the daemon socket, send the `estop` op. The daemon cancels every pending alarm + any future in-flight work contexts and replies with a count. Tool receipt chains stay intact; the daemon keeps running so subsequent commands work.

2. Signal cascade (fallback): if the RPC fails OR the user passes --force, fall back to SIGTERM the daemon + session owners, SIGKILL survivors after 3s. This is the "axe" — use when the daemon itself is the thing being stopped.

Designed for "the agent is doing the wrong thing — stop it now".

Package main — daemon-side estop RPC. When the CLI runs `overkill estop`, it first tries this graceful RPC path: the daemon cancels every running task and replies with the count of broadcasts sent. If the RPC fails or the daemon isn't running, the CLI falls back to the signal-based kill cascade (estop.go).

Graceful first because:

• signals are coarse — SIGTERM the daemon and you lose its ability to log the halt cleanly
• in-flight tool calls running under daemon-owned contexts get a chance to flush state before exit
• tool receipts (the audit chain) are preserved instead of being truncated mid-write

Package main — bridge between FlowState checkpoints and the alarm clock. When a flow checkpoint lands (either via the daemon's own agent or via the TUI's flow.checkpoint RPC), schedule a resume alarm using a stable per-flow ID so successive checkpoints replace the existing alarm rather than stacking them up.

Package main — flow RPC. The TUI's agent shouldn't open the daemon's Badger DB directly (single-process constraint). When the TUI's stream loop hits maxSteps it serialises the FlowState and asks the daemon to persist it via "flow.checkpoint". The daemon's alarm dispatcher reads from the same DB on resume.

Resume reads (List, Load) aren't exposed today — the daemon does its own resume via the alarm fire callback. If a future feature needs to inspect flow records from the TUI (e.g. an "active flows" sidebar), add `flow.list` here.

Package main — bridge between agent.HallucinationScanner and the internal/halluscan package. Lives here so the agent package doesn't import halluscan directly.

lsp_adapter.go — thin adapter mapping the concrete *lsp.Manager onto the LSPQuerier interface defined in internal/tools. Keeps the tools package from depending on the manager's public surface directly.

Package main — `overkill orders add|rm|list|toggle` manages standing orders (master plan §7.1). Stored at ~/.overkill/standing-orders.jsonl; loaded by the TUI's per-turn context provider.

Package main — pairing CLI commands for DM sender approval (§7.1.7).

Package main — `overkill push --preview` (master plan §4.8).

Renders an ASCII pre-push window: per-commit summary, total diff stats, and a confirmation prompt. Designed to surface "wait, this is going to push 47 commits" before you regret it.

Without --preview, falls through to plain `git push` so users can wire the binary as a git alias.

Package main — `overkill route preview "<input>"` shows what the smart router would pick for a hypothetical message without sending it. Useful for tuning the classifier thresholds without having to round-trip a real turn.

Package main — wire model catalogs into a SmartRouter (master plan §4.2 + §5.2). Source priority:

1. Local TOML catalog at ~/.overkill/models/ (canonical per §4.2).
2. Network catalog from providers.FetchCatalog (models.dev mirror) as fallback when local is empty.

The local catalog also attaches to the router so family-aware and capability-aware lookups work — those need the rich Capabilities struct that doesn't exist on the network catalog.

Package main — `overkill task list|get` inspects the in-process daemon ledger (master plan §7.1). The ledger is per-process — outside the daemon it shows only what this CLI invocation has recorded; inside `daemon start` it accumulates everything the daemon has done.

Package main — `overkill update` (master plan §7.6).

Checks the GitHub releases API for a newer tag than `Version`, downloads the matching binary asset for the current GOOS/GOARCH, and atomic-renames it over the running executable. The download path is a sibling tempfile so a failed download never replaces the live binary.

Repo coordinates are configured via env (OVERKILL_UPDATE_REPO=owner/name); fallback is "Sahaj-Tech-ltd/overkill". Set OVERKILL_UPDATE_REPO="" to disable.

Package main — `overkill usage [--session ID] [--days N]` prints a cost breakdown across every recorded turn (master plan §4.5).

Package main — bridge between agent.PostWriteVerifier and the internal/verify package. Lives in cmd/overkill so the agent package doesn't import internal/verify (keeps the agent's dependency graph thin).

Package main — WhatsApp gateway wiring + `overkill whatsapp pair` command.

Two pieces glued here:

1. registerWhatsApp picks a backend per cfg.WhatsApp.Backend and adds it to the gateway hub. Called from gateway_cmd.go.

2. The whatsapp Cobra subcommand owns the QR-pair flow. We keep it OUT of the daemon path because pairing is a one-time interactive operation, not an always-on service.