<p align="center">
  <img src="docs/assets/godkiller-mcp-banner.png" alt="GODKILLER MCP" width="560" />
</p>

<h1 align="center">GODKILLER MCP</h1>

<p align="center">
  <strong>Gates on disk beat chat.</strong><br/>
  The agent may <em>say</em> done. The harness decides.
</p>

<p align="center">
  Built for <strong>Google Antigravity</strong> · works on other MCP hosts too<br/>
  Plan → gate → verify on disk → <code>claim_done</code>
</p>

<p align="center">
  <a href="https://pypi.org/project/godkiller-mcp/"><img src="https://img.shields.io/pypi/v/godkiller-mcp.svg" alt="PyPI" /></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT" /></a>
  <a href="https://github.com/taurus42119-stack/godkiller-mcp/actions/workflows/ci.yml"><img src="https://github.com/taurus42119-stack/godkiller-mcp/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://github.com/taurus42119-stack/godkiller-mcp/stargazers"><img src="https://img.shields.io/github/stars/taurus42119-stack/godkiller-mcp?style=social" alt="Stars" /></a>
</p>

<p align="center">
  <a href="https://instagram.com/Kayvin.th">Instagram @Kayvin.th</a>
  ·
  <a href="https://github.com/taurus42119-stack/godkiller-mcp">Star the repo</a>
  ·
  <code>pip install godkiller-mcp</code>
</p>

---

## 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.

```text
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`](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`](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`](docs/HOST_VS_MCP.md).

---

## 60-second install

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

Drop into your MCP host config:

```json
{
  "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/WRITE_GUARD_HOOKS.md) · [`docs/HOST_VS_MCP.md`](docs/HOST_VS_MCP.md) · [`docs/SEAL_KEY.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`](docs/WRITE_GUARD_HOOKS.md).

---

## Try this

After MCP is live:

1. Call `gk_meta.status` — if it fails, stop. Don’t invent that the kernel is up.
2. `/plan` a real feature. Watch phase gates bite.
3. Fix with `blast_radius` → `edit_safe` — not chat “I searched.”
4. 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`](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.

<p align="center">
  <a href="https://github.com/taurus42119-stack/godkiller-mcp">github.com/taurus42119-stack/godkiller-mcp</a>
</p>

---

## Security

[`SECURITY.md`](SECURITY.md)

---

## License

MIT © 2026 GODKILLER Team — [LICENSE](LICENSE)