README
¶
overkill
The Frontier AI Harness That Has A Personality And Lets You Vibecode From Bed.
Overkill is a Go coding-agent backend with a terminal interface and a development desktop workspace. It supports configurable model providers, PostgreSQL session storage, local workflow files, and optional messaging integrations. Feature availability depends on the entry point and configured services; the development desktop is still being stabilized.
desktop preview — v0.11.0-beta.2
Download the desktop app from GitHub Releases:
| Platform | Desktop installer |
|---|---|
| macOS Apple Silicon | Overkill-0.11.0-beta.2-development-arm64.dmg |
| Windows x64 | Overkill-0.11.0-beta.2-windows-x64-setup.exe |
The preview includes chat/workspace UI, a private bundled database, peer-agent messages, automatic checkpoints, durable continuation, DAG memory, reviewed project skills and isolated /think items. Provider credentials are configured inside the app. The Mac build is ad-hoc signed and unnotarized; the Windows installer is unsigned. See the release notes and distribution status for tested platforms and remaining limits. overkill-windows-amd64.exe is the separate terminal executable.
terminal installation
curl -fsSL https://overkill.my/install | sh
Or with Go: go install github.com/Sahaj-Tech-ltd/overkill/cmd/overkill@main
what it does
- Model providers — native adapters and OpenAI-compatible endpoints, with catalog-based model metadata and routing. Catalog entries do not prove credentials, model access, or live compatibility.
- Persistent sessions and memory — PostgreSQL stores conversation history and database-backed memory. Plans, tasks, tags, playbooks and other local workflow data also use files; see the storage map.
- Configurable personality — bounded response-style and language instructions, with optional personality subsystems. Automatic long-term relationship tracking remains incomplete.
- Messaging integrations — Telegram, Discord, Slack, Matrix and Mattermost adapters; Signal through an external REST service; WhatsApp cloud and paired-device implementations; and an HTTP bridge for user-supplied sidecars. SMS and iMessage need external integrations; Feishu is not implemented. See the capability and setup matrix.
- Checks and agent coordination — actual post-write check results, peer messages, task budgets, blockers and contracts. Heuristic confidence is separate from test evidence; the full iterative self-evaluation loop remains unavailable.
- Open application source — MIT + Apache-2.0. Bundled dependencies have their own licenses and source obligations; see the dependency inventory.
what it isn't
- A complete production release yet. The desktop development guide describes the application bundle and its outstanding distribution gates; the architecture notes describe unfinished surfaces.
- Another Claude Code clone. Different architecture, different philosophy.
- Polite. It'll tell you when your idea is bad.
Read the local documentation → | Gateway setup → | Desktop development →
Contributors
| User | Contributions | |
|---|---|---|
 |
xyzmr114 | 24 |
Documentation
¶
Overview ¶
Package bundled ships the repo's skills/ tree inside the Overkill binary. BootstrapOverkillHome unpacks these into ~/.overkill/skills/ on first run so every agent session starts with battle-tested skills.
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var SkillsFS embed.FS
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
overkill
command
Package main — alarm fire dispatcher.
|
Package main — alarm fire dispatcher. |
|
examples
|
|
|
plugins/git-stats
command
git-stats plugin: surfaces lightweight git context to the agent.
|
git-stats plugin: surfaces lightweight git context to the agent. |
|
plugins/notes
command
notes plugin: capture quick notes from chat.
|
notes plugin: capture quick notes from chat. |
|
plugins/sdk-go
Package sdk provides a thin Go SDK for writing Overkill plugins.
|
Package sdk provides a thin Go SDK for writing Overkill plugins. |
|
internal
|
|
|
acp
Package acp implements the Agent Communication Protocol — a small HTTP/SSE API that lets other agents (claude code, opencode, custom agents) send messages to a running overkill and receive streaming replies.
|
Package acp implements the Agent Communication Protocol — a small HTTP/SSE API that lets other agents (claude code, opencode, custom agents) send messages to a running overkill and receive streaming replies. |
|
agent
Package agent — Caveman Mode + prompt compression (master plan §4.4).
|
Package agent — Caveman Mode + prompt compression (master plan §4.4). |
|
atomicfile
Package atomicfile provides crash-safe file writes via the temp-then-rename pattern.
|
Package atomicfile provides crash-safe file writes via the temp-then-rename pattern. |
|
audit
Package audit — completion auditor that verifies agent output.
|
Package audit — completion auditor that verifies agent output. |
|
auth
Package auth implements OAuth device-code flows for providers that don't use static API keys (Anthropic Claude.ai, GitHub Copilot, etc.).
|
Package auth implements OAuth device-code flows for providers that don't use static API keys (Anthropic Claude.ai, GitHub Copilot, etc.). |
|
automation
Package automation — alarm persistence backed by PostgreSQL.
|
Package automation — alarm persistence backed by PostgreSQL. |
|
automemory
Package automemory extracts explicitly opted-in, bounded durable facts.
|
Package automemory extracts explicitly opted-in, bounded durable facts. |
|
browser
Package browser provides an agent-driven headless Chrome wrapper built on chromedp.
|
Package browser provides an agent-driven headless Chrome wrapper built on chromedp. |
|
browser/devbrowser
Package devbrowser provides a narrow structured Chrome interface.
|
Package devbrowser provides a narrow structured Chrome interface. |
|
checkpoint
Package checkpoint — filesystem checkpoints (master plan §4.8).
|
Package checkpoint — filesystem checkpoints (master plan §4.8). |
|
childruntime
Package childruntime builds isolated children using the application's agent loop.
|
Package childruntime builds isolated children using the application's agent loop. |
|
compaction
Package compaction — LCM-inspired dual-state context management.
|
Package compaction — LCM-inspired dual-state context management. |
|
compaction/seahorse
Package seahorse implements hierarchical DAG summarization — a more sophisticated alternative to flat LCM compaction.
|
Package seahorse implements hierarchical DAG summarization — a more sophisticated alternative to flat LCM compaction. |
|
config
Package config — the Configurable interface.
|
Package config — the Configurable interface. |
|
coordination
Package coordination provides durable, project-scoped correspondence between agents.
|
Package coordination provides durable, project-scoped correspondence between agents. |
|
credentials
Package credentials stores application credentials in the operating system's credential vault.
|
Package credentials stores application credentials in the operating system's credential vault. |
|
credit
Package credit — retrospective credit assignment (§8.6 Wave 4, approximation of Zhang 2026).
|
Package credit — retrospective credit assignment (§8.6 Wave 4, approximation of Zhang 2026). |
|
cron
Package cron — activity tracking for gateway-aware cron fire dispatch.
|
Package cron — activity tracking for gateway-aware cron fire dispatch. |
|
daemon
Package daemon implements the job queue for overkill's daemon mode (§8.7.3).
|
Package daemon implements the job queue for overkill's daemon mode (§8.7.3). |
|
db
Package db provides shared PostgreSQL connections and central bootstrap migrations.
|
Package db provides shared PostgreSQL connections and central bootstrap migrations. |
|
dbschema
Package dbschema owns SQL shared by application bootstrap and store startup.
|
Package dbschema owns SQL shared by application bootstrap and store startup. |
|
diagnostic
orphan: agent self-debugging (master plan §5.7); to be invoked from error-recovery flow once a result-channel is plumbed
|
orphan: agent self-debugging (master plan §5.7); to be invoked from error-recovery flow once a result-channel is plumbed |
|
doctor
orphan: 'overkill doctor' command runs subset; remaining checks here pending integration into cmd/overkill/doctor.go
|
orphan: 'overkill doctor' command runs subset; remaining checks here pending integration into cmd/overkill/doctor.go |
|
doctor/checks
Package checks bundles the individual subsystem checks that the Runner composes for `overkill doctor`.
|
Package checks bundles the individual subsystem checks that the Runner composes for `overkill doctor`. |
|
doctor/health
Package health provides the HealthCheck registry — the single best pattern stolen from OpenClaw's src/flows/.
|
Package health provides the HealthCheck registry — the single best pattern stolen from OpenClaw's src/flows/. |
|
drift
Package drift — behavioral drift detection (§8.3 Wave 4).
|
Package drift — behavioral drift detection (§8.3 Wave 4). |
|
events
Package events provides the completion-event pipeline (§8.7.2).
|
Package events provides the completion-event pipeline (§8.7.2). |
|
events/sinks
Package sinks provides built-in Sink implementations for CompletionEvents.
|
Package sinks provides built-in Sink implementations for CompletionEvents. |
|
extensions
Package extensions is a thin, read-mostly unification layer over the four existing extension surfaces in Overkill: skills, plugins, hooks, and MCP servers (Phase 1.5 #5).
|
Package extensions is a thin, read-mostly unification layer over the four existing extension surfaces in Overkill: skills, plugins, hooks, and MCP servers (Phase 1.5 #5). |
|
features
Package features is a small runtime feature-flag layer for Overkill (Phase 1.5 #4).
|
Package features is a small runtime feature-flag layer for Overkill (Phase 1.5 #4). |
|
flows
Package flows provides the unified flow type system stolen from OpenClaw's src/flows/.
|
Package flows provides the unified flow type system stolen from OpenClaw's src/flows/. |
|
gateway
Package gateway — simple PostgreSQL-backed bookmark store for session bookmarks.
|
Package gateway — simple PostgreSQL-backed bookmark store for session bookmarks. |
|
gateway/bridge
Package bridge is a one-size HTTP gateway any sidecar (Baileys for WhatsApp, discord.js, an SMS relay) can plug into.
|
Package bridge is a one-size HTTP gateway any sidecar (Baileys for WhatsApp, discord.js, an SMS relay) can plug into. |
|
gateway/discord
Package discord — Discord gateway via discordgo (Batch H).
|
Package discord — Discord gateway via discordgo (Batch H). |
|
gateway/matrix
Package matrix implements a Matrix messaging gateway via raw HTTP against the Matrix Client-Server API (no heavy SDK).
|
Package matrix implements a Matrix messaging gateway via raw HTTP against the Matrix Client-Server API (no heavy SDK). |
|
gateway/mattermost
Package mattermost implements a Mattermost messaging gateway via the Mattermost WebSocket API (wss://server/api/v4/websocket) for real-time events and the REST API for posting messages.
|
Package mattermost implements a Mattermost messaging gateway via the Mattermost WebSocket API (wss://server/api/v4/websocket) for real-time events and the REST API for posting messages. |
|
gateway/signal
Package signal implements a Signal messaging gateway via signal-cli's REST API mode.
|
Package signal implements a Signal messaging gateway via signal-cli's REST API mode. |
|
gateway/slack
Package slack — Slack gateway via Socket Mode.
|
Package slack — Slack gateway via Socket Mode. |
|
gateway/telegram
Package telegram is a minimal Bot API client used by the Telegram gateway.
|
Package telegram is a minimal Bot API client used by the Telegram gateway. |
|
gateway/whatsapp/cloud
Package cloud — WhatsApp Business Cloud API gateway (Batch L, official-path backend).
|
Package cloud — WhatsApp Business Cloud API gateway (Batch L, official-path backend). |
|
gateway/whatsapp/whatsmeow
Package whatsmeow — WhatsApp gateway via go.mau.fi/whatsmeow (Batch L, unofficial-path backend).
|
Package whatsmeow — WhatsApp gateway via go.mau.fi/whatsmeow (Batch L, unofficial-path backend). |
|
halluscan
Package halluscan — conservative hallucination detector (Batch G3).
|
Package halluscan — conservative hallucination detector (Batch G3). |
|
hooks
Package hooks — user-defined hooks loaded from disk (master plan §6.3).
|
Package hooks — user-defined hooks loaded from disk (master plan §6.3). |
|
hotreload
Package hotreload wires live config notifications to an agent.
|
Package hotreload wires live config notifications to an agent. |
|
input
Package input classifies user-typed text into intent categories so the TUI can route or hint accordingly.
|
Package input classifies user-typed text into intent categories so the TUI can route or hint accordingly. |
|
instructions
Package instructions loads explicitly authorized workspace guidance.
|
Package instructions loads explicitly authorized workspace guidance. |
|
introspection
orphan: on-demand CODEBASE.md generator (master plan §5.8); needs /introspect slash command
|
orphan: on-demand CODEBASE.md generator (master plan §5.8); needs /introspect slash command |
|
journal
Package journal — CLAIM-CONFIRM async compression queue (§4.19, inspired by claude-mem).
|
Package journal — CLAIM-CONFIRM async compression queue (§4.19, inspired by claude-mem). |
|
lats
Package lats — multi-branch task exploration (§8.5 Wave 4, inspired by Zhou 2024 LATS: Language Agent Tree Search).
|
Package lats — multi-branch task exploration (§8.5 Wave 4, inspired by Zhou 2024 LATS: Language Agent Tree Search). |
|
learning
Package learning implements a lightweight learning-from-corrections system.
|
Package learning implements a lightweight learning-from-corrections system. |
|
localdb
Package localdb owns a private, bundled PostgreSQL cluster for one application session.
|
Package localdb owns a private, bundled PostgreSQL cluster for one application session. |
|
lsp
Package lsp implements a minimal Language Server Protocol client over stdio.
|
Package lsp implements a minimal Language Server Protocol client over stdio. |
|
mcp
Package mcp implements a Go client for the Model Context Protocol.
|
Package mcp implements a Go client for the Model Context Protocol. |
|
mcp/testfixture
Package testfixture supplies a controlled local MCP subprocess for acceptance tests.
|
Package testfixture supplies a controlled local MCP subprocess for acceptance tests. |
|
memory
Package memory — semantic + episodic memory orchestration (Go side).
|
Package memory — semantic + episodic memory orchestration (Go side). |
|
models
Package models is the TOML-as-data model catalog (master plan §4.2).
|
Package models is the TOML-as-data model catalog (master plan §4.2). |
|
modelusage
Package modelusage propagates actual model-call accounting across optional middleware without depending on the agent or changing provider contracts.
|
Package modelusage propagates actual model-call accounting across optional middleware without depending on the agent or changing provider contracts. |
|
multimodal
Package multimodal — audio transcription via whisper.cpp.
|
Package multimodal — audio transcription via whisper.cpp. |
|
personality
Package personality — blind-spot tracking: patterns the agent overestimates its ability on, used for self-awareness nudges before executing risky operations.
|
Package personality — blind-spot tracking: patterns the agent overestimates its ability on, used for self-awareness nudges before executing risky operations. |
|
pipeline
orphan: vertical slicer (master plan §5.4); needs /slice slash command
|
orphan: vertical slicer (master plan §5.4); needs /slice slash command |
|
plan
Package plan — current-task plan + todo store.
|
Package plan — current-task plan + todo store. |
|
playbooks
Package playbooks — ACE-style evolving playbooks (§8.2 Phase 5 #6, inspired by Zhang 2025 Agentic Context Engineering).
|
Package playbooks — ACE-style evolving playbooks (§8.2 Phase 5 #6, inspired by Zhang 2025 Agentic Context Engineering). |
|
plugin
Package plugin implements a subprocess-based plugin runtime for Overkill.
|
Package plugin implements a subprocess-based plugin runtime for Overkill. |
|
processrunner
Package processrunner executes bounded subprocess trees on Unix and Windows.
|
Package processrunner executes bounded subprocess trees on Unix and Windows. |
|
prompt
Package prompt provides a modular context chip system for injecting dynamic context into the AI agent's prompt.
|
Package prompt provides a modular context chip system for injecting dynamic context into the AI agent's prompt. |
|
prompt/chips
Package chips provides built-in context chips for the Overkill agent.
|
Package chips provides built-in context chips for the Overkill agent. |
|
providers
Package providers — canonical provider default URLs, env vars, and base configuration.
|
Package providers — canonical provider default URLs, env vars, and base configuration. |
|
pty
Package pty wraps github.com/creack/pty to provide a simple Session type for running interactive commands inside a pseudo-terminal.
|
Package pty wraps github.com/creack/pty to provide a simple Session type for running interactive commands inside a pseudo-terminal. |
|
reflect
Package reflect — Reflexion-class self-correction (paper #51 AlphaGRPO / Shinn 2023 Reflexion).
|
Package reflect — Reflexion-class self-correction (paper #51 AlphaGRPO / Shinn 2023 Reflexion). |
|
rewriter
Package rewriter provides LLM prompt rewriter middleware (master plan §6.x).
|
Package rewriter provides LLM prompt rewriter middleware (master plan §6.x). |
|
routing
Package routing — adapter that lets a SmartRouter satisfy the agent.ModelRouter contract without the agent package importing routing.
|
Package routing — adapter that lets a SmartRouter satisfy the agent.ModelRouter contract without the agent package importing routing. |
|
runtimedb
Package runtimedb resolves explicit database configuration and owns the pool and, only when requested, a private local PostgreSQL process.
|
Package runtimedb resolves explicit database configuration and owns the pool and, only when requested, a private local PostgreSQL process. |
|
security
Package security — encoding-aware scan layer.
|
Package security — encoding-aware scan layer. |
|
session
Package session — prompt stash storage.
|
Package session — prompt stash storage. |
|
settings
Package settings provides a declarative, reflection-based settings system for Overkill, inspired by Warp's define_settings_group! macro.
|
Package settings provides a declarative, reflection-based settings system for Overkill, inspired by Warp's define_settings_group! macro. |
|
shadows
Package shadows — hidden easter eggs and secret commands.
|
Package shadows — hidden easter eggs and secret commands. |
|
share
Package share renders a session as a self-contained HTML page and uploads it to a paste service for easy URL-based sharing.
|
Package share renders a session as a self-contained HTML page and uploads it to a paste service for easy URL-based sharing. |
|
skills
Package skills — context-aware activation conditions (Phase 1.5 #7).
|
Package skills — context-aware activation conditions (Phase 1.5 #7). |
|
skills/registry
Package registry — ClawHub-compatible HTTP client for skill discovery + install (§6.4).
|
Package registry — ClawHub-compatible HTTP client for skill discovery + install (§6.4). |
|
skills/safety
Package safety — antivirus scanning for skill files (§6.4).
|
Package safety — antivirus scanning for skill files (§6.4). |
|
slack
Deprecated: This package is the pre-gateway Slack bot implementation.
|
Deprecated: This package is the pre-gateway Slack bot implementation. |
|
speculation
Package speculation provides idle-time predictive execution.
|
Package speculation provides idle-time predictive execution. |
|
speculative
Package speculative — read cache + prefetcher for §8.5 Phase 5 speculative tool execution.
|
Package speculative — read cache + prefetcher for §8.5 Phase 5 speculative tool execution. |
|
subagent
Package subagent — autonomous-execution loop.
|
Package subagent — autonomous-execution loop. |
|
sync
Package sync ships local Overkill sessions to a remote backend so the user can switch machines and resume.
|
Package sync ships local Overkill sessions to a remote backend so the user can switch machines and resume. |
|
tags
Package tags stores user-applied annotations on file paths.
|
Package tags stores user-applied annotations on file paths. |
|
tasks
Package tasks — cross-session task graph (§8.3 Phase 5 #2).
|
Package tasks — cross-session task graph (§8.3 Phase 5 #2). |
|
term
Package term — OSC 10/11 background-color probe (master plan §5.1).
|
Package term — OSC 10/11 background-color probe (master plan §5.1). |
|
testpg
Package testpg provides isolated PostgreSQL schemas for integration tests.
|
Package testpg provides isolated PostgreSQL schemas for integration tests. |
|
testsocket
Package testsocket creates private, short-lived paths for Unix socket tests.
|
Package testsocket creates private, short-lived paths for Unix socket tests. |
|
tools
Package tools — alarm_set / alarm_list / alarm_cancel tools exposed to the agent.
|
Package tools — alarm_set / alarm_list / alarm_cancel tools exposed to the agent. |
|
tools/bash
Package bash provides security classification for shell commands.
|
Package bash provides security classification for shell commands. |
|
tools/imagegen
Package imagegen provides text-to-image generation tools for Overkill.
|
Package imagegen provides text-to-image generation tools for Overkill. |
|
tools/messaging
Package messaging provides cross-platform messaging tools for Overkill.
|
Package messaging provides cross-platform messaging tools for Overkill. |
|
tools/tts
Package tts provides text-to-speech tools for Overkill.
|
Package tts provides text-to-speech tools for Overkill. |
|
verify
Package verify — default registry wiring + tool-input path extraction.
|
Package verify — default registry wiring + tool-input path extraction. |
|
vision
Package vision turns image bytes into prose a text-only main agent can reason over (master plan §7.4).
|
Package vision turns image bytes into prose a text-only main agent can reason over (master plan §7.4). |
|
walls
Package walls — OVERKILL_ARCH.md + CONTEXT.md generation (master plan §6.5 Wall 2).
|
Package walls — OVERKILL_ARCH.md + CONTEXT.md generation (master plan §6.5 Wall 2). |
|
walls/impossibleprobe
Package impossibleprobe — ImpossibleBench-style cheating detection (§8.4 Zhong 2025).
|
Package impossibleprobe — ImpossibleBench-style cheating detection (§8.4 Zhong 2025). |
|
walls/mcpshield
Package mcpshield — MCP tool-call policy layer (§8.4 MCPSHIELD, Acharya 2026).
|
Package mcpshield — MCP tool-call policy layer (§8.4 MCPSHIELD, Acharya 2026). |
|
walls/monitor
Package monitor — heuristic detectors (Wall 4, paper #48).
|
Package monitor — heuristic detectors (Wall 4, paper #48). |
|
walls/promptinject
Package promptinject — prompt-injection scanner (§8.4 Owner-Harm threat model, Zhang 2026).
|
Package promptinject — prompt-injection scanner (§8.4 Owner-Harm threat model, Zhang 2026). |
|
walls/truthsource
Package truthsource — "user is source of truth" behavioral wall (§8.7.6).
|
Package truthsource — "user is source of truth" behavioral wall (§8.7.6). |
|
web
Package web serves the Overkill browser UI: an embedded SPA over HTTP plus a WebSocket event channel for live agent streams.
|
Package web serves the Overkill browser UI: an embedded SPA over HTTP plus a WebSocket event channel for live agent streams. |
|
worktree
Package worktree manages isolated task checkouts without discarding user work.
|
Package worktree manages isolated task checkouts without discarding user work. |
|
scripts
|
|
|
windows-user-runner
command
Disposable native acceptance launcher.
|
Disposable native acceptance launcher. |
Click to show internal directories.
Click to hide internal directories.