brain-bootstrap

claude-brain

A portable Claude Code "brain" — three lightweight conventions you can drop into any project so Claude has consistent structural awareness, durable memory, and a place to capture work-in-flight.

The trifecta

Pillar	What it answers	Where it lives	Plugin
Awareness	"What tooling exists in this project?"	.claude/AWARENESS.md (auto-generated)	awareness
Memory	"What do I know about this user / project?"	~/.claude/projects/<slug>/memory/ (harness-native)	no plugin — built in
Backlog	"What's left to do here?"	backlog.md in the repo	backlog

Plus a bootstrap plugin (brain-bootstrap) with a single /brain-init that drops the scaffolding into a fresh project.

Each plugin is independently togglable — pick whichever ones you want per project.

Why three things, not one?

They answer different questions and have different lifecycles:

• Awareness is regenerated from files. Throwaway and recomputable.
• Memory is durable across conversations. Hand-curated by Claude as it learns.
• Backlog is explicit, version-controlled, you-edit-it.

Mixing them is what makes most "AI scratchpad" setups rot. Keeping them separate keeps each one tidy.

Memory itself is built into Claude Code — this repo just teaches Claude how to use it well via the CLAUDE.md fragment that brain-bootstrap drops.

Install

/plugin marketplace add ChrisonSimtian/claude-brain
/plugin install awareness@claude-brain
/plugin install backlog@claude-brain
/plugin install brain-bootstrap@claude-brain

(Or pick whichever subset you want. They have no inter-dependencies.)

Use

In a fresh project:

/brain-init             # one-shot scaffolding
/refresh-awareness      # populate AWARENESS.md
/backlog-add Wire up Service Bus retry classification
/backlog-status

In an existing project: install whichever plugins you want; they discover files automatically.

Repo layout

claude-brain/
├── .claude-plugin/
│   └── marketplace.json     ← lists the three plugins
└── plugins/
    ├── awareness/
    │   ├── .claude-plugin/plugin.json
    │   ├── commands/refresh-awareness.md
    │   ├── scripts/update-awareness.ps1
    │   └── README.md
    ├── backlog/
    │   ├── .claude-plugin/plugin.json
    │   ├── commands/{backlog-add,backlog-status}.md
    │   ├── skills/backlog/SKILL.md
    │   ├── templates/backlog.template.md
    │   └── README.md
    └── brain-bootstrap/
        ├── .claude-plugin/plugin.json
        ├── commands/brain-init.md
        ├── skills/brain-init/SKILL.md
        ├── templates/{AWARENESS.md,backlog.template.md,CLAUDE.fragment.md}
        └── README.md

Requirements

• Claude Code with plugin support
• PowerShell 7+ (pwsh) on PATH for the awareness script. Cross-platform — works on Windows and macOS.

Bonus — Wave terminal badges (not a plugin)

If you use the Wave terminal you can get little status icons on the tab while Claude is running: a green tick when it finishes, a yellow bell when it's waiting on a permission prompt, a yellow ? when it's asking a question. This is not part of any plugin — it's just three hooks in ~/.claude/settings.json. Snippets:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "wsh badge check --color '#58c142' --priority 10", "timeout": 5 }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "wsh badge bell-exclamation --color '#e0b956' --priority 20 --beep", "timeout": 5 }
        ]
      },
      {
        "matcher": "elicitation_dialog",
        "hooks": [
          { "type": "command", "command": "wsh badge message-question --color '#e0b956' --priority 20", "timeout": 5 }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "AskUserQuestion",
        "hooks": [
          { "type": "command", "command": "wsh badge message-question --color '#e0b956' --priority 20", "timeout": 5 }
        ]
      }
    ]
  }
}

Requires wsh (Wave's CLI) on PATH. Outside Wave the hooks just fail silently — no harm, but no badges either.

Origin

Extracted from Chris Simon's MyFoodBag workspace, where the awareness/backlog/memory conventions co-evolved over months. The MFB-specific defaults (doc section names like Patterns, Operational, Migrations) have been stripped — the awareness script now auto-discovers whatever doc subdirectories your project happens to use.

License

MIT.