togi (研ぎ)
Sharpen AI context docs through friction.
Togi is a Claude Code plugin that captures the moments when an AI coding agent stumbles — corrections, clarifications, wrong assumptions, denied tool calls — and turns them into context-doc improvements via pull requests.
Each stumble is a friction event: a signal that the shared context docs failed. Togi captures them in-session as they happen, accumulates them silently, and reminds the developer who hits the threshold to process them. Processing means editing the docs that caused the friction, so the same mistake doesn't recur — and the fix lands as a pull request the whole team reviews.
How it works
you work → model hits friction → writes a note to .togi/friction/pending/ (denied tool calls: recorded by a hook)
↓
a Stop hook keeps the capture directive salient as context grows
↓
next session start → session-start.sh → "12 friction events. Update the docs."
↓
developer runs /togi:update-context-docs → docs edited → PR opened
↓
PR merged → agent reads better docs → fewer stumbles next session
Requirements
- macOS or Linux
- Claude Code
- jq on PATH
- A way for Claude to open pull requests on your behalf — the
gh CLI (authenticated with gh auth login), a GitHub MCP server, or the GitHub HTTP API with a token
Install
Togi is distributed as a Claude Code plugin marketplace — no cloning or file editing. In Claude Code:
/plugin marketplace add gwenneg/togi
/plugin install togi@togi
/reload-plugins
/togi:setup
/togi:setup explains what togi does, commits an inert adoption note as a reviewable PR (nothing executable — see Team adoption), and offers to enable capture for you.
Togi is dormant by default: TOGI_ENABLED defaults to 0, so the hooks stay inert and no directive is delivered — nothing is captured until you opt in. A user-scope install (Claude Code's default) therefore stays silent in every repo where you haven't enabled it.
Usage
Enable / disable capture — opt-in is per developer, at your choice of scope (this repo, or all your repos), and never committed:
/togi:enable # turn on friction capture
/togi:disable # turn it back off
Process accumulated friction — when enough events pile up, a startup reminder appears. Run:
/togi:update-context-docs
The skill groups events by root cause, proposes which docs to fix, flags recurrences (fixes that didn't take), lets you exclude noise, edits the docs, and opens a PR with a friction-metrics summary.
Configuration
TOGI_ENABLED is set per developer by /togi:enable in .claude/settings.json (global) or .claude/settings.local.json (this repo); TOGI_EVENT_THRESHOLD can be set in either.
| Variable | Default | Description |
|---|
TOGI_ENABLED | 0 | The only switch, off by default. 1 activates the capture hooks (the Stop-refresh and the denial recorder). A repo-local 0 overrides a global 1. |
TOGI_EVENT_THRESHOLD | 10 | Friction events before the startup reminder appears. |
Cost
Effectively free. Capture runs inside your normal Claude Code session — the working model writes a short note when it hits friction, and a local hook records denied tool calls — so there is no separate API call and no meaningful added cost. (togi's original design used a billed end-of-session sweep; that is now a documented alternative, not the implementation. See why inline capture.)
Privacy & safety
Everything stays on your machine. Friction notes are written locally under .togi/friction/ (git-ignored) and nothing is sent to any third party — capture happens in your own session under your own credentials. The capture directive ships in the plugin (assets/prompts/friction-capture.md) as plain, readable instructions, delivered into your session only when you've enabled togi; denied tool calls are recorded by a hook with no model involved. Doc edits never happen automatically — they only land through /togi:update-context-docs, which you review before it opens a PR. See Privacy & security.
Staying up to date
Auto-update is off and Claude Code sends no new-version notification — watch this repo → Releases only. To update (plugin docs):
