@vincentkoc/multicodex 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +153 -0
  2. package/dist/cli.mjs +1560 -0
  3. package/package.json +63 -0
package/README.md ADDED
@@ -0,0 +1,153 @@
1
+ # MultiCodex
2
+
3
+ MultiCodex is a self-contained multiplayer control room for normal local Codex
4
+ sessions. One person hosts the room and conductor. Everyone else joins with
5
+ their own Codex installation, authentication, repository, tools, and local
6
+ terminal.
7
+
8
+ The browser shows a live structured view of each lane and gives the host
9
+ visible, policy-controlled coordination actions. It does not proxy a raw
10
+ terminal or answer local Codex approvals.
11
+
12
+ ## Quickstart
13
+
14
+ Requirements:
15
+
16
+ - Node.js 22.13 or newer
17
+ - a working `codex` CLI
18
+ - the same repository available on each participant machine
19
+
20
+ Start a room from the repository:
21
+
22
+ ```bash
23
+ npx --yes @vincentkoc/multicodex@latest doctor
24
+ npx --yes @vincentkoc/multicodex@latest host --repo . --title "OpenAI event build"
25
+ ```
26
+
27
+ Open the printed control URL. Use **add a person** to copy a named invite
28
+ command:
29
+
30
+ ```bash
31
+ npx --yes @vincentkoc/multicodex@latest join '<invite-url>' \
32
+ --repo . \
33
+ --name Queenie \
34
+ --policy suggest
35
+ ```
36
+
37
+ The join command launches a normal local Codex TUI. Running the same command
38
+ again resumes the same MultiCodex lane and Codex thread. Add `--fresh` only to
39
+ create a new lane intentionally.
40
+
41
+ ## Multi-Machine Rooms
42
+
43
+ The host binds to loopback by default. For a trusted LAN, Tailscale network, or
44
+ tunnel, bind a reachable interface and advertise the participant-facing URL:
45
+
46
+ ```bash
47
+ npx --yes @vincentkoc/multicodex@latest host \
48
+ --repo . \
49
+ --bind 0.0.0.0 \
50
+ --public-url https://multicodex.example
51
+ ```
52
+
53
+ `--public-url` can point at a LAN/Tailscale address or a temporary tunnel. The
54
+ room server and conductor still run on the host machine.
55
+
56
+ ## What The Host Can Do
57
+
58
+ The control room keeps the team rail, selected lane activity, and conductor
59
+ conversation visible together.
60
+
61
+ - add people with named copyable invite commands;
62
+ - remove a lane and revoke its capability;
63
+ - inspect coalesced messages, plans, commands, file changes, approvals, and
64
+ turn state;
65
+ - ask the host-local conductor a room question;
66
+ - send a visible suggestion;
67
+ - request status;
68
+ - start a follow-up Codex turn;
69
+ - steer an active turn;
70
+ - interrupt an active turn.
71
+
72
+ Every action is checked against the participant's local policy:
73
+
74
+ | Policy | Suggest | Status | Follow-up | Steer | Interrupt |
75
+ | --------- | ------- | ------ | --------- | ----- | --------- |
76
+ | `observe` | no | no | no | no | no |
77
+ | `suggest` | yes | yes | no | no | no |
78
+ | `steer` | yes | yes | yes | yes | yes |
79
+
80
+ The host cannot answer local command, file, network, or permission approvals.
81
+
82
+ ## Security Model
83
+
84
+ MultiCodex creates separate random capabilities for the host browser, room
85
+ invite, and each lane.
86
+
87
+ - The host capability protects conductor controls and participant removal.
88
+ - The invite capability creates new lanes.
89
+ - A lane capability resumes one lane, publishes its events, and receives its
90
+ permitted commands.
91
+ - Removing a lane revokes its capability and disconnects its managed bridge.
92
+ - Capabilities do not appear in public room snapshots.
93
+ - The participant's Codex app-server always binds to loopback.
94
+ - Repository contents, credentials, hidden reasoning, and complete terminal
95
+ streams are not published.
96
+
97
+ Room and lane state is written under `.multicodex/` with owner-only
98
+ permissions.
99
+
100
+ ## Repository Development
101
+
102
+ Run the CLI directly from this repository:
103
+
104
+ ```bash
105
+ pnpm install
106
+ pnpm multicodex doctor
107
+ pnpm multicodex host --repo .
108
+ ```
109
+
110
+ Use the printed `dev join` command for a second terminal. The production-style
111
+ join command uses `npx --yes @vincentkoc/multicodex@latest`.
112
+
113
+ Checks:
114
+
115
+ ```bash
116
+ pnpm check
117
+ pnpm build
118
+ npm pack --dry-run
119
+ ```
120
+
121
+ ## Architecture
122
+
123
+ ```text
124
+ Host browser -> host capability -> multicodex host
125
+ |- local HTTP room server + durable state
126
+ |- ACPx persistent conductor
127
+ `- visible lane command router
128
+
129
+ multicodex join -> lane capability -> room server
130
+ |
131
+ |- local event spool and policy enforcement
132
+ |- loopback Codex app-server
133
+ `- normal local Codex TUI
134
+ ```
135
+
136
+ Crabfleet, Crabbox, server OpenAI keys, server GitHub tokens, and hosted
137
+ terminals are not required by the self-contained product.
138
+
139
+ The repository still contains the earlier Cloudflare/Crabfleet event-room
140
+ implementation while the local-first replacement lands. It is not the default
141
+ MultiCodex runtime.
142
+
143
+ ## Legacy Worker Development
144
+
145
+ The earlier Worker product remains testable during replacement:
146
+
147
+ ```bash
148
+ pnpm db:local
149
+ pnpm dev
150
+ ```
151
+
152
+ `pnpm dev` enables simulation only for the local Wrangler process. Production
153
+ keeps simulation explicitly disabled.