convez.ai
SkillAutomaçãoIntermediário
bizzar0helldemon

Claude Brain Toolkit

bizzar0helldemon/claude-brain-toolkit

Memória persistente com hooks inteligentes para Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Um sistema de memória persistente para Claude Code que captura conhecimento entre sessões através de hooks inteligentes. Mantém um vault pessoal de projetos, padrões e soluções, com detecção de erros, proteção contra comandos perigosos e monitoramento de contexto em tempo real.

Instalação

$npx convez-ai bizzar0helldemon/claude-brain-toolkit

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
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Manter histórico de soluções e padrões entre sessões de código
  • Detectar e reutilizar soluções para erros recorrentes
  • Proteger contra commits acidentais com secrets e comandos perigosos
  • Monitorar uso de contexto e prevenir loops infinitos do agent

Veredito

Ferramenta madura e bem-arquitetada que resolve um problema real: Claude Code sem memória entre sessões. A implementação via hooks é sólida, com proteções de segurança robustas. Recomendado para desenvolvedores que trabalham intensivamente com Claude Code e querem acumular conhecimento reutilizável.

README

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

Claude Brain Toolkit

A persistent knowledge layer for Claude Code. Brain mode gives Claude memory across sessions — it loads your past context at startup, captures what you learn as you work, and surfaces relevant knowledge when you need it.

What It Does

Without brain mode, every Claude Code session starts from zero. With it:

  • Session start: Hooks automatically load your vault context — projects, pitfalls, patterns — into Claude's context window
  • While you work: Error pattern recognition surfaces past solutions. Safety hooks block dangerous commands and secret leaks before they happen. Session guardian monitors context usage and research focus.
  • When you pause: An idle detection hook gently offers to capture useful patterns
  • Session end: A smart stop hook evaluates whether the session produced something worth capturing
  • Statusline: Two-row branded display with brain state, git info, context bar, lines changed, and session duration

Everything runs through Claude Code's hook system. You just work normally.

Quick Start

Prerequisites

Install

git clone https://github.com/bizzar0helldemon/claude-brain-toolkit.git
cd claude-brain-toolkit
bash onboarding-kit/setup.sh

The setup script:

  1. Deploys the brain-mode agent to ~/.claude/agents/
  2. Installs all global skills (15 skills)
  3. Deploys all hook scripts to ~/.claude/hooks/ (9 hooks + 2 libraries)
  4. Registers hooks in ~/.claude/settings.json (idempotent — safe to re-run)
  5. Deploys slash commands and the statusline script
  6. Verifies everything is in place

First Run

claude --agent brain-mode

On first run, BRAIN_PATH won't be set yet. Claude will detect this and offer to run /brain-setup, which walks you through:

  • Choosing a vault directory
  • Creating the directory structure
  • Setting BRAIN_PATH in your shell profile and settings.json

After setup, restart Claude Code and brain mode is active.

How It Works

Hook Architecture

Brain mode uses hooks across 6 event types:

HookEventWhat It Does
session-start.shSessionStartLoads vault context into Claude's context window. Caches for fast /clear reloads.
pre-compact.shPreCompactTriggers capture before context window compaction.
post-tool-use.shPostToolUseDetects git commits and suggests capture.
session-guardian.shPostToolUseMonitors context % (warns at 70%/85%) and detects runaway research loops (5+ reads without writes).
post-tool-use-failure.shPostToolUseFailureMatches errors against stored patterns and surfaces past solutions with adaptive tier responses.
risk-classifier.shPreToolUseBlocks dangerous bash commands (git reset --hard, rm -rf /, chmod 777, etc.).
pre-commit-secrets.shPreToolUseScans staged diffs for API keys, tokens, and private keys before allowing commits.
loop-detector.shPreToolUseCatches agents repeating identical tool calls 5+ times and breaks the loop.
notification-idle.shNotification (idle)Offers to capture when the session has content and the user pauses. One offer per session.

A stop.sh hook is also included for project-level use (smart capture detection at session end) but is not deployed globally.

Safety Hooks (PreToolUse)

Three hooks run before every tool call to prevent common mistakes:

Risk Classifier — hard-blocks destructive commands:

  • git reset --hard, git clean -f, force push to main/master
  • rm -rf on broad paths, chmod 777
  • DROP TABLE, TRUNCATE, DELETE FROM without WHERE
  • Advisory warnings for --no-verify, git checkout .

Pre-Commit Secrets — blocks commits containing:

  • API keys (AWS, GitHub, Anthropic, OpenAI, Stripe, Google, Slack)
  • Private keys (RSA, SSH, PGP), JWT tokens
  • Database connection strings with embedded passwords, .env files

Loop Detector — tracks tool calls in a rolling window and blocks after 5+ identical calls with a diagnostic message.

Session Intelligence

Session Guardian monitors two risks that cause partial achievement:

  • Context exhaustion: Warns at 70% usage, urgently prompts handoff at 85%
  • Runaway research: Flags 5+ consecutive read operations without writes

Run /session-guardian anytime for a status check.

Error Pattern Intelligence

When a command fails, the PostToolUseFailure hook checks your pattern store for matches. Responses adapt:

EncountersResponse
1st timeFull explanation with solution steps
2-4 timesBrief reminder
5+ timesRoot cause investigation flag

Statusline

Two-row branded display with 256-color support:

🧠 Brain │ 📂 my-repo 🌿 main │ 🤖 Opus 4
🟢 captured │ ▓▓▓▓▓▓░░░░ 62% │ +47 -12 │ 📝 3 │ ⏱ 14m

Row 1: Brain branding, repo + branch (with worktree detection), model name Row 2: Brain state, context bar (color-coded), lines changed, dirty files, session duration

Commands

Knowledge Management

CommandWhat It Does
/brain-captureExtract patterns, prompts, and lessons from the current conversation
/brain-graduatePromote learnings with reliability scoring (high/medium/experimental); --auto mode passively extracts learnings from completed work
/daily-noteLog a journal entry to daily_notes/

Quality & Safety

CommandWhat It Does
/pre-pr-scanMulti-agent quality gate — CI compliance, security, logic bugs, commit hygiene
/brain-auditVault health check — stale entries, missing indexes, broken links
/brain-investigateStructured debugging with 3-level diagnostic (EXISTS → SUBSTANTIVE → WIRED)

Session & Ops

CommandWhat It Does
/session-guardianCheck session health — context usage, read/write ratio, risk assessment
/daily-syncFast operational snapshot — vault health, git state, drift detection, priorities
/brain-handoffSession continuity document — accomplished, in-progress, blockers, decisions
/brain-evolveSelf-improvement cycle — 3 auditor agents, 5-axis scoring, inline proposal review

Workflow

CommandWhat It Does
/brain-shipShip completed work — push branch, create PR, update Linear, log to vault
/brain-ticketCreate work tickets in Linear from backlog
/brain-linear-syncSync Linear tickets with brain vault
/brain-add-patternAdd an error pattern and solution to the pattern store
/brain-setupFirst-time onboarding wizard
/brain-relocateMove your vault to a new path

Play

CommandWhat It Does
/brain-gameGame night — AI Fluency games (riddles, crosswords, RPG) and resumable quest campaigns

Vault Structure

Your vault lives at $BRAIN_PATH — wherever you choose during setup:

$BRAIN_PATH/
  learnings/             # Graduated knowledge with reliability scores
  prompts/               # Prompt and pattern library
  projects/              # Project summaries by category
  investigations/        # Structured debugging investigations
  handoffs/              # Session continuity documents
  daily_notes/           # Daily journal entries
  evolution/             # Self-improvement proposals and synthesis
    proposals/           # EVO-*.md scored proposals
    synthesis/           # SYNTH-*.md cycle summaries
  brain-mode/
    pattern-store.json   # Error patterns and solutions
  .brain-state           # Current hook state (idle/captured/error)
  .brain-session-metrics.json  # Session guardian tracking
  .brain-cached-context.json   # Cached context for fast /clear
  .brain-errors.log      # Hook error log

The vault is Obsidian-compatible but doesn't require Obsidian.

Configuration

Brain mode needs one environment variable:

export BRAIN_PATH="/path/to/your/vault"

This is set in two places (both are needed):

  1. Shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile) — for interactive terminal use
  2. ~/.claude/settings.json under "env" — for hook subprocesses (which don't load shell profiles)

The /brain-setup wizard handles both.

Project Structure

claude-brain-toolkit/
  agents/
    brain-mode.md               # Agent definition
  hooks/
    session-start.sh            # SessionStart — vault context loading
    pre-compact.sh              # PreCompact — capture suggestion
    post-tool-use.sh            # PostToolUse — git commit detection
    post-tool-use-failure.sh    # PostToolUseFailure — error patterns
    notification-idle.sh        # Notification — idle capture offer
    session-guardian.sh         # PostToolUse — context & focus monitoring
    risk-classifier.sh          # PreToolUse — dangerous command blocking
    pre-commit-secrets.sh       # PreToolUse — secret leak prevention
    loop-detector.sh            # PreToolUse — repeated call detection
    stop.sh                     # Stop — project-level capture (not global)
    lib/
      brain-path.sh             # Shared utilities
      brain-context.sh          # Vault context builder
  global-skills/
    brain-capture/              # Pattern extraction
    brain-graduate/             # Knowledge graduation (manual + --auto passive extraction)
    brain-investigate/          # Structured debugging
    brain-audit/                # Vault health check
    brain-evolve/               # Self-improvement cycle
    brain-handoff/              # Session continuity
    brain-ship/                 # PR shipping + Linear
    brain-ticket/               # Linear ticket creation
    brain-linear-sync/          # Linear sync
    session-guardian/            # Context & focus protection
    daily-sync/                 # Operational snapshot
    pre-pr-scan/                # Multi-agent quality gate
    brain-game/                 # Game night + quest campaigns
    daily-note/                 # Journal entries
  commands/
    brain-add-pattern.md        # Error pattern management
    brain-relocate.md           # Vault relocation
  onboarding-kit/
    setup.sh                    # Automated installer
    skills/                     # Onboarding-only skills
  settings.json                 # Template settings
  statusline.sh                 # Two-row branded statusline
  frameworks/                   # AI Fluency Framework reference

Developing

If you're working on the toolkit itself:

  1. Clone the repo
  2. Create a CLAUDE.local.md (gitignored) with your real BRAIN_PATH
  3. Run bash onboarding-kit/setup.sh after changes to deploy to ~/.claude/

Changes to hook scripts in the repo don't take effect until deployed — the running hooks are the copies in ~/.claude/hooks/.

License

MIT. See LICENSE.

AI Fluency Framework content adapted from Dakan & Feller (CC BY-NC-ND 4.0). See frameworks/ai-fluency-framework.md for full attribution.

Ver o original no GitHub

Bom para

Relacionados