opencode-multiplexer 0.2.0 → 0.2.2
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.
- package/README.md +76 -43
- package/docs/output1.gif +0 -0
- package/docs/output2.gif +0 -0
- package/docs/output3.gif +0 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,38 +1,58 @@
|
|
|
1
|
-
# OpenCode Multiplexer
|
|
1
|
+
# OCMux — OpenCode Multiplexer
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/opencode-multiplexer)
|
|
4
|
+
[](#requirements)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
[](https://opencode.ai)
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
A terminal multiplexer for [opencode](https://opencode.ai) AI coding agent sessions.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
**Run multiple opencode sessions across different projects from one fast, focused dashboard**—see which agents are working, idle, blocked on your input, or failing, then jump into the right session instantly.
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
When you're juggling several repositories at once, OCMux removes the friction of switching panes, losing context, and missing the moment an agent needs you.
|
|
10
13
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
14
|
+
## Demo
|
|
15
|
+
|
|
16
|
+
### Instantly see your current sessions and attach to existing work
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
> OCMux stays responsive to your existing working sessions and lets you attach to them without hunting through terminal panes.
|
|
21
|
+
|
|
22
|
+
### Track agent status, subagents, and sessions that need your attention
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
> Live status indicators show whether an agent is working, idle, or waiting on you. You can also inspect subagents and attach to them directly.
|
|
27
|
+
|
|
28
|
+
### Start new sessions or kill existing ones without leaving the dashboard
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
> Spawn a new session, jump into it immediately, or terminate a session right from OCMux.
|
|
19
33
|
|
|
34
|
+
## Install
|
|
20
35
|
|
|
21
|
-
|
|
36
|
+
### Requirements
|
|
22
37
|
|
|
23
38
|
- [Bun](https://bun.sh) runtime
|
|
24
39
|
- [opencode](https://opencode.ai) installed and available on `PATH`
|
|
25
40
|
- macOS or Linux
|
|
26
41
|
- Optional: [fzf](https://github.com/junegunn/fzf) for the folder picker when spawning new sessions
|
|
27
42
|
|
|
28
|
-
|
|
29
|
-
## Installation
|
|
43
|
+
### Install from npm
|
|
30
44
|
|
|
31
45
|
```bash
|
|
46
|
+
# install
|
|
32
47
|
npm install -g opencode-multiplexer
|
|
48
|
+
|
|
49
|
+
# to run, run
|
|
50
|
+
ocmux
|
|
51
|
+
# or
|
|
52
|
+
opencode-multiplexer
|
|
33
53
|
```
|
|
34
54
|
|
|
35
|
-
|
|
55
|
+
### Run from source
|
|
36
56
|
|
|
37
57
|
```bash
|
|
38
58
|
git clone https://github.com/joeyism/opencode-multiplexer
|
|
@@ -41,21 +61,38 @@ bun install
|
|
|
41
61
|
bun src/index.tsx
|
|
42
62
|
```
|
|
43
63
|
|
|
64
|
+
## Features
|
|
65
|
+
|
|
66
|
+
OCMux gives you a single TUI for managing several opencode sessions at once.
|
|
67
|
+
|
|
68
|
+
- Dashboard view showing all running opencode sessions with live status indicators (working, needs input, idle, error)
|
|
69
|
+
- Expandable subagent tree per session, showing what child agents are running and their status
|
|
70
|
+
- Read conversation history for any session without attaching to it
|
|
71
|
+
- Send messages directly to sessions spawned via OCMux (which run a background HTTP server)
|
|
72
|
+
- Cycle through agent modes (Orchestrator, Chat, Code) and models per session
|
|
73
|
+
- Spawn new sessions with a folder picker, attaching immediately to the new session
|
|
74
|
+
- Kill instances directly from the dashboard
|
|
75
|
+
- Vim-style navigation throughout (`j`/`k`, `Ctrl-U`/`Ctrl-D`, `G`/`gg`)
|
|
76
|
+
|
|
77
|
+
## Usage
|
|
44
78
|
|
|
45
|
-
|
|
79
|
+
### Overview
|
|
80
|
+
|
|
81
|
+
When working with several opencode sessions simultaneously across different repositories, switching between terminal panes and losing track of which agent needs attention becomes a friction point. OCMux addresses this by providing a single TUI that aggregates all running opencode instances, shows their real-time status, and lets you jump between them efficiently.
|
|
82
|
+
|
|
83
|
+
### How it works
|
|
46
84
|
|
|
47
85
|
OCMux discovers opencode instances in two ways:
|
|
48
86
|
|
|
49
|
-
**Existing sessions** (started outside OCMux): OCMux scans for running `opencode` processes using `ps`, identifies their working directories, and matches them to sessions in the shared opencode SQLite database at `~/.local/share/opencode/opencode.db`. These sessions are read-only in OCMux
|
|
87
|
+
**Existing sessions** (started outside OCMux): OCMux scans for running `opencode` processes using `ps`, identifies their working directories, and matches them to sessions in the shared opencode SQLite database at `~/.local/share/opencode/opencode.db`. These sessions are read-only in OCMux — you can view the conversation history, but to send messages you must attach to the TUI.
|
|
50
88
|
|
|
51
89
|
**Spawned sessions** (started via OCMux): When you create a new session from within OCMux, it starts `opencode serve --port X` as a background process. This exposes an HTTP API that OCMux uses to send messages directly, cycle agent modes, and list available models. The session persists after you leave the conversation view.
|
|
52
90
|
|
|
53
91
|
The dashboard polls every 2 seconds and updates status indicators automatically.
|
|
54
92
|
|
|
93
|
+
### Dashboard
|
|
55
94
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
```
|
|
95
|
+
```text
|
|
59
96
|
OCMux
|
|
60
97
|
[Orchestrator] opus-4-6 [NORMAL] 73%
|
|
61
98
|
─────────────────────────────────────────────────────────────────────────
|
|
@@ -66,7 +103,7 @@ The dashboard polls every 2 seconds and updates status indicators automatically.
|
|
|
66
103
|
k/j: nav Enter: open Tab: expand a: attach x: kill n: new q: quit
|
|
67
104
|
```
|
|
68
105
|
|
|
69
|
-
Status indicators
|
|
106
|
+
#### Status indicators
|
|
70
107
|
|
|
71
108
|
| Symbol | Meaning |
|
|
72
109
|
|--------|---------|
|
|
@@ -75,8 +112,23 @@ Status indicators:
|
|
|
75
112
|
| `○` white | Idle |
|
|
76
113
|
| `✗` red | Error in the last tool call |
|
|
77
114
|
|
|
78
|
-
Pressing Tab on an instance expands its subagent tree, showing what child sessions are running beneath it. Each child shows its agent type (`[fixer]`, `[explorer]`, etc.), title, model, and how long ago it was active. Subagents can themselves be expanded if they spawned further children.
|
|
115
|
+
Pressing `Tab` on an instance expands its subagent tree, showing what child sessions are running beneath it. Each child shows its agent type (`[fixer]`, `[explorer]`, etc.), title, model, and how long ago it was active. Subagents can themselves be expanded if they spawned further children.
|
|
116
|
+
|
|
117
|
+
### Spawned vs discovered sessions
|
|
118
|
+
|
|
119
|
+
Sessions spawned via OCMux (`n`) run as `opencode serve --port X` in the background. These sessions:
|
|
120
|
+
|
|
121
|
+
- Show `[live]` in the conversation header
|
|
122
|
+
- Support inline messaging from the conversation view
|
|
123
|
+
- Allow cycling agent modes with `Tab`
|
|
124
|
+
- Persist when you exit the conversation view
|
|
125
|
+
- Can be killed from the dashboard with `x`
|
|
126
|
+
|
|
127
|
+
Sessions discovered from existing `opencode` processes show `[read-only]`. These support:
|
|
79
128
|
|
|
129
|
+
- Full conversation history viewing
|
|
130
|
+
- Attaching to the TUI with `a` or `i` to send messages
|
|
131
|
+
- Agent mode display (read from the last assistant message)
|
|
80
132
|
|
|
81
133
|
## Keybindings
|
|
82
134
|
|
|
@@ -120,7 +172,6 @@ Pressing Tab on an instance expands its subagent tree, showing what child sessio
|
|
|
120
172
|
| `Ctrl-X E` | Open current text in `$EDITOR` |
|
|
121
173
|
| `Esc` | Exit insert mode, return to normal mode |
|
|
122
174
|
|
|
123
|
-
|
|
124
175
|
## Configuration
|
|
125
176
|
|
|
126
177
|
Config file: `~/.config/ocmux/config.json`
|
|
@@ -163,24 +214,6 @@ All fields are optional. Unspecified fields use the defaults shown below.
|
|
|
163
214
|
}
|
|
164
215
|
```
|
|
165
216
|
|
|
166
|
-
|
|
167
|
-
## Spawned vs discovered sessions
|
|
168
|
-
|
|
169
|
-
Sessions spawned via OCMux (`n`) run as `opencode serve --port X` in the background. These sessions:
|
|
170
|
-
|
|
171
|
-
- Show `[live]` in the conversation header
|
|
172
|
-
- Support inline messaging from the conversation view
|
|
173
|
-
- Allow cycling agent modes with Tab
|
|
174
|
-
- Persist when you exit the conversation view
|
|
175
|
-
- Can be killed from the dashboard with `x`
|
|
176
|
-
|
|
177
|
-
Sessions discovered from existing `opencode` processes show `[read-only]`. These support:
|
|
178
|
-
|
|
179
|
-
- Full conversation history viewing
|
|
180
|
-
- Attaching to the TUI with `a` or `i` to send messages
|
|
181
|
-
- Agent mode display (read from the last assistant message)
|
|
182
|
-
|
|
183
|
-
|
|
184
217
|
## Architecture
|
|
185
218
|
|
|
186
219
|
OCMux reads session data directly from opencode's SQLite database (`~/.local/share/opencode/opencode.db`), which it shares with the opencode TUI. This means it sees all sessions instantly without any IPC or polling overhead beyond the 2-second refresh cycle.
|
package/docs/output1.gif
ADDED
|
Binary file
|
package/docs/output2.gif
ADDED
|
Binary file
|
package/docs/output3.gif
ADDED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "opencode-multiplexer",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Multiplexer for opencode AI coding agent sessions",
|
|
6
6
|
"keywords": ["opencode", "ai", "agent", "tui", "multiplexer"],
|
|
7
7
|
"bin": {
|
|
8
|
-
"ocmux": "./src/index.tsx"
|
|
8
|
+
"ocmux": "./src/index.tsx",
|
|
9
|
+
"opencode-multiplexer": "./src/index.tsx"
|
|
9
10
|
},
|
|
10
11
|
"scripts": {
|
|
11
12
|
"dev": "bun src/index.tsx",
|