The problem everyone feels

AI coding agents are loud and optimistic.

They type “Fixed! All done.” while tests still fail.
They dump fat JSON into context until the model forgets the goal — and your token bill climbs.
They skip /plan, edit twenty files, and call it a day.
Chat becomes the source of truth. Disk never gets a vote.

GODKILLER flips that.
If it isn’t proven on disk, it isn’t done.

Who it’s for

Developers, AI engineers, and power users who run agents hard — and refuse to trust the chat bubble.

Pain	Without GODKILLER	With GODKILLER
Fake completion	“All done!” / “All green” in chat	`claim_done` blocked until verify + evidence land
Token bloat	Schema / dump floods every turn	Compact payloads by default
Skipped ritual	Plan → edit → vibes	Phase gates · illegal jumps die
Blind edits	Multi-file rush, no blast	`edit_safe` · blast · hollow · fault probe

Why people install it

Proof over promises

Chat vibes don’t open the gate. Sealed evidence on disk does.

Phase kernel that actually bites

gk_route puts the agent on a real pipeline:

Mode	Job
`/ask`	Read-only. Answers with citations.
`/plan`	Spec first. No silent “just ship it.”
`/debug`	Repro + hypotheses before the fix.
`/ultradeep`	One file · think → plan → edit.
`/view`	Study patterns. Don’t paste a whole repo as done.
`/verify`	Disk proof → then `claim_done`.

One MCP. Full surface.

Code · scan · browser · guard · memory · handoff — facades in one place.
Pair specialty MCPs as brains. GODKILLER is the judge.

The flex

The model proposes. GODKILLER disposes.

goal → mode → plan → search/blast → gated edit
    → disk verify → hollow → probe → exit → claim_done | blocked

How to use

	Do this
Once (machine)	`pip install godkiller-mcp` · add MCP server · set `GODKILLER_SEAL_KEY` (`docs/SEAL_KEY.md`)
Once per project	`godkiller-bootstrap --workspace .` · reload the IDE
Every task	`gk_mode.activate` → `/plan` → `/ultradeep Phase N` → `set_paths` → `end_turn` → `/verify` → `claim_done`
Full lock (optional)	Prove deny/allow, then `GODKILLER_WRITE_GUARD_PROVEN=1` — `docs/WRITE_GUARD_HOOKS.md`

godkiller-bootstrap writes .agents/AGENTS.md, .agents/PROMPTS.md (copy-paste prompts), and portable write-guard hooks. Do not commit godkiller-write-guard.local.cmd / .local.sh (machine pin).

Ship write turns: one set_paths per turn (default max 1 path); gk_guard.end_turn before the next Phase. Ultradeep allowlists the current file only.
Mode pin: /ask /view /verify deny native app Write; /plan only .agents/plans/.

MCP gates gk_* only. Native Write stays free until PreToolUse is wired. Details: docs/HOST_VS_MCP.md.

60-second install

pip install godkiller-mcp
python -c "import secrets; print(secrets.token_hex(32))"

Drop into your MCP host config:

{
  "mcpServers": {
    "godkiller": {
      "command": "godkiller-mcp",
      "env": {
        "GODKILLER_PROFILE": "ship",
        "GODKILLER_WORKSPACE": "/absolute/path/to/your/project",
        "GODKILLER_HOME": "/absolute/path/to/your/project/.godkiller-session",
        "GODKILLER_SEAL_KEY": "REPLACE_WITH_64_HEX",
        "GODKILLER_SEAL_REQUIRE_ENV": "1"
      }
    }
  }
}

Alternate entry: python -m godkiller_mcp.server
From source: pip install "git+https://github.com/taurus42119-stack/godkiller-mcp.git"

Modes ship inside the package — a full .agents/workflows tree is not required.
One GODKILLER_HOME per concurrent host.

Ship tip: wire host PreToolUse → godkiller-write-guard, then set GODKILLER_WRITE_GUARD_PROVEN=1 only after a live deny/allow test.
Until that hook is real, native Write can still bypass MCP tools.
Details: docs/WRITE_GUARD_HOOKS.md · docs/HOST_VS_MCP.md · docs/SEAL_KEY.md

Intensity (honest)

You installed	What you actually get
MCP only	Judge on the `gk_*` path. Native IDE Write is free.
+ `.agents/AGENTS.md`	Soft standing orders. Agents can still skip.
+ host write-guard (opt-in)	Native Write/Edit blocked unless allowlisted.

We do not ship a hostile filesystem lock inside MCP. Full lock is your PreToolUse hook — see docs/WRITE_GUARD_HOOKS.md.

Try this

After MCP is live:

Call gk_meta.status — if it fails, stop. Don’t invent that the kernel is up.
/plan a real feature. Watch phase gates bite.
Fix with blast_radius → edit_safe — not chat “I searched.”
Finish with gk_verify.exit → gk_phase.claim_done.

No .godkiller/ state on disk? You didn’t use the kernel. You used vibes.

Tool map

Facade	What it owns
`gk_meta`	Honesty status · 9-step plan
`gk_route`	Mode switchboard
`gk_task`	open · blast · edit_safe
`gk_phase`	assert · claim_done
`gk_evidence`	shots · visual_step · critic
`gk_verify`	bundle · hollow · probe · exit
`gk_memory`	lessons · marathon
`gk_code`	map · search · council · swarm
`gk_guard`	write allowlist for host hooks
`gk_scan`	heuristic scan
`gk_browser`	Playwright fallback (prefer chrome-devtools when present)
`gk_mode`	protocols · skills
`gk_handoff`	spec / feedback

Agent protocol notes: docs/AGENT_PROTOCOL.md

Star · fork · flex

If this killed a fake “done” for you — star the repo.
Fork it. Wire it. Make your agent earn the win.

Security

SECURITY.md

godkiller-mcp