# kepil

Security gate and tamper-evident audit journal for AI agents. Enforces permission mandates and requires human approval for risky steps.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: oleg-vdv
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/oleg-vdv/kepil
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/mcp/kepil

## What it does

Kepil stands between an AI agent and external infrastructure to evaluate every planned action. The gate checks tasks against an explicit mandate before invoking any model. If a step lacks clear permission, the system triggers a fail-closed refusal. Records stream to an append-only JSONL journal where each entry contains the previous record's hash, making silent log tampering detectable.

The MCP interface exposes seven tools for reviewing agent passports, triggering job steps, and reading order states. A confirmation tool is omitted on purpose: models cannot approve their own irreversible actions. Approvals route exclusively to a human operator via the admin panel at `http://localhost:7317` or through Telegram. Pending confirmation cards wait up to 4 hours before alerting the operator again.

When a workflow fails, Kepil walks the dependency tree backwards and executes compensating actions until it encounters an irreversible step. The entire state lives in plain JSON files inside `KEPIL_DATA` (defaults to `./data`), removing any need for external database servers.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `KEPIL_DATA` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env KEPIL_DATA=<KEPIL_DATA> --transport stdio kepil -- uvx kepil
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>

### Codex

**Platform CLI**
```bash
codex mcp add kepil --env KEPIL_DATA=<KEPIL_DATA> -- uvx kepil
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "kepil": {
            "command": "uvx",
            "args": [
                "kepil"
            ],
            "env": {
                "KEPIL_DATA": "<KEPIL_DATA>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "kepil": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "kepil"
            ],
            "env": {
                "KEPIL_DATA": "<KEPIL_DATA>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e KEPIL_DATA=<KEPIL_DATA> kepil uvx kepil
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>

## When to use it
- block unauthorized tool invocations before external APIs are hit
- verify audit journal integrity using an append-only hash chain
- route sensitive task sign-offs directly to an operator in Telegram
- replay compensating actions backward to safely undo agent progress

## Example prompts
- Inspect the agent passport and start the next step for ord-0042
- List all pending actions that require human confirmation
- Verify the integrity of the action journal with Kepil

## Similar
- [sanctuary](https://affpapa.org/en/nevibecode/mcp/sanctuary.md) — MCP server · ★ 9
- [signet](https://affpapa.org/en/nevibecode/plugins/signet.md) — plugin · ★ 40
- [Agoragentic Agent OS MCP](https://affpapa.org/en/nevibecode/mcp/agoragentic-agent-os-mcp.md) — MCP server · ★ 41
- [januscope](https://affpapa.org/en/nevibecode/mcp/januscope.md) — MCP server · ★ 32
- [SchemaBrain](https://affpapa.org/en/nevibecode/mcp/schemabrain.md) — MCP server · ★ 12
- [Covenant Guard](https://affpapa.org/en/nevibecode/mcp/covenant-guard.md) — MCP server · ★ 8

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md