Keiyaku

MCP server. AI code changes run on an isolated branch. Tasks are written into the repo. Nothing closes without your sign-off.

npm install -g @astrosheep/keiyaku

Before You Start

Missing any of these? Don't come crying.

• Git repo. Clean worktree. Dirty = refused.

• MCP client. Claude Desktop, Claude Code, anything stdio.

• Subagent CLI. claude, gemini, or codex. Installed. Logged in. Keiyaku doesn't run code itself — it delegates everything to a subprocess. No CLI = nothing happens.

  Codex users, one extra step. Codex clears env before spawning MCP servers. Add this to your ~/.codex/config.toml or keiyaku won't know when it's running as a subagent:

  [mcp_servers.keiyaku]
  # ... rest of your config ...
  env_vars = ["KEIYAKU_DISABLE_SUBAGENT_SPAWN"]

Setup

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "keiyaku": {
      "command": "npx",
      "args": ["-y", "@astrosheep/keiyaku"]
    }
  }
}

Restart client. Open a git repo. Run status. Done.

Flow

ask (anytime)  |  summon → [drive | ask]* → petition

Tools

ask — For questions. No branch, no contract. Use it freely.

Where's the retry logic? Run the unit tests for that file.

summon — Opens a branch, writes the contract. Repo must be clean.

Vague criteria = vague results. Write "make it better" and don't blame anyone but yourself.

summon:
  title: "Retry logic for HTTP client"
  goal: "5xx failures retry up to 3 times with exponential backoff"
  criteria:
    - Retry unit tests pass
    - Public API unchanged
    - Existing tests still pass

drive — Next round. Review the diff, say what's wrong, run another round.

Backoff is 1.5x, should be 2x. Fix it, update the tests too.

petition — Close the task.

CLAIM = verified, all criteria pass. FORFEIT = abandon, throw everything away.

Scores required (0–10). Oath required. The gates will actually reject you. Don't show up without checking.

status — Current state and what's blocking you.

help — Full reference.

What Gets Written to the Repo

| File | | |------|--| | KEIYAKU.md | Active contract | | KEIYAKU_TRACE.md | Per-round log | | KEIYAKU.draft.md | Recovery draft if summon fails | | .keiyaku/response/*.md | Per-round output |

Don't want these tracked:

.keiyaku/draft/
.keiyaku/response/

Advanced

keiyaku dump-env

| Variable | Default | | |----------|---------|--| | KEIYAKU_MCP_TRANSPORT | stdio | stdio or streamable-http | | KEIYAKU_MCP_HTTP_PORT | 3000 | HTTP port | | KEIYAKU_SUBAGENT_EXEC_TIMEOUT_MS | — | Execution timeout | | KEIYAKU_SUBAGENT_EXEC_IDLE_TIMEOUT_MS | — | Idle timeout | | KEIYAKU_INCREMENTAL_DIFF_MODE | targeted | targeted | stat | unified | | KEIYAKU_FAKE_SUBAGENT | 0 | 1 = test stub |

HTTP transport:

KEIYAKU_MCP_TRANSPORT=streamable-http \
KEIYAKU_MCP_HTTP_HOST=127.0.0.1 \
KEIYAKU_MCP_HTTP_PORT=3000 \
npx -y @astrosheep/keiyaku

MIT