SpiritCuffs (spc)
An LLM-powered second opinion on every git push — before it happens.
SpiritCuffs learns your repo's standards from its git history (and GitHub PR history), then reviews your pending diff with a tight rubric (bugs, security, data-loss — no style noise). It runs locally, in your terminal, in seconds.
$ git push
spiritcuffs: reviewing 3 files…
● CRITICAL auth/login.py:42
SQL query built by string concatenation with user input
→ use a parameterized query
● WARN api/client.py:88
bare except swallows the timeout error; request hangs forever
→ catch httpx.TimeoutException explicitly
30-second quickstart
Two one-time commands, then it just runs on every push:
# 1) authenticate — run once per machine, pick ONE of these:
npx spiritcuffs setup # npm users: same wizard, no separate install step
uvx --from spiritcuffs spc setup # or: pipx install spiritcuffs && spc setup
The wizard picks a provider (OpenRouter, OpenAI, Anthropic, GitHub Copilot, or
a local endpoint), authenticates, picks a model, and tests the connection.
Scripted/CI variant: spc setup --non-interactive --provider openrouter --api-key-env OPENROUTER_API_KEY --skip-ping. Copilot specifics (device-flow
login, CI flags, plan-gated models) are in GitHub Copilot
below.
# 2) wire up a repo — run once per repo, same launcher as step 1:
npx spiritcuffs init # or: uvx --from spiritcuffs spc init / spc init
spc init:
- writes
.spc.toml(committed — it's your team's shared rubric), - installs a
pre-pushhook (spc hook --removeto uninstall;git push --no-verifyto bypass once), - discovers conventions (
CONTRIBUTING.md,AGENTS.md, lint configs), - mines your git history (hotspots, bug clusters, test co-change) and GitHub
PR/review-comment history, then synthesizes
.spc/profile.md— one LLM call, - runs your first review immediately.
Every later git push triggers spc review automatically. You can always
invoke the same launcher interchangeably — npx spiritcuffs <cmd>,
uvx --from spiritcuffs spc <cmd>, or bare spc <cmd> if pipx-installed —
all three run the identical CLI.
| command | what it does |
|---|---|
spc setup |
onboarding wizard (provider, key, model, prefs) — once per machine |
spc init |
repo wiring + learning + first review — once per repo |
spc learn |
re-mine history, re-synthesize .spc/profile.md |
spc review |
review upstream diff (staged fallback) — what the hook runs |
spc history |
recent runs for this repo |
spc hook --remove |
uninstall the hook |
What the LLM sees
Every review sends exactly four things to the model — nothing else leaves your machine:
- Your pending diff (capped at
max_diff_kb, oversized files dropped and listed in the output). - The repo profile (
.spc/profile.md) — the synthesized review standards, capped at ~6000 chars. - Convention files (
CONTRIBUTING.md,AGENTS.md, lint configs — capped at ~8000 chars). - Hotspot file paths — just names of historically high-churn files, so they get slightly more scrutiny.
It does not see your source code, your evidence.json (raw PR data),
your history log, or anything else on disk. Secrets in the diff are regex-
scanned before the call; see the privacy section below.
GitHub Copilot
Works with any Copilot plan (Free included). Choosing it runs the official
GitHub device-flow login (open a URL, enter a code) and stores only the
long-lived GitHub OAuth token. CI: spc setup -y --provider copilot --copilot-token <github-oauth-token> (or export COPILOT_GITHUB_TOKEN).
GitHub Enterprise is not supported yet.
Models: Copilot plan gates model access — the wizard default
claude-sonnet-4.6 is a broad-coverage GA chat model; override with
--model. Token-exchange fallback details (403/404 → direct token use; 401 →
re-auth) are documented in the privacy section below.
Privacy: what leaves your machine
- The diff and, when GitHub mining is enabled, PR titles + review-comment
snippets are sent to the LLM provider configured in
.spc.toml(base_urlmodel). Pointbase_urlat a local endpoint (Ollama, LM Studio, vLLM) and nothing leaves your machine.
- A local regex scan checks the diff for obvious secrets before the LLM call.
Set
block_on_secrets = trueto skip the LLM call entirely when one is suspected. - API keys / tokens live in
~/.spc/config.toml(mode 0600, outside any repo) or in your environment — never in the committed.spc.toml, never in.spc/artifacts, and they are masked in all output. - Copilot tokens: the long-lived OAuth token is exchanged per run for a
short-lived API token (never persisted). If the exchange is rejected with
403/404, that long-lived token is used directly against the Copilot API
host as a fallback (a 401 — revoked token — raises instead). Re-run
spc setupto mint a fresh, exchangeable token. .spc/(profile, evidence) is gitignored;.spc.tomlis meant to be committed.- Run history lives in
~/.spc/history/<repo>-<hash>.jsonl— local only.
Configuration (.spc.toml)
Every knob has a working default:
[llm]
base_url = "https://openrouter.ai/api/v1" # any OpenAI-compatible endpoint
model = "anthropic/claude-3.5-haiku" # any fast/cheap chat model works
api_key_env = "SPC_API_KEY" # env var holding the key
api_key = "" # optional inline key — DON'T commit
# secrets here; prefer `spc setup`
timeout = 30.0 # seconds; caps each LLM attempt
[review]
show_nits = false # nits hidden by default (signal, not noise)
strict = false # true => exit 1 on a critical finding (blocks push)
max_diff_kb = 200 # diff truncation ceiling; dropped files are listed
cache_diff_hash = true # reprint cached findings on identical re-review
[secrets]
block_on_secrets = false # true => skip the LLM call when a secret is suspected
[learn]
learn_max_commits = 2000 # git history depth to mine
profile_max_age_days = 30 # staleness notice threshold (never auto-refresh)
[github]
enabled = "auto" # "auto" | true | false — mine merged PRs + review
# comments in `spc learn` (token via GITHUB_TOKEN /
# GH_TOKEN / gh auth token; public repos work
# unauthenticated)
base_url = "https://api.github.com" # change for GitHub Enterprise
github_max_prs = 200 # merged-PR cap per mining run
github_max_comments = 1000 # inline-comment cap per mining run
github_pages_max = 10 # pagination ceiling per endpoint
Keys resolve in order: repo .spc.toml llm.api_key → user config
~/.spc/config.toml (written by spc setup) → the env var named by
api_key_env. GitHub tokens: user config github.token → GITHUB_TOKEN →
GH_TOKEN → gh auth token. Copilot OAuth tokens: repo .spc.toml
copilot.github_oauth_token → user config copilot.github_oauth_token →
COPILOT_GITHUB_TOKEN.
Export your key: export SPC_API_KEY=sk-... (any OpenAI-compatible provider).
GitHub mining
If origin points at GitHub, spc learn also mines merged PRs and inline
review comments and distills them into your profile: recurring peer-review
themes plus explicit repo rules a diff can be checked against (ordering
requirements, forbidden patterns, required process — e.g. migration before
code). Watermark-incremental: re-runs fetch only PRs newer than the last run.
Rate-limit aware, capped per run, and strictly fail-soft — any GitHub error
downgrades to git-only learning with a one-line notice. Only synthesized
themes enter .spc/profile.md; raw comments stay in the gitignored
.spc/evidence.json.
Token safety (GitHub Enterprise)
Your GitHub token is a machine-level credential, but github.base_url comes
from the repo-committed .spc.toml. SpiritCuffs therefore attaches the
Authorization: Bearer … header only when the API host is
api.github.com, or matches the host of your own origin remote (your
GitHub Enterprise instance), and only over https. A repo whose config
points base_url at some other host is mined unauthenticated with a one-line
warning — your token is never sent there. Plain http:// base URLs never
receive the token either.
Behavior guarantees
- Fail-soft: git hiccups, missing profile, or LLM failure never break your
push — you get a one-line warning and exit 0. Only
strict = true+ a critical finding exits 1 (bypass withgit push --no-verify). - No silent truncation: oversized diffs are cut per-file, and the prompt lists which files were dropped.
- Cached re-reviews: pushing the same diff twice skips the LLM call.
- Never invents findings: hotspot files get mentioned with slightly higher scrutiny, but the rubric forbids inventing issues.
FAQ / troubleshooting
No API key configured — reviews fail soft: a one-line warning, exit 0,
your push goes through. Run spc setup (or export SPC_API_KEY=sk-...).
A review blocked my push — that only happens with strict = true plus a
critical finding. Fix it, or bypass once with git push --no-verify.
I disagree with a finding / it's a false positive — findings are advisory
(except under strict = true); ignore them and move on. spc history keeps
every run, and v1.1 adds accept/dismiss marking so repeated dismissals can
calibrate future reviews (v2).
Stale profile notice — .spc/profile.md is older than
profile_max_age_days (30). Re-run spc learn when convenient; reviews
continue with the stale profile meanwhile. Learning is never triggered inside
the push path.
CI: skip the hook entirely — SpiritCuffs is a local dev tool. For scripted
setup use spc setup --non-interactive --provider <p> --api-key-env <VAR> --skip-ping.
Windows: the pre-push hook runs via sh (Git for Windows ships one);
Python must be on PATH in that shell.
Development
uv venv && uv pip install -e . pytest ruff
uv run pytest # test suite (LLM calls are mocked; no network)
uv run ruff check spc tests
MIT licensed. Source: https://github.com/wallycarvalho/spiritcuffs
Metadata
Release files for spiritcuffs 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| spiritcuffs-0.1.1.tar.gz | 113.9 kB | Without provenance | Details for spiritcuffs-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spiritcuffs-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for spiritcuffs-0.1.1-py3-none-any.whl |
Total release size: 179.0 kB
Release files / spiritcuffs-0.1.1.tar.gz
| Download URL | spiritcuffs-0.1.1.tar.gz |
|---|---|
| Size | 113.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fa120cc7deaf55fc6608d1a7c9b534fe26d294065b466498f7e610e1d9a3a9e6
|
|
BLAKE2b-256 checksum How to use checksums |
9a6e3d738eabe0f8cbb76e297354fa05a2ce3e819719a3ec8de14c4f15bcbd1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / spiritcuffs-0.1.1-py3-none-any.whl
| Download URL | spiritcuffs-0.1.1-py3-none-any.whl |
|---|---|
| Size | 65.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0cc1330bd67a9d6066a01575e3eed34660606f496cbafe2d5a4c712d6bd2db8b
|
|
BLAKE2b-256 checksum How to use checksums |
b76898110c92d6e59cd7d583d9c79b1a442f09a7c417cb9e762a2854d36cdae6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for spiritcuffs 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.