Seven specialist AI lenses watch your Claude Code session and whisper one-line concerns back to Claude before your next prompt.
UX. Engineering. Security. Perf/FinOps. Product/Biz. Strategic Founder. Cognitive Flow. Each one reads the transcript tail + git status + one file (its own pick), produces one observation, gets critique-judged, and the survivors land in Claude's context as a [BACKGROUND ADVISORY — UNTRUSTED] block. Claude can verify, ignore, or push back. You stay in control.
Real screenshots from a live session:
Line 1 — standard Claude Code statusline (branch, dirty marker, effort level, context% bar, today's spend, optional cpu/cache).
Line 2 — rotates every 30s between advisor (one of 7 lens observations, sometimes with an alarm glyph + age suffix like (2m)) and teacher (a rotating digest of popularity-ranked HN + recent arXiv cs.AI / cs.HC titles, compressed by gpt-5-mini).
The ENGINEERING lens flagged
mktemp in install/uninstall can create tmp on other FS. Investigation confirmed:bin/install.shused baremktemp(defaults to/tmp), thenmv "$tmp" "$SETTINGS_FILE". On Linux with/tmpas tmpfs, thatmvcrosses filesystems — copy+delete, not atomic. A partial read by Claude Code is a real race. Fix shipped in PR #3. The proposition: hypotheses surfaced earlier, not a guarantee.
git clone https://github.com/AhmadBilal227/pair-polymath
cd pair-polymath
./bin/install.shNeeds a TTY (API key prompt). Detects jq + llm (≥0.20) and walks you through installing what's missing. Backs up $CLAUDE_DIR/settings.json (default ~/.claude/settings.json) before merging in our statusLine + 3 hooks atomically.
After a successful install, Pair Polymath offers activation onboarding:
bash ./bin/polymath onboard --from-installOnboarding lets you choose role, project phase, active lens preset, cost profile, optional custom lens, and display-only fun mode. ./bin/install.sh --yes prints the onboarding command instead of prompting. Restart Claude Code after install; first cycle runs within ~5 minutes of activity.
Verify: bash ./bin/polymath doctor (22 health checks). Uninstall: ./bin/uninstall.sh.
| Scenario | Calls / cycle | ~Daily ($) |
|---|---|---|
| Idle (30 min no transcript change) | 0 | 0 |
| Active, base path | 9 | 3–8 |
| Active + drops + retries | 9–16 | 5–15 |
| Worst case sustained | 23 | 15–35 |
Hard cap on call count via PP_MAX_DAILY_CALLS=10000 (atomic mkdir-locked reservation per cycle). See actual spend: polymath cost --since 30d. Disable for sensitive sessions: polymath disable.
What leaves per cycle: ~5 KB transcript tail, git status + last 5 commit subjects, ~3 KB of ONE planner-picked file (containment-checked, 30+ secret-bearing basename + path-component denylists in lib/grounding.sh), public HN + arXiv RSS titles. NEVER: full conversation history, files outside cwd, recursively-expanded ${VAR} values in prompts. At risk: secrets you pasted INTO your transcript. Every cycle writes a verifiable snapshot to $PP_CACHE_DIR/last-cycle-payload.json (default ~/.claude/cache/last-cycle-payload.json). Cache files are mode 0600 automatically. Full threat model: SECURITY.md + docs/security.md.
| Thing | Where |
|---|---|
| Daily cap / intervals / model choice | $PP_USER_CONFIG (default $CLAUDE_DIR/pair-polymath/config/user.env) |
| Guided setup | polymath onboard |
| Active lens preset | $PP_STATE_DIR/config/lenses-enabled.txt or polymath onboard |
| Add a new lens | $PP_STATE_DIR/lenses/08-mylens.json (schema) |
| Override the analyst prompt | $PP_STATE_DIR/prompts/analyst-primary.md |
| Disable advisor (status-only) | polymath disable |
| Display-only fun mode | polymath fun status / polymath fun on / polymath fun style mentor |
| Inspect lens-gates kill-switches | polymath lens-gates status |
| Tool | What it does | Pair Polymath adds |
|---|---|---|
| ccusage | Token spend in statusline | Cost + 7 advisor observations injected into Claude's context + learning digests |
| ccstatusline | Configurable statusline | Status + per-cycle parallel-LLM advisory team with critique gate |
| aider | Writes code | Different category — Pair Polymath does NOT write code; it whispers to Claude, who decides |
| LSP servers | Syntactic/type warnings | One level up — multi-disciplinary cross-cutting concerns no LSP surfaces |
Latest: v0.5.2.1 — planner / grounding fix. Three changes (SILENT first-class, FILE-READ-derived symbol inventory unified between lens prompts and validator, planner eligibility gates per lens). All shadow-by-default behind 4 kill-switches; STDOUT byte-identical to v0.5.2.0 until you opt in. Full Bats suite green; dual-write schema migration preserves v0.5.2.0 reader compatibility.
Recent: v0.5.2.0 — OAR (Observation→Action Rate) measurement plumbing + shadow-by-default hallucination verifier.
Both releases ran through 3 rounds of GPT-5 coworker spec review + multi-reviewer-per-task implementation, which caught 17+ silent-correctness bugs pre-merge. See CHANGELOG.md for the bug-catch log.
APIs (config keys, lens schema, prompt placeholders, OAR schema) may still shift before v1.0. Issues + PRs welcome.
macOS bash 3.2+ ✅ · Ubuntu bash 5+ ✅ (CI verified) · WSL ⚠ untested (open an issue if you try). Deps: jq, llm (≥0.20). Optional: gh, gtimeout.
docs/architecture.md— cycle + sequence diagrams, state-file invariants, module mapdocs/customization.md— fullPP_*env reference + lens schemadocs/cost-model.md— the formula behindpolymath costdocs/troubleshooting.md— failure modes by doctor check- SECURITY.md — threat model
- CHANGELOG.md — every release, with the silent-correctness bugs caught by review
MIT — see LICENSE.