claude-teams-brain 1.5.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "claude-teams-brain",
+  "version": "1.5.1",
+  "description": "Persistent cross-session memory for Agent Teams. Automatically indexes teammate outputs, decisions, and file changes — then injects role-specific context into each new teammate so your team never starts blind.",
+  "author": {
+    "name": "claude-teams-brain contributors",
+    "url": "https://github.com/Gr122lyBr/claude-teams-brain"
+  },
+  "homepage": "https://github.com/Gr122lyBr/claude-teams-brain",
+  "repository": "https://github.com/Gr122lyBr/claude-teams-brain",
+  "license": "MIT",
+  "keywords": ["agent-teams", "memory", "context", "persistence", "multi-agent", "mcp", "token-optimization", "ai-agents", "sqlite", "claude-code"],
+  "mcpServers": {
+    "claude-teams-brain": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/start.mjs"]
+    }
+  },
+  "skills": "./skills/",
+  "commands": "./commands/"
+}

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.1.0] - 2026-03-10
+
+### Added
+- **Cross-platform Python hook runner** (`hook_runner.py`) — replaces all bash scripts; works natively on macOS, Linux, WSL2, and Windows. Requires only Python 3.8+ (already a dependency). No WSL2 required on macOS
+- **Solo mode** — memory now builds even without Agent Teams enabled. Previous session context is injected into the main Claude instance at every `SessionStart`. Solo mode is now a first-class supported workflow
+- **`/brain-seed <profile>`** — instantly seed the brain with pre-built stack conventions. Five built-in profiles: `nextjs-prisma`, `fastapi`, `go-microservices`, `react-native`, `python-general`. Accepts custom JSON profile files
+- **`/brain-replay [run-id]`** — time-travel through any past session as a chronological Markdown narrative: timeline of tasks, decisions, files touched, and session summary. Use `latest` for the most recent run
+- **`/brain-github-export`** — export CONVENTIONS.md and open a GitHub Pull Request via `gh` CLI. Includes reusable GitHub Actions workflow template (`profiles/github-actions-conventions.yml`) for automatic PR creation after every session
+- Auto-seed from existing `.cursorrules`, `AGENTS.md`, and `CONVENTIONS.md` files at session warm-up (zero-config onboarding)
+- New `brain_engine.py` commands: `replay-run`, `seed-profile`, `list-profiles`
+
+### Changed
+- All hooks now use `python3 hook_runner.py <event>` instead of bash — identical behaviour, all platforms
+- Session start message distinguishes solo mode from Agent Teams mode with appropriate messaging
+- Agent Teams env var absence no longer shows a warning — replaced with a friendly "solo mode active" tip
+
+## [1.0.4] - 2026-03-10
+
+### Added
+- Agent Teams env var check on SessionStart — warns if `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is not set
+- TaskCompleted confirmation — shows `🧠 Indexed: [agent] task` so users see the brain capturing work in real time
+- `/brain-search <query>` — search the full brain knowledge base directly from conversation
+- `/brain-stats` — full stats summary: persistent memory + session KB
+
+### Improved
+- SessionStart status now shows decisions count alongside tasks and sessions
+
+## [1.0.3] - 2026-03-10
+
+### Added
+- Smart context pruning: memories ranked by relevance to the current task description
+- Command result caching in batch_execute (60s TTL) — identical commands served from cache
+- Session warm-up: CLAUDE.md, git log, directory tree, and config files indexed at SessionStart
+- Cache hit counter in stats output
+
+### Improved
+- Deduplication of decisions and files before context injection
+- Large command output auto-summarized before indexing (keeps KB lean)
+
+## [1.0.2] - 2026-03-10
+
+### Added
+- `/brain-remember <text>` — manually store rules and conventions that get injected into every future teammate
+- `/brain-forget <text>` — remove a manually stored memory by partial text match
+- `/brain-export` — distill all accumulated brain knowledge into a committable `CONVENTIONS.md` file
+- Manual memories shown as "Project Rules & Conventions" section in teammate context (before team decisions)
+
+## [1.0.1] - 2026-03-10
+
+### Added
+- `/brain-update` skill — pull the latest version from GitHub without reinstalling
+- Version check on `SessionStart` — non-intrusive hint when a new version is available
+- Token-efficient tool guidance injected into every subagent on spawn (`batch_execute`, `search`, `execute`, `index`)
+- Skill files for all user commands: `brain-status`, `brain-query`, `brain-runs`, `brain-clear`
+- First-run welcome message on cold start (empty brain)
+- `SECURITY.md` with vulnerability reporting process
+- GitHub Actions CI — validates JSON, lints shell scripts, checks Python syntax, enforces version consistency
+
+### Fixed
+- `marketplace.json` source path corrected to `./claude-teams-brain`
+
+## [1.0.0] - 2026-02-10
+
+### Added
+
+- Persistent memory system for Claude Code Agent Teams
+- SQLite brain engine with FTS5 full-text search (`brain_engine.py`)
+- 6 lifecycle hooks: SessionStart, SubagentStart, TaskCompleted, SubagentStop, TeammateIdle, SessionEnd
+- Auto-injection of context from past sessions into agent conversations
+- 4 user commands: `brain-status`, `brain-query`, `brain-runs`, `brain-clear`
+- Semantic memory organization by topic
+- Claude Code marketplace plugin integration
+- Configurable settings via `settings.json`

package/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to Claude Teams Brain
+
+Thank you for your interest in contributing. This guide covers how to get involved.
+
+## Bug Reports
+
+Open an issue with:
+
+- A clear, descriptive title
+- Steps to reproduce the problem
+- Expected vs actual behavior
+- Your environment (OS, shell, Claude Code version)
+
+## Feature Requests
+
+Open an issue describing:
+
+- The problem your feature would solve
+- Your proposed solution
+- Any alternatives you considered
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Make your changes
+4. Commit with a clear message (see Commit Messages below)
+5. Push to your fork and open a pull request
+
+Keep PRs focused on a single change. Include a description of what changed and why.
+
+## Code Style
+
+- **Python**: Follow PEP 8. Run a linter before submitting.
+- **Shell scripts**: Write shellcheck-compatible scripts. Use `set -euo pipefail` where appropriate.
+
+## Development Setup
+
+1. Clone the repo and install the plugin locally:
+   ```bash
+   git clone https://github.com/Gr122lyBr/claude-teams-brain
+   # In Claude Code:
+   /plugin marketplace add /path/to/clone
+   /plugin install claude-teams-brain@claude-teams-brain
+   ```
+2. Make changes to scripts or the MCP server, then reload Claude Code.
+3. Inspect the brain database at any time:
+   ```bash
+   sqlite3 ~/.claude-teams-brain/projects/<hash>/brain.db ".tables"
+   ```
+4. Test the brain engine directly:
+   ```bash
+   python3 scripts/brain_engine.py status /your/project/path
+   python3 scripts/brain_engine.py query-role backend /your/project/path
+   ```
+
+**Requirements:** Python 3.8+, Node.js 18+, Claude Code v2.1+
+
+## Testing
+
+The project does not yet have an automated test suite. When adding new functionality, manually verify using the steps above and check brain output with `/claude-teams-brain:brain-status`.
+
+## Commit Messages
+
+Use the imperative mood in the subject line (e.g., "Add feature" not "Added feature"). Keep the subject under 72 characters. Use the body to explain what and why, not how.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 Shay Tal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+<p align="center">
+  <img src="assets/logo.png" alt="claude-teams-brain" width="120" />
+</p>
+
+# claude-teams-brain
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)
+[![Node](https://img.shields.io/badge/node-18%2B-green.svg)](https://nodejs.org)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-orange.svg)](https://claude.ai/claude-code)
+
+**Persistent cross-session memory for Claude Code Agent Teams.**
+
+Claude Code's Agent Teams are powerful — but ephemeral. Every teammate spawns with a blank slate. Every session forgets what the last one built. claude-teams-brain fixes this by automatically indexing everything your team produces and injecting role-specific memory into every new teammate the moment they spawn.
+
+Your AI team gets smarter with every session. No extra prompting. No manual context copying. No more starting from zero.
+
+---
+
+## Why this matters
+
+Agent Teams introduced true multi-agent parallelism to Claude Code — teammates that communicate directly, own separate file scopes, and collaborate without a single-session bottleneck. But they have one fundamental weakness:
+
+> *Teammates exist for the duration of a session and then they're gone. No persistent identity, no memory across sessions, no `/resume`.*
+
+This creates a compounding problem on real projects. Your backend agent spent two hours establishing architecture decisions, learning your conventions, and building the auth system. Tomorrow, a new backend agent spawns and rediscovers everything from scratch — making inconsistent decisions, touching files already settled, asking questions already answered.
+
+claude-teams-brain solves this at the infrastructure level. It hooks into the Agent Teams lifecycle, indexes every task completion, file change, and architectural decision, and injects the relevant history directly into each new teammate's context before they write a single line of code.
+
+---
+
+## How it works
+
+claude-teams-brain hooks into six lifecycle events:
+
+| Hook | What happens |
+|------|-------------|
+| `SessionStart` | Brain initializes, reports how much memory exists for this project |
+| `SubagentStart` | ⭐ Role-specific memory injected directly into each new teammate |
+| `TaskCompleted` | Task subject and agent identity indexed immediately on completion |
+| `SubagentStop` | Rich indexing: files touched, decisions made, output summary extracted from transcript |
+| `TeammateIdle` | Passive checkpoint |
+| `SessionEnd` | Full session compressed into a summary entry |
+
+The `SubagentStart` hook is the core mechanism. When a teammate named `backend` spawns, the brain queries everything the backend agent has done across all past sessions — tasks completed, files owned, decisions made — and injects it as context before the agent processes its first message. The teammate starts informed, not blank.
+
+All data lives in `~/.claude-teams-brain/projects/<project-hash>/brain.db` — a local SQLite database. Nothing is sent anywhere. No external dependencies beyond Python 3.8+ stdlib.
+
+---
+
+## MCP Tools
+
+claude-teams-brain includes an MCP server that exposes five tools to all Task subagents. These tools keep large command output out of context windows by indexing it into a session knowledge base and returning only relevant search results.
+
+### batch_execute
+
+Run multiple shell commands, auto-index all output, and search with queries in a single call.
+
+```json
+{
+  "commands": [
+    {"label": "git log", "command": "git log --oneline -20"},
+    {"label": "test results", "command": "npm test 2>&1"}
+  ],
+  "queries": ["recent commits about auth", "failing tests"],
+  "timeout": 60000
+}
+```
+
+### search
+
+Search the session knowledge base built by previous batch_execute or index calls.
+
+```json
+{
+  "queries": ["authentication middleware", "error handling patterns"],
+  "limit": 3
+}
+```
+
+### index
+
+Manually index content (findings, analysis, data) for later retrieval.
+
+```json
+{
+  "content": "The auth module uses RS256 JWT tokens with 15-minute expiry...",
+  "source": "auth-analysis"
+}
+```
+
+### execute
+
+Run code in a sandboxed subprocess. Set `intent` to auto-index and search large output.
+
+```json
+{
+  "language": "python",
+  "code": "import ast; print(ast.dump(ast.parse(open('main.py').read())))",
+  "timeout": 30000,
+  "intent": "find all class definitions"
+}
+```
+
+Supported languages: `shell`, `javascript`, `python`.
+
+### stats
+
+Show session context savings metrics.
+
+```json
+{}
+```
+
+Returns bytes indexed vs bytes returned, call counts, and context savings ratio.
+
+---
+
+## Installation
+
+**Requirements:** Python 3.8+, Node.js 18+, Claude Code v2.1+
+
+### 1. Install the plugin
+
+In Claude Code, run:
+
+```
+/plugin marketplace add https://github.com/Gr122lyBr/claude-teams-brain
+/plugin install claude-teams-brain@claude-teams-brain
+```
+
+### 2. Enable Agent Teams
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+If `settings.json` already has content, merge the `env` block:
+
+```json
+{
+  "someExistingSetting": true,
+  "env": {
+    "YOUR_EXISTING_VAR": "value",
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+
+Restart Claude Code after saving.
+
+### 3. Configure CLAUDE.md (recommended)
+
+Add to your project's `CLAUDE.md` to make Claude automatically use Agent Teams:
+
+```markdown
+## Agent Teams
+
+Always use agent teams for tasks that can be parallelized across concerns.
+Spawn specialized teammates with role-specific names rather than doing everything
+in a single session. Good team structures:
+
+- Feature work: `backend`, `frontend`, `tests`
+- Reviews: `security`, `performance`, `coverage`  
+- Architecture: `architect`, `devil-advocate`, `implementer`
+- Debugging: name teammates after the hypothesis they're testing
+
+The claude-teams-brain plugin is active — each teammate will automatically receive
+memory from past sessions relevant to their role.
+```
+
+---
+
+## Usage
+
+Once installed, the brain works silently in the background. Just use Agent Teams normally.
+
+**First session (cold start):**
+```
+You: Create an agent team to build the payments module.
+     backend: API endpoints and business logic
+     database: schema and migrations
+     tests: integration test coverage
+
+[Agent Teams session runs — claude-teams-brain indexes everything]
+```
+
+**Second session (warm start):**
+```
+You: Create an agent team to add webhook support to payments.
+     backend: extend the existing payment API
+
+[backend agent spawns and immediately receives:]
+  "## 🧠 claude-teams-brain: Memory for role [backend]
+   
+   ### Your Past Work
+   - Built payment API endpoints in /src/payments/api.ts
+   - Implemented idempotency key validation middleware
+   
+   ### Key Team Decisions
+   - [database] Using UUID v7 for all payment record IDs
+   - [backend] Chose RS256 over HS256 for JWT — better key rotation
+   - [backend] All payment endpoints require idempotency keys
+   
+   ### Files You Own
+   - /src/payments/api.ts
+   - /src/payments/middleware/idempotency.ts"
+```
+
+The teammate starts with full context from day one.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/claude-teams-brain:brain-status` | Memory stats for this project |
+| `/claude-teams-brain:brain-query <role>` | Preview the context a new teammate would receive |
+| `/claude-teams-brain:brain-runs` | List past Agent Team sessions |
+| `/claude-teams-brain:brain-clear` | Reset all memory for this project |
+
+---
+
+## Project structure
+
+```
+claude-teams-brain/                    ← repo root (marketplace)
+  .claude-plugin/
+    marketplace.json
+  claude-teams-brain/                  ← the plugin
+    .claude-plugin/
+      plugin.json
+    hooks/
+      hooks.json                       ← 6 lifecycle hooks
+    scripts/
+      brain_engine.py                  ← SQLite engine (pure stdlib)
+      on-session-start.sh
+      on-subagent-start.sh             ← core: injects memory into teammates
+      on-subagent-stop.sh              ← rich indexing from transcript
+      on-task-completed.sh
+      on-teammate-idle.sh
+      on-session-end.sh
+    commands/                          ← /brain-* slash commands
+    skills/claude-teams-brain/          ← auto-activates for agent team workflows
+    settings.json                      ← enables CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
+```
+
+---
+
+## Memory storage
+
+```
+~/.claude-teams-brain/
+  └── projects/
+      └── <project-hash>/
+          └── brain.db    ← SQLite, one file per project
+```
+
+Each project has its own isolated brain. Memory never crosses project boundaries. The SQLite file is fully inspectable with any database viewer.
+
+---
+
+## Tips
+
+- **Use descriptive agent names** that match their role (`backend`, `database`, `security`) — the brain routes memory by role name
+- **Memory compounds** — the first session is cold, but quality improves significantly from the second session onwards
+- **Check `/claude-teams-brain:brain-status`** before starting a large session to confirm memory is available
+- **Run `/claude-teams-brain:brain-query backend`** to preview exactly what context the backend agent will receive before spawning
+
+---
+
+## License
+
+MIT