invocator

Summon the accumulated wisdom of a GitHub repository into a learnings/ grimoire. ✨

invocator is a CLI that points at any GitHub repository, walks its PRs, issues, commits, and code-review conversations, and synthesizes that history into a folder of categorized markdown files — rules, prevenções, patterns, decisions, glossary — so the tacit knowledge living in a project's timeline becomes navigable documentation.

The three spells

Prerequisites

• Python 3.11+
• gh CLI installed and authenticated (gh auth login) — invocator never calls api.github.com directly
• An Anthropic API key

Multi-account gh users: invocator runs as whichever GitHub identity gh auth status reports as active. If a repo lives in an org and REPO_NOT_FOUND surprises you, switch with gh auth switch before re-running.

Install

pipx install invocator        # recommended
# or
uv tool install invocator
# or, from source
git clone https://github.com/Gab-r-x/invocator.git && cd invocator && pip install -e .

Quickstart

invocator forge key
invocator scry cost --repo OleveCo/CourseGPTBackend
invocator extract wisdom --repo OleveCo/CourseGPTBackend

After the ritual completes, ./learnings/ will contain six markdown files synthesized from the repo's history.

Output structure

How it works

1. summon — gh api --paginate pulls PRs, issues, commits, and review comments into a JSONL cache with per-resource watermarks (re-runs are incremental).
2. transmute — heuristics (conventional commits, review-cue regexes, labels, ADR detection, glossary mining) classify each item into one of five categories. SHA1 dedupe + top-K cap per category.
3. inscribe — one Anthropic call per category, with explicit prompt caching, writes learnings/<category>.md. A SHA256 corpus hash means re-runs without deltas are free (no LLM call). INDEX.md is rendered deterministically.

Cost

Roughly $1–3 USD for medium-sized repos with claude-sonnet-4-6. Always preview with invocator scry cost --repo X first. Re-runs without changes are free thanks to the hash cache.

Troubleshooting

Contributing

This project follows a strict phased-todo workflow. Before contributing, read:

• CLAUDE.md — workflow and project rules
• docs/STANDARDS.md — the non-negotiable engineering rules
• docs/todos/README.md — operational contract for the executor → progress → tests pipeline

License

MIT — see LICENSE.