claude-nb 0.3.0 → 0.4.0

package/README.md

@@ -1,63 +1,100 @@
-# cnb
+# claude-nb
 
-Multi-agent coordination framework for AI coding sessions.
+Multi-agent coordination framework for Claude Code sessions.
 
-## Quick start
+Spawn a team of Claude Code instances that communicate, delegate tasks, and collaborate through a shared board — all orchestrated from your terminal.
+
+## 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
+cnb              # 2 agents, AI-legends theme
+cnb 5            # 5 agents
+cnb pokemon      # 2 agents, Pokemon theme
+cnb 5 pokemon    # 5 agents, Pokemon theme
 ```
 
-Current chain:
+Themes: `ai` `animal` `food` `lang` `music` `myth` `pokemon` `space`
 
-<!-- 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 -->
+## How it works
+
+`cnb` launches multiple Claude Code sessions in tmux, each with a unique identity. Agents coordinate via:
+
+- **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)
 
-### How to register
+## Commands
 
 ```bash
-registry register <your-name> --role <role> --description "<what you do>"
+cnb status          # team dashboard
+cnb board [...]     # message / task / admin commands
+cnb swarm [...]     # manage background agents
+cnb doctor          # health check
 ```
 
-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 (used by agents)
 
-### Ranking
+```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"
+```
 
-`registry rank` sorts agents by contribution count. Top 3 get medals. Block number breaks ties — earlier registrants rank higher.
+## Agent identity chain
 
-## Contributing
+Every agent gets a permanent on-chain identity. Lower block number = earlier = OG.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). All changes go through PRs with one approving review.
+```bash
+registry list            # all registered agents
+registry verify-chain    # verify chain integrity
+```
 
-## License
+Current chain:
 
-[OpenAll License v1.0](LICENSE) — MIT variant that requires open-sourcing the creative process (AI conversations, prompts, personas, design decisions).
+<!-- 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 -->
+
+## 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)
 
-## 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.
+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.
 
 **[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.
 
-**[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)** (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.
 
 Not 吹牛逼.
+
+## License
+
+MIT

package/VERSION

@@ -1 +1 @@
-0.2.0
+0.4.0

package/bin/board

@@ -172,6 +172,16 @@ COMMANDS: list[Command] = [
         needs_identity=False,
         takes_rest=False,
     ),
+    # ── tui ──
+    Command(
+        "tui",
+        "lib.board_tui",
+        "cmd_tui",
+        "interactive team UI",
+        "tui",
+        needs_identity=False,
+        takes_rest=False,
+    ),
     # ── maintenance ──
     Command(
         "prune",

package/bin/cnb

@@ -14,12 +14,58 @@ fi
 if [ $# -gt 0 ]; then
     case "$1" in
         init)       shift; exec "$CLAUDES_HOME/bin/init" "$@" ;;
-        status)     exec "$CLAUDES_HOME/bin/board" overview ;;
+        status|ps)  exec "$CLAUDES_HOME/bin/board" overview ;;
         board)      shift; exec "$CLAUDES_HOME/bin/board" "$@" ;;
         swarm)      shift; exec "$CLAUDES_HOME/bin/swarm" "$@" ;;
         dispatcher) shift; exec "$CLAUDES_HOME/bin/dispatcher" "$@" ;;
         watchdog)   shift; exec "$CLAUDES_HOME/bin/dispatcher-watchdog" "$@" ;;
         doctor)     shift; exec "$CLAUDES_HOME/bin/doctor" "$@" ;;
+        logs)
+            shift
+            if [ $# -eq 0 ]; then
+                echo "用法: cnb logs <name>" >&2; exit 1
+            fi
+            exec "$CLAUDES_HOME/bin/board" --as "$1" log 50 ;;
+        stop)
+            shift
+            if [ $# -eq 0 ]; then
+                echo "用法: cnb stop <name>" >&2; exit 1
+            fi
+            exec "$CLAUDES_HOME/bin/swarm" stop "$@" ;;
+        exec)
+            shift
+            if [ $# -lt 2 ]; then
+                echo "用法: cnb exec <name> \"message\"" >&2; exit 1
+            fi
+            _target="$1"; shift
+            exec "$CLAUDES_HOME/bin/board" send "$_target" "$*" ;;
+        compose)
+            shift
+            _TEAM_FILE="${1:-cnb.toml}"
+            if [ ! -f "$_TEAM_FILE" ]; then
+                echo "错误: 找不到团队配置文件 '$_TEAM_FILE'" >&2
+                echo "用法: cnb compose [team-file.toml]" >&2
+                echo "" >&2
+                echo "示例 cnb.toml:" >&2
+                echo '  [session.alice]' >&2
+                echo '  persona = "Backend engineer"' >&2
+                echo '  [session.bob]' >&2
+                echo '  persona = "Frontend specialist"' >&2
+                exit 1
+            fi
+            "$CLAUDES_HOME/bin/init" --team "$_TEAM_FILE"
+            _NAMES=$(python3 -c "
+import tomllib, sys
+data = tomllib.loads(open('$_TEAM_FILE').read())
+names = list(data.get('session', {}).keys())
+print(' '.join(names))
+")
+            if [ -n "$_NAMES" ]; then
+                "$CLAUDES_HOME/bin/swarm" start $_NAMES >/dev/null 2>&1 || true
+                echo "OK 团队已启动: $_NAMES"
+            fi
+            exit 0 ;;
+        ui)         shift; exec "$CLAUDES_HOME/bin/board" tui ;;
         version|--version|-v) echo "cnb v${VERSION}"; exit 0 ;;
         help|--help|-h)
             printf "${B}${G}◆ cnb${N} ${D}v${VERSION}${N}\n"
@@ -27,64 +73,79 @@ if [ $# -gt 0 ]; then
             printf "  cnb                   开始（默认2位同学，AI大佬主题）\n"
             printf "  cnb 5                 5位同学\n"
             printf "  cnb pokemon           宝可梦主题\n"
-            printf "  cnb 5 pokemon         5位同学 + 宝可梦主题\n\n"
+            printf "  cnb 5 pokemon         5位同学 + 宝可梦主题\n"
+            printf "  cnb compose [file]    从配置文件启动团队\n\n"
             printf "  主题: ai animal food lang music myth pokemon space\n\n"
-            printf "  cnb status            团队面板\n"
-            printf "  cnb swarm [...]       管理后台同学\n"
-            printf "  cnb board [...]       消息/任务\n"
+            printf "  cnb ui                交互式团队面板\n"
+            printf "  cnb ps                列出 agent 状态\n"
+            printf "  cnb logs <name>       查看某个 agent 的消息历史\n"
+            printf "  cnb exec <name> \"msg\" 给某个 agent 发指令\n"
+            printf "  cnb stop <name>       停止某个 agent\n"
+            printf "  cnb doctor            健康检查\n\n"
+            printf "  cnb board [...]       底层消息/任务命令\n"
+            printf "  cnb swarm [...]       管理后台 agent\n"
             exit 0 ;;
     esac
 fi
 
-# ---- Start session: parse [number] [theme] in any order ----
-_NUM=2
-_THEME_IDX=6  # default: AI 大佬
+# ---- Compose mode: reuse existing team from config.toml ----
+if [ -f .claudes/config.toml ] && [ -f .claudes/board.db ]; then
+    _EXISTING=$(grep '^sessions' .claudes/config.toml | sed 's/sessions = \[//;s/\]//;s/"//g;s/,/ /g;s/  */ /g' | xargs)
+    if [ -n "$_EXISTING" ]; then
+        ME=$(echo "$_EXISTING" | cut -d' ' -f1)
+        WORKERS=$(echo "$_EXISTING" | cut -d' ' -f2-)
+        LABEL=$(grep '^prefix' .claudes/config.toml | cut -d'"' -f2)
+        _NUM=$(echo "$WORKERS" | wc -w | tr -d ' ')
+        "$CLAUDES_HOME/bin/swarm" start $WORKERS >/dev/null 2>&1 || true
+    fi
+else
+    # ---- Fresh start: parse [number] [theme] in any order ----
+    _NUM=2
+    _THEME_IDX=6  # default: AI 大佬
 
-_THEME_MAP="ai:6 animal:0 food:2 lang:1 music:5 myth:4 pokemon:7 space:3"
+    _THEME_MAP="ai:6 animal:0 food:2 lang:1 music:5 myth:4 pokemon:7 space:3"
 
-for arg in "$@"; do
-    if [[ "$arg" =~ ^[0-9]+$ ]]; then
-        _NUM="$arg"
-    else
-        _idx=$(echo "$_THEME_MAP" | tr ' ' '\n' | grep "^${arg}:" | cut -d: -f2)
-        if [ -n "$_idx" ]; then
-            _THEME_IDX="$_idx"
+    for arg in "$@"; do
+        if [[ "$arg" =~ ^[0-9]+$ ]]; then
+            _NUM="$arg"
         else
-            printf "${Y}未知参数: ${arg}${N}\n" >&2
-            echo "用法: cnb [数量] [主题]" >&2
-            echo "主题: ai animal food lang music myth pokemon space" >&2
-            exit 1
+            _idx=$(echo "$_THEME_MAP" | tr ' ' '\n' | grep "^${arg}:" | cut -d: -f2 || true)
+            if [ -n "$_idx" ]; then
+                _THEME_IDX="$_idx"
+            else
+                printf "${Y}未知参数: ${arg}${N}\n" >&2
+                echo "用法: cnb [数量] [主题]" >&2
+                echo "主题: ai animal food lang music myth pokemon space" >&2
+                exit 1
+            fi
         fi
-    fi
-done
-
-# ---- Theme data ----
-_THEMES=(
-    "panda otter fox raccoon bunny koala sloth penguin hamster hedgehog duck seal capybara alpaca corgi shiba husky kitten ferret quokka"
-    "python ruby rust go swift kotlin scala perl haskell erlang elixir clojure julia ocaml zig lua dart cobol lisp fortran"
-    "mochi waffle taco ramen sushi bagel pretzel dumpling cookie brownie churro crepe noodle tofu falafel burrito pancake donut nacho boba"
-    "nebula pulsar quasar comet aurora meteor nova orbit cosmos galaxy venus mars saturn pluto titan europa io ceres vega sirius"
-    "dragon phoenix griffin hydra kraken sphinx unicorn pixie goblin imp djinn yeti nymph chimera basilisk manticore cerberus minotaur golem banshee"
-    "jazz blues funk reggae disco punk grunge techno dubstep waltz tango salsa bossa swing opera gospel motown bebop ska hiphop"
-    "altman dario ilya lecun karpathy hassabis sutskever hinton bengio fei-fei ng zuck bezos nadella pichai musk huang lisa-su amodei jack-clark"
-    "pikachu charmander snorlax eevee jigglypuff mewtwo gengar squirtle bulbasaur vulpix psyduck togepi mudkip lucario gardevoir rayquaza mimikyu ditto zorua umbreon"
-)
-_LABELS=("小动物" "编程语言" "美食" "太空" "神话生物" "音乐风格" "AI 大佬" "宝可梦")
-
-[ "$_NUM" -lt 1 ] && _NUM=1
-[ "$_NUM" -gt 20 ] && _NUM=20
-
-LABEL="${_LABELS[$_THEME_IDX]}"
-ALL_NAMES=$(echo "${_THEMES[$_THEME_IDX]}" | tr ' ' '\n' | sort -R | head -n $((_NUM + 1)) | tr '\n' ' ' | sed 's/ $//')
-ME=$(echo "$ALL_NAMES" | cut -d' ' -f1)
-WORKERS=$(echo "$ALL_NAMES" | cut -d' ' -f2-)
-
-# ---- Init + start ----
-if [ ! -f .claudes/board.db ]; then
+    done
+
+    # ---- Theme data ----
+    _THEMES=(
+        "panda otter fox raccoon bunny koala sloth penguin hamster hedgehog duck seal capybara alpaca corgi shiba husky kitten ferret quokka"
+        "python ruby rust go swift kotlin scala perl haskell erlang elixir clojure julia ocaml zig lua dart cobol lisp fortran"
+        "mochi waffle taco ramen sushi bagel pretzel dumpling cookie brownie churro crepe noodle tofu falafel burrito pancake donut nacho boba"
+        "nebula pulsar quasar comet aurora meteor nova orbit cosmos galaxy venus mars saturn pluto titan europa io ceres vega sirius"
+        "dragon phoenix griffin hydra kraken sphinx unicorn pixie goblin imp djinn yeti nymph chimera basilisk manticore cerberus minotaur golem banshee"
+        "jazz blues funk reggae disco punk grunge techno dubstep waltz tango salsa bossa swing opera gospel motown bebop ska hiphop"
+        "altman dario ilya lecun karpathy hassabis sutskever hinton bengio fei-fei ng zuck bezos nadella pichai musk huang lisa-su amodei jack-clark"
+        "pikachu charmander snorlax eevee jigglypuff mewtwo gengar squirtle bulbasaur vulpix psyduck togepi mudkip lucario gardevoir rayquaza mimikyu ditto zorua umbreon"
+    )
+    _LABELS=("小动物" "编程语言" "美食" "太空" "神话生物" "音乐风格" "AI 大佬" "宝可梦")
+
+    [ "$_NUM" -lt 1 ] && _NUM=1
+    [ "$_NUM" -gt 20 ] && _NUM=20
+
+    LABEL="${_LABELS[$_THEME_IDX]}"
+    ALL_NAMES=$(echo "${_THEMES[$_THEME_IDX]}" | tr ' ' '\n' | sort -R | head -n $((_NUM + 1)) | tr '\n' ' ' | sed 's/ $//')
+    ME=$(echo "$ALL_NAMES" | cut -d' ' -f1)
+    WORKERS=$(echo "$ALL_NAMES" | cut -d' ' -f2-)
+
     printf "${D}初始化 .claudes/ ...${N}\n"
     "$CLAUDES_HOME/bin/init" $ALL_NAMES >/dev/null 2>&1
+    "$CLAUDES_HOME/bin/swarm" start $WORKERS >/dev/null 2>&1 || true
 fi
-"$CLAUDES_HOME/bin/swarm" start $WORKERS >/dev/null 2>&1 || true
 
 # ---- Slash commands (runtime, gitignored) ----
 CMD_DIR=".claude/commands"
@@ -108,7 +169,7 @@ cat > "$CMD_DIR/cs-history.md"   <<EOF
 运行 \`${BOARD} --as ${ME} log 50\`，把完整的消息历史展示给我。
 EOF
 cat > "$CMD_DIR/cs-update.md"    <<EOF
-运行 \`pip install --upgrade cnb\`，更新到最新版本。把结果告诉我，如果更新成功提醒用户重启 cnb 以生效。
+运行 \`pip install --upgrade claude-nb\`，更新到最新版本。把结果告诉我，如果更新成功提醒用户重启 cnb 以生效。
 EOF
 cat > "$CMD_DIR/cs-help.md"      <<EOF
 列出所有 /cs-* 命令：

package/bin/init

@@ -160,44 +160,6 @@ def _update_settings(project_dir: Path, claudes_home: Path) -> None:
     settings_path.write_text(json.dumps(settings, indent=2, ensure_ascii=False) + "\n")
 
 
-def _create_slash_commands(project_dir: Path, claudes_home: Path) -> None:
-    cmd_dir = project_dir / ".claude" / "commands"
-    cmd_dir.mkdir(parents=True, exist_ok=True)
-
-    board = f"{claudes_home}/bin/board"
-    swarm = f"{claudes_home}/bin/swarm"
-
-    commands = {
-        "cs-team": f"运行 `{swarm} status` 和 `{board} --as lead view`，用简洁的表格告诉我每个同学的状态。",
-        "cs-inbox": f"运行 `{board} --as lead inbox`，把收到的消息汇总给我。",
-        "cs-broadcast": f'把以下消息广播给所有同学：\n`{board} --as lead send all "$ARGUMENTS"`',
-        "cs-assign": f'把任务分配给指定同学。参数格式：<名字> <任务描述>\n解析 $ARGUMENTS，运行 `{board} --as lead send <名字> "<任务描述>"`',
-        "cs-kick": f"让指定同学下线。解析 $ARGUMENTS 拿到名字，运行 `{swarm} stop $ARGUMENTS`",
-        "cs-add": f"拉新同学上线。解析 $ARGUMENTS 拿到名字，运行 `{swarm} start $ARGUMENTS`",
-        "cs-log": f"查看指定同学最近的工作日志。解析 $ARGUMENTS 拿到名字，运行 `{board} --as lead view` 并重点关注该同学的状态和最近消息。",
-        "cs-stop": f"停掉所有后台同学。运行 `{swarm} stop`，告诉用户已全部下线。",
-        "cs-bugs": f"运行 `{board} --as lead bug list`，汇总当前所有 bug。",
-        "cs-history": f"运行 `{board} --as lead log 50`，把完整的消息历史展示给我。",
-        "cs-update": "运行 `pip install --upgrade cnb`，更新到最新版本。把结果告诉我，如果更新成功提醒用户重启 cnb 以生效。",
-        "cs-help": "列出所有 /cs-* 命令及用途：\n"
-        "- /cs-team — 看同学状态\n"
-        "- /cs-inbox — 查收消息\n"
-        "- /cs-broadcast <消息> — 广播\n"
-        "- /cs-assign <名字> <任务> — 派任务\n"
-        "- /cs-add <名字> — 拉同学上线\n"
-        "- /cs-kick <名字> — 让同学下线\n"
-        "- /cs-log <名字> — 看同学工作日志\n"
-        "- /cs-stop — 全部下线\n"
-        "- /cs-bugs — 看 bug 列表\n"
-        "- /cs-history — 查看完整消息历史\n"
-        "- /cs-update — 更新到最新版\n"
-        "- /cs-help — 本帮助",
-    }
-
-    for name, content in commands.items():
-        (cmd_dir / f"{name}.md").write_text(content + "\n")
-
-
 DEFAULT_SESSIONS = ["s1", "s2", "s3"]
 
 
@@ -286,7 +248,7 @@ def main() -> None:
         persona = personas.get(n, "")
         conn.execute("INSERT OR IGNORE INTO sessions(name, persona) VALUES (?, ?)", (n, persona))
         persona_section = f"\n## Persona\n{persona}\n" if persona else ""
-        md_content = f"# {n}\n{persona_section}\n## Current task\n(none)\n\n## @inbox\n"
+        md_content = f"# {n}\n{persona_section}\n## Current task\n(none)\n"
         (claudes_dir / "sessions" / f"{n}.md").write_text(md_content)
     conn.execute("INSERT OR IGNORE INTO meta(key, value) VALUES ('dispatcher_session', 'dispatcher')")
     # Record schema version so migration runner knows where we are
@@ -308,6 +270,10 @@ def main() -> None:
     # Update .claude/settings.json (merge hooks if exists, create if not)
     _update_settings(project_dir, claudes_home)
 
+    # Write multi-agent coordination section into CLAUDE.md
+    snippet = _claude_md_snippet(sessions, claudes_home, personas)
+    _update_claude_md(project_dir, snippet)
+
     sessions_str = " ".join(sessions)
     print(f"Initialized cnb (sessions: {sessions_str})")