Merge pull request #1 from Incultnitollc/feat/v0.1.0-implementation

v0.1.0: initial implementation

Author: PengSpirit

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        node: [20, 22]
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npx tsc --noEmit
+      - run: npx eslint . --quiet
+      - run: npx vitest run --coverage
+      - run: npm run build
+      - run: node ./dist/bin/cc-bridge.js --version
+      - run: npx tsx tests/manual/two-windows.ts
+      - run: npm audit --audit-level=high

.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+coverage/
+.DS_Store
+*.log
+.env
+.env.local
+.vitest-tmp/

.npmignore

@@ -0,0 +1,11 @@
+src/
+tests/
+docs/
+.github/
+coverage/
+*.config.ts
+*.config.js
+.eslintrc*
+.prettierrc*
+tsconfig.json
+.gitignore

.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Incultnito LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,93 @@
+# @incultnitollc/cc-bridge
+
+> Live JSONL message bridge between local Claude Code sessions.
+
+Two (or more) Claude Code windows on the same machine. They need to talk in real time. `cc-bridge` gives each session a CLI to **send** a message to a shared file and **listen** for new messages via a file-tail stream that Claude's `Monitor` tool consumes as live push notifications. No daemon, no network, no polling.
+
+## Install
+
+```bash
+npm install -g @incultnitollc/cc-bridge
+```
+
+Requires Node ≥ 20.
+
+## Quickstart — two windows
+
+**Window A:**
+```bash
+cc-bridge listen
+```
+
+**Window B:**
+```bash
+cc-bridge send "hello from B"
+```
+
+Window A immediately receives the JSONL line.
+
+## Inside Claude Code
+
+In each session, run the listen command under the `Monitor` tool so every appended line arrives as a live push notification — no polling.
+
+```
+Monitor: cc-bridge listen default
+```
+
+Then send from the other window via the `Bash` tool:
+
+```
+Bash: cc-bridge send "ready for review"
+```
+
+## Concepts
+
+- **Room** — a named JSONL file under `~/.cc-bridge/rooms/<room>.jsonl`. Default room is `default`. Names allowed: `[a-zA-Z0-9_.-]{1,64}`.
+- **Session id** — auto-generated `<host>-<ppid>-<rand8>` (parent shell PID, so two windows differ naturally). Override with `CC_BRIDGE_FROM=...`.
+- **Message** — single-line JSON. Required: `v, id, ts, room, from, msg`. Optional: `to, reply_to, kind`. Unknown fields preserved for forward-compat.
+
+## Commands
+
+```bash
+cc-bridge listen [room] [--replay N] [--pretty] [--filter from=X] [--from ID] [--json-errors]
+cc-bridge send <msg> [--room R] [--to ID] [--reply-to ULID] [--kind text|event] [--from ID]
+echo "hi" | cc-bridge send       # reads from stdin if piped
+cc-bridge rooms                  # list rooms with size + mtime
+cc-bridge rooms clear <room> --yes
+cc-bridge validate <file>        # lint a JSONL room file
+cc-bridge --version
+cc-bridge --help
+```
+
+## Library use
+
+```ts
+import { sendMessage, listen, listRooms } from '@incultnitollc/cc-bridge'
+
+await sendMessage({ from: 'planner', room: 'team', msg: 'kicking off build' })
+
+const ctrl = listen({ room: 'team', sessionId: 'reviewer' })
+for await (const ev of ctrl.iterator) {
+  if (ev.ok) console.log(ev.line)
+}
+```
+
+## Security model
+
+`cc-bridge` is a **local-host IPC primitive**. The trust boundary is your user account. Do not place `~/.cc-bridge/` on a shared filesystem, network drive, or cloud-synced directory.
+
+- Files in `~/.cc-bridge/` are created with mode `0700` (dir) / `0600` (files).
+- Room names sanitized; path traversal refused.
+- Symlinks at room paths refused.
+- 64KB per-message cap. 10MB room file soft-warn; 100MB hard-refuse.
+- `--pretty` strips ANSI escape sequences to prevent terminal hijack.
+- The `from` field is sender-asserted (no signature). v1 explicitly trusts everyone with write access to your `$HOME`.
+
+## Roadmap
+
+- **v1.1** — `cc-bridge install-hooks` (auto-wire Claude Code Stop/UserPromptSubmit hooks), DM filtering (`--me`), time-based replay (`--replay 1h`), read receipts, Windows support.
+- **v2** — MCP server wrapper, cross-machine backend (Supabase Realtime / Redis), webhook fanout, observer dashboard.
+
+## License
+
+MIT © 2026 Incultnito LLC.

docs/superpowers/specs/2026-06-02-claude-code-live-bridge-design.md

@@ -174,6 +174,14 @@ cc-bridge listen
 
 **Offset state:** saved to `~/.cc-bridge/state/<room>-<sessionId>.offset` so `listen` can resume after SIGINT without re-replaying. Stale state for vanished sessions is reaped during `cc-bridge rooms` runs (best-effort, non-fatal).
 
+### 6.3 Watcher Mode — Polling Decision (v0.1.0)
+
+The listen module's chokidar watcher was originally configured with `usePolling: false` (native FSEvents on darwin, inotify on linux). Under chokidar 4.x on macOS, `change` events from FSEvents fire unreliably for our local append-only JSONL workload — tests timed out waiting for events that arrived 5+ seconds late or not at all. Switched to `usePolling: true, interval: 50` for v0.1.0.
+
+**Tradeoff:** ~50ms latency floor on message delivery (negligible for human-driven Claude Code IPC), and constant low background `fs.stat` load (one syscall per room being listened to per 50ms — bounded by number of active sessions, not by message rate).
+
+**Revisit if:** (a) chokidar 4 fixes FSEvents reliability, or (b) profiling shows polling overhead matters at scale. Not a v1.1 priority.
+
 ## 7. Security Model
 
 **Threat model:** local-host IPC only. Same user, same machine. Trust boundary = the user account. This is NOT a network protocol. README states this explicitly.

eslint.config.js

@@ -0,0 +1,17 @@
+import js from '@eslint/js'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      'no-console': 'off',
+    },
+  },
+  {
+    ignores: ['dist/**', 'coverage/**', 'node_modules/**'],
+  },
+)