channel-management

name	channel-management
description	Manage Claude Code --channels sessions (start/stop/status/health) via channel-manager.cjs and terminal-tracker.cjs.
version	1.0.0
model	sonnet
invoked_by	both
user_invocable	true
tools	["Read","Bash","TaskUpdate"]
agents	["developer","devops","heartbeat-orchestrator"]
category	External Integrations
tags	["channels","telegram","session","lifecycle","pid","terminal","health"]
best_practices	["Always call isChannelRunning() before startChannel() to avoid duplicate sessions","Track PID via terminal-tracker after every start","Run health check within 10 seconds of start to confirm session is live","Use CHANNEL_AUTO_START=true in .env only for supervised production environments"]
error_handling	strict
streaming	not-applicable
source	builtin
trust_score	100
provenance_sha	76303e7de92f80e4

Channel Management

Overview

This skill manages the full lifecycle of a Claude Code --channels session (Telegram bot, Discord bot, or any plugin-based channel integration). It wraps the CLI tools at .claude/tools/cli/channel-manager.cjs and .claude/tools/cli/terminal-tracker.cjs and provides a repeatable, observable workflow for:

1. Starting a channel session in a new Windows Terminal tab
2. Stopping a running channel session cleanly
3. Checking status and PID liveness
4. Health-checking the session via the terminal tracker

When to Invoke

Skill({ skill: 'channel-management' });

Invoke when:

• CHANNEL_AUTO_START=true is set and session startup must be verified on agent boot
• A user or cron job requests manual channel lifecycle management
• A channel session appears to have crashed and needs restart
• Diagnosing why Telegram/Discord messages are not being received
• Inspecting or pruning orphaned channel PID entries

The Iron Law

NEVER start a channel session without checking isChannelRunning() first.
NEVER assume a tracked PID is alive without calling isPidAlive(pid).
NEVER restart after a crash without calling killOrphaned() to prune stale entries.

---

Workflow

Step 0: Read Memory Context (MANDATORY)

Before executing any lifecycle action, read memory to check for known issues:

node -e "const fs=require('fs');const p='.claude/context/memory/learnings.md';if(fs.existsSync(p))console.log(fs.readFileSync(p,'utf8').split(/\r?\n/).slice(0,80).join('\n'));"

Check .claude/context/memory/issues.md for any known channel startup problems:

node -e "const fs=require('fs');const p='.claude/context/memory/issues.md';if(fs.existsSync(p))console.log(fs.readFileSync(p,'utf8').split(/\r?\n/).slice(0,60).join('\n'));"

Step 1: Check isChannelRunning

Command:

node -e "
const { isChannelRunning, getChannelPid } = require('./.claude/tools/cli/channel-manager.cjs');
const running = isChannelRunning();
const pid = getChannelPid();
console.log(JSON.stringify({ running, pid }));
"