coc-cli

Game state manager for Call of Cthulhu 7th Edition solo sessions with an AI Keeper.

Setup

1. Install

uv tool install /path/to/coc-cli

2. Install skills

coc-skill install claude-code   # for Claude Code
coc-skill install opencode      # for OpenCode
coc-skill install codex         # for Codex

This installs two skills (/coc-keeper for gameplay, /coc-setup for campaign bootstrap) in your AI tool's skills directory. To remove them: coc-skill uninstall <tool>.

3. Bootstrap a campaign

Create a directory for your campaign, put the module PDF inside, then start an agent there and run:

/coc-setup

The agent will extract the PDF and generate:

• module/ — extracted module text
• rules/ + INDEX_RULE.md — bundled QSR reference
• INDEX_MODULE.md — module section index (fill in after reviewing)
• CLAUDE.md / AGENTS.md — Keeper instruction file (fill in)
• state.json — investigator state (fill in)
• CLI.md — command reference

Edit state.json, CLAUDE.md, and INDEX_MODULE.md before playing.

4. Open the player dashboard

In a separate terminal, run the TUI viewer from the campaign directory:

coc-viewer              # watches ./state.json
coc-viewer path/to/state.json

This shows a live, player-safe view of your investigator stats, inventory, explored rooms, clues, and log. It auto-refreshes whenever the Keeper updates state.json. Press q to quit.

5. Start playing

Open a new agent (or clear context) in the campaign directory and invoke the skill:

/coc-keeper

The Keeper agent will read CLAUDE.md, load state via coc-cli status, and begin the session.

---

Runtime commands

Run coc-cli from the campaign directory (where state.json lives):

coc-cli status    # full session snapshot — use at the start of each turn
coc-cli log "…"  # append a log entry — use at the end of each turn

Full command reference: coc_cli/assets/CLI.md

---

Development

uv run pytest