@logicseek/hello-cc 0.1.0

package/docs/design.md

@@ -0,0 +1,263 @@
+# hello-cc Design
+
+Date: 2026-06-09
+
+## Requirement Boundary
+
+hello-cc targets same-project, cross-session coordination for ordinary local
+terminal sessions:
+
+- multiple Claude Code sessions;
+- multiple Codex CLI sessions;
+- sessions started independently from different terminals;
+- durable tasks, messages, locks, handoffs, and events;
+- conflict visibility while peers edit the same project;
+- LAN web observability and terminal operation.
+
+This is not only "Claude talks to Codex". It is a local coordination layer for
+all active coding CLI sessions in one project.
+
+The model is a flat peer mesh, not a CCB-style main/worker topology:
+
+```text
+codex-a  <->  codex-b
+   ^            ^
+   |            |
+claude-a <-> claude-b
+```
+
+Every session is a named peer. Optional labels such as `reviewer`, `runner`, or
+`docs` may help humans route work, but they do not create hierarchy.
+
+## Project Boundary
+
+By default, "same project" means the exact current working directory. On first
+use hello-cc creates:
+
+```text
+<cwd>/.hello-cc/mesh.db
+```
+
+It does not automatically walk to parent directories and inherit their bus. This
+keeps project membership predictable: two terminals communicate automatically
+when they are started from the same project path.
+
+Cross-path sharing is explicit:
+
+```bash
+hcc --root /path/to/project web
+export HCC_ROOT=/path/to/project
+export HCC_DB=/path/to/project/.hello-cc/mesh.db
+```
+
+## Default UX
+
+The default user path is one command:
+
+```bash
+cd /path/to/project
+hcc web
+```
+
+`hcc web` must:
+
+- initialize the project-local SQLite bus;
+- install or refresh Claude Code hooks;
+- install or refresh Codex hooks;
+- install or refresh `claude` and `codex` shell shims;
+- add the shim directory to PATH when needed;
+- ensure `tmux` is available, with best-effort automatic install and a clear
+  install command if it cannot install;
+- start the web runtime in the background;
+- print URL, PID, runtime path, log path, and stop command;
+- return control to the invoking terminal.
+
+Plain `claude` and `codex` commands in a new shell should then become
+tmux-backed hello-cc peers automatically. The local terminal attaches to the
+same tmux session that the web console can display and operate.
+
+`hcc up` remains a lower-level command for local coordination without Web or
+shims. Maintenance commands may exist for tests and manual cleanup, but they are
+not the public product path.
+
+## Capability Levels
+
+```text
+Level 1: Coordination
+  Any Claude/Codex/human terminal can communicate by running hcc commands or by
+  firing installed hooks. This covers tasks, messages, locks, handoffs, and
+  status.
+
+Level 2: Web-attached local terminals
+  hello-cc starts Claude/Codex/shell as local tmux-backed terminals, wraps
+  direct claude/codex launches through shims, or attaches an existing tmux pane.
+  The web UI displays and operates those terminals through WebSocket.
+
+Level 3: Existing raw terminal takeover
+  A terminal already opened outside hello-cc cannot be fully captured or
+  controlled unless it is already inside tmux, screen, or another attachable PTY
+  layer. It can still participate in coordination.
+```
+
+`hcc down` stops only the web runtime. It does not kill tmux-backed terminals.
+Running `hcc web` again reattaches live recorded panes.
+
+## Technical Route
+
+Recommended first layer:
+
+```text
+Node npm CLI
+  + built-in node:sqlite
+  + project-local .hello-cc/mesh.db
+  + Claude/Codex hooks for prompt-time context
+  + tmux as the browser-controllable local terminal backend
+  + shell shims for transparent claude/codex launch
+```
+
+Why:
+
+- ordinary terminals can join;
+- no MCP requirement for local communication;
+- no A2A requirement for local terminal/worktree coordination;
+- SQLite transactions are enough for low-volume coordination writes;
+- Node gives a natural npm CLI packaging path;
+- Node 24 has built-in SQLite;
+- tmux gives persistent local terminals that survive web runtime restarts.
+
+Rejected as the first layer:
+
+- A2A: useful for remote peer interoperability, not required for local terminal
+  coordination.
+- MCP-only: useful later as a tool surface, but too indirect for transparent
+  cross-session operation.
+- tmux-only: good for managed terminals, but hooks and CLI commands are still
+  needed for already-open raw sessions.
+- shared markdown/jsonl files: simple, but weak for atomic task claims and lock
+  acquisition.
+
+## Runtime Framework
+
+```text
+Node >= 24
+node:sqlite DatabaseSync
+SQLite WAL
+Node HTTP server
+ws WebSocket
+xterm.js browser renderer
+tmux create/capture/send for terminal control
+Claude Code hooks
+Codex hooks
+shell shim wrappers
+```
+
+Control plane:
+
+```text
+CLI commands and HTTP JSON APIs read/write SQLite.
+```
+
+Terminal plane:
+
+```text
+Browser xterm.js sends keyboard bytes over WebSocket.
+Server writes bytes into tmux panes.
+Server polls/captures tmux pane output and broadcasts it to browsers.
+```
+
+## Core Tables
+
+```text
+peers         stable terminal identities and heartbeat
+peer_bindings provider session binding and runtime transport metadata
+tasks         task assignment, ownership, and lifecycle
+messages      direct or broadcast messages
+message_reads per-peer ack state
+locks         advisory exclusive locks with TTL
+handoffs      durable cross-session handoff summaries
+events        audit trail for observability
+```
+
+## Coordination Semantics
+
+- `task claim`, `task next`, `lock acquire`, `lock release`, and `handoff
+  create` use `BEGIN IMMEDIATE`.
+- SQLite runs with WAL and `busy_timeout=5000`.
+- Tasks are project facts. They remain visible to all peers until status becomes
+  `done` or `abandoned`.
+- Messages are addressed mailbox items. Read state is tracked per peer.
+- Broadcast messages use per-peer acknowledgement, so one peer cannot consume a
+  message for everyone else.
+- Locks are advisory and TTL-based. Peers must follow the protocol.
+
+## Hook Path
+
+The primary model-facing path is hook context injection, not project markdown.
+
+`hcc web` installs hooks that register sessions and inject hello-cc snapshots at
+session start and before model answers. The injected snapshot contains current
+peer identity, active peers, open tasks, unread messages, active locks, and the
+commands the model should use to inspect state.
+
+`CLAUDE.md`, `AGENTS.md`, and `.hello-cc/HCC.md` are fallback instruction
+layers. Existing root files are updated only inside a bounded hello-cc block.
+
+## Provider Session Binding
+
+hello-cc peer IDs are separate from Claude/Codex conversation IDs:
+
+```text
+peer:                 codex-a
+provider:             codex
+provider_session_id:  Codex/Claude resume id or name when known
+resume_mode:          new | resume | last | continue | fork | fork-resume
+transport:            tmux | hcc-run | detected | optional pty
+```
+
+Known resume IDs map to stable peer IDs. Launch modes that do not expose the
+real provider session before startup use a terminal-derived peer ID first, then
+hooks or discovery record provider metadata after the session starts.
+
+`hcc peer start` records bindings when it launches or reuses a tmux-backed
+terminal:
+
+```bash
+hcc peer start codex-a --kind codex --resume <session-id-or-name>
+hcc peer start codex-b --kind codex --last
+hcc peer start claude-a --kind claude --resume <session-id>
+hcc peer start claude-b --kind claude --continue
+```
+
+`hcc peer attach` records a tmux transport binding when it imports an existing
+pane:
+
+```bash
+hcc peer attach codex-a --pane %1
+```
+
+If a known provider session is already bound to another peer, hello-cc blocks a
+second binding unless `--force` is used.
+
+## Applied Lessons
+
+- `claude_codex_bridge` proves tmux-backed mixed-provider workspaces are useful,
+  but hello-cc avoids fixed main/worker topology.
+- `hcom` proves local SQLite plus hooks is a strong cross-session communication
+  model.
+- `squad` proves a project-local mailbox/task protocol can stay transparent and
+  easy to operate.
+- `dmux` proves npm CLI plus worktree/session management is a good outer layer,
+  but it is not itself the communication bus.
+- `agent-bus` has strong bus semantics, but its primary integration path is MCP.
+
+hello-cc combines hooks + SQLite + tmux first, leaving MCP/A2A/worktree layers
+optional.
+
+## Next Iterations
+
+1. Harden hook payloads for lock warnings and handoff reminders.
+2. Add a watch command for live inbox/event tailing.
+3. Add terminal output snapshot/export commands for runtime-attached sessions.
+4. Add screen attach support for already-running attachable sessions.
+5. Publish as an npm package with a stable `npx hcc` flow.
+6. Add worktree helpers only after the core bus and terminal model are stable.

package/docs/implementation.md

@@ -0,0 +1,345 @@
+# hello-cc Implementation Plan
+
+Date: 2026-06-09
+
+## Product Requirement
+
+hello-cc is a project-local peer mesh for coding CLI sessions. It connects
+multiple Claude Code and Codex terminals in the same project so they can
+communicate, coordinate work, avoid conflicts, hand off progress, and be
+operated through a LAN web UI.
+
+Default project identity is the exact current working directory. On first use,
+hello-cc creates `<cwd>/.hello-cc/mesh.db`; it does not inherit a parent
+directory's mesh automatically. Users who want several paths or worktrees to
+share one bus must set `--root`, `HCC_ROOT`, or `HCC_DB` explicitly.
+
+The model is flat:
+
+```text
+codex-a  <->  codex-b
+   ^            ^
+   |            |
+claude-a <-> claude-b
+```
+
+There is no required `main`, `worker`, or `reviewer`. Every session is a peer.
+
+## Target UX
+
+The default user experience is:
+
+```bash
+cd /path/to/project
+hcc web
+```
+
+Expected output:
+
+```text
+hello-cc web started in background
+pid: 12345
+project: /path/to/project
+database: /path/to/project/.hello-cc/mesh.db
+runtime: /path/to/project/.hello-cc/runtime.json
+log: /path/to/project/.hello-cc/web.log
+open: http://<machine-ip>:8787/?token=xxxxx
+local: http://127.0.0.1:8787/?token=xxxxx
+shims: installed claude, codex
+PATH updated in ~/.bashrc; open a new terminal or source it
+stop: hcc down
+```
+
+`hcc web` is responsible for bootstrap and runtime startup:
+
+- project-local SQLite bus;
+- bounded guidance files;
+- Claude Code hooks;
+- Codex hooks;
+- `claude` and `codex` shell shims;
+- shell PATH entry for the shims;
+- tmux availability;
+- background web runtime.
+
+After that, opening a new shell and typing `claude` or `codex` should create or
+reuse a tmux-backed local terminal. The user interacts in the local terminal,
+and the web console can operate the same tmux pane. `hcc down` stops the web
+runtime only and leaves tmux terminals alive.
+
+`hcc up` remains a lower-level local coordination command. Maintenance commands
+remain available for tests and manual recovery, but the public product path is
+`hcc web`.
+
+## Architecture
+
+hello-cc is session-runtime-first:
+
+```text
+hcc CLI
+  |
+  +-- neutral web runtime
+  |     |
+  |     +-- peer registry
+  |     +-- routing and injection
+  |     +-- task / message / lock / handoff services
+  |     +-- tmux terminal supervisor
+  |
+  +-- control plane
+  |     |
+  |     +-- SQLite WAL
+  |     +-- HTTP REST
+  |     +-- hook entrypoints
+  |
+  +-- terminal plane
+        |
+        +-- tmux adapter
+        +-- shell shims
+        +-- optional node-pty adapter
+        +-- WebSocket terminal stream
+        +-- xterm.js web terminal
+```
+
+The runtime is not a main peer. It is a neutral router and state machine.
+
+## Core Protocol
+
+Peers:
+
+```text
+id          codex-a, claude-a, shell-a
+kind        codex | claude | shell | custom
+tags        optional routing labels
+transport   tmux | hcc-run | detected | optional pty
+target      tmux pane id or optional pty session id
+status      idle | busy | blocked | stale | exited
+```
+
+Messages:
+
+```text
+from peer
+to peer | all | tag:<tag> | task:<task-id>
+kind note | ask | handoff | system
+delivery store-only | inject-terminal | both
+```
+
+Tasks:
+
+```text
+pending -> claimed -> running -> review/block/done|abandoned
+owner is dynamic; there is no fixed dispatcher
+```
+
+Default task reads are lifecycle-based: all peers see tasks until they are
+`done` or `abandoned`. Read/ack state exists only for messages.
+
+Locks:
+
+```text
+resource -> owner peer
+TTL-based advisory lock
+resource can be file, directory, module, test env, GPU, or service port
+```
+
+## User-Facing Commands
+
+Primary:
+
+```bash
+hcc web
+hcc down
+```
+
+Coordination:
+
+```bash
+hcc peers
+hcc status
+hcc task create/list/claim/next/update/done
+hcc msg send/inbox/ack
+hcc lock acquire/renew/release/list
+hcc handoff create/list
+hcc event tail
+hcc ask
+hcc broadcast
+```
+
+Terminal control:
+
+```bash
+hcc peer list
+hcc peer start codex-a --kind codex -- codex
+hcc peer start codex-a --kind codex --resume <session-id-or-name>
+hcc peer start codex-a --kind codex --last
+hcc peer start claude-a --kind claude --resume <session-id>
+hcc peer start claude-a --kind claude --continue
+hcc peer attach codex-a --pane %1
+hcc peer stop codex-a
+hcc inject codex-a "hcc msg inbox --peer codex-a"
+```
+
+Lower-level:
+
+```bash
+hcc up
+hcc run --peer codex-a --kind codex -- codex
+```
+
+`hcc run` registers and runs a command in the current terminal. Browser
+control should use `hcc peer start`, the web UI, or the installed shims.
+
+## Technical Stack
+
+Runtime and CLI:
+
+```text
+Node.js >= 24
+node:sqlite
+local option parser
+```
+
+State:
+
+```text
+SQLite WAL
+project-local DB
+busy_timeout for concurrent CLI access
+BEGIN IMMEDIATE for task claim and lock acquisition
+```
+
+Terminal control:
+
+```text
+tmux
+tmux send-keys
+tmux load-buffer / paste-buffer
+tmux capture-pane
+tmux attach-session / switch-client
+node-pty optional internal backend
+```
+
+Web:
+
+```text
+Node HTTP server
+ws WebSocket
+xterm.js
+token authentication for LAN access
+```
+
+Integrations:
+
+```text
+Claude Code hooks
+Codex hooks
+UserPromptSubmit additionalContext
+SessionStart additionalContext
+shell shim wrappers
+```
+
+## Shim Behavior
+
+`hcc web` installs shims into `~/.hcc-shims`. Each shim:
+
+1. Resolves the hello-cc project root from the current directory or `HCC_ROOT`.
+2. Parses provider resume/session arguments for a stable peer ID.
+3. Exports `HCC_PEER` and `HCC_ROOT`.
+4. Ensures the web runtime is running.
+5. Calls `hcc peer start <peer> --kind <kind> -- <real-binary> ...`.
+6. Attaches the local terminal to the tmux session returned by `peer start`.
+
+If the shim is invoked non-interactively, it prints the `peer start` output and
+does not attach.
+
+## Reference Projects
+
+### claude_codex_bridge
+
+Path:
+
+```text
+<checkout>/claude_codex_bridge
+```
+
+Use for tmux session ownership, pane registry, injection with `send-keys` /
+`load-buffer` / `paste-buffer`, output capture, and recoverable visible CLI
+workspaces. Do not copy fixed main/worker topology or role-pack assumptions.
+
+### hcom
+
+Use for local SQLite + hooks communication and live cross-session notification
+ideas.
+
+### squad
+
+Use for project-local mailbox/task ergonomics.
+
+### dmux
+
+Use for npm CLI UX and optional worktree/session management ideas.
+
+### agent-bus
+
+Use for richer task/message/handoff/review semantics. MCP remains optional.
+
+## Implementation Phases
+
+Phase 1: current protocol
+
+```text
+SQLite bus
+flat peer identities
+task/message/lock/handoff/event
+run wrapper
+tmux-backed peer start
+tmux pane attach
+```
+
+Phase 2: default bootstrap
+
+```text
+hcc web as the one-command entrypoint
+hooks installed by default
+shims installed by default
+tmux ensured by default
+background web runtime
+```
+
+Phase 3: terminal hardening
+
+```text
+create or reuse tmux-backed local terminal with hcc peer start
+attach existing tmux pane with hcc peer attach
+record peer -> pane_id
+inject via send-keys
+capture output via capture-pane
+detach without killing user panes
+```
+
+Phase 4: direct CLI ergonomics
+
+```text
+plain claude/codex auto-start tmux-backed peers
+resume/fork/continue-aware peer identity
+hooks for prompt-time snapshots, heartbeat, lock reminders, and handoff reminders
+```
+
+Phase 5: hardening
+
+```text
+stale session recovery
+token and access controls
+audit log
+worktree isolation
+merge queue
+MCP adapter only if useful
+A2A adapter only for remote/server peers
+```
+
+## Non-Goals For The Core
+
+- No required MCP setup.
+- No required A2A protocol.
+- No fixed main/worker hierarchy.
+- No attempt to invisibly control a raw existing terminal that was not started
+  by hello-cc, tmux, screen, or another attachable PTY layer.