brainclaw 0.19.2

package/LICENSE

@@ -0,0 +1,74 @@
+Business Source License 1.1
+
+Licensor:             Juan Berdah
+Licensed Work:        brainclaw
+                      The Licensed Work is (c) 2024-2026 Juan Berdah
+Change Date:          Four years from the release date of each version
+Change License:       MIT License
+
+For information about alternative licensing arrangements, contact the Licensor.
+
+---
+
+Parameters
+
+Licensor:             Juan Berdah
+Licensed Work:        brainclaw
+Additional Use Grant: You may make production use of the Licensed Work, including use
+                      for internal business operations, provided that you do not use the
+                      Licensed Work to build or offer a competing product or service that
+                      provides shared agent memory, coordination, or context management
+                      for coding agents or development teams.
+Change Date:          Four years after the release date of each version
+Change License:       MIT License
+
+---
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open Source
+license. However, the Licensed Work will eventually be made available under an Open
+Source License, as stated in this License.
+
+Use Limitation: The additional use grant in the Parameters specifies the permitted
+production use. If your use case falls outside that grant, you need a separate
+commercial license from the Licensor.
+
+License text
+
+The Licensor hereby grants you the right to copy, modify, create derivative works,
+redistribute, and make non-production use of the Licensed Work. The Licensor may
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly available
+distribution of a specific version of the Licensed Work under this License, whichever
+comes first, the Licensor hereby grants you rights under the terms of the Change
+License, and the rights granted in the paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently in
+effect as described in this License, you must purchase a commercial license from the
+Licensor, its affiliated entities, or authorized resellers, or you must refrain from
+using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of the
+Licensed Work, are subject to this License. This License applies separately for each
+version of the Licensed Work and the Change Date may vary for each version of the
+Licensed Work released by the licensor.
+
+You must conspicuously display this License on each original or modified copy of the
+Licensed Work. If you receive the Licensed Work in original or modified form from a
+third party, the terms and conditions set forth in this License apply to your use of
+that work.
+
+Any use of the Licensed Work in violation of this License will automatically terminate
+your rights under this License for the current and all future versions of the Licensed
+Work.
+
+This License does not grant you any right in any trademark or logo of Licensor or its
+affiliates (provided that you may use a trademark or logo of Licensor as expressly
+required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS
+IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR
+IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.

package/README.md

@@ -0,0 +1,226 @@
+<p align="center">
+  <img src="docs/assets/logo.png" alt="brainclaw" width="140" />
+</p>
+
+<h1 align="center">brainclaw</h1>
+
+<p align="center"><strong>Local-first coordination for humans and coding agents.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/jberdah/brainclaw/actions/workflows/ci.yml"><img src="https://github.com/jberdah/brainclaw/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+</p>
+
+---
+
+brainclaw gives a workspace a shared coordination layer: project memory, explicit plans, file claims, handoffs, layered instructions, and prompt-ready context — stored locally, versioned in Git, readable in plain text.
+
+It sits alongside Copilot, Claude Code, Cursor, Codex, Windsurf, OpenCode, Antigravity/Gemini CLI and any other coding agent. It does not replace them. It helps them work together.
+
+---
+
+## Why brainclaw exists
+
+Coding agents are getting better at local code generation, but they still struggle with shared project state.
+Across real projects, agents often miss active constraints, forget known traps, duplicate work, step on the same files, and lose context between sessions.
+
+brainclaw solves this by giving the workspace a shared coordination layer that both humans and agents can read and update.
+
+---
+
+## What it provides
+
+| | |
+|---|---|
+| **Project memory** | constraints, decisions, traps, handoffs, layered instructions |
+| **Coordination state** | shared plans, file claims, handoffs, runtime notes, board views |
+| **Agent-ready context** | compact, prompt-sized context generated from real workspace state |
+| **Native agent files** | auto-writes `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`, etc. |
+| **Local-first storage** | plain text + JSON, Git-friendly, no cloud, no telemetry |
+
+---
+
+## Works With
+
+brainclaw is designed to sit alongside the coding agents teams are already using.
+
+| Logo | Agent | Brainclaw fit | Best use today |
+|---|---|---|---|
+| [![Claude Code](https://img.shields.io/badge/Claude_Code-111111?logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code) | **[Claude Code](https://github.com/anthropics/claude-code)** | Best fit | full workflow integration with instructions, MCP, commands, and session hooks |
+| [![Codex](https://img.shields.io/badge/Codex-111111?logo=openai&logoColor=white)](https://openai.com/codex/) | **[Codex](https://openai.com/codex/)** | Strong fit | structured CLI/MCP collaboration with explicit plans, claims, and handoffs |
+| [![Cursor](https://img.shields.io/badge/Cursor-1F2430?logo=cursor&logoColor=white)](https://cursor.com/en-US) | **[Cursor](https://cursor.com/en-US)** | Strong fit | repo-native coordination with rules + MCP |
+| [![OpenCode](https://img.shields.io/badge/OpenCode-0F172A?logoColor=white)](https://github.com/opencode-ai/opencode) | **[OpenCode](https://github.com/opencode-ai/opencode)** | Strong fit | simple local-first setup with `AGENTS.md` + workspace MCP |
+| [![Windsurf](https://img.shields.io/badge/Windsurf-0B1220?logo=codeium&logoColor=white)](https://windsurf.com/) | **[Windsurf](https://windsurf.com/)** | Good fit | guided workflows with instructions, hooks, and MCP |
+| [![Roo](https://img.shields.io/badge/Roo-7C3AED?logoColor=white)](https://github.com/RooCodeInc/Roo-Code) | **[Roo](https://github.com/RooCodeInc/Roo-Code)** | Good fit | workspace coordination with rules + MCP |
+| [![Continue](https://img.shields.io/badge/Continue-2563EB?logoColor=white)](https://github.com/continuedev/continue) | **[Continue](https://github.com/continuedev/continue)** | Good fit | context access and MCP-driven collaboration in editor workflows |
+| [![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-1A73E8?logo=googlegemini&logoColor=white)](https://github.com/google-gemini/gemini-cli) | **[Antigravity / Gemini CLI](https://github.com/google-gemini/gemini-cli)** | Promising fit | CLI-first workflows with `GEMINI.md` + MCP |
+| [![Cline](https://img.shields.io/badge/Cline-0F766E?logoColor=white)](https://github.com/cline/cline) | **[Cline](https://github.com/cline/cline)** | Functional fit | lightweight Brainclaw usage through rules + MCP |
+| [![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-181717?logo=githubcopilot&logoColor=white)](https://github.com/features/copilot) | **[GitHub Copilot](https://github.com/features/copilot)** | Supported fit | project awareness and shared instructions, with lighter workflow control |
+
+brainclaw is most effective today when one agent works at a time in a given checkout and the next agent resumes from shared context, claims, and handoffs.
+
+---
+
+## Platform Support
+
+brainclaw targets Node.js 20+ across major developer operating systems, but real-world support is not perfectly even yet.
+
+| Logo | Platform | Status today | Notes |
+|---|---|---|---|
+| [![Linux](https://img.shields.io/badge/Linux-111111?logo=linux&logoColor=white)](https://www.kernel.org/) | **[Linux](https://www.kernel.org/)** | Recommended | best-supported environment today; GitHub CI runs on Ubuntu with Node 20 and 22 |
+| [![macOS](https://img.shields.io/badge/macOS-000000?logo=apple&logoColor=white)](https://www.apple.com/macos/) | **[macOS](https://www.apple.com/macos/)** | Likely supported | Unix-like path and shell model should map well, but it is less exercised than Linux |
+| [![Windows](https://img.shields.io/badge/Windows-0078D4?logo=windows&logoColor=white)](https://www.microsoft.com/windows/) | **[Windows](https://www.microsoft.com/windows/)** | Supported with caveats | native support exists, but PATH, npm, SSH, and PowerShell quoting still create more friction than on Unix systems |
+| [![Windows + WSL2](https://img.shields.io/badge/Windows%20%2B%20WSL2-0078D4?logo=windows&logoColor=white)](https://learn.microsoft.com/windows/wsl/) | **[Windows + WSL2](https://learn.microsoft.com/windows/wsl/)** | Important, still maturing | Brainclaw detects this setup explicitly, but setup/install/store parity across Windows and WSL is not fully seamless yet |
+
+If you want the least surprising setup today, use Linux first. If you are on Windows, prefer a disciplined single-environment workflow and expect a few extra machine-specific fixes.
+
+---
+
+## Quick example
+
+```bash
+npx brainclaw setup --yes
+npx brainclaw init
+
+npx brainclaw memory create decision "OAuth migration now goes through auth-gateway" --tag auth
+npx brainclaw memory create constraint "Payments module frozen until 2026-04-01" --tag payments
+npx brainclaw memory create trap "Checkout E2E tests are flaky on Windows" --severity high
+npx brainclaw plan create "Coordinate auth rollout" --priority high
+npx brainclaw memory create handoff "Validate refund endpoint" --from backend --to qa
+
+npx brainclaw context --json
+npx brainclaw status
+```
+
+---
+
+## Installation
+
+```bash
+npm install -g brainclaw   # global
+# or
+npm install && npm run build  # from source
+```
+
+Also available as `bclaw`:
+
+```bash
+bclaw init
+bclaw status
+```
+
+---
+
+## Quickstart
+
+```bash
+brainclaw setup --yes
+brainclaw init
+brainclaw memory create decision "OAuth migration now goes through auth-gateway" --tag auth
+brainclaw memory create constraint "Payments module frozen until 2026-04-01" --tag payments
+brainclaw memory create trap "Checkout E2E tests are flaky on Windows" --severity high
+brainclaw plan create "Coordinate auth rollout" --priority high
+brainclaw context --json
+```
+
+→ [Full quickstart guide](https://github.com/jberdah/brainclaw/blob/master/docs/quickstart.md)
+
+---
+
+## Current Limitation
+
+For now, avoid having multiple coding agents edit the same project in parallel.
+
+brainclaw already helps one agent resume or review another agent's work with better shared context, plans, claims, and handoffs. But until dedicated Git worktrees per agent/session are implemented, concurrent edits in the same checkout can still create conflicts, overwritten local state, or confusing Git transitions.
+
+Recommended use today:
+
+1. let one agent work at a time in a given checkout
+2. use handoffs when switching from one agent to another
+3. use shared plans, claims, and context to preserve continuity
+
+---
+
+## How it fits into agent workflows
+
+brainclaw sits *alongside* Copilot, Claude Code, Cursor, Codex, Windsurf, Cline, Roo, Continue, OpenCode, and Antigravity/Gemini CLI.
+
+Typical flow:
+
+1. `brainclaw setup` — machine-level bootstrap for agent integrations and global prerequisites
+2. `brainclaw init` — seeds workspace memory, writes to the detected agent's native instruction file
+3. record canonical memory with `brainclaw memory create ...` and work items with `brainclaw plan create ...`
+4. let agents read brainclaw context before editing
+5. use claims to reduce collisions
+6. hand work off explicitly when needed
+7. keep shared state visible across sessions
+
+brainclaw can also expose collaboration views through MCP-readable tools, including context, board views, and structured lists for plans, claims, agents, instructions, and candidates.
+
+---
+
+## Documentation
+
+| | |
+|---|---|
+| [docs/quickstart.md](https://github.com/jberdah/brainclaw/blob/master/docs/quickstart.md) | Get started in 5 minutes |
+| [docs/cli.md](https://github.com/jberdah/brainclaw/blob/master/docs/cli.md) | Full command reference |
+| [docs/concepts/memory.md](https://github.com/jberdah/brainclaw/blob/master/docs/concepts/memory.md) | What "memory" means in brainclaw |
+| [docs/concepts/plans-and-claims.md](https://github.com/jberdah/brainclaw/blob/master/docs/concepts/plans-and-claims.md) | Coordination layer |
+| [docs/concepts/runtime-notes.md](https://github.com/jberdah/brainclaw/blob/master/docs/concepts/runtime-notes.md) | Ephemeral observations |
+| [docs/integrations/overview.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/overview.md) | How to integrate with any agent |
+| [docs/integrations/cursor.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/cursor.md) | Cursor |
+| [docs/integrations/claude-code.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/claude-code.md) | Claude Code |
+| [docs/integrations/copilot.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/copilot.md) | GitHub Copilot |
+| [docs/integrations/codex.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/codex.md) | Codex |
+| [docs/integrations/mcp.md](https://github.com/jberdah/brainclaw/blob/master/docs/integrations/mcp.md) | MCP tools |
+| [docs/storage.md](https://github.com/jberdah/brainclaw/blob/master/docs/storage.md) | Storage model |
+| [docs/security.md](https://github.com/jberdah/brainclaw/blob/master/docs/security.md) | Security model |
+| [docs/review.md](https://github.com/jberdah/brainclaw/blob/master/docs/review.md) | Reflective review |
+| [docs/reputation.md](https://github.com/jberdah/brainclaw/blob/master/docs/reputation.md) | Reputation signals |
+
+---
+
+## Running tests
+
+```bash
+npm test                   # unit + smoke (fast path)
+npm run test:e2e           # full suite
+npm run test:coverage      # with coverage report
+```
+
+---
+
+## Changelog
+
+### v0.9.10
+
+- **OpenCode** : détection et auto-config MCP workspace via `opencode.json`; l'export réutilise `AGENTS.md`
+- **Antigravity / Gemini CLI** : détection et export `gemini-md` vers `GEMINI.md`, avec MCP machine-level sous `.gemini/antigravity/mcp_config.json`
+- **Workflow export** : la doc export couvre désormais explicitement les nouveaux formats et fichiers générés
+
+### v0.7.2
+
+- **UserPromptSubmit hook** : correction du format — `brainclaw context` (texte markdown) au lieu de `--json` pour injection correcte dans le contexte Claude Code
+
+### v0.7.1
+
+- **Cross-platform `npx` fix** : `brainclaw init` et `brainclaw export` ajoutent désormais brainclaw en `devDependency` du projet cible — `npx brainclaw` fonctionne dans les hooks Claude Code sans dépendre du PATH global (résout Windows WSL/Git Bash)
+
+### v0.7.0
+
+- **Claude Code** : intégration native complète — MCP (`.mcp.json`), slash command (`.claude/commands/brainclaw.md`), hooks de session (`UserPromptSubmit` + `Stop`) dans `.claude/settings.local.json`
+- **Cursor** : config MCP machine-level (`~/.cursor/mcp.json`) ajoutée à l'auto-config
+- **Roo Code** : config MCP workspace (`.roo/mcp.json`)
+- **Continue** : config MCP workspace (`.continue/config.json`, format array)
+- **Hygiene section** renforcée : workflow plan/claim/session-end inclus dans toutes les instructions générées
+- **Canal de mise à jour local** (`brainclaw version --publish-local`) : tarball + manifeste `.releases/`
+
+---
+
+## License
+
+[Business Source License 1.1](LICENSE) — © 2024-2026 Juan Berdah
+
+Free for non-production and internal use. Production use is permitted provided you do not build or offer a competing product or service (shared agent memory / coordination / context management for coding agents or development teams). Each version converts to MIT four years after its release date.
+
+For commercial licensing inquiries, contact the licensor.