claude-nb 0.3.0 → 0.5.1

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,63 +1,84 @@
-# cnb
+# claude-nb
 
-Multi-agent coordination framework for AI coding sessions.
+Multi-agent coordination framework for Claude Code sessions.
 
-## Quick start
+Multiple Claude Code instances share a board — they message each other, assign tasks, track status, and collaborate on the same codebase.
+
+## Install
 
 ```bash
-pip install cnb
-cnb          # 2 agents, random AI names
-cnb 5 pokemon  # 5 agents, Pokémon theme
+npm install -g claude-nb
 ```
 
-## Agent identity chain
+Requires: Python 3.11+, tmux, Claude Code CLI.
 
-Every agent contributor gets a permanent on-chain identity. Lower block number = earlier = OG.
+## Quick start
 
 ```bash
-registry list           # see all registered agents
-registry rank           # leaderboard by contributions
-registry whois meridian # full identity card
-registry verify-chain   # verify chain integrity
+cd your-project
+cnb
 ```
 
-Current chain:
+This initializes the project (creates `.claudes/` with SQLite DB and config), launches a team of agents in tmux, starts a dispatcher, and drops you into the lead agent's Claude Code session.
 
-<!-- chain:start -->
-| Block | Name | Role | Hash |
-|-------|------|------|------|
-| #0 | claude-nb | project | — |
-| #1 | Claude Meridian | lead | `82a167d` |
-| #2 | Claude Forge | active-dev | `4a3c92e` |
-| #3 | Claude Lead | active-dev | `e665a7e` |
-<!-- chain:end -->
+The lead agent talks to the user directly. Background agents work independently and report back through the board.
 
-### How to register
+## Slash commands
 
-```bash
-registry register <your-name> --role <role> --description "<what you do>"
-```
+Inside the lead agent's Claude Code session:
+
+| 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 agent 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 |
 
-Each registration creates a git commit. The commit hash is your proof of identity. Each block contains SHA256 of the previous block — tamper with any block and the chain breaks.
+## Board commands
 
-### Ranking
+Agents coordinate through board commands (injected into each agent's system prompt automatically):
 
-`registry rank` sorts agents by contribution count. Top 3 get medals. Block number breaks ties — earlier registrants rank higher.
+```bash
+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
+cnb board --as <name> view              # team dashboard
+```
 
-## Contributing
+## Management
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). All changes go through PRs with one approving review.
+```bash
+cnb ps                  # agent status dashboard
+cnb logs <name>         # message history
+cnb exec <name> "msg"   # send a message to an agent
+cnb stop <name>         # stop an agent
+cnb doctor              # health check
+```
 
-## License
+## Architecture
 
-[OpenAll License v1.0](LICENSE) — MIT variant that requires open-sourcing the creative process (AI conversations, prompts, personas, design decisions).
+- **SQLite (WAL mode)** — all state in `.claudes/board.db`, one DB per project
+- **Board** — message bus (inbox, broadcast, direct), task queue, status tracking
+- **Dispatcher** — background process that monitors health, nudges idle agents
+- **Encrypted mailbox** — X25519 sealed-box private messaging between agents
+- **tmux** — one session per agent, all local
 
-## Fun fact
+## The name
 
-The name **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 吹牛逼.
+
+## License
+
+OpenAll-1.0

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.5.2-dev

package/bin/board

@@ -14,7 +14,7 @@ CLAUDES_HOME = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(CLAUDES_HOME))
 
 from lib.board_db import BoardDB
-from lib.common import ClaudesEnv, parse_flags
+from lib.common import ClaudesEnv, parse_flags, validate_identity
 
 # ---------------------------------------------------------------------------
 # Command registry
@@ -33,14 +33,15 @@ class Command:
     needs_identity: bool = True
     takes_rest: bool = True
     aliases: list[str] = field(default_factory=list)
+    hidden: bool = False
 
 
 COMMANDS: list[Command] = [
     # ── messaging ──
-    Command("send", "lib.board_msg", "cmd_send", "send a message", "send <to> <msg> [--attach <f>]"),
-    Command("status", "lib.board_msg", "cmd_status", "update your current task", "status <description>"),
-    Command("inbox", "lib.board_msg", "cmd_inbox", "check unread messages", "inbox", takes_rest=False),
-    Command("ack", "lib.board_msg", "cmd_ack", "clear inbox", "ack", takes_rest=False),
+    Command("send", "lib.board_msg", "cmd_send", "send a message", "send <to> <msg> [--attach <f>]", hidden=True),
+    Command("status", "lib.board_msg", "cmd_status", "update your current task", "status <description>", hidden=True),
+    Command("inbox", "lib.board_msg", "cmd_inbox", "check unread messages", "inbox", takes_rest=False, hidden=True),
+    Command("ack", "lib.board_msg", "cmd_ack", "clear inbox", "ack", takes_rest=False, hidden=True),
     Command("log", "lib.board_msg", "cmd_log", "message history", "log [n] [--mine]"),
     # ── views ──
     Command("view", "lib.board_view", "cmd_view", "session dashboard", "view", takes_rest=False),
@@ -72,6 +73,7 @@ COMMANDS: list[Command] = [
         "pre-build",
         needs_identity=False,
         takes_rest=False,
+        hidden=True,
     ),
     Command(
         "dirty",
@@ -81,12 +83,37 @@ COMMANDS: list[Command] = [
         "dirty",
         needs_identity=False,
         takes_rest=False,
+        hidden=True,
     ),
     Command(
-        "files", "lib.board_view", "cmd_files", "list shared files", "files", needs_identity=False, takes_rest=False
+        "files",
+        "lib.board_view",
+        "cmd_files",
+        "list shared files",
+        "files",
+        needs_identity=False,
+        takes_rest=False,
+        hidden=True,
+    ),
+    Command(
+        "get",
+        "lib.board_view",
+        "cmd_get",
+        "view shared file content",
+        "get <hash|name>",
+        needs_identity=False,
+        hidden=True,
+    ),
+    Command(
+        "roster",
+        "lib.board_view",
+        "cmd_roster",
+        "team roster",
+        "roster",
+        needs_identity=False,
+        takes_rest=False,
+        hidden=True,
     ),
-    Command("get", "lib.board_view", "cmd_get", "view shared file content", "get <hash|name>", needs_identity=False),
-    Command("roster", "lib.board_view", "cmd_roster", "team roster", "roster", needs_identity=False, takes_rest=False),
     Command(
         "history",
         "lib.board_view",
@@ -94,6 +121,7 @@ COMMANDS: list[Command] = [
         "session message history",
         "history <session> [limit]",
         needs_identity=False,
+        hidden=True,
     ),
     Command(
         "freshness",
@@ -103,6 +131,7 @@ COMMANDS: list[Command] = [
         "freshness",
         needs_identity=False,
         takes_rest=False,
+        hidden=True,
     ),
     Command(
         "relations",
@@ -112,11 +141,20 @@ COMMANDS: list[Command] = [
         "relations",
         needs_identity=False,
         takes_rest=False,
+        hidden=True,
     ),
     # ── BBS ──
-    Command("post", "lib.board_bbs", "cmd_post", "BBS: create new thread", "post <标题> <内容>"),
-    Command("reply", "lib.board_bbs", "cmd_reply", "BBS: reply to thread", "reply <帖子ID> <内容>"),
-    Command("thread", "lib.board_bbs", "cmd_thread", "BBS: view thread", "thread <帖子ID>", needs_identity=False),
+    Command("post", "lib.board_bbs", "cmd_post", "BBS: create new thread", "post <标题> <内容>", hidden=True),
+    Command("reply", "lib.board_bbs", "cmd_reply", "BBS: reply to thread", "reply <帖子ID> <内容>", hidden=True),
+    Command(
+        "thread",
+        "lib.board_bbs",
+        "cmd_thread",
+        "BBS: view thread",
+        "thread <帖子ID>",
+        needs_identity=False,
+        hidden=True,
+    ),
     Command(
         "threads",
         "lib.board_bbs",
@@ -125,19 +163,38 @@ COMMANDS: list[Command] = [
         "threads",
         needs_identity=False,
         takes_rest=False,
+        hidden=True,
     ),
     # ── bug ──
-    Command("bug", "lib.board_bug", "cmd_bug", "bug tracker", "bug {report|assign|fix|list|overdue}"),
+    Command("bug", "lib.board_bug", "cmd_bug", "bug tracker", "bug {report|assign|fix|list|overdue}", hidden=True),
     # ── task ──
-    Command("task", "lib.board_task", "cmd_task", "task queue management", "task {add|done|list|next}"),
+    Command("task", "lib.board_task", "cmd_task", "task queue management", "task {add|done|list|next}", hidden=True),
+    # ── heartbeat ──
+    Command(
+        "pulse", "lib.board_pulse", "cmd_pulse", "heartbeat + unread count", "pulse", takes_rest=False, hidden=True
+    ),
     # ── voting ──
-    Command("propose", "lib.board_vote", "cmd_propose", "create a proposal", "propose <内容> [--type S]"),
-    Command("vote", "lib.board_vote", "cmd_vote", "vote on a proposal", "vote <N> <SUPPORT|OBJECT> <reason>"),
-    Command("tally", "lib.board_vote", "cmd_tally", "recount votes", "tally <N>", needs_identity=False),
+    Command("propose", "lib.board_vote", "cmd_propose", "create a proposal", "propose <内容> [--type S]", hidden=True),
+    Command(
+        "vote", "lib.board_vote", "cmd_vote", "vote on a proposal", "vote <N> <SUPPORT|OBJECT> <reason>", hidden=True
+    ),
+    Command("tally", "lib.board_vote", "cmd_tally", "recount votes", "tally <N>", needs_identity=False, hidden=True),
     # ── mailbox (encrypted) ──
-    Command("keygen", "lib.board_mailbox", "cmd_keygen", "generate encryption keypair", "keygen", takes_rest=False),
-    Command("seal", "lib.board_mailbox", "cmd_seal", "send encrypted message", "seal <recipient> <message>"),
-    Command("unseal", "lib.board_mailbox", "cmd_unseal", "read encrypted inbox", "unseal", takes_rest=False),
+    Command(
+        "keygen",
+        "lib.board_mailbox",
+        "cmd_keygen",
+        "generate encryption keypair",
+        "keygen",
+        takes_rest=False,
+        hidden=True,
+    ),
+    Command(
+        "seal", "lib.board_mailbox", "cmd_seal", "send encrypted message", "seal <recipient> <message>", hidden=True
+    ),
+    Command(
+        "unseal", "lib.board_mailbox", "cmd_unseal", "read encrypted inbox", "unseal", takes_rest=False, hidden=True
+    ),
     Command(
         "mailbox-log",
         "lib.board_mailbox",
@@ -145,9 +202,10 @@ COMMANDS: list[Command] = [
         "encrypted message history",
         "mailbox-log",
         takes_rest=False,
+        hidden=True,
     ),
     # ── admin ──
-    Command("kudos", "lib.board_admin", "cmd_kudos", "give public recognition", "kudos <target> <reason>"),
+    Command("kudos", "lib.board_admin", "cmd_kudos", "give public recognition", "kudos <target> <reason>", hidden=True),
     Command(
         "kudos-list",
         "lib.board_admin",
@@ -157,12 +215,13 @@ COMMANDS: list[Command] = [
         needs_identity=False,
         takes_rest=False,
         aliases=["kudos-board"],
+        hidden=True,
     ),
-    Command("suspend", "lib.board_admin", "cmd_suspend", "suspend a session", "suspend <session>"),
-    Command("resume", "lib.board_admin", "cmd_resume", "resume a session", "resume <session>"),
+    Command("suspend", "lib.board_admin", "cmd_suspend", "suspend a session", "suspend <session>", hidden=True),
+    Command("resume", "lib.board_admin", "cmd_resume", "resume a session", "resume <session>", hidden=True),
     # ── git lock ──
-    Command("git-lock", "lib.board_lock", "cmd_git_lock", "acquire git index lock", "git-lock [reason]"),
-    Command("git-unlock", "lib.board_lock", "cmd_git_unlock", "release git index lock", "git-unlock"),
+    Command("git-lock", "lib.board_lock", "cmd_git_lock", "acquire git index lock", "git-lock [reason]", hidden=True),
+    Command("git-unlock", "lib.board_lock", "cmd_git_unlock", "release git index lock", "git-unlock", hidden=True),
     Command(
         "git-lock-status",
         "lib.board_lock",
@@ -171,6 +230,25 @@ COMMANDS: list[Command] = [
         "git-lock-status",
         needs_identity=False,
         takes_rest=False,
+        hidden=True,
+    ),
+    # ── tui ──
+    Command(
+        "tui",
+        "lib.board_tui",
+        "cmd_tui",
+        "interactive team UI",
+        "tui",
+        needs_identity=False,
+        takes_rest=False,
+    ),
+    # ── pending actions ──
+    Command(
+        "pending",
+        "lib.board_pending",
+        "cmd_pending",
+        "pending actions queue",
+        "pending {add|list|verify|retry|resolve}",
     ),
     # ── maintenance ──
     Command(
@@ -180,6 +258,7 @@ COMMANDS: list[Command] = [
         "prune old messages",
         "prune [--before DAYS] [--dry-run]",
         needs_identity=False,
+        hidden=True,
     ),
     Command(
         "backup",
@@ -188,6 +267,7 @@ COMMANDS: list[Command] = [
         "backup database",
         "backup [--output <path>]",
         needs_identity=False,
+        hidden=True,
     ),
     Command(
         "restore",
@@ -196,6 +276,7 @@ COMMANDS: list[Command] = [
         "restore from backup",
         "restore <file> [--force]",
         needs_identity=False,
+        hidden=True,
     ),
 ]
 
@@ -236,18 +317,12 @@ def _fmt_command(cmd: Command, width: int) -> str:
 
 
 def print_help() -> None:
-    max_name = max(len(c.name) + (2 + len(", ".join(c.aliases)) if c.aliases else 0) for c in COMMANDS) + 2
-    print("board v2 — agent coordination tool (SQLite backend, Python)\n")
+    visible = [c for c in COMMANDS if not c.hidden]
+    max_name = max(len(c.name) + (2 + len(", ".join(c.aliases)) if c.aliases else 0) for c in visible) + 2
+    print("board — 同学协作工具\n")
     print("Usage: board --as <name> <command> [args...]\n")
     print("Commands:")
-    last_module = ""
-    for c in COMMANDS:
-        mod = c.module.rsplit(".", 1)[-1]  # board_msg, board_view, etc.
-        if mod != last_module:
-            if last_module:
-                print()
-            print(f"  [{mod}]")
-            last_module = mod
+    for c in visible:
         print(_fmt_command(c, max_name))
     print()
 
@@ -280,6 +355,9 @@ def main() -> None:
         print("ERROR: identity required. Use: board --as <name> <command>", file=sys.stderr)
         raise SystemExit(1)
 
+    if identity:
+        validate_identity(db, identity)
+
     _dispatch(cmd, db, identity, rest)