convez.ai
PluginDevOps & InfraestruturaIntermediário
akihidem

Claude Env Coach Kit

akihidem/claude-env-coach-kit

Tuner de ambiente sem alucinações para Claude Code com PR automático

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin que monitora automaticamente a documentação do Claude Code, detecta atualizações e propõe melhorias verificadas para sua configuração local (~/.claude/). Usa verificação em duas etapas com re-grep contra os docs para eliminar alucinações, entregando propostas confiáveis e abrindo PRs automáticos no seu repositório dotclaude.

Instalação

$npx convez-ai akihidem/claude-env-coach-kit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
v2.12.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Manter configurações do Claude Code sincronizadas com atualizações oficiais
  • Receber propostas verificadas de melhorias em hooks, agents e skills
  • Automatizar adoção de mudanças via pull requests no repositório dotclaude

Veredito

Solução sólida de automação que resolve um problema real: manter ambientes Claude Code atualizados sem alucinações. A estratégia de verificação verbatim contra docs é engenhosa e o fluxo de cron + PR automático reduz fricção operacional. Recomendado para times que usam Claude Code em produção.

README

A tradução para o português deste README ainda está na fila.

claude-env-coach

License: MIT Python 3.11+

English · 日本語

Watches the official Claude Code documentation, detects updates, and proposes hallucination-free improvements to your local ~/.claude/ setup. Verified proposals are delivered to your notifier of choice and (optionally) opened as PRs against your dotclaude repo so you can adopt them with one merge click.

Why

  • code.claude.com/docs evolves constantly. Local settings (settings.json / hooks / agents / skills / scripts) only catch up by hand.
  • Asking an LLM "what's new in Claude Code?" reliably hallucinates feature names, hook events, and config keys that don't exist.
  • This tool detects diff → asks Claude (haiku) for proposals → re-greps each proposal verbatim against the docs page → drops anything that didn't literally appear → de-duplicates → delivers.

The verbatim re-grep pass is the load-bearing trick. It eliminates fabricated identifiers without giving up on creative use of real features the docs added.

How it works

[cron 30 * * * *] coach.py
   ↓
   ① fetch + sha256(normalized text) — 19 sources by default
   ↓ no change → tick-log appended, exit silently
   ↓ changed
   ② sentence-set diff → "added since last snapshot" only
   ↓
   ③ Step 1 (extract.md): haiku returns literal phrases only — no titles
   ↓
   ④ local verify_phrase: re-fetch each URL → grep → drop hallucinations
       evidence_source = "diff" | "corpus" tagged from §②
   ↓
   ⑤ Step 2 (propose.md): only verified phrases as input → titles/why/snippets
       (phrase mutation forbidden)
   ↓
   ⑥ verify_snippet: 4-char identifiers in snippet → grep against docs_corpus →
       unverified tokens flagged as ⚠️ warning (proposal not dropped)
   ↓
   ⑦ deliver: notifier.send() + inbox.md + proposals-log.jsonl append
   ↓
   ⑧ (optional, v2.0) auto-PR: open a PR against your dotclaude repo so a
       merge click adopts the proposal; --sync-pr cron syncs status back

[cron 0 9 * * *]     coach.py --sync-pr        (PR state poll → status sync)
[cron 0 10 * * 0]    coach.py --cleanup-scan   (deprecation → removal PR, weekly)
[cron 0 12 * * 6]    coach.py --heartbeat      (weekly summary)
[cron 0 9 1 * *]     coach.py --rotate         (monthly archive)

Default monitored docs

19 sources, managed in docs.yaml (re-read on every run):

  • Claude Code docs (code.claude.com/docs/en/): hooks, settings, sub-agents, output-styles, memory, slash-commands, mcp, plugins, plugin-marketplaces, statusline, skills, sandboxing, monitoring-usage
  • Anthropic API / Agent SDK (platform.claude.com): release-notes, agent-sdk, tool-use, prompt-engineering
  • Changelogs (GitHub raw): claude-code, anthropic-sdk-python

File layout

claude-env-coach/
├── coach.py                    # main, single-file
├── docs.yaml                   # monitored URLs
├── .claude-plugin/             # Claude Code plugin manifest + self-hosting marketplace
│   ├── plugin.json
│   └── marketplace.json
├── commands/                   # slash commands (/coach-setup, /coach-init, /coach-scan, /coach-status)
├── scripts/
│   └── build-kit.sh            # build the distributable zip kit into dist/
├── prompts/
│   ├── extract.md              # step 1 — literal phrase extractor
│   ├── propose.md              # step 2 — proposal generator (phrase frozen)
│   ├── cleanup.md              # weekly deprecation scan (v2.8)
│   ├── user-context.md.example # generic template (commit-able)
│   ├── user-context.md         # your context (gitignored)
│   └── contexts/               # per-project context (gitignored; *.md.example committed)
├── data/                       # state (gitignored)
│   ├── docs-cache/             # last HTML snapshot per URL
│   ├── docs-state.json         # per-URL hash baseline
│   ├── proposals-log.jsonl     # proposal history with status / pr_url / evidence_source
│   ├── tick-log.jsonl          # per-cron-tick liveness stats (v1.1)
│   ├── inbox.md                # local delivery log
│   └── archive/YYYY-MM/        # monthly rotation (v1.2)
├── tests/
│   └── test_sync_smoke.py      # network-free smoke tests (python3 tests/test_sync_smoke.py)
├── .env.example                # env var template
├── LICENSE                     # MIT
├── CONTRIBUTING.md
├── README.md                   # English (this file)
└── README.ja.md                # 日本語

Install as a Claude Code plugin

This repo is also a Claude Code plugin (it ships a .claude-plugin/ manifest and a self-hosting marketplace). Installing it adds slash commands that drive the daemon from inside Claude Code:

/plugin marketplace add akihidem/claude-env-coach-kit
/plugin install claude-env-coach@akihidem

Then, from any Claude Code session:

CommandWhat it does
/coach-setupFirst-time setup: create .env from the template, baseline, print the recommended cron lines
/coach-initTake the docs baseline (run once)
/coach-scan [--force]Force a scan now and preview verified proposals (dry-run, nothing delivered)
/coach-statusShow the proposals log + a 7-day activity heartbeat

The plugin does not install the cron schedule for you — the daemon still runs as a background cron job (see below). The commands wrap manual operations and source the plugin's own .env, so configure it via /coach-setup first. Python 3.11+ and pyyaml must be available on the machine running Claude Code.

akihidem/claude-env-coach-kit is the public distribution repo — a clean-history mirror of released versions, synced by scripts/release-kit.sh. Development happens in a private repo. Prefer fully offline? Use the zip kit below — same plugin, no GitHub access required.

Install from the zip kit

The whole tool ships as a self-contained zip, built with git archive so it contains tracked files only — your data/, .env and prompts/user-context.md can never leak into it.

Grab a prebuilt zip from GitHub Releases (a .sha256 file is attached to each release), or build it yourself.

Maintainer side — build & publish:

bash scripts/build-kit.sh    # → dist/claude-env-coach-kit-v<version>.zip
bash scripts/release-kit.sh  # build + sync the tree to the public kit repo + GitHub Release

Recipient side — unzip to a permanent location (the folder is the daemon home: .env, data/ and cron all live there), then pick one:

A. Standalone (cron daemon only):

unzip claude-env-coach-kit-v*.zip && cd claude-env-coach
cp .env.example .env             # fill in notifier / repo settings
python3 coach.py --init          # take the docs baseline
crontab -e                       # add the lines from "Cron layout" below

B. Plugin UX (adds the /coach- commands to Claude Code):*

/plugin marketplace add /absolute/path/to/claude-env-coach
/plugin install claude-env-coach@akihidem
/coach-setup

claude plugin marketplace add accepts a local path, so the unzipped folder doubles as a self-hosting marketplace. /coach-setup prints the resolved plugin root — use that path in your cron lines so the daemon and the slash commands share one .env and one data/.

Requirements on the target machine: Python 3.11+, pyyaml, the Claude Code CLI (claude) for the haiku step, gh + git only if you enable auto-PR.

Usage

First-time baseline

python3 coach.py --init   # fetch all monitored pages and store hashes

Manual run

python3 coach.py --dry-run   # propose if there are diffs, but don't deliver
python3 coach.py             # full path: deliver + auto-PR

Cron layout (recommended)

Each line cds into the repo and sources .env first:

# Hourly: detect doc changes, run pipeline, deliver, optionally open PRs
30 * * * * cd /path/to/claude-env-coach && set -a && . ./.env && set +a && python3 ./coach.py >> ./data/cron.log 2>&1
# Daily 09:00: poll dotclaude PR states and sync proposals-log status
0 9 * * * cd /path/to/claude-env-coach && set -a && . ./.env && set +a && python3 ./coach.py --sync-pr >> ./data/cron.log 2>&1
# Sunday 10:00: verbatim deprecation scan → removal PRs (auto-merge always OFF)
0 10 * * 0 cd /path/to/claude-env-coach && set -a && . ./.env && set +a && python3 ./coach.py --cleanup-scan >> ./data/cron.log 2>&1
# Saturday 12:00: weekly heartbeat summary
0 12 * * 6 cd /path/to/claude-env-coach && set -a && . ./.env && set +a && python3 ./coach.py --heartbeat >> ./data/cron.log 2>&1
# 1st of month 09:00: rotate last month's logs into archive/YYYY-MM/
0 9 1 * * cd /path/to/claude-env-coach && set -a && . ./.env && set +a && python3 ./coach.py --rotate >> ./data/cron.log 2>&1
# (optional) every 5 min: receive /apply・/reject commands from Telegram
*/5 * * * * cd /path/to/claude-env-coach && set -a && . ./.env && set +a && python3 ./coach.py --receive-commands >> ./data/cron.log 2>&1

Manual proposal management

python3 coach.py --list                       # show all proposals + status
python3 coach.py --apply "title-substring"    # mark applied (CLI-only flow)
python3 coach.py --reject "title-substring"   # mark rejected
python3 coach.py --sync-pr                    # poll PR states → sync status
python3 coach.py --cleanup-scan --dry-run     # preview deprecation removal candidates
python3 coach.py --memory-sync [--write]      # write applied proposals back to memory (dry-run by default)
python3 coach.py --worklog-sync [--write]     # upsert active proposals into worklogs (dry-run by default)
python3 coach.py --receive-commands --dry-run # parse pending Telegram commands without applying
python3 coach.py --heartbeat --dry-run        # render the weekly summary to stdout
python3 coach.py --rotate --dry-run           # show what monthly rotate would move

Forking guide (v2.1+)

Minimum setup:

  1. Copy .env.example to .env (or export the same vars in your shell / cron). ENV_COACH_USER_PROJECTS is required if you have multiple cwd-encoded directories under ~/.claude/projects/.
  2. Copy prompts/user-context.md.example to prompts/user-context.md and describe your setup (OS / how you use Claude Code / parallel projects / priorities). The file is gitignored. The contents are inlined into the extractor prompt so the haiku picks proposals specific to your setup.
  3. (Optional) Set ENV_COACH_WEBHOOK_URL to a Slack/Discord incoming webhook for delivery. Empty disables external delivery — data/inbox.md still accumulates.
  4. (Optional) Set ENV_COACH_DOTCLAUDE_REPO=<owner>/<repo> to enable auto-PR. Empty disables it; proposals are still delivered.

Privacy / data flow: the default ENV_COACH_SNAPSHOT_MODE=keys sends only the key structure of settings.json (values are <redacted>) plus the title list of MEMORY.md to the haiku — CLAUDE.md is omitted entirely. Only opt into full mode if you trust the API path with the full contents (this was the v2.0 default and is what akihidem still uses for own runs).

Required external tools: the Claude Code CLI (claude on $PATH) for the haiku step, plus gh for auto-PR. git for branch operations on your dotclaude.

Notifier backends (v2.2)

ENV_COACH_NOTIFIERWhat it does
auto (default)Pick webhook if ENV_COACH_WEBHOOK_URL set, else openclaw if ENV_COACH_TELEGRAM_TARGET set, else none
webhookPOST {"text": ...} (slack), {"content": ...} (discord), or raw text (generic) to ENV_COACH_WEBHOOK_URL. Format via ENV_COACH_WEBHOOK_FORMAT
openclawSend via the openclaw CLI to ENV_COACH_TELEGRAM_TARGET (akihidem's own bridge)
noneSkip; data/inbox.md still accumulates

Watched-doc management

Edit docs.yaml. The sources: list is read on every run (no restart). If the YAML is malformed or missing, coach.py falls back to _FALLBACK_DOCS. Prefer GitHub-raw URLs for noisy pages (e.g. CHANGELOG.md) to avoid HTML normalization drift.

Status & roadmap

VersionHighlights
v1.0two-step prompt: 0% → 100% verify pass on benchmark
v1.1tick-log + weekly heartbeat (cron-down vs docs-static disambiguation)
v1.2monthly archive rotation (load_log reads archive too for dedupe)
v1.3snippet token verify (unverified_tokens warning, catches fabricated keys like sessionFilesRetention)
v2.0auto-PR against dotclaude + --sync-pr for status sync
v2.1env-var configuration / user-context separation / snapshot opt-in
v2.2notifier abstraction / LICENSE / English README / public release
v2.3snippet verify against system command --help output
v2.414→19 monitored sources (Anthropic API / SDK added)
v2.5per-project context + cross-project proposals
v2.6ENV_COACH_AUTO_MERGE auto-squash-merges verified PRs
v2.7two-way Telegram (--receive-commands handles /apply・/reject)
v2.8--cleanup-scan deprecation detection → removal PRs (auto-merge OFF)
v2.9--memory-sync / --worklog-sync write-back
v2.10concept proposals routed to docs/concepts/ PRs
v2.11idle notice after 24h of docs silence (liveness signal)
v2.12Claude Code plugin + distributable zip kit (personal paths removed)

License

MIT © 2026 akihidem.

Contributing

See CONTRIBUTING.md. Bug reports and notifier-backend PRs especially welcome.

Ver o original no GitHub

Bom para

Relacionados