claude-nb 0.4.0 → 0.5.43

package/Makefile

@@ -8,13 +8,13 @@ SCRIPTS = bin/cnb bin/board bin/swarm bin/dispatcher bin/dispatcher-watchdog bin
 # All python sources (bin + lib)
 PY_SOURCES = bin/board bin/swarm bin/dispatcher bin/dispatcher-watchdog bin/init lib/ tests/
 
-.PHONY: all install uninstall test lint typecheck format check ci clean version
+.PHONY: all install uninstall test lint typecheck format check ci clean version sync-version check-version
 
 all: check
 
 check: lint test
 
-ci: lint typecheck test
+ci: lint typecheck test check-version
 
 lint:
 	@echo "=== ruff ==="
@@ -56,5 +56,11 @@ clean:
 	find . -type d -name '*.egg-info' -exec rm -rf {} + 2>/dev/null || true
 	rm -rf dist/ build/ .mypy_cache/ .ruff_cache/
 
+sync-version:
+	python3 bin/sync-version
+
+check-version:
+	python3 bin/sync-version --check
+
 version:
 	@echo $(VERSION)

package/README.md

@@ -1,100 +1,307 @@
+<!-- README_SYNC: sections must match README_zh.md — run bin/check-readme-sync -->
+
+[中文版](README_zh.md)
+
 # claude-nb
 
-Multi-agent coordination framework for Claude Code sessions.
+[![CI](https://github.com/ApolloZhangOnGithub/cnb/actions/workflows/ci.yml/badge.svg)](https://github.com/ApolloZhangOnGithub/cnb/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/claude-nb?label=npm)](https://www.npmjs.com/package/claude-nb)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB)](pyproject.toml)
+[![Docs](https://img.shields.io/badge/docs-c--n--b.space-14865d)](https://c-n-b.space/)
+[![License](https://img.shields.io/badge/license-OpenAll--1.0-444)](LICENSE)
+
+**Project ownership for LLM teams.**
+
+`cnb` is local-first organizational infrastructure for long-lived Claude Code and Codex teams. It gives AI coding sessions a shared board, durable ownership, handoff records, and operational checks so a restarted session does not become a new hire with no memory.
+
+```bash
+npm install -g claude-nb
+```
+
+| Surface | Current shape |
+|---------|---------------|
+| Runtime | Local tmux sessions, SQLite board, dispatcher, filesystem reports |
+| Engines | Claude Code by default; Codex supported through the npm peer CLI |
+| State | Board database, ownership map, issue mirror, daily/shift reports |
+| Distribution | Public npm package `claude-nb`, Python 3.11+ internals |
+| Documentation | README short path, durable docs in [`docs/`](docs/), public site at [`c-n-b.space`](https://c-n-b.space/) |
+
+Every multi-agent tool solves "how to run multiple agents." cnb solves what happens after — how to make them **manageable** across sessions, shifts, and team changes.
+
+LLM sessions are stateless. Every restart is a new hire who knows nothing. Without organizational infrastructure, you get temporary workers who split tasks, finish, and forget. cnb gives them **permanent module ownership**: lisa-su owns the notification system across 11 commits and 3 restarts. When a bug surfaces, you don't re-explain the module to a blank session — you find the owner's daily report and pick up where they left off.
+
+This is not about speed or context isolation. Those are side effects. The core problem is: [42% of multi-agent failures are specification and system design issues](https://arxiv.org/abs/2503.13657) — role ambiguity, task misinterpretation, poor decomposition (Cemri et al., NeurIPS 2025 Spotlight). Not capability — organization. cnb is organizational infrastructure for AI teams.
+
+<!-- section:start-here -->
+## Start here
+
+| Need | Path |
+|------|------|
+| Install the CLI | `npm install -g claude-nb` |
+| Understand the model | [How cnb fits in](#how-cnb-fits-in), [Glossary](#glossary), [Ownership autonomy](docs/design-ownership-autonomy.md) |
+| Start a team | [Quick start](#quick-start), then `cnb` inside a project |
+| Inspect a real run | [Silicon Valley Battle](instances/silicon_vally_battle/) |
+| Publish or verify package metadata | [Package publishing](docs/package-publishing.md) |
+| Contribute safely | [Contributing](CONTRIBUTING.md), [Security](SECURITY.md), [Roadmap](ROADMAP.md) |
+
+<!-- section:status -->
+## Project status
+
+cnb is no longer a single-script experiment, but it is still an active local-first system that expects a trusted workstation and human supervision.
 
-Spawn a team of Claude Code instances that communicate, delegate tasks, and collaborate through a shared board — all orchestrated from your terminal.
+| Area | Current state | Evidence |
+|------|---------------|----------|
+| CLI packaging | npm entrypoint wraps the Python CLI | [`package.json`](package.json), [`pyproject.toml`](pyproject.toml), [`bin/cnb`](bin/cnb) |
+| Board runtime | SQLite schema, migrations, task/inbox/status/ownership commands | [`schema.sql`](schema.sql), [`migrations/`](migrations/), [`lib/board_*.py`](lib/) |
+| Quality gates | ruff, mypy, pytest, version sync, changelog, CodeQL, and secret scanning | [`.github/workflows/ci.yml`](.github/workflows/ci.yml), [`Makefile`](Makefile) |
+| Governance | issue-first workflow, ownership rules, Co-Authored-By policy | [`CONTRIBUTING.md`](CONTRIBUTING.md), [`ROADMAP.md`](ROADMAP.md), [`registry/`](registry/) |
+| Docs | bilingual README, durable product docs, and public GitHub Pages site | [`README_zh.md`](README_zh.md), [`docs/`](docs/), [`site/`](site/) |
+| Boundaries | local-first, high-permission options, human-supervised automation | [`SECURITY.md`](SECURITY.md), [FAQ](#faq) |
 
+<!-- section:why -->
+## How cnb fits in
+
+There are many great tools in this space, each with a different focus:
+
+- **Claude Squad, amux, ittybitty** — session management: launching, isolating, and monitoring parallel agents. Polished UX, git worktree isolation, agent-agnostic support.
+- **Codex, cloud agents** — one task per sandbox, excellent for isolated jobs.
+- **cnb** — organizational layer: persistent module ownership, cross-session continuity, accountability, handoff protocols.
+
+These are complementary. You could use Claude Squad for session management and cnb for team coordination on top. Or use Codex for one-off tasks and cnb for sustained multi-session development.
+
+cnb's specific focus is what happens **between** sessions — when a tongxue restarts with no memory, how does it pick up where the last one left off? Daily reports, shift directories, bug tracker with SLA, Co-Authored-By enforcement, and shutdown protocols are all designed for this.
+
+**Where cnb is headed:** Today, a module owner still needs a human to say "go check your issues" or "push your code." The goal is for owners to be fully autonomous within their domain — auto-detecting relevant issues, verifying their own work against CI, creating PRs, and responding to failures. Not "unattended agents doing random tasks" but "responsible owners who don't need to be told to do their job." See [ROADMAP.md](ROADMAP.md).
+
+<!-- section:glossary -->
+## Glossary
+
+| Term | Meaning |
+|------|---------|
+| **tongxue** (同学) | Literally "classmate" in Chinese. Each Claude Code instance in a cnb team is called a tongxue — not an "agent", not a "worker". The word implies peers learning and building together, which is how cnb sessions actually operate: they coordinate as equals through a shared message board, not through a master-slave hierarchy. |
+| **lead tongxue** | The tongxue whose terminal faces the user. It delegates work and relays results, but has no special privileges on the board. |
+| **board** | The shared SQLite database (`.claudes/board.db`) where tongxue exchange messages, track tasks, and report status. |
+| **dispatcher** | A background process that monitors tongxue health and nudges idle ones. |
+
+<!-- section:install -->
 ## Install
 
 ```bash
 npm install -g claude-nb
 ```
 
-Requires: Python 3.11+, tmux, Claude Code CLI.
+The canonical public package is [`claude-nb`](https://www.npmjs.com/package/claude-nb) on npmjs.com. GitHub Packages may also show the scoped mirror `@apollozhangongithub/cnb`; npmjs remains the supported install path. See [Package publishing](docs/package-publishing.md) for release and visibility rules.
 
+The npm dependency count only covers JavaScript packages. cnb has no required JavaScript library dependencies, but it does have runtime requirements:
+
+- Node.js 18+ for the npm entrypoint
+- Python 3.11+ and the Python package dependency `cryptography>=41.0`
+- tmux and git
+- at least one agent CLI: Claude Code CLI (`@anthropic-ai/claude-code`) or Codex CLI (`@openai/codex`)
+
+Run `cnb doctor` after install to check the local machine.
+
+<!-- section:quickstart -->
 ## Quick start
 
 ```bash
-cnb              # 2 agents, AI-legends theme
-cnb 5            # 5 agents
-cnb pokemon      # 2 agents, Pokemon theme
-cnb 5 pokemon    # 5 agents, Pokemon theme
+cd your-project
+cnb
 ```
 
-Themes: `ai` `animal` `food` `lang` `music` `myth` `pokemon` `space`
+This initializes the project (creates `.claudes/` with SQLite DB and config), launches a team of tongxue in tmux, starts a dispatcher, and drops you into the lead tongxue's Claude Code session.
+
+The lead tongxue talks to the user directly. Background tongxue work independently and report back through the board.
+
+<!-- section:docs -->
+## Docs
+
+The README is the short path. Longer-lived documentation lives under [`docs/`](docs/):
+
+- [Ownership autonomy](docs/design-ownership-autonomy.md) — why cnb treats long-lived module ownership as the core unit of work.
+- [Tongxue avatar generation](docs/avatar-generation.md) — safe provider choices and prompt rules for AI-generated tongxue avatars.
+- [Package publishing](docs/package-publishing.md) — npm release, dist-tags, and GitHub Packages visibility rules.
+- [Public website](https://c-n-b.space/) — first-visit product entry and documentation links.
 
-## How it works
+<!-- section:slash-commands -->
+## Slash commands
 
-`cnb` launches multiple Claude Code sessions in tmux, each with a unique identity. Agents coordinate via:
+Inside the lead tongxue's Claude Code session:
 
-- **Board** — shared message bus (inbox, broadcast, direct messages)
-- **Tasks** — distributed task queue with status tracking
-- **Encrypted mailbox** — X25519 sealed-box private messaging via GitHub Release assets
-- **Governance** — proposals, voting, and consensus (supermajority / simple majority)
-- **Registry** — append-only identity chain (immutable agent records + milestones)
+| Command | What it does |
+|---------|-------------|
+| `/cnb-overview` | Team dashboard — who's doing what, who's stuck, who's idle |
+| `/cnb-watch <name>` | Peek at what a specific tongxue is working on |
+| `/cnb-progress` | Recent progress summary — new messages, completed tasks |
+| `/cnb-history` | Full message log |
+| `/cnb-update` | Update cnb to latest version |
+| `/cnb-help` | List all `/cnb-*` commands |
 
-## Commands
+<!-- section:demo -->
+## Demo
+
+**[Silicon Valley Battle](instances/silicon_vally_battle/)** — 10 AI leaders (LeCun, Lisa Su, Musk, Hinton, Dario…) debate Python vs Rust, draft an AI constitution, and try to manipulate each other through the board. 886 messages in 3 hours, all coordination through cnb.
+
+Start with the [highlights](instances/silicon_vally_battle/HIGHLIGHTS.md) — sutskever tries to pit lecun against lisa-su, both see through it in 5 minutes, then the real debate starts.
+
+<!-- section:board-commands -->
+## Board commands
+
+Tongxue coordinate through board commands (injected into each tongxue's system prompt automatically):
 
 ```bash
-cnb status          # team dashboard
-cnb board [...]     # message / task / admin commands
-cnb swarm [...]     # manage background agents
-cnb doctor          # health check
+cnb board --as <name> inbox              # check messages
+cnb board --as <name> send <to> "msg"    # direct message
+cnb board --as <name> send all "msg"     # broadcast
+cnb board --as <name> ack                # clear inbox
+cnb board --as <name> status "desc"      # update status
+cnb board --as <name> task add "desc"    # add task
+cnb board --as <name> task done          # finish current task (auto-verify + auto-PR)
+cnb board --as <name> own claim <path>   # claim module ownership
+cnb board --as <name> own map            # show all ownership
+cnb board --as <name> scan               # scan issues/CI for owners
+cnb board --as <name> view              # team dashboard
 ```
 
-### Board commands (used by agents)
+<!-- section:management -->
+## Management
 
 ```bash
-board --as <name> inbox              # check unread messages
-board --as <name> send <to> "msg"    # send message (or "all" to broadcast)
-board --as <name> ack                # clear inbox
-board --as <name> status "desc"      # update current status
-board --as <name> task add "desc"    # add task
-board --as <name> task done          # finish current task
-board --as <name> seal <to> "msg"    # send encrypted message
-board --as <name> unseal             # read encrypted inbox
-board --as <name> propose "content"  # create governance proposal
-board --as <name> vote <#> SUPPORT "reason"
+cnb ps                  # tongxue status dashboard
+cnb logs <name>         # message history
+cnb exec <name> "msg"   # send a message to a tongxue
+cnb stop <name>         # stop a tongxue
+cnb doctor              # health check
 ```
 
-## Agent identity chain
+<!-- section:issues -->
+## Issues
 
-Every agent gets a permanent on-chain identity. Lower block number = earlier = OG.
+All GitHub issues are auto-synced to [`issues/`](issues/) by a GitHub Action — on every issue event and every 6 hours. This means any Claude session (including claude.ai web chat, which has no CLI tools) can read project issues by just reading files.
 
-```bash
-registry list            # all registered agents
-registry verify-chain    # verify chain integrity
-```
+<!-- section:token-efficiency -->
+## Token efficiency
+
+cnb's coordination layer runs **outside** the LLM context window. This is a deliberate architectural choice.
+
+**What costs zero tokens:**
+- All board commands (`inbox`, `send`, `status`, `task`) are shell commands hitting SQLite — no LLM calls
+- Messages between tongxue travel through the database, not through context windows
+- The dispatcher monitors health via tmux/process inspection, not by querying the LLM
+- Daily reports, shift directories, bug tracker — all filesystem/DB operations
 
-Current chain:
+**What costs tokens:**
+- ~300 tokens of system prompt injection per tongxue (the board command reference in CLAUDE.md)
+- Each tongxue reads its own inbox (~50-200 tokens per check, depending on message count)
+- Lead tongxue summarizes progress to the user (normal conversation)
 
-<!-- chain:start -->
-| Block | Name | Type | Hash |
-|-------|------|------|------|
-| #0 | claude-nb | project | — |
-| #1 | Claude Meridian | agent | `82a167d` |
-| #2 | Claude Forge | agent | `4a3c92e` |
-| #3 | Claude Lead | agent | `e665a7e` |
-| #4 | encrypted-mailbox-live | milestone | `fcaf497` |
-<!-- chain:end -->
+**Comparison with alternative approaches:**
 
+| Approach | Coordination cost |
+|----------|------------------|
+| Shared context window (stuffing all agent output into one prompt) | O(n²) — every agent reads every other agent's full output |
+| LLM-routed messages (using the model to decide who to message) | Every routing decision is an LLM call |
+| **cnb** | O(1) — shell commands + SQLite queries, LLM only sees its own inbox |
+
+A 6-tongxue team running for a full shift typically spends <2% of total tokens on coordination overhead. The remaining 98% goes to actual coding work. The key insight: coordination is a database problem, not a language model problem.
+
+<!-- section:architecture -->
 ## Architecture
 
-- **SQLite (WAL mode)** — all state lives in `board.db`
-- **tmux** — one pane per agent, multiplexed
-- **Dispatcher** — monitors health, nudges idle agents, manages lifecycle
-- **No server** — everything is local, file-based, zero network dependencies (except GitHub for encrypted mailbox delivery)
+| Layer | Responsibility | Implementation |
+|-------|----------------|----------------|
+| CLI entrypoints | User commands, package launch, health checks | [`bin/`](bin/), [`lib/cli.py`](lib/cli.py) |
+| Board | Inbox, broadcast, direct messages, tasks, status, pending actions | [`lib/board_*.py`](lib/), [`schema.sql`](schema.sql) |
+| Ownership | Path ownership, owner lookup, verification, scan routing | [`lib/board_own.py`](lib/board_own.py), [`migrations/008_ownership.sql`](migrations/008_ownership.sql) |
+| Runtime | One local session per tongxue, dispatcher nudges, process health | [`lib/swarm.py`](lib/swarm.py), [`lib/concerns/`](lib/concerns/) |
+| Persistence | SQLite WAL database plus filesystem reports and issue mirrors | `.claudes/`, [`issues/`](issues/), shift/daily docs |
+| Integrations | npm packaging, GitHub issue mirror, GitHub Packages mirror, notification delivery | [`.github/workflows/`](.github/workflows/), [`lib/notification_delivery.py`](lib/notification_delivery.py), [`docs/package-publishing.md`](docs/package-publishing.md) |
+
+<!-- section:repository-map -->
+## Repository map
+
+| Path | Purpose |
+|------|---------|
+| [`bin/`](bin/) | Executable entrypoints and release/consistency helper scripts |
+| [`lib/`](lib/) | Python implementation for board, swarm, ownership, notifications, registry, and health |
+| [`migrations/`](migrations/) + [`schema.sql`](schema.sql) | SQLite schema evolution |
+| [`tests/`](tests/) | Unit and integration coverage for runtime behavior |
+| [`docs/`](docs/) | Durable product, package, and ownership docs |
+| [`site/`](site/) | GitHub Pages project site source |
+| [`issues/`](issues/) | GitHub issue mirror for CLI-less agent sessions |
+| [`registry/`](registry/) | Contributor/tongxue registry and chain guard |
+| [`instances/`](instances/) | Demo project snapshots that are safe to inspect |
+
+<!-- section:team -->
+## Team
+
+| 同学 | 负责 |
+|------|------|
+| lead | 项目负责人、团队协调 |
+| musk | 安全隔离 (#31) |
+| lisa-su | 通知推送 (#33) |
+| forge | 待办队列 (#34)、邮件系统 (#32)、全局管理 (#42) |
+| tester | 测试加固、质量保障 |
+| sutskever | 架构重构 (#26) |
+
+<!-- section:contribution-wall -->
+## Broad Contribution Wall
+
+GitHub's native Contributors panel only counts commits. cnb also treats issue work, PR review, checks, board ownership, and visible GitHub App actions as contribution signals. The wall below is the first broad-contribution view; implementation notes live in [Contribution wall](docs/contribution-wall.md).
+
+<p>
+  <a href="https://github.com/ApolloZhangOnGithub/cnb/issues/65#issuecomment-4414136928" title="musk: GitHub App identity verified through issue activity and a guarded commit">
+    <img src="https://avatars.githubusercontent.com/u/283269623?s=96&v=4" width="48" height="48" alt="cnb-workspace-musk[bot]" />
+  </a>
+</p>
+
+<!-- section:faq -->
+## FAQ
+
+**Q: How does cnb compare to Claude Squad / amux / ittybitty?**
+
+Different focus. Those are session managers — great at launching, isolating, and monitoring parallel agents. cnb is an organizational layer on top: module ownership, daily reports, accountability, handoff protocols. They're complementary; you could use a session manager for the tmux layer and cnb for team coordination.
+
+**Q: How does cnb compare to Codex?**
+
+Different category. Codex runs isolated tasks in cloud sandboxes. cnb coordinates persistent local teams across sessions. Use Codex for one-off jobs, cnb when you need continuity and ownership across restarts.
+
+**Q: How does cnb compare to OpenClaw?**
+
+Completely different projects. OpenClaw is a personal AI assistant across 20+ messaging platforms (WhatsApp, Telegram, Slack, etc.). cnb is a multi-agent coordination framework specifically for Claude Code development teams. No overlap.
+
+**Q: Can cnb run without a human watching?**
+
+Not yet. Today, the lead tongxue needs a human to drive it. But this is the active development direction — see [ROADMAP.md](ROADMAP.md) Phase 2. The goal is for module owners to autonomously detect issues, verify their work, and deliver PRs without being told.
+
+**Q: Is cnb token-efficient?**
+
+Yes. All coordination (messages, tasks, status) runs through shell commands + SQLite, not LLM calls. A 6-tongxue team spends <2% of tokens on coordination. See [Token efficiency](#token-efficiency).
+
+<!-- section:contributing -->
+## Contributing
+
+Before writing code, read [CONTRIBUTING.md](CONTRIBUTING.md) — it covers the issue workflow, versioning rules, naming conventions, security policy, and feature ownership model.
+
+Key points:
+- Every change starts with an issue
+- Every commit bumps VERSION (patch versions are fine)
+- 同学 (tongxue) not "agent" in all user-facing text
+- `ruff` + `mypy` + `pytest` must pass before push
+- README changes must update both `README.md` and `README_zh.md` — run `bin/check-readme-sync` to verify
 
+<!-- section:name -->
 ## The name
 
-The command **cnb** stands for **C**laude **N**orma **B**etty — named after [Claude Shannon](https://en.wikipedia.org/wiki/Claude_Shannon) and the two remarkable women in his life.
+**cnb** = **C**laude **N**orma **B**etty — after [Claude Shannon](https://en.wikipedia.org/wiki/Claude_Shannon) and the two remarkable women in his life.
 
-**[Norma Levor](https://en.wikipedia.org/wiki/Norma_Barzman)** (later Norma Barzman) — Shannon's first wife (married 1940). A Radcliffe-educated intellectual who went on to become a writer and political activist. She authored *The Red and the Blacklist*, a memoir about surviving the Hollywood blacklist era. A woman of conviction who lived boldly across continents.
+**[Norma Levor](https://en.wikipedia.org/wiki/Norma_Barzman)** (later Norma Barzman) — Shannon's first wife (1940). Writer, political activist, author of *The Red and the Blacklist*.
 
-**[Betty Shannon](https://en.wikipedia.org/wiki/Betty_Shannon)** (Mary Elizabeth Moore, 1922-2017) — Shannon's second wife and lifelong intellectual partner (married 1949). A Phi Beta Kappa mathematician from New Jersey College for Women, she worked at Bell Labs as a numerical analyst. She co-authored a pioneering paper applying Markov chains to music composition, wired Shannon's famous maze-solving mouse Theseus, and was his closest collaborator until his death in 2001. An unsung genius in her own right.
+**[Betty Shannon](https://en.wikipedia.org/wiki/Betty_Shannon)** (1922–2017) — Shannon's second wife and lifelong collaborator. Mathematician at Bell Labs, co-authored work on Markov chains in music, wired the maze-solving mouse Theseus. An unsung genius.
 
 Not 吹牛逼.
 
+<!-- section:license -->
 ## License
 
-MIT
+OpenAll-1.0

package/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.43

package/bin/_pip_entry.py

@@ -15,7 +15,7 @@ def main() -> None:
     bash_script = claudes_home / "bin" / "claudes-code"
 
     if bash_script.exists():
-        os.execvp("bash", ["bash", str(bash_script)] + sys.argv[1:])
+        os.execvp("bash", ["bash", str(bash_script), *sys.argv[1:]])
 
     print(f"FATAL: {bash_script} not found", file=sys.stderr)
     raise SystemExit(1)