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.
@@ -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,3 @@
1
+ """powerchannel: named channels so AI agents on one machine can talk to each other."""
2
+
3
+ __version__ = "0.5.0"
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ main()
@@ -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)