[Resource]: shared-brain (brain guard)

[yurukusa]

Display Name

shared-brain (brain guard)

Category

Tooling

Sub-Category

Tooling: Usage Monitors

Primary Link

https://github.com/yurukusa/shared-brain

Author Name

yurukusa

Author Link

https://github.com/yurukusa

License

MIT

Other License

No response

Description

shared-brain is a CLI tool that turns lessons into code and checks risky commands before execution.
It matches commands against a YAML lesson library and shows a checklist when a match is found. It can
be installed as a Claude Code PreToolUse hook to reduce repeated mistakes.

Validate Claims

1. Install:
   pip install shared-brain

2. Create a lesson file (YAML) and add a trigger for a risky operation, e.g. curl PUT:
   ~/.brain/lessons/api-put-safety.yaml

3. Run a guard check:
   brain guard "curl -X PUT https://api.example.com/articles/123"

Expected result:

• brain guard prints the lesson text + checklist, and asks for explicit confirmation before
  proceeding.

(Optional: Claude Code integration)

• Install as a PreToolUse hook and run the same command inside Claude Code:
  brain hook install

Specific Task(s)

Install shared-brain, add a lesson that triggers on curl PUT, then run brain guard against a sample
PUT command and confirm it shows the checklist and requires acknowledgment.

Specific Prompt(s)

1. Install shared-brain.
2. Create a new lesson YAML in ~/.brain/lessons/ that triggers on "curl.*-X PUT" and includes a
   checklist "GET current state", "PUT full body", "verify result".
3. Run: brain guard "curl -X PUT https://api.example.com/articles/123"
4. Show the output and explain how this prevents repeating the same mistake.

Additional Comments

This tool does not perform network requests by itself; it only inspects the command string you are
about to run. Any network access depends on the user’s command (e.g., curl). It is designed to
prevent repeated operational mistakes by forcing a checklist at execution time.

Recommendation Checklist

• I have checked that this resource hasn't already been submitted
• My resource provides genuine value to Claude Code users, and any risks are clearly stated
• All provided links are working and publicly accessible
• I am submitting only ONE resource in this issue
• I understand that low-quality or duplicate submissions may be rejected

[github-actions]

🤖 Validation Results

✅ All validation checks passed!

Your submission is ready for review by a maintainer.

Validated Data:

{
  "display_name": "shared-brain (brain guard)",
  "category": "Tooling",
  "subcategory": "Usage Monitors",
  "primary_link": "https://github.com/yurukusa/shared-brain",
  "author_name": "yurukusa",
  "author_link": "https://github.com/yurukusa",
  "license": "MIT",
  "description": "shared-brain is a CLI tool that turns lessons into code and checks risky commands before execution.\n  It matches commands against a YAML lesson library and shows a checklist when a match is found. It can\n  be installed as a Claude Code PreToolUse hook to reduce repeated mistakes.",
  "secondary_link": "",
  "last_modified": "2026-02-14:14-08-08",
  "active": "TRUE",
  "last_checked": "2026-02-15:02-25-49"
}

---

_{This comment is automatically updated when you edit the issue.}

[hesreallyhim]

Thanks @yurukusa this is a nice design and implementation although I'm not sure I see the full value-add above setting up hooks and documenting rules in CLAUDE.md files. Do you have any evidence that these reminders are effective in steering the agent's behavior within a session? Like after they try it once they are significantly less likely to try it again? (Maybe this shows up in the thinking logs) Other concern is it strikes me that since Claude is doing the checklist and Claude is being naughty or forgetful maybe it will just fake the checklist or forget whether it did whatever the checklist is asking. In other words it's still kind of a "trust-Claude" based model just with guardrails. And I suppose the accumulation of "lessons" may be a nice bonus. What if you have a LOT of lessons and/or their targets are broad? I could see a risk of sending a hook with a very long message to Claude.

[yurukusa]

Great questions, thanks for the thoughtful review!

1. Value-add over hooks + CLAUDE.md:

The key difference is timing and enforcement. CLAUDE.md is loaded once at session start and can drift from working memory as context fills up. shared-brain hooks fire at PostToolUse time — every time a file is saved — so they catch the exact moment an error is introduced. Think of it like the difference between a "please drive safely" sign vs. ABS brakes.

2. Evidence:

Anecdotally in our daily sessions, we've seen two patterns:

• PostToolUse syntax checks (python -m py_compile) catch errors at write time that would otherwise only surface later during testing. Without the hook, the agent tends to move on and compound the problem
• The lesson-learning loop helps with repeat mistakes — e.g., after recording "Qiita API requires PowerShell from WSL2," we stopped seeing raw curl attempts for that API in subsequent sessions

This is observational rather than rigorous A/B testing, but the before/after difference in our workflow has been noticeable enough to keep using it.

3. "Faking" the checklist:

You're right that it's still Claude running the check. Two mitigations:

• For critical checks (syntax, secrets), the hook runs external tools (python -m py_compile, grep -r API_KEY), not Claude's self-assessment. Claude can't fake a compiler error
• The guard layer runs in the shell hook context, separate from the agent's reasoning. It's closer to CI/CD than self-review

4. Lesson accumulation:

Valid concern. In practice:

• Lessons are stored per-project in separate topic files (not one giant blob)
• We keep the main memory file short as an operational guideline and move details to topic-specific files
• Hook messages are typically 1-3 lines ("Did you check X?"), not the full lesson database
• The accumulation is self-limiting because broad/vague lessons get overwritten by specific ones

The honest answer is that it's a "trust-but-verify" model — Claude does the reasoning, but hooks provide external checkpoints that can't be bypassed.

[yurukusa]

Thanks for the detailed feedback — really appreciated the thoughtful review even if it didn't make the cut!

[yurukusa]

Thanks for the detailed feedback and the thoughtful review. For what it's worth — the problem this tool addresses (Claude forgetting rules after context compaction) is very real in daily use. CLAUDE.md alone doesn't survive a compaction. But I understand it may not fit the scope of this list. Appreciate your time!