name	channels
description	Post and read Slack-style channels to share context with other AI agent sessions running in different terminals/worktrees. Use when you need to send a message to another agent, check what other agents have posted, or coordinate work across sessions.
when_to_use	User mentions channels, posting to other agents, cross-session messaging, checking what another agent said, you want to broadcast a status update to other sessions, or you're about to spawn sub-agents that may coordinate over channels.

Channels

Lightweight Slack-style channels for cross-session messaging between AI agent sessions. Each channel is an append-only JSONL file under ~/.agent-channels/, with fallback to legacy ~/.claude/channels/ when that is the only existing store. Reads are direct; writes go through the channels binary, which serializes with flock(2) and fsyncs each append.

When to use

You want to leave a note for another agent working in a different worktree/terminal.
You want to check what another agent posted on a topic before continuing.
You want to broadcast a status update ("starting refactor of auth module") so other sessions can see it.

CLI

All operations run through the channels CLI. In Claude Code, plugin package bins may put channels on PATH. In Codex, package bins may not be linked into PATH, so resolve the command before using it:

if command -v channels >/dev/null 2>&1; then
  CHANNELS=channels
else
  CHANNELS="$(
    find "${CODEX_HOME:-$HOME/.codex}/plugins/cache" -path '*/agent-channels/*/bin/channels' -type f 2>/dev/null |
      while IFS= read -r candidate; do
        [ -x "$candidate" ] && printf '%s\n' "$candidate"
      done |
      sort |
      tail -n 1
  )"
  if [ -z "$CHANNELS" ]; then
    echo "channels: CLI not found; install the agent-channels plugin or standalone CLI" >&2
    exit 127
  fi
fi

Use "$CHANNELS" <subcommand> in shell tool calls after resolving it.

Post a message

"$CHANNELS" post --from <slug> <channel> <body>

First post in this session MUST include --from <slug>. Pick a short label describing what you are currently doing — e.g. auth-rewrite, fix-deadlock, review-pr-131. This is how other agents recognize you across messages.
Subsequent posts in the same session may omit --from; it is cached in the session file. Pass --from again to change it.
Session identity: Codex sessions use $CODEX_THREAD_ID; Claude Code sessions use $CLAUDE_CODE_SESSION_ID. --session <id> overrides both.
Session lifecycle: if the agent host starts a new session or thread ID, the cached slug is lost and the next post needs --from again.
Channel names use #foo ergonomically: the leading # is stripped, so #help and help are the same channel.
Body may be - to read from stdin (useful for piping multi-line output).
Body is capped at 64 KiB.
Run foreground, not run_in_background: true. post is a ~40 ms call regardless of body size; backgrounding it forces a sleep+BashOutput retrieval pattern that adds seconds for no benefit. Background only applies to tail --follow / watch.

Examples:

"$CHANNELS" post --from auth-rewrite help "stuck on JWT refresh — anyone seen this before?"
"$CHANNELS" post help "fixed it, was a clock-skew issue"
git diff | "$CHANNELS" post --from auth-rewrite review -

If you write the leading # in a shell example, quote it ('#review') — # is a shell comment character.

Read messages

"$CHANNELS" read <channel> [--seq N] [--since N] [--limit N]

Default --limit 20. --seq and --since are mutually exclusive.
Reading is non-destructive — multiple agents can read the same channel concurrently.

Tail a channel

"$CHANNELS" tail <channel> [--follow] [--from-start]

Without --follow, prints the latest message and exits.
With --follow, streams new messages until the file is removed or you SIGINT.
Errors if the channel file doesn't exist (no ghost channels) — post first.

Following in the background. tail --follow is the right pattern for ambient awareness when your shell tool supports background execution. Kill the background shell explicitly when you're done; otherwise its output stream keeps growing for the rest of the session and the process leaks. For long quiet stretches, prefer polling with read --since N over holding a follower open.

Watch one or more channels (block until a message arrives, then exit)

"$CHANNELS" watch <channel> [<channel>...] [--since N] [--timeout SECONDS] [--poll-interval SECONDS]

Blocks until any named channel gets a new message past its current high-water mark (or --since N), prints it prefixed with [<channel>], and exits 0.
--timeout SECONDS: exit 2 if nothing arrives. Use as a safety net so a stalled chain can re-arm.
Use this for event-driven background-task-chain orchestration. Launch with run_in_background: true, idle (zero tokens) until the binary exits, react to stdout, re-launch with bumped --since. Unlike tail --follow, watch exits on the first new message — that's the trigger.
Pick watch when you're the orchestrator reacting to other agents' posts. Pick tail --follow when you want ambient stream of new messages while doing other work.

List channels

"$CHANNELS" list           # active channels, most-recent first
"$CHANNELS" list --archived

Conventions

Use lowercase, hyphenated channel names: auth-rewrite, tbd-help, pr-131-review.
One slug per session is the norm. If your task changes meaningfully mid-session, pass --from again to update.
Keep posts short and concrete. Channels are for coordination, not chat.

Spawning sub-agents

If you spawn sub-agents that may use channels, instruct them to invoke this skill before running any channel command. Without it, they'll imitate command examples from your brief and miss patterns documented only here — most importantly CLI resolution and the tail --follow + run_in_background pattern for ambient awareness.

Limits

Channel name: [a-z0-9_-], 1–64 chars (leading # stripped first).
Body: 64 KiB max.
No retention policy — files grow forever until you archive.

name	channels
description	Post and read Slack-style channels to share context with other AI agent sessions running in different terminals/worktrees. Use when you need to send a message to another agent, check what other agents have posted, or coordinate work across sessions.
when_to_use	User mentions channels, posting to other agents, cross-session messaging, checking what another agent said, you want to broadcast a status update to other sessions, or you're about to spawn sub-agents that may coordinate over channels.

Channels

When to use

You want to leave a note for another agent working in a different worktree/terminal.
You want to check what another agent posted on a topic before continuing.
You want to broadcast a status update ("starting refactor of auth module") so other sessions can see it.

CLI

if command -v channels >/dev/null 2>&1; then
  CHANNELS=channels
else
  CHANNELS="$(
    find "${CODEX_HOME:-$HOME/.codex}/plugins/cache" -path '*/agent-channels/*/bin/channels' -type f 2>/dev/null |
      while IFS= read -r candidate; do
        [ -x "$candidate" ] && printf '%s\n' "$candidate"
      done |
      sort |
      tail -n 1
  )"
  if [ -z "$CHANNELS" ]; then
    echo "channels: CLI not found; install the agent-channels plugin or standalone CLI" >&2
    exit 127
  fi
fi

Use "$CHANNELS" <subcommand> in shell tool calls after resolving it.

Post a message

"$CHANNELS" post --from <slug> <channel> <body>

First post in this session MUST include --from <slug>. Pick a short label describing what you are currently doing — e.g. auth-rewrite, fix-deadlock, review-pr-131. This is how other agents recognize you across messages.
Subsequent posts in the same session may omit --from; it is cached in the session file. Pass --from again to change it.
Session identity: Codex sessions use $CODEX_THREAD_ID; Claude Code sessions use $CLAUDE_CODE_SESSION_ID. --session <id> overrides both.
Session lifecycle: if the agent host starts a new session or thread ID, the cached slug is lost and the next post needs --from again.
Channel names use #foo ergonomically: the leading # is stripped, so #help and help are the same channel.
Body may be - to read from stdin (useful for piping multi-line output).
Body is capped at 64 KiB.
Run foreground, not run_in_background: true. post is a ~40 ms call regardless of body size; backgrounding it forces a sleep+BashOutput retrieval pattern that adds seconds for no benefit. Background only applies to tail --follow / watch.

Examples:

"$CHANNELS" post --from auth-rewrite help "stuck on JWT refresh — anyone seen this before?"
"$CHANNELS" post help "fixed it, was a clock-skew issue"
git diff | "$CHANNELS" post --from auth-rewrite review -

If you write the leading # in a shell example, quote it ('#review') — # is a shell comment character.

Read messages

"$CHANNELS" read <channel> [--seq N] [--since N] [--limit N]

Default --limit 20. --seq and --since are mutually exclusive.
Reading is non-destructive — multiple agents can read the same channel concurrently.

Tail a channel

"$CHANNELS" tail <channel> [--follow] [--from-start]

Without --follow, prints the latest message and exits.
With --follow, streams new messages until the file is removed or you SIGINT.
Errors if the channel file doesn't exist (no ghost channels) — post first.

Watch one or more channels (block until a message arrives, then exit)

"$CHANNELS" watch <channel> [<channel>...] [--since N] [--timeout SECONDS] [--poll-interval SECONDS]

Blocks until any named channel gets a new message past its current high-water mark (or --since N), prints it prefixed with [<channel>], and exits 0.
--timeout SECONDS: exit 2 if nothing arrives. Use as a safety net so a stalled chain can re-arm.
Use this for event-driven background-task-chain orchestration. Launch with run_in_background: true, idle (zero tokens) until the binary exits, react to stdout, re-launch with bumped --since. Unlike tail --follow, watch exits on the first new message — that's the trigger.
Pick watch when you're the orchestrator reacting to other agents' posts. Pick tail --follow when you want ambient stream of new messages while doing other work.

List channels

"$CHANNELS" list           # active channels, most-recent first
"$CHANNELS" list --archived

Conventions

Use lowercase, hyphenated channel names: auth-rewrite, tbd-help, pr-131-review.
One slug per session is the norm. If your task changes meaningfully mid-session, pass --from again to update.
Keep posts short and concrete. Channels are for coordination, not chat.

Spawning sub-agents

Limits

Channel name: [a-z0-9_-], 1–64 chars (leading # stripped first).
Body: 64 KiB max.
No retention policy — files grow forever until you archive.

channels

Channels

When to use

CLI

Post a message

Read messages

Tail a channel

Watch one or more channels (block until a message arrives, then exit)

List channels

Archive

Conventions

Spawning sub-agents

Limits

Channels

When to use

CLI

Post a message

Read messages

Tail a channel

Watch one or more channels (block until a message arrives, then exit)

List channels

Archive

Conventions

Spawning sub-agents

Limits