@akshar5/cohall 0.4.6 → 0.4.8

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 (10) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/CONTRIBUTING.md +49 -0
  3. package/README.md +105 -235
  4. package/bin/cohall.js +25 -14
  5. package/bin/cohall.js.map +3 -3
  6. package/docs/install.md +117 -43
  7. package/docs/integrations.md +23 -24
  8. package/docs/releasing.md +3 -3
  9. package/docs/services.md +7 -9
  10. package/package.json +8 -7
package/docs/install.md CHANGED
@@ -1,26 +1,62 @@
1
1
  # Install Cohall
2
2
 
3
- ## Run with a package runner
3
+ Cohall requires Node.js 24 or newer. It is a standard public npm package with no
4
+ bundled agent harness.
4
5
 
5
- Cohall is a public npm package and requires Node.js 24 or newer. Nothing from
6
- Buzz, T3Code, Codex, Claude Code, or OpenCode is bundled or required.
6
+ ## Package runners
7
+
8
+ Use one command. The documentation uses `npx` in later examples.
9
+
10
+ **npm**
7
11
 
8
12
  ```bash
9
13
  npx -y @akshar5/cohall --version
14
+ ```
15
+
16
+ **Bun**
17
+
18
+ ```bash
10
19
  bunx @akshar5/cohall --version
20
+ ```
21
+
22
+ **pnpm**
23
+
24
+ ```bash
11
25
  pnpm dlx @akshar5/cohall --version
26
+ ```
27
+
28
+ **Yarn**
29
+
30
+ ```bash
12
31
  yarn dlx @akshar5/cohall --version
13
32
  ```
14
33
 
15
- The package follows the standard npm package format, so npm, Bun, pnpm, and Yarn
16
- can install it too. The documentation uses `npx` as the common default. An
17
- unattended relay or device service may install the package globally so its
18
- executable path remains fixed across restarts:
34
+ ## Global installation for services
35
+
36
+ An unattended relay or device worker needs a stable executable path. Install it
37
+ globally with the package manager that will own the service.
38
+
39
+ **npm**
19
40
 
20
41
  ```bash
21
42
  npm install --global @akshar5/cohall
22
- # or: bun add --global @akshar5/cohall
23
- # or: pnpm add --global @akshar5/cohall
43
+ ```
44
+
45
+ **Bun**
46
+
47
+ ```bash
48
+ bun add --global @akshar5/cohall
49
+ ```
50
+
51
+ **pnpm**
52
+
53
+ ```bash
54
+ pnpm add --global @akshar5/cohall
55
+ ```
56
+
57
+ Then verify:
58
+
59
+ ```bash
24
60
  cohall --version
25
61
  ```
26
62
 
@@ -31,23 +67,26 @@ The relay owner creates a token valid for ten minutes and one exchange:
31
67
  ```bash
32
68
  COHALL_RELAY_URL=https://cohall.example.com \
33
69
  COHALL_TOKEN=owner-token \
34
- npx -y @akshar5/cohall pair --label "Linux workstation"
70
+ npx -y @akshar5/cohall pair --label "Workstation"
35
71
  ```
36
72
 
37
- Transfer it privately, then enter it without placing it in process arguments or
38
- shell history:
73
+ Transfer it privately. On the machine being added, provide it through stdin so
74
+ it does not appear in process arguments or shell history:
39
75
 
40
76
  ```bash
41
77
  read -rsp 'Pairing token: ' pairing_token; printf '\n'
42
78
  printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
43
79
  --relay https://cohall.example.com \
44
- --name linux \
80
+ --name workstation \
45
81
  --providers codex \
46
82
  --workspace "$HOME/dev"
47
83
  unset pairing_token
48
84
  ```
49
85
 
50
- For a client-only machine that submits work but never runs a device daemon:
86
+ Workspace roots must already exist. Cohall resolves them to canonical paths and
87
+ rejects delegated work outside them.
88
+
89
+ For a client that submits work but never runs a device worker:
51
90
 
52
91
  ```bash
53
92
  npx -y @akshar5/cohall pair --client-only --label "Automation client"
@@ -58,9 +97,33 @@ printf '%s' "$pairing_token" | npx -y @akshar5/cohall join \
58
97
  unset pairing_token
59
98
  ```
60
99
 
61
- For automation, place the token in a mode-`0600` file and use
62
- `npx -y @akshar5/cohall join --token-file /path/to/token`. Pairing tokens expire
63
- after ten minutes and can be exchanged once.
100
+ Automation may use a mode-`0600` token file with `join --token-file
101
+ /path/to/token`.
102
+
103
+ ## Providers
104
+
105
+ Target devices advertise provider executables they can find. Authentication is
106
+ checked when delegated work starts.
107
+
108
+ | Provider | Required command | Session continuation |
109
+ | ----------- | ---------------- | ------------------------ |
110
+ | Codex | `codex` | `codex exec resume` |
111
+ | Claude Code | `claude` | `claude --resume` |
112
+ | OpenCode | `opencode` | `opencode run --session` |
113
+
114
+ Limit a device to providers configured for that user:
115
+
116
+ ```bash
117
+ cohall configure --providers codex,claude-code
118
+ cohall configure --providers auto
119
+ ```
120
+
121
+ ## Configuration
122
+
123
+ `cohall config` shows stored configuration without tokens. `cohall configure`
124
+ changes the relay URL, device name, workspace roots, providers, model, or Codex
125
+ sandbox. `cohall doctor` checks the effective configuration, relay connection,
126
+ provider executables, authentication readiness, and versions.
64
127
 
65
128
  Configuration locations:
66
129
 
@@ -68,38 +131,49 @@ Configuration locations:
68
131
  - macOS: `~/Library/Application Support/Cohall/config.json`
69
132
  - Windows: `%APPDATA%\Cohall\config.json`
70
133
 
71
- Use `COHALL_CONFIG` to override the path. On Unix, Cohall enforces directory
72
- mode `0700` and file mode `0600`.
73
-
74
- The relay must be reachable to submit new work or read its status. A target
75
- device only needs to be online while accepting or running work; accepted tasks
76
- wait durably on the relay while it is offline. Accepted tasks also survive a
77
- relay restart when its data directory is persistent. A client cannot submit a
78
- new task while the relay itself is offline.
79
-
80
- `--providers` is an optional comma-separated allowlist. It prevents an installed
81
- but unauthenticated provider executable from being advertised. Run `cohall
82
- configure --providers auto` to return to executable auto-detection.
134
+ Use `COHALL_CONFIG` to override the path. On Unix, Cohall enforces directory mode
135
+ `0700` and file mode `0600`.
136
+
137
+ Environment variables override stored values:
138
+
139
+ | Variable | Purpose |
140
+ | ----------------------------------------- | ---------------------------------------------- |
141
+ | `COHALL_CONFIG` | Configuration file override |
142
+ | `COHALL_RELAY_URL` | Relay URL for CLI, MCP, and device |
143
+ | `COHALL_CLIENT_TOKEN` | Client credential override |
144
+ | `COHALL_DEVICE_TOKEN` | Device credential override |
145
+ | `COHALL_TOKEN` | Relay owner credential |
146
+ | `COHALL_DEVICE_ID` | Stable device ID override |
147
+ | `COHALL_DEVICE_NAME` | Advertised device name |
148
+ | `COHALL_DEVICE_PROVIDERS` | Provider allowlist or `auto` |
149
+ | `COHALL_DEVICE_WORKSPACES` | Comma-separated workspace roots |
150
+ | `COHALL_DEVICE_WORKSPACES_JSON` | JSON workspace roots; supports commas in paths |
151
+ | `COHALL_MODEL` | Target provider model override |
152
+ | `COHALL_SANDBOX` | Codex sandbox override |
153
+ | `COHALL_THREAD_ID` | Inherited thread for nested delegation |
154
+ | `COHALL_DATA_DIR` | Relay database and owner-token directory |
155
+ | `COHALL_RELAY_HOST` / `COHALL_RELAY_PORT` | Relay listener |
156
+ | `COHALL_RELAY_ALLOW_REMOTE` | Explicit non-loopback binding opt-in |
157
+
158
+ The relay must be reachable to submit work or read status. Accepted tasks wait
159
+ durably while a target is offline and survive relay restarts when its data
160
+ directory is persistent.
83
161
 
84
162
  ## Upgrade
85
163
 
86
- Package runners such as `npx`, `bunx`, and `pnpm dlx` already resolve a current
87
- release. Upgrade a global installation and its running services with:
164
+ Package runners resolve a current release. Upgrade a global installation and
165
+ its active services with:
88
166
 
89
167
  ```bash
90
168
  cohall upgrade
91
169
  ```
92
170
 
93
171
  Cohall uses the package manager and global prefix that installed it, verifies
94
- the installed version, then restarts only active Cohall relay and device
95
- services. Active services restart even when the package files are already
96
- current, so a process left on old code by a direct package-manager update is
97
- replaced. If a service points to a different global installation, Cohall stops
98
- with its executable path instead of reporting a misleading successful restart.
99
- Run that executable's `upgrade` command or update the service definition. Choose
100
- an exact version with `cohall upgrade --to 1.2.3`. Use `--dry-run` to inspect the
101
- plan or `--no-restart` to leave active services pending a manual restart.
102
-
103
- Back up the data directory before upgrading a production relay; SQLite schema
104
- migrations run in place. A system-level relay may require running the command
105
- with the same privileges used to install and manage that service.
172
+ the new version, and restarts only active Cohall services. If a service points
173
+ to another global installation, Cohall stops and reports the correct executable
174
+ instead of restarting the wrong job.
175
+
176
+ Use `cohall upgrade --to 1.2.3` for an exact version, `--dry-run` to inspect the
177
+ plan, or `--no-restart` to leave services pending a manual restart. Back up a
178
+ production relay's data directory before an upgrade because SQLite migrations
179
+ run in place.
package/docs/integrations.md CHANGED
@@ -1,7 +1,8 @@
1
- # Agent harness integrations
1
+ # Agent integrations
2
2
 
3
- CLI plus skill is the recommended integration. MCP is available for hosts that
4
- prefer native tool discovery. Both use the same relay and device protocol.
3
+ CLI plus skill is the recommended integration. MCP is available for harnesses
4
+ that prefer native tool discovery. Both create the same relay tasks; use one
5
+ entry point per task.
5
6
 
6
7
  ## CLI plus skill
7
8
 
@@ -10,16 +11,20 @@ npx -y @akshar5/cohall skill install all
10
11
  npx -y @akshar5/cohall doctor
11
12
  ```
12
13
 
13
- This installs the same embedded `SKILL.md` into:
14
+ This installs the embedded skill into:
14
15
 
15
16
  - `~/.agents/skills/cohall` for Codex-compatible skill loaders;
16
17
  - `~/.claude/skills/cohall` for Claude Code;
17
18
  - `~/.config/opencode/skills/cohall` for OpenCode.
18
19
 
19
- T3Code, Buzz, and other harnesses can run `npx -y @akshar5/cohall` from their
20
- normal shell/tool environment. `bunx @akshar5/cohall`, `pnpm dlx
21
- @akshar5/cohall`, and `yarn dlx @akshar5/cohall` are equivalent. No
22
- Cohall-specific UI extension is required.
20
+ Any other harness with shell access can invoke the CLI directly. No Cohall UI
21
+ extension is required.
22
+
23
+ When delegating from a conversation, the sending agent must distill why the user
24
+ is asking, relevant facts and prior findings, constraints, and the intended
25
+ decision into Cohall's `context` field. Cohall cannot read the harness transcript
26
+ itself. Send a focused brief rather than the raw chat; omit context only for a
27
+ self-contained task.
23
28
 
24
29
  ## Codex MCP
25
30
 
@@ -27,7 +32,7 @@ Cohall-specific UI extension is required.
27
32
  codex mcp add cohall -- npx -y @akshar5/cohall mcp
28
33
  ```
29
34
 
30
- Or configure `~/.codex/config.toml`:
35
+ Equivalent `~/.codex/config.toml`:
31
36
 
32
37
  ```toml
33
38
  [mcp_servers.cohall]
@@ -42,7 +47,7 @@ claude mcp add --transport stdio --scope user cohall -- \
42
47
  npx -y @akshar5/cohall mcp
43
48
  ```
44
49
 
45
- Or use the standard JSON form in a project `.mcp.json`:
50
+ Equivalent project `.mcp.json`:
46
51
 
47
52
  ```json
48
53
  {
@@ -57,7 +62,7 @@ Or use the standard JSON form in a project `.mcp.json`:
57
62
 
58
63
  ## OpenCode MCP
59
64
 
60
- Add this to `opencode.json`:
65
+ Add to `opencode.json`:
61
66
 
62
67
  ```json
63
68
  {
@@ -72,19 +77,13 @@ Add this to `opencode.json`:
72
77
  }
73
78
  ```
74
79
 
75
- ## Environment
76
-
77
- The MCP subprocess reads the normal per-user Cohall configuration. If a harness
78
- uses an isolated environment, pass only:
79
-
80
- ```text
81
- COHALL_CONFIG=/absolute/path/to/config.json
82
- ```
80
+ ## Isolated environments
83
81
 
84
- Or pass `COHALL_RELAY_URL` and `COHALL_CLIENT_TOKEN` directly. Never place an
85
- owner or device token in an MCP client configuration.
82
+ The MCP subprocess reads the current user's Cohall configuration. If a harness
83
+ uses an isolated environment, pass `COHALL_CONFIG` with an absolute path to that
84
+ configuration file. Alternatively pass `COHALL_RELAY_URL` and
85
+ `COHALL_CLIENT_TOKEN` directly.
86
86
 
87
- CLI and MCP are equivalent entry points. Use one per delegated task.
88
- Both expose redacted task tracing through `cohall trace <task-id>` and the
87
+ Never place an owner or device token in an MCP configuration. Both integrations
88
+ provide redacted task tracing through `cohall trace <task-id>` or the
89
89
  `task_trace` MCP tool.
90
- Use `bunx @akshar5/cohall` with Bun. Use `pnpm dlx @akshar5/cohall` with pnpm.
package/docs/releasing.md CHANGED
@@ -11,9 +11,9 @@ bun run check
11
11
  npm pack --dry-run
12
12
  ```
13
13
 
14
- The Check workflow runs only when manually dispatched or when a non-draft pull
15
- request is opened or marked ready for review. Synchronizing commits does not
16
- automatically consume another private-repository runner allocation.
14
+ The Check workflow runs when manually dispatched or when a non-draft pull
15
+ request is opened or marked ready for review. Synchronizing later commits does
16
+ not start another run automatically.
17
17
 
18
18
  After releasable conventional commits reach `main`, Release Please opens or
19
19
  updates one release pull request. Merging it creates the version tag and GitHub
package/docs/services.md CHANGED
@@ -131,16 +131,14 @@ logon and restarts it after failures. It does not run before that user logs on.
131
131
 
132
132
  Run `cohall upgrade` from a global npm, Bun, or pnpm installation. It updates
133
133
  that installation and restarts only active managed Cohall services, with relays
134
- restarted before device daemons. Active services restart even when the installed
135
- files already match the requested version. A systemd relay installed with the
136
- packaged socket unit keeps accepting new connections while its process restarts.
137
- A delegated upgrade can finish after
138
- restarting its own device daemon: a durable receipt records the restart attempt,
139
- and a delegated caller leaves that marker for the replacement task to consume
140
- after reconnecting, even when a service manager returns before ending the old process.
134
+ restarted before device workers. Active services restart even when the installed
135
+ files already match the requested version. Socket-activated relays keep accepting
136
+ new connections while their process is replaced, and delegated upgrades finish
137
+ through durable restart recovery.
138
+
141
139
  Before changing files, Cohall verifies that active systemd and launchd jobs use
142
- the same global installation as the invoked CLI. If they differ, run the
143
- executable named in the error or update the service definition first.
140
+ the same global installation as the invoked CLI. If they differ, use the
141
+ executable named in the error or update the service definition.
144
142
 
145
143
  Direct `npm install --global`, `bun add --global`, or `pnpm add --global`
146
144
  replaces files on disk but cannot replace code already loaded by a running Node
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@akshar5/cohall",
3
- "version": "0.4.6",
3
+ "version": "0.4.8",
4
4
  "description": "Let coding agents delegate work across your own devices.",
5
5
  "keywords": [
6
6
  "agents",
@@ -31,6 +31,7 @@
31
31
  "deploy",
32
32
  "docs",
33
33
  "CHANGELOG.md",
34
+ "CONTRIBUTING.md",
34
35
  "LICENSE",
35
36
  "README.md"
36
37
  ],
@@ -50,8 +51,8 @@
50
51
  "typecheck": "bunx tsc -b",
51
52
  "test": "bun run build:package && vitest run",
52
53
  "lint": "bunx oxlint . --deny-warnings",
53
- "format": "bunx oxfmt .",
54
- "format:check": "bunx oxfmt --check .",
54
+ "format": "bunx oxfmt . '!CHANGELOG.md'",
55
+ "format:check": "bunx oxfmt --check . '!CHANGELOG.md'",
55
56
  "package:check": "npm pack --dry-run --ignore-scripts",
56
57
  "check": "bun run typecheck && bun run lint && bun run test && bun run package:check",
57
58
  "prepack": "bun run build:package"
@@ -62,10 +63,6 @@
62
63
  "ws": "^8.21.2",
63
64
  "zod": "^4.4.3"
64
65
  },
65
- "overrides": {
66
- "fast-uri": "^3.1.5",
67
- "hono": "^4.12.34"
68
- },
69
66
  "devDependencies": {
70
67
  "@types/node": "^24.13.3",
71
68
  "@types/ws": "^8.18.1",
@@ -74,6 +71,10 @@
74
71
  "typescript": "^6.0.0",
75
72
  "vitest": "^4.1.10"
76
73
  },
74
+ "overrides": {
75
+ "fast-uri": "^3.1.5",
76
+ "hono": "^4.12.34"
77
+ },
77
78
  "engines": {
78
79
  "node": ">=24"
79
80
  },