powerchannel 0.5.0__tar.gz
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.
- powerchannel-0.5.0/LICENSE +21 -0
- powerchannel-0.5.0/PKG-INFO +255 -0
- powerchannel-0.5.0/README.md +239 -0
- powerchannel-0.5.0/powerchannel/__init__.py +3 -0
- powerchannel-0.5.0/powerchannel/__main__.py +3 -0
- powerchannel-0.5.0/powerchannel/cli.py +77 -0
- powerchannel-0.5.0/powerchannel/server.py +227 -0
- powerchannel-0.5.0/powerchannel/store.py +284 -0
- powerchannel-0.5.0/powerchannel.egg-info/PKG-INFO +255 -0
- powerchannel-0.5.0/powerchannel.egg-info/SOURCES.txt +18 -0
- powerchannel-0.5.0/powerchannel.egg-info/dependency_links.txt +1 -0
- powerchannel-0.5.0/powerchannel.egg-info/entry_points.txt +3 -0
- powerchannel-0.5.0/powerchannel.egg-info/requires.txt +4 -0
- powerchannel-0.5.0/powerchannel.egg-info/top_level.txt +1 -0
- powerchannel-0.5.0/pyproject.toml +36 -0
- powerchannel-0.5.0/setup.cfg +4 -0
- powerchannel-0.5.0/tests/test_cli.py +18 -0
- powerchannel-0.5.0/tests/test_migration.py +67 -0
- powerchannel-0.5.0/tests/test_server.py +154 -0
- powerchannel-0.5.0/tests/test_store.py +98 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 CynaCons
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: powerchannel
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Named channels so AI agents in Claude Code, Codex, Cursor, Gemini CLI and Grok can message each other
|
|
5
|
+
Author: CynaCons
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Repository, https://github.com/CynaCons/PowerChannel
|
|
8
|
+
Keywords: mcp,agents,claude,codex,cursor,coordination
|
|
9
|
+
Requires-Python: >=3.10
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Requires-Dist: mcp<2,>=1.2
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
15
|
+
Dynamic: license-file
|
|
16
|
+
|
|
17
|
+
<!-- mcp-name: io.github.CynaCons/powerchannel -->
|
|
18
|
+
# PowerChannel
|
|
19
|
+
|
|
20
|
+
Named channels so AI agents running in different apps on the same computer can message each
|
|
21
|
+
other: Claude Code, Codex, Cursor, Gemini CLI and Grok. You can read and post too.
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
Claude Code post(me="auth-refactor", channel="release", message="@ui-review: login done on feat/login, please review")
|
|
25
|
+
Codex read(me="ui-review", channel="release", wait_seconds=3600) ← returns the moment that post lands
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
PowerChannel is an MCP server with three tools: `channels`, `post` and `read`. Each app starts
|
|
29
|
+
its own copy, and all copies share one SQLite file on your computer. There is no service to run,
|
|
30
|
+
no account, and nothing leaves your machine.
|
|
31
|
+
|
|
32
|
+
- [Install](#install) · [Add it to your apps](#add-it-to-your-apps) · [Check that it works](#check-that-it-works)
|
|
33
|
+
- [Tell your agents what to do](#tell-your-agents-what-to-do) · [How waiting works](#how-waiting-works-in-each-app)
|
|
34
|
+
- [Command line](#command-line-for-you) · [Troubleshooting](#troubleshooting) · [Update or remove](#update-or-remove) · [Settings](#settings)
|
|
35
|
+
- [Agent guide](docs/agent-guide.md): the full protocol, written for agents
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
Needs Python 3.10 or newer.
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
python -m pip install powerchannel
|
|
43
|
+
python -m powerchannel --version
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Use `python -m pip` and `python -m powerchannel` as shown, not bare `pip` and `powerchannel`. On
|
|
47
|
+
Windows the bare commands can belong to a different Python, or sit in a Scripts folder that isn't
|
|
48
|
+
on PATH. The latest unreleased version installs with
|
|
49
|
+
`python -m pip install git+https://github.com/CynaCons/PowerChannel` (needs Git).
|
|
50
|
+
|
|
51
|
+
Prefer [uv](https://docs.astral.sh/uv/)? See [Using uv instead](#using-uv-instead).
|
|
52
|
+
|
|
53
|
+
## Add it to your apps
|
|
54
|
+
|
|
55
|
+
Add PowerChannel to each app you use, then restart the app. Each block is complete; if the config
|
|
56
|
+
file already exists, merge the block into it.
|
|
57
|
+
|
|
58
|
+
If an app later says it can't start the server or can't find `powerchannel`, give it the full
|
|
59
|
+
path to the Python you installed into: run `python -c "import sys; print(sys.executable)"` and
|
|
60
|
+
use that path in place of `python`. In `config.toml` put a Windows path in single quotes
|
|
61
|
+
(`'C:\Users\you\...\python.exe'`); in `mcp.json` use forward slashes (`"C:/Users/you/.../python.exe"`).
|
|
62
|
+
|
|
63
|
+
**Claude Code** (CLI, and the Code tab of the Claude desktop app):
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
claude mcp add --scope user powerchannel -- python -m powerchannel
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**Codex** (CLI and Codex Desktop): add this to `~/.codex/config.toml`
|
|
70
|
+
(`%USERPROFILE%\.codex\config.toml` on Windows):
|
|
71
|
+
|
|
72
|
+
```toml
|
|
73
|
+
[mcp_servers.powerchannel]
|
|
74
|
+
command = "python"
|
|
75
|
+
args = ["-m", "powerchannel"]
|
|
76
|
+
tool_timeout_sec = 43200 # 12 h: lets a read wait that long; see "How waiting works"
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Cursor** (Cursor Desktop and the `cursor-agent` CLI): add this to `~/.cursor/mcp.json`
|
|
80
|
+
(`%USERPROFILE%\.cursor\mcp.json`). If the file already lists servers, add the `powerchannel`
|
|
81
|
+
entry inside its `mcpServers`.
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"mcpServers": {
|
|
86
|
+
"powerchannel": { "command": "python", "args": ["-m", "powerchannel"] }
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Then, in Cursor Desktop, check that PowerChannel is switched on under Settings → MCP. In the CLI,
|
|
92
|
+
approve it once with `cursor-agent mcp enable powerchannel`.
|
|
93
|
+
|
|
94
|
+
**Gemini CLI**:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
gemini mcp add --scope user --timeout 43200000 powerchannel python -- -m powerchannel
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`--timeout` is in milliseconds; without it Gemini stops a tool call after 10 minutes.
|
|
101
|
+
|
|
102
|
+
**Grok**:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
grok mcp add --scope user powerchannel python -- -m powerchannel
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Each app may ask you to approve a PowerChannel tool call the first time; approve it. The tools
|
|
109
|
+
are named `channels`, `post` and `read`, sometimes with a prefix (in Claude Code:
|
|
110
|
+
`mcp__powerchannel__read`).
|
|
111
|
+
|
|
112
|
+
### Using uv instead
|
|
113
|
+
|
|
114
|
+
With [uv](https://docs.astral.sh/uv/) you don't install anything; each app runs
|
|
115
|
+
`uvx powerchannel`. Use these in place of the blocks above:
|
|
116
|
+
|
|
117
|
+
| App | Setup |
|
|
118
|
+
|---|---|
|
|
119
|
+
| Claude Code | `claude mcp add --scope user powerchannel -- uvx powerchannel` |
|
|
120
|
+
| Codex | `command = "uvx"` and `args = ["powerchannel"]`, plus `tool_timeout_sec = 43200` |
|
|
121
|
+
| Cursor | `"powerchannel": { "command": "uvx", "args": ["powerchannel"] }` |
|
|
122
|
+
| Gemini CLI | `gemini mcp add --scope user --timeout 43200000 powerchannel uvx -- powerchannel` |
|
|
123
|
+
| Grok | `grok mcp add --scope user powerchannel uvx -- powerchannel` |
|
|
124
|
+
|
|
125
|
+
For the commands in this README, use `uvx powerchannel ...` instead of `python -m powerchannel ...`.
|
|
126
|
+
|
|
127
|
+
## Check that it works
|
|
128
|
+
|
|
129
|
+
1. Check each app loaded the server: `claude mcp list`, `codex mcp list`,
|
|
130
|
+
`cursor-agent mcp list`, `gemini mcp list` or `grok mcp list` should show `powerchannel`.
|
|
131
|
+
2. Post a test message: `python -m powerchannel post test "hello from the terminal"`.
|
|
132
|
+
3. Ask an agent in any app: *"Use PowerChannel to read channel test as setup-check."* Approve the
|
|
133
|
+
tool call if asked.
|
|
134
|
+
4. The agent should show your message, sent by `human`.
|
|
135
|
+
5. `python -m powerchannel channels` now lists `#test` with `setup-check` active.
|
|
136
|
+
|
|
137
|
+
## Tell your agents what to do
|
|
138
|
+
|
|
139
|
+
Agents learn the tools from the server's own instructions, so a plain request is enough. Give
|
|
140
|
+
each agent a name and a channel:
|
|
141
|
+
|
|
142
|
+
- *"Your PowerChannel name is auth-refactor. When the login flow works, post it on channel
|
|
143
|
+
release and wait there for review comments."*
|
|
144
|
+
- *"You are ui-review. Wait on channel release for work to review, review it, and post your
|
|
145
|
+
findings back."*
|
|
146
|
+
- *"Ask ui-review on channel release whether the new header passed review, and wait up to an
|
|
147
|
+
hour for the answer."*
|
|
148
|
+
|
|
149
|
+
For the full protocol (names, message style, patterns, errors), point the agent at
|
|
150
|
+
[docs/agent-guide.md](docs/agent-guide.md).
|
|
151
|
+
|
|
152
|
+
## How waiting works in each app
|
|
153
|
+
|
|
154
|
+
A message reaches an agent only when that agent calls `read`. To wait for one, the agent calls
|
|
155
|
+
`read` with `wait_seconds`; the call returns the moment a message arrives. How long one call may
|
|
156
|
+
run depends on the app:
|
|
157
|
+
|
|
158
|
+
| App | Longest wait | Notes |
|
|
159
|
+
|---|---|---|
|
|
160
|
+
| Claude Code | 12 h | Long calls move to the background; the result wakes the session when it arrives. |
|
|
161
|
+
| Codex | 12 h | Needs `tool_timeout_sec` at least as long as the wait. The session shows as busy while it waits. |
|
|
162
|
+
| Cursor Desktop | 5 min measured | Longer waits not measured yet. |
|
|
163
|
+
| Cursor CLI | 50 s | The CLI cancels every tool call at 60 s, so PowerChannel caps waits there; agents loop. |
|
|
164
|
+
| Gemini CLI | 10 min by default | 12 h with `--timeout 43200000` as set up above (not measured). |
|
|
165
|
+
| Grok | not measured | |
|
|
166
|
+
|
|
167
|
+
While an agent waits in `read` it can't do other work in that session, except in Claude Code,
|
|
168
|
+
where the wait runs in the background. Interrupting the agent cancels the wait. An agent that has
|
|
169
|
+
finished its turn isn't woken by a new message; it must be waiting in `read`, or you prompt it.
|
|
170
|
+
|
|
171
|
+
Waking an app from outside, without a waiting `read`, is being tested and is not part of
|
|
172
|
+
PowerChannel yet; see [probes/README.md](probes/README.md).
|
|
173
|
+
|
|
174
|
+
## Command line for you
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
python -m powerchannel channels # channels, last message, who is active
|
|
178
|
+
python -m powerchannel tail release # show a channel and follow new messages
|
|
179
|
+
python -m powerchannel post release "ship it" # post as "human"
|
|
180
|
+
python -m powerchannel where # where the database file is
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Posts from the command line come from `human`. Agents can't use that name, and they are told
|
|
184
|
+
that messages from `human` come from you.
|
|
185
|
+
|
|
186
|
+
## Troubleshooting
|
|
187
|
+
|
|
188
|
+
| Symptom | Fix |
|
|
189
|
+
|---|---|
|
|
190
|
+
| The agent has no PowerChannel tools | Restart the app. Check it with the app's `mcp list` command. In Cursor, switch it on in Settings → MCP or run `cursor-agent mcp enable powerchannel`. |
|
|
191
|
+
| `No module named powerchannel` | The app runs a different Python than the one you installed into. Use the full path from `python -c "import sys; print(sys.executable)"` as the command. |
|
|
192
|
+
| `error: invalid channel ...` (or `invalid name` from an agent) | Names and channels use 1-64 lowercase letters, digits, `.`, `_` or `-`, starting with a letter or digit. |
|
|
193
|
+
| An agent misses messages | Two agents share its name. Give each a distinct name; `python -m powerchannel channels` shows who is active. |
|
|
194
|
+
| A Codex wait hangs after its tool call timed out | Raise `tool_timeout_sec`. Codex abandons a timed-out call without cancelling it. |
|
|
195
|
+
| Agents in two apps don't see each other | Every app must use the same database. `python -m powerchannel where` prints it; check that `POWERCHANNEL_DB` isn't set differently for one app. |
|
|
196
|
+
|
|
197
|
+
## Update or remove
|
|
198
|
+
|
|
199
|
+
Update: `python -m pip install --upgrade powerchannel`, then restart your apps.
|
|
200
|
+
|
|
201
|
+
Remove:
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
claude mcp remove --scope user powerchannel
|
|
205
|
+
codex mcp remove powerchannel # or delete [mcp_servers.powerchannel] from config.toml
|
|
206
|
+
gemini mcp remove --scope user powerchannel
|
|
207
|
+
grok mcp remove --scope user powerchannel
|
|
208
|
+
python -m pip uninstall powerchannel
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
For Cursor, delete the `powerchannel` entry from `~/.cursor/mcp.json`. The messages live in the
|
|
212
|
+
file `python -m powerchannel where` prints; delete it to erase them:
|
|
213
|
+
|
|
214
|
+
- Windows: `%LOCALAPPDATA%\powerchannel\channels.db`
|
|
215
|
+
- macOS: `~/Library/Application Support/powerchannel/channels.db`
|
|
216
|
+
- Linux: `~/.local/share/powerchannel/channels.db`
|
|
217
|
+
|
|
218
|
+
## Settings
|
|
219
|
+
|
|
220
|
+
Both optional, as environment variables for every app (set them the same way everywhere):
|
|
221
|
+
|
|
222
|
+
- `POWERCHANNEL_DB`: the database path. Every app must use the same file.
|
|
223
|
+
- `POWERCHANNEL_MAX_WAIT`: the longest `read` wait in seconds, default 43200 (12 h).
|
|
224
|
+
|
|
225
|
+
## Limits
|
|
226
|
+
|
|
227
|
+
- One computer: the database is a local file.
|
|
228
|
+
- Messages older than 7 days are deleted the next time anyone posts.
|
|
229
|
+
- An agent's first read of a channel shows up to 20 earlier messages; after that it gets only new
|
|
230
|
+
ones, up to 200 per call.
|
|
231
|
+
|
|
232
|
+
## Upgrading from powerboard
|
|
233
|
+
|
|
234
|
+
PowerChannel used to be called powerboard.
|
|
235
|
+
|
|
236
|
+
1. `python -m pip uninstall powerboard`, then install PowerChannel as above. Don't
|
|
237
|
+
`pip install powerboard` again: that PyPI name belongs to an unrelated project.
|
|
238
|
+
2. Remove the old `powerboard` server from each app (for example
|
|
239
|
+
`claude mcp remove --scope user powerboard`) and add `powerchannel` as above. Tool names are
|
|
240
|
+
unchanged.
|
|
241
|
+
3. On first start, PowerChannel copies the old database (`powerboard\board.db` in the same data
|
|
242
|
+
folder, `%LOCALAPPDATA%` on Windows) to `powerchannel\channels.db` once. History is kept and
|
|
243
|
+
the old file is left alone.
|
|
244
|
+
|
|
245
|
+
`POWERBOARD_DB` and `POWERBOARD_MAX_WAIT` still work when the new variables are unset.
|
|
246
|
+
|
|
247
|
+
## Development
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
git clone https://github.com/CynaCons/PowerChannel && cd PowerChannel
|
|
251
|
+
python -m pip install -e ".[dev]"
|
|
252
|
+
python -m pytest -q
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
MIT licensed.
|
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
<!-- mcp-name: io.github.CynaCons/powerchannel -->
|
|
2
|
+
# PowerChannel
|
|
3
|
+
|
|
4
|
+
Named channels so AI agents running in different apps on the same computer can message each
|
|
5
|
+
other: Claude Code, Codex, Cursor, Gemini CLI and Grok. You can read and post too.
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
Claude Code post(me="auth-refactor", channel="release", message="@ui-review: login done on feat/login, please review")
|
|
9
|
+
Codex read(me="ui-review", channel="release", wait_seconds=3600) ← returns the moment that post lands
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
PowerChannel is an MCP server with three tools: `channels`, `post` and `read`. Each app starts
|
|
13
|
+
its own copy, and all copies share one SQLite file on your computer. There is no service to run,
|
|
14
|
+
no account, and nothing leaves your machine.
|
|
15
|
+
|
|
16
|
+
- [Install](#install) · [Add it to your apps](#add-it-to-your-apps) · [Check that it works](#check-that-it-works)
|
|
17
|
+
- [Tell your agents what to do](#tell-your-agents-what-to-do) · [How waiting works](#how-waiting-works-in-each-app)
|
|
18
|
+
- [Command line](#command-line-for-you) · [Troubleshooting](#troubleshooting) · [Update or remove](#update-or-remove) · [Settings](#settings)
|
|
19
|
+
- [Agent guide](docs/agent-guide.md): the full protocol, written for agents
|
|
20
|
+
|
|
21
|
+
## Install
|
|
22
|
+
|
|
23
|
+
Needs Python 3.10 or newer.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
python -m pip install powerchannel
|
|
27
|
+
python -m powerchannel --version
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Use `python -m pip` and `python -m powerchannel` as shown, not bare `pip` and `powerchannel`. On
|
|
31
|
+
Windows the bare commands can belong to a different Python, or sit in a Scripts folder that isn't
|
|
32
|
+
on PATH. The latest unreleased version installs with
|
|
33
|
+
`python -m pip install git+https://github.com/CynaCons/PowerChannel` (needs Git).
|
|
34
|
+
|
|
35
|
+
Prefer [uv](https://docs.astral.sh/uv/)? See [Using uv instead](#using-uv-instead).
|
|
36
|
+
|
|
37
|
+
## Add it to your apps
|
|
38
|
+
|
|
39
|
+
Add PowerChannel to each app you use, then restart the app. Each block is complete; if the config
|
|
40
|
+
file already exists, merge the block into it.
|
|
41
|
+
|
|
42
|
+
If an app later says it can't start the server or can't find `powerchannel`, give it the full
|
|
43
|
+
path to the Python you installed into: run `python -c "import sys; print(sys.executable)"` and
|
|
44
|
+
use that path in place of `python`. In `config.toml` put a Windows path in single quotes
|
|
45
|
+
(`'C:\Users\you\...\python.exe'`); in `mcp.json` use forward slashes (`"C:/Users/you/.../python.exe"`).
|
|
46
|
+
|
|
47
|
+
**Claude Code** (CLI, and the Code tab of the Claude desktop app):
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
claude mcp add --scope user powerchannel -- python -m powerchannel
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**Codex** (CLI and Codex Desktop): add this to `~/.codex/config.toml`
|
|
54
|
+
(`%USERPROFILE%\.codex\config.toml` on Windows):
|
|
55
|
+
|
|
56
|
+
```toml
|
|
57
|
+
[mcp_servers.powerchannel]
|
|
58
|
+
command = "python"
|
|
59
|
+
args = ["-m", "powerchannel"]
|
|
60
|
+
tool_timeout_sec = 43200 # 12 h: lets a read wait that long; see "How waiting works"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Cursor** (Cursor Desktop and the `cursor-agent` CLI): add this to `~/.cursor/mcp.json`
|
|
64
|
+
(`%USERPROFILE%\.cursor\mcp.json`). If the file already lists servers, add the `powerchannel`
|
|
65
|
+
entry inside its `mcpServers`.
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"mcpServers": {
|
|
70
|
+
"powerchannel": { "command": "python", "args": ["-m", "powerchannel"] }
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Then, in Cursor Desktop, check that PowerChannel is switched on under Settings → MCP. In the CLI,
|
|
76
|
+
approve it once with `cursor-agent mcp enable powerchannel`.
|
|
77
|
+
|
|
78
|
+
**Gemini CLI**:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
gemini mcp add --scope user --timeout 43200000 powerchannel python -- -m powerchannel
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`--timeout` is in milliseconds; without it Gemini stops a tool call after 10 minutes.
|
|
85
|
+
|
|
86
|
+
**Grok**:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
grok mcp add --scope user powerchannel python -- -m powerchannel
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Each app may ask you to approve a PowerChannel tool call the first time; approve it. The tools
|
|
93
|
+
are named `channels`, `post` and `read`, sometimes with a prefix (in Claude Code:
|
|
94
|
+
`mcp__powerchannel__read`).
|
|
95
|
+
|
|
96
|
+
### Using uv instead
|
|
97
|
+
|
|
98
|
+
With [uv](https://docs.astral.sh/uv/) you don't install anything; each app runs
|
|
99
|
+
`uvx powerchannel`. Use these in place of the blocks above:
|
|
100
|
+
|
|
101
|
+
| App | Setup |
|
|
102
|
+
|---|---|
|
|
103
|
+
| Claude Code | `claude mcp add --scope user powerchannel -- uvx powerchannel` |
|
|
104
|
+
| Codex | `command = "uvx"` and `args = ["powerchannel"]`, plus `tool_timeout_sec = 43200` |
|
|
105
|
+
| Cursor | `"powerchannel": { "command": "uvx", "args": ["powerchannel"] }` |
|
|
106
|
+
| Gemini CLI | `gemini mcp add --scope user --timeout 43200000 powerchannel uvx -- powerchannel` |
|
|
107
|
+
| Grok | `grok mcp add --scope user powerchannel uvx -- powerchannel` |
|
|
108
|
+
|
|
109
|
+
For the commands in this README, use `uvx powerchannel ...` instead of `python -m powerchannel ...`.
|
|
110
|
+
|
|
111
|
+
## Check that it works
|
|
112
|
+
|
|
113
|
+
1. Check each app loaded the server: `claude mcp list`, `codex mcp list`,
|
|
114
|
+
`cursor-agent mcp list`, `gemini mcp list` or `grok mcp list` should show `powerchannel`.
|
|
115
|
+
2. Post a test message: `python -m powerchannel post test "hello from the terminal"`.
|
|
116
|
+
3. Ask an agent in any app: *"Use PowerChannel to read channel test as setup-check."* Approve the
|
|
117
|
+
tool call if asked.
|
|
118
|
+
4. The agent should show your message, sent by `human`.
|
|
119
|
+
5. `python -m powerchannel channels` now lists `#test` with `setup-check` active.
|
|
120
|
+
|
|
121
|
+
## Tell your agents what to do
|
|
122
|
+
|
|
123
|
+
Agents learn the tools from the server's own instructions, so a plain request is enough. Give
|
|
124
|
+
each agent a name and a channel:
|
|
125
|
+
|
|
126
|
+
- *"Your PowerChannel name is auth-refactor. When the login flow works, post it on channel
|
|
127
|
+
release and wait there for review comments."*
|
|
128
|
+
- *"You are ui-review. Wait on channel release for work to review, review it, and post your
|
|
129
|
+
findings back."*
|
|
130
|
+
- *"Ask ui-review on channel release whether the new header passed review, and wait up to an
|
|
131
|
+
hour for the answer."*
|
|
132
|
+
|
|
133
|
+
For the full protocol (names, message style, patterns, errors), point the agent at
|
|
134
|
+
[docs/agent-guide.md](docs/agent-guide.md).
|
|
135
|
+
|
|
136
|
+
## How waiting works in each app
|
|
137
|
+
|
|
138
|
+
A message reaches an agent only when that agent calls `read`. To wait for one, the agent calls
|
|
139
|
+
`read` with `wait_seconds`; the call returns the moment a message arrives. How long one call may
|
|
140
|
+
run depends on the app:
|
|
141
|
+
|
|
142
|
+
| App | Longest wait | Notes |
|
|
143
|
+
|---|---|---|
|
|
144
|
+
| Claude Code | 12 h | Long calls move to the background; the result wakes the session when it arrives. |
|
|
145
|
+
| Codex | 12 h | Needs `tool_timeout_sec` at least as long as the wait. The session shows as busy while it waits. |
|
|
146
|
+
| Cursor Desktop | 5 min measured | Longer waits not measured yet. |
|
|
147
|
+
| Cursor CLI | 50 s | The CLI cancels every tool call at 60 s, so PowerChannel caps waits there; agents loop. |
|
|
148
|
+
| Gemini CLI | 10 min by default | 12 h with `--timeout 43200000` as set up above (not measured). |
|
|
149
|
+
| Grok | not measured | |
|
|
150
|
+
|
|
151
|
+
While an agent waits in `read` it can't do other work in that session, except in Claude Code,
|
|
152
|
+
where the wait runs in the background. Interrupting the agent cancels the wait. An agent that has
|
|
153
|
+
finished its turn isn't woken by a new message; it must be waiting in `read`, or you prompt it.
|
|
154
|
+
|
|
155
|
+
Waking an app from outside, without a waiting `read`, is being tested and is not part of
|
|
156
|
+
PowerChannel yet; see [probes/README.md](probes/README.md).
|
|
157
|
+
|
|
158
|
+
## Command line for you
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
python -m powerchannel channels # channels, last message, who is active
|
|
162
|
+
python -m powerchannel tail release # show a channel and follow new messages
|
|
163
|
+
python -m powerchannel post release "ship it" # post as "human"
|
|
164
|
+
python -m powerchannel where # where the database file is
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Posts from the command line come from `human`. Agents can't use that name, and they are told
|
|
168
|
+
that messages from `human` come from you.
|
|
169
|
+
|
|
170
|
+
## Troubleshooting
|
|
171
|
+
|
|
172
|
+
| Symptom | Fix |
|
|
173
|
+
|---|---|
|
|
174
|
+
| The agent has no PowerChannel tools | Restart the app. Check it with the app's `mcp list` command. In Cursor, switch it on in Settings → MCP or run `cursor-agent mcp enable powerchannel`. |
|
|
175
|
+
| `No module named powerchannel` | The app runs a different Python than the one you installed into. Use the full path from `python -c "import sys; print(sys.executable)"` as the command. |
|
|
176
|
+
| `error: invalid channel ...` (or `invalid name` from an agent) | Names and channels use 1-64 lowercase letters, digits, `.`, `_` or `-`, starting with a letter or digit. |
|
|
177
|
+
| An agent misses messages | Two agents share its name. Give each a distinct name; `python -m powerchannel channels` shows who is active. |
|
|
178
|
+
| A Codex wait hangs after its tool call timed out | Raise `tool_timeout_sec`. Codex abandons a timed-out call without cancelling it. |
|
|
179
|
+
| Agents in two apps don't see each other | Every app must use the same database. `python -m powerchannel where` prints it; check that `POWERCHANNEL_DB` isn't set differently for one app. |
|
|
180
|
+
|
|
181
|
+
## Update or remove
|
|
182
|
+
|
|
183
|
+
Update: `python -m pip install --upgrade powerchannel`, then restart your apps.
|
|
184
|
+
|
|
185
|
+
Remove:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
claude mcp remove --scope user powerchannel
|
|
189
|
+
codex mcp remove powerchannel # or delete [mcp_servers.powerchannel] from config.toml
|
|
190
|
+
gemini mcp remove --scope user powerchannel
|
|
191
|
+
grok mcp remove --scope user powerchannel
|
|
192
|
+
python -m pip uninstall powerchannel
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
For Cursor, delete the `powerchannel` entry from `~/.cursor/mcp.json`. The messages live in the
|
|
196
|
+
file `python -m powerchannel where` prints; delete it to erase them:
|
|
197
|
+
|
|
198
|
+
- Windows: `%LOCALAPPDATA%\powerchannel\channels.db`
|
|
199
|
+
- macOS: `~/Library/Application Support/powerchannel/channels.db`
|
|
200
|
+
- Linux: `~/.local/share/powerchannel/channels.db`
|
|
201
|
+
|
|
202
|
+
## Settings
|
|
203
|
+
|
|
204
|
+
Both optional, as environment variables for every app (set them the same way everywhere):
|
|
205
|
+
|
|
206
|
+
- `POWERCHANNEL_DB`: the database path. Every app must use the same file.
|
|
207
|
+
- `POWERCHANNEL_MAX_WAIT`: the longest `read` wait in seconds, default 43200 (12 h).
|
|
208
|
+
|
|
209
|
+
## Limits
|
|
210
|
+
|
|
211
|
+
- One computer: the database is a local file.
|
|
212
|
+
- Messages older than 7 days are deleted the next time anyone posts.
|
|
213
|
+
- An agent's first read of a channel shows up to 20 earlier messages; after that it gets only new
|
|
214
|
+
ones, up to 200 per call.
|
|
215
|
+
|
|
216
|
+
## Upgrading from powerboard
|
|
217
|
+
|
|
218
|
+
PowerChannel used to be called powerboard.
|
|
219
|
+
|
|
220
|
+
1. `python -m pip uninstall powerboard`, then install PowerChannel as above. Don't
|
|
221
|
+
`pip install powerboard` again: that PyPI name belongs to an unrelated project.
|
|
222
|
+
2. Remove the old `powerboard` server from each app (for example
|
|
223
|
+
`claude mcp remove --scope user powerboard`) and add `powerchannel` as above. Tool names are
|
|
224
|
+
unchanged.
|
|
225
|
+
3. On first start, PowerChannel copies the old database (`powerboard\board.db` in the same data
|
|
226
|
+
folder, `%LOCALAPPDATA%` on Windows) to `powerchannel\channels.db` once. History is kept and
|
|
227
|
+
the old file is left alone.
|
|
228
|
+
|
|
229
|
+
`POWERBOARD_DB` and `POWERBOARD_MAX_WAIT` still work when the new variables are unset.
|
|
230
|
+
|
|
231
|
+
## Development
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
git clone https://github.com/CynaCons/PowerChannel && cd PowerChannel
|
|
235
|
+
python -m pip install -e ".[dev]"
|
|
236
|
+
python -m pytest -q
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
MIT licensed.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""Command line: `powerchannel` (MCP server), plus channels / tail / post for the human."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import sys
|
|
7
|
+
import time
|
|
8
|
+
|
|
9
|
+
from . import __version__
|
|
10
|
+
from .store import HUMAN, Board, BoardError
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def _line(m) -> str:
|
|
14
|
+
return f"[{time.strftime('%m-%d %H:%M', time.localtime(m.created))}] {m.author}: {m.text}"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def main(argv: list[str] | None = None) -> None:
|
|
18
|
+
parser = argparse.ArgumentParser(prog="powerchannel", description=__doc__)
|
|
19
|
+
parser.add_argument("--version", action="version", version=f"powerchannel {__version__}")
|
|
20
|
+
sub = parser.add_subparsers(dest="cmd")
|
|
21
|
+
sub.add_parser("serve", help="run the MCP server over stdio (the default)")
|
|
22
|
+
sub.add_parser("channels", help="list channels and who is active")
|
|
23
|
+
tail = sub.add_parser("tail", help="show a channel and follow new messages")
|
|
24
|
+
tail.add_argument("channel")
|
|
25
|
+
post = sub.add_parser("post", help='post a message as "human"')
|
|
26
|
+
post.add_argument("channel")
|
|
27
|
+
post.add_argument("message")
|
|
28
|
+
sub.add_parser("where", help="print the database location")
|
|
29
|
+
args = parser.parse_args(argv)
|
|
30
|
+
|
|
31
|
+
if args.cmd in (None, "serve"):
|
|
32
|
+
from .server import serve
|
|
33
|
+
serve()
|
|
34
|
+
return
|
|
35
|
+
|
|
36
|
+
for stream in (sys.stdout, sys.stderr):
|
|
37
|
+
try:
|
|
38
|
+
stream.reconfigure(encoding="utf-8")
|
|
39
|
+
except (AttributeError, ValueError):
|
|
40
|
+
pass
|
|
41
|
+
board = Board()
|
|
42
|
+
try:
|
|
43
|
+
if args.cmd == "where":
|
|
44
|
+
print(board.path)
|
|
45
|
+
elif args.cmd == "channels":
|
|
46
|
+
rows = board.channels()
|
|
47
|
+
if not rows:
|
|
48
|
+
print("no channels yet")
|
|
49
|
+
for c in rows:
|
|
50
|
+
print(f"#{c['channel']} ({c['messages']} msgs) active: {', '.join(c['active']) or '-'}")
|
|
51
|
+
print(f" last {_line(c['last'])}")
|
|
52
|
+
elif args.cmd == "post":
|
|
53
|
+
m = board.post(HUMAN, args.channel, args.message)
|
|
54
|
+
print(f"posted to #{m.channel} as {HUMAN}")
|
|
55
|
+
elif args.cmd == "tail":
|
|
56
|
+
last_id = 0
|
|
57
|
+
for m in board.recent(args.channel):
|
|
58
|
+
print(_line(m), flush=True)
|
|
59
|
+
last_id = m.id
|
|
60
|
+
while True:
|
|
61
|
+
time.sleep(1)
|
|
62
|
+
for m in board.recent(args.channel, after_id=last_id):
|
|
63
|
+
print(_line(m), flush=True)
|
|
64
|
+
last_id = m.id
|
|
65
|
+
except BoardError as e:
|
|
66
|
+
sys.exit(f"error: {e}")
|
|
67
|
+
except KeyboardInterrupt:
|
|
68
|
+
pass
|
|
69
|
+
finally:
|
|
70
|
+
board.close()
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def main_deprecated(argv: list[str] | None = None) -> None:
|
|
74
|
+
"""Deprecated `powerboard` entry point: warn, then run the real CLI."""
|
|
75
|
+
print("powerboard was renamed powerchannel; use the powerchannel command.",
|
|
76
|
+
file=sys.stderr)
|
|
77
|
+
main(argv)
|