Keiyaku

CLI for contract-style coding work in git repositories. 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.
• Supported providers. codex-cli, codex-sdk, claude-agent-sdk, gemini-cli-core, opencode-sdk. CLI-backed providers need their matching executable (codex, gemini, opencode). claude-agent-sdk uses the installed Agent SDK package and can optionally point at a claude executable override via executable.

Setup

Open a git repo. Run keiyaku guide and keiyaku zako list. Then use keiyaku <command> --help for exact command formats.

Flow

bind → round open → [summon/ask | amend | delivery work] → delivery commits → round close → [round open | amend | petition]

Tools

summon <name> [prompt|-] — Calls in an agent to do scoped work. If a round is open, the round scope is injected. Add --incognito for a one-off run with no response history.

ask <name> [prompt|-] is the short alias for the same behavior.

Implement the retry tests. Report touched files and verification.

resume <response-path> [prompt|-] — Continues a prior summon session from a response artifact.

keiyaku resume .keiyaku/response/previous.md "Continue from here"

zako list / zako show <name> — Inspect available helpers before choosing keiyaku summon NAME.

keiyaku zako list
keiyaku zako show codex

bind — Opens a branch and writes KEIYAKU.md. Repo must be clean.

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

bind:
  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

round open — Frame a delivery round before work starts.

# Retry backoff

## Objective
Implement retries with exponential backoff.

## Brief
Keep the public API unchanged. Commit the delivery work before closing the round.

round close — Record a completed round from git commits.

## Commits
- abc1234

## Report
Retry tests pass and backoff is now 2x.

petition — Close the task.

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

Oath required unless you explicitly bypass gates. Configured verification and reviewer gates will reject weak claims.

status — Current state and what's blocking you.

keiyaku guide — Full reference.

What Gets Written to the Repo

| File | | |------|--| | KEIYAKU.md | Active contract | | .keiyaku/draft/*.md | Recovery input if bind/stdin execution fails | | .keiyaku/response/*.md | Tool response history |

Don't want these tracked:

.keiyaku/draft/
.keiyaku/response/

Advanced

keiyaku dump-env

Per-agent runtime settings live in .keiyaku/settings.json and use provider / executable:

{
  "agents": {
    "claude": {
      "provider": "claude-agent-sdk",
      "model": "claude-sonnet-4-5",
      "executable": "claude",
      "description": "Claude-side Zako for review and integration.",
      "systemPromptFile": ".keiyaku/claude-system.md"
    },
    "codex": {
      "provider": "codex-sdk",
      "executable": "codex",
      "description": "Default Codex-side Zako.",
      "config": {
        "developer_instructions": "Adapter-level instructions appended to Codex sessions."
      }
    },
    "gemini": {
      "provider": "gemini-cli-core",
      "model": "gemini-2.5-pro",
      "description": "Gemini-side Zako for preview and synthesis.",
      "systemPromptFile": ".keiyaku/gemini-system.md"
    }
  },
  "default": "codex",
  "reviewer": "codex"
}

Claude defaults:

• settingSources: ["project"]
• permissionMode: "bypassPermissions"
• keiyaku resume RESPONSE_PATH resumes via persisted provider session metadata

Codex SDK notes:

• config is passed through to Codex. Use developer_instructions for adapter-level instructions.
• model_instructions_file is also accepted through config, but it replaces Codex built-in instructions.

Gemini notes:

• systemPromptFile is passed to Gemini CLI core as GEMINI_SYSTEM_MD, which replaces Gemini's base system prompt.

keiyaku zako list and keiyaku zako ls show each profile's description when present.

| Variable | Default | | |----------|---------|--| | KEIYAKU_SUBAGENT_EXEC_TIMEOUT_MS | — | Execution timeout | | KEIYAKU_SUBAGENT_EXEC_IDLE_TIMEOUT_MS | — | Idle timeout | | KEIYAKU_FAKE_SUBAGENT | 0 | 1 = test stub |

MIT