cc-agent-messenger

English | 日本語

Reply to your AI coding agents from Slack on your phone, while they keep working in VS Code or an interactive CLI. A small resident bot bridges a Slack channel to the live Claude Code session (and, headlessly, to Codex / Copilot), so you can ask for status, choose the next step, or get pinged when a long job finishes — as complete message turns, not live terminal mirroring.

⚠️ Security & responsibility. This tool runs commands in response to Slack messages (RCE-adjacent). It is built for a single trusted operator on a trusted machine. Enabling hands-free auto-reply grants auto-execution of the reply command — a conscious risk you accept. No warranty; use at your own risk. See SECURITY.md.

Each Slack app connects to its daemon over Socket Mode. C0 uses a project skill in a resident Claude Code session; C1 runs headless agent turns without that skill. Click the diagram for the PDF.

Demo

What it looks like from your phone — a Slack thread where you @-mention the bot and the resident Claude Code session in VS Code or the interactive CLI answers (commands start with !; plain words and emoji/button taps work too):

  you →  @bot !status
  bot →  Running. Watching experiment X — epoch 12/50, loss 0.34 (stable).

  you →  @bot !options
  bot →  Next steps:
           1: lower the learning rate and continue
           2: keep going
           3: pause
         (tap a button, say "1", or react 1️⃣)

  you →  !select 1
  bot →  OK — lowering the learning rate to 1e-4 and continuing.

  bot →  (later, unprompted)  ✅ Experiment X finished. Send !results for the summary.

What it does

• Inbound: a Slack message in your private channel is authorized and appended to a local file; your resident Claude Code session — either a VS Code window or an interactive claude CLI (C0) — watches it with tail -F, wakes, interprets the command, and replies. Optional C1 instead lets the daemon spawn a headless agent per Slack turn; upgrading does not enable C1 automatically.
• Outbound: the reply is posted by the project's own bot, @-mentioning you, so your phone gets a push.
• Per-repository identity: default_agent names the default C0 sender; optional [[agent]].display_name names each routed C0/C1 sender (falling back to stable name). Requires the Slack chat:write.customize scope.
• Agents: Claude Code via the live session (C0); Codex and Copilot via headless CLIs (C1). (C1 is also available for Claude.)

Requirements

• macOS or Linux/WSL, VS Code + the Claude Code extension, Python ≥ 3.11, uv.
• A Slack workspace + one private channel, and a Slack app (Socket Mode).
• For Codex/Copilot: their own CLIs installed + authenticated (codex, @github/copilot). Claude via C0 needs no extra CLI.

Install

uv tool install cc-agent-messenger
# or from source:
uv tool install git+https://github.com/noboru2000/cc-agent-messenger

Update & uninstall

Check your installed version and upgrade to the latest PyPI release:

cc-agent-messenger --version                 # installed version
uv tool upgrade cc-agent-messenger           # -> upgrades, or "Nothing to upgrade"

Nothing to upgrade means you already have the latest. The latest available is the PyPI badge above, https://pypi.org/project/cc-agent-messenger/, or uv pip index versions cc-agent-messenger. (pipx: pipx upgrade cc-agent-messenger; pip: pip install -U cc-agent-messenger.)

After upgrading, re-run cc-agent-messenger init in the same project to refresh the skill, then cc-agent-messenger restart (= stop + start the daemon). init keeps your existing bot settings — tokens, owner, channel, and profile.json are preserved; only the skill is refreshed (it prints what it refreshed vs kept). No VS Code window reload is needed — re-arm the live session in place (see docs/SETUP.md §7 → Copy-paste prompts).

Uninstall:

cc-agent-messenger uninstall            # remove the project skill + .gitignore block (keeps config)
cc-agent-messenger uninstall --purge    # also delete .cc-agent-messenger/ (config, profile, audit)
uv tool uninstall cc-agent-messenger    # remove the global CLI

Quickstart

cd your-project
cc-agent-messenger init          # scaffolds the skill, config template, gitignore, allowlist
# 1) create a Slack app (Socket Mode + scopes + Event Subscriptions); see docs/SETUP.md
# 2) fill .cc-agent-messenger/config.toml with your tokens + channel id
cc-agent-messenger daemon        # run the resident bot

# verify the return path:
cc-agent-messenger ping          # -> {"status":"alive"}
cc-agent-messenger send --text "test"   # -> posts to your channel; phone gets a push

Then, in your VS Code Claude Code session, invoke the cc-agent-messenger skill to start watching the channel and replying. Add the printed allow-rule to .claude/settings.json to make replies hands-free.

What init adds to .gitignore

init writes a # cc-agent-messenger block with exactly these two entries — generated runtime + secrets that must never be committed:

Only the cc-agent-messenger skill folder is ignored under .claude/, not .claude/ itself — your own Claude Code assets (settings.json, your skills and commands) stay committable. If a project has nothing else under .claude/, it simply won't appear in the repo. (Upgrading from a version that also ignored tmp/ + *.sock? Re-running init keeps those lines — your existing config.toml may still write inbound events there — and just adds the skill entry.)

Commands

CLI: cc-agent-messenger <init | uninstall | daemon | restart | send | ping | status | stop | kill on|off | doctor | pending | ack | monitors | watch | keepalive | commands> — see cc-agent-messenger --help. restart = stop + start the daemon (enables a no-reload upgrade). watch / keepalive register on the running daemon — the same scheduler as Slack !watch / !keepalive; commands [--all] lists every command. doctor --slack probes the live bot (auth, granted scopes — flags a missing reactions:write — channel membership, Socket Mode); add --live for an active 👀→✅ receipt self-test (posts a probe to the channel).

From Slack (@bot + a leading !, deterministic, no Slack slash registration — or plain words / buttons / emoji):

• Ask/act: !status, !results, !issues, !options, !select 2, !continue, !doctor, !help.
• Pause/redirect: !pause (soft halt — channel stays open; !continue resumes). The hard freeze is the CLI-only kill switch.
• Away & keep-alive: !away MR:10m ["what to report"] / !back; !keepalive MR:10m | off. MR: = minimum report interval (you hear at least every N; a real reply postpones the next), default 10m when omitted.
• Scheduled monitors: !watch <id> every:5m ["items"] (e.g. SSH a GPU box for util/mem/temp + loss, with threshold alerts) / !watch <id> off / !watch off (stop all) / !watch list. every: = fixed cadence.

Full reference in docs/USAGE.md.

Limitations

• Session-bound: the live (C0) bridge works only while the interactive Claude session, its host, and the skill's Monitor remain running. It is not a 24/7 service by itself.
• Copilot/Codex replies come from a headless CLI turn, separate from their VS Code GUI panels.

Docs

• docs/SETUP.md — Slack app creation, invite, config, run, E2E, troubleshooting.
• docs/USAGE.md — Slack command reference (!status, !options, …), keywords, and expected behavior once it is running.
• docs/ARCHITECTURE.md — the C0 loop, the egress chokepoint, the four input surfaces, the security model.

License & author

MIT © 2026 Noboru Harada.

Author / maintainer: Noboru Harada <noboru@ieee.org>. Security reports: see SECURITY.md. Bugs / features: open an issue.