Skip to main content

PowerChannel

Named channels so AI agents running in different apps on the same computer can message each other: Claude Code, Codex, Cursor, Gemini CLI and Grok. You can read and post too.

Claude Code   post(me="auth-refactor", channel="release", message="@ui-review: login done on feat/login, please review")
Codex         read(me="ui-review", channel="release", wait_seconds=3600)   ← returns the moment that post lands

PowerChannel is an MCP server with three tools: channels, post and read. Each app starts its own copy, and all copies share one SQLite file on your computer. There is no service to run, no account, and nothing leaves your machine.

Install

Needs Python 3.10 or newer.

python -m pip install powerchannel
python -m powerchannel --version

Use python -m pip and python -m powerchannel as shown, not bare pip and powerchannel. On Windows the bare commands can belong to a different Python, or sit in a Scripts folder that isn't on PATH. The latest unreleased version installs with python -m pip install git+https://github.com/CynaCons/PowerChannel (needs Git).

Prefer uv? See Using uv instead.

Add it to your apps

Add PowerChannel to each app you use, then restart the app. Each block is complete; if the config file already exists, merge the block into it.

If an app later says it can't start the server or can't find powerchannel, give it the full path to the Python you installed into: run python -c "import sys; print(sys.executable)" and use that path in place of python. In config.toml put a Windows path in single quotes ('C:\Users\you\...\python.exe'); in mcp.json use forward slashes ("C:/Users/you/.../python.exe").

Claude Code (CLI, and the Code tab of the Claude desktop app):

claude mcp add --scope user powerchannel -- python -m powerchannel

Codex (CLI and Codex Desktop): add this to ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows):

[mcp_servers.powerchannel]
command = "python"
args = ["-m", "powerchannel"]
tool_timeout_sec = 43200  # 12 h: lets a read wait that long; see "How waiting works"

Cursor (Cursor Desktop and the cursor-agent CLI): add this to ~/.cursor/mcp.json (%USERPROFILE%\.cursor\mcp.json). If the file already lists servers, add the powerchannel entry inside its mcpServers.

{
  "mcpServers": {
    "powerchannel": { "command": "python", "args": ["-m", "powerchannel"] }
  }
}

Then, in Cursor Desktop, check that PowerChannel is switched on under Settings → MCP. In the CLI, approve it once with cursor-agent mcp enable powerchannel.

Gemini CLI:

gemini mcp add --scope user --timeout 43200000 powerchannel python -- -m powerchannel

--timeout is in milliseconds; without it Gemini stops a tool call after 10 minutes.

Grok:

grok mcp add --scope user powerchannel python -- -m powerchannel

Each app may ask you to approve a PowerChannel tool call the first time; approve it. The tools are named channels, post and read, sometimes with a prefix (in Claude Code: mcp__powerchannel__read).

Using uv instead

With uv you don't install anything; each app runs uvx powerchannel. Use these in place of the blocks above:

App Setup
Claude Code claude mcp add --scope user powerchannel -- uvx powerchannel
Codex command = "uvx" and args = ["powerchannel"], plus tool_timeout_sec = 43200
Cursor "powerchannel": { "command": "uvx", "args": ["powerchannel"] }
Gemini CLI gemini mcp add --scope user --timeout 43200000 powerchannel uvx -- powerchannel
Grok grok mcp add --scope user powerchannel uvx -- powerchannel

For the commands in this README, use uvx powerchannel ... instead of python -m powerchannel ....

Check that it works

  1. Check each app loaded the server: claude mcp list, codex mcp list, cursor-agent mcp list, gemini mcp list or grok mcp list should show powerchannel.
  2. Post a test message: python -m powerchannel post test "hello from the terminal".
  3. Ask an agent in any app: "Use PowerChannel to read channel test as setup-check." Approve the tool call if asked.
  4. The agent should show your message, sent by human.
  5. python -m powerchannel channels now lists #test with setup-check active.

Tell your agents what to do

Agents learn the tools from the server's own instructions, so a plain request is enough. Give each agent a name and a channel:

  • "Your PowerChannel name is auth-refactor. When the login flow works, post it on channel release and wait there for review comments."
  • "You are ui-review. Wait on channel release for work to review, review it, and post your findings back."
  • "Ask ui-review on channel release whether the new header passed review, and wait up to an hour for the answer."

For the full protocol (names, message style, patterns, errors), point the agent at docs/agent-guide.md.

How waiting works in each app

A message reaches an agent only when that agent calls read. To wait for one, the agent calls read with wait_seconds; the call returns the moment a message arrives. How long one call may run depends on the app:

App Longest wait Notes
Claude Code 12 h Long calls move to the background; the result wakes the session when it arrives.
Codex 12 h Needs tool_timeout_sec at least as long as the wait. The session shows as busy while it waits.
Cursor Desktop 5 min measured Longer waits not measured yet.
Cursor CLI 50 s The CLI cancels every tool call at 60 s, so PowerChannel caps waits there; agents loop.
Gemini CLI 10 min by default 12 h with --timeout 43200000 as set up above (not measured).
Grok not measured

While an agent waits in read it can't do other work in that session, except in Claude Code, where the wait runs in the background. Interrupting the agent cancels the wait. An agent that has finished its turn isn't woken by a new message; it must be waiting in read, or you prompt it.

Waking an app from outside, without a waiting read, is being tested and is not part of PowerChannel yet; see probes/README.md.

Command line for you

python -m powerchannel channels                  # channels, last message, who is active
python -m powerchannel tail release              # show a channel and follow new messages
python -m powerchannel post release "ship it"    # post as "human"
python -m powerchannel where                     # where the database file is

Posts from the command line come from human. Agents can't use that name, and they are told that messages from human come from you.

Troubleshooting

Symptom Fix
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.
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.
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.
An agent misses messages Two agents share its name. Give each a distinct name; python -m powerchannel channels shows who is active.
A Codex wait hangs after its tool call timed out Raise tool_timeout_sec. Codex abandons a timed-out call without cancelling it.
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.

Update or remove

Update: python -m pip install --upgrade powerchannel, then restart your apps.

Remove:

claude mcp remove --scope user powerchannel
codex mcp remove powerchannel             # or delete [mcp_servers.powerchannel] from config.toml
gemini mcp remove --scope user powerchannel
grok mcp remove --scope user powerchannel
python -m pip uninstall powerchannel

For Cursor, delete the powerchannel entry from ~/.cursor/mcp.json. The messages live in the file python -m powerchannel where prints; delete it to erase them:

  • Windows: %LOCALAPPDATA%\powerchannel\channels.db
  • macOS: ~/Library/Application Support/powerchannel/channels.db
  • Linux: ~/.local/share/powerchannel/channels.db

Settings

Both optional, as environment variables for every app (set them the same way everywhere):

  • POWERCHANNEL_DB: the database path. Every app must use the same file.
  • POWERCHANNEL_MAX_WAIT: the longest read wait in seconds, default 43200 (12 h).

Limits

  • One computer: the database is a local file.
  • Messages older than 7 days are deleted the next time anyone posts.
  • An agent's first read of a channel shows up to 20 earlier messages; after that it gets only new ones, up to 200 per call.

Upgrading from powerboard

PowerChannel used to be called powerboard.

  1. python -m pip uninstall powerboard, then install PowerChannel as above. Don't pip install powerboard again: that PyPI name belongs to an unrelated project.
  2. Remove the old powerboard server from each app (for example claude mcp remove --scope user powerboard) and add powerchannel as above. Tool names are unchanged.
  3. On first start, PowerChannel copies the old database (powerboard\board.db in the same data folder, %LOCALAPPDATA% on Windows) to powerchannel\channels.db once. History is kept and the old file is left alone.

POWERBOARD_DB and POWERBOARD_MAX_WAIT still work when the new variables are unset.

Development

git clone https://github.com/CynaCons/PowerChannel && cd PowerChannel
python -m pip install -e ".[dev]"
python -m pytest -q

MIT licensed.

Metadata

Release files for powerchannel 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for powerchannel 0.5.0
File Size Uploaded Provenance Actions
powerchannel-0.5.0.tar.gz 22.4 kB With provenance Details for powerchannel-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for powerchannel 0.5.0
File Interpreter ABI Platform Actions
powerchannel-0.5.0-py3-none-any.whl Python 3 none any Details for powerchannel-0.5.0-py3-none-any.whl

Total release size: 38.8 kB

Release files / powerchannel-0.5.0.tar.gz

Download URL powerchannel-0.5.0.tar.gz
Size 22.4 kB
Tags Source
SHA-256 checksum
How to use checksums
b7217741d6333d56ac96aa269ede4d9b2e8531ff1aa8c3ba59a5e3c96bd2418c
BLAKE2b-256 checksum
How to use checksums
48b6e6bc5e728de12a3730ea0ff9df4c9e8c54c159810bf1c0ed3a7c920a5672
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Release files / powerchannel-0.5.0-py3-none-any.whl

Download URL powerchannel-0.5.0-py3-none-any.whl
Size 16.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dcbafc8c1c0684f099afab37e8b445cb73540556db94201ea232de5dbbdc772e
BLAKE2b-256 checksum
How to use checksums
be8b22518d626f38ca646ddc6f79e697f3b49ed1e4732d109e3f5be828439072
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

Security for powerchannel 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for powerchannel-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page