Install and run agentchannels from Claude Code via /ach:init-slack and /ach:serve

version
0.2.0
GitHub stars
12

Install

/plugin install agentchannels@agentchannels

Run it inside Claude Code after adding the marketplace with /plugin marketplace add agentchannels/agentchannels-archived.

Contents

Discovered from source

Skills 2

/ach:init-slack

Initialize a complete agentchannels stack — Claude Managed Agent, Environment, optional Vault IDs, and Slack bot — by collecting credentials conversationally and writing them to .env.

Overview

This skill guides the user through the full agentchannels setup in five phases:

  1. API Key — Validate ANTHROPIC_API_KEY against the Anthropic API
  2. Agent — Select an existing Claude Managed Agent or create a new one
  3. Environment — Select an existing Claude Environment or create a new one
  4. Vaults — Optionally attach Vault IDs for MCP OAuth credentials (skippable)
  5. Slack — Configure the Slack bot (bot token, app token, signing secret)

All five phases complete before anything is written to .env. If any phase fails, the user stays in that phase until it succeeds or they abort.

Why this order? Agent and environment validation require a live API key. Validating these before Slack setup means users never configure Slack only to discover their agent is broken — the failure is surfaced immediately.


Pre-flight — Read existing .env

Before asking any questions, use the Read tool to check for an existing .env file in the current working directory. Extract these values if present:

  • ANTHROPIC_API_KEY
  • CLAUDE_AGENT_ID
  • CLAUDE_ENVIRONMENT_ID
  • CLAUDE_VAULT_IDS
  • SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_SIGNING_SECRET, SLACK_REFRESH_TOKEN

Store them as defaults for the steps that follow. Never echo raw token or key values back to the user — show only the prefix (e.g., sk-ant-... confirmed) or confirm the last four characters.


Phase 1 — API Key

1a. Check existing key

If ANTHROPIC_API_KEY is already set in .env or the current environment, inform the user and validate it immediately (see 1b):

"I found an existing ANTHROPIC_API_KEY (ending ...{last4}) in .env. Validating it now..."

If no key is found:

"To get started, I need your Anthropic API key. You can find it at https://console.anthropic.com/keys (starts with sk-ant-).

Please paste it when prompted — it will not be displayed."

Collect it without echoing (treat like a password field).

1b. Validate the key

Run the following Bash command to validate the key by listing agents as a lightweight health check:

ANTHROPIC_API_KEY='<key>' node --input-type=module <<'EOF'
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
try {
  await client.beta.agents.list({ limit: 1 });
  console.log('VALID');
} catch (e) {
  console.log('INVALID:' + e.message);
}
EOF
  • Output VALID: proceed to Phase 2.
  • Output starts with INVALID:: show the error message and re-prompt for the key. Do not proceed until the key validates successfully.
  • Node/SDK failure: inform the user and ask them to confirm the key is correct before proceeding.

Phase 2 — Agent

2a. Check existing agent ID

If CLAUDE_AGENT_ID is found in .env, validate it immediately:

"Found CLAUDE_AGENT_ID=<id> in .env. Validating it..."

ANTHROPIC_API_KEY='<key>' node --input-type=module <<'EOF'
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
try {
  const agent = await client.beta.agents.retrieve('<agent_id>');
  console.log(JSON.stringify({ id: agent.id, name: agent.name }));
} catch (e) {
  console.log('ERROR:' + e.message);
}
EOF
  • Valid response: Confirm (✅ Agent "<name>" (<id>) is accessible) and ask whether to keep it or choose a different one.

    • Keep it: proceed to Phase 3 with this agent ID.
    • Choose differently: continue to 2b.
  • Error / not found: Warn the user explicitly — do not silently drop the stale value:

    ⚠️ The agent ID in your .env (<id>) is no longer accessible (stale). You'll need to select or create a replacement.

    Then continue to 2b.

2b. List available agents

ANTHROPIC_API_KEY='<key>' node --input-type=module <<'EOF'
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
try {
  const response = await client.beta.agents.list({ limit: 20 });
  const data = response.data ?? response;
  console.log(JSON.stringify(Array.isArray(data)
    ? data.map(a => ({ id: a.id, name: a.name }))
    : []));
} catch (e) {
  console.log('ERROR:' + e.message);
}
EOF

If the list is empty or returns an error, skip selection and jump directly to 2c (create). Do not show a blank menu.

If agents exist, present them with a final "Create a new agent" option:

"Here are your existing Claude Managed Agents:

  1. <name> (<id>)
  2. <name> (<id>) ... N. Create a new agent

Which would you like to use?"

2c. Create a new agent

Ask:

  1. Name — default: agentchannels-bot
  2. Description (optional — press Enter to skip)
  3. System prompt (optional — can be configured later in the Anthropic Console)
  4. Model (optional — press Enter to use the API default, e.g. claude-opus-4-5)

Then create:

ANTHROPIC_API_KEY='<key>' node --input-type=module <<'EOF'
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
try {
  const params = { name: '<name>' };
  if ('<model>') params.model = '<model>';
  if ('<description>') params.description = '<description>';
  if ('<system>') params.system = '<system>';
  const agent = await client.beta.agents.create(params);
  console.log(JSON.stringify({ id: agent.id, name: agent.name }));
} catch (e) {
  console.log('ERROR:' + e.message);
}
EOF
  • Success: confirm (✅ Agent "<name>" created — ID: <id>) and proceed to Phase 3.
  • Error: show the message and re-prompt. Do not proceed until an agent is resolved.

Phase 3 — Environment

Agents and environments are independent top-level resources. The environment does not need to share a name with the agent, though a matching suffix (e.g., agentchannels-bot-env) is a helpful convention.

3a. Check existing environment ID

If CLAUDE_ENVIRONMENT_ID is found in .env, validate it:

"Found CLAUDE_ENVIRONMENT_ID=<id> in .env. Validating it..."

ANTHROPIC_API_KEY='<key>' node --input-type=module <<'EOF'
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
try {
  const env = await client.beta.environments.retrieve('<env_id>');
  console.log(JSON.stringify({ id: env.id, name: env.name }));
} catch (e) {
  console.log('ERROR:' + e.message);
}
EOF
  • Valid: Confirm and offer to keep it or choose a different one.
  • Error / not found: Warn explicitly (stale state) and continue to 3b. Never silently discard the stale ID without warning.

3b. List available environments

ANTHROPIC_API_KEY='<key>' node --input-type=module <<'EOF'
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
try {
  const response = await client.beta.environments.list({ limit: 20 });
  const data = response.data ?? response;
  console.log(JSON.stringify(Array.isArray(data)
    ? data.map(e => ({ id: e.id, name: e.name }))
    : []));
} catch (e) {
  console.log('ERROR:' + e.message);
}
EOF

If the list is empty, skip to 3c (create). If environments exist, present them with a "Create a new environment" option.

3c. Create a new environment

Ask:

  1. Name — default: <agent-name>-env
  2. Description (optional)
ANTHROPIC_API_KEY='<key>' node --input-type=module <<'EOF'
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
try {
  const params = { name: '<name>' };
  if ('<description>') params.description = '<description>';
  const env = await client.beta.environments.create(params);
  console.log(JSON.stringify({ id: env.id, name: env.name }));
} catch (e) {
  console.log('ERROR:' + e.message);
}
EOF
  • Success: confirm (✅ Environment "<name>" created — ID: <id>) and proceed to Phase 4.
  • Error: show the message and re-prompt.

Phase 4 — Vaults (optional)

"Do you have any Vault IDs for MCP tool OAuth credentials? Vaults let the agent access services like Google Drive or GitHub using stored OAuth tokens managed by Anthropic.

Enter vault IDs as a comma-separated list (e.g., vault_abc123,vault_def456), or press Enter to skip."

  • If CLAUDE_VAULT_IDS is already in .env, show the existing value as the default and offer to keep or replace it.
  • If the user presses Enter without providing values, CLAUDE_VAULT_IDS is left unset (omitted from .env).

Note: Vault creation is out of scope for this wizard. To create a vault, visit the Anthropic Console.


Phase 5 — Slack Setup

5a. Determine setup path

"How would you like to set up your Slack integration?

  1. Manual — I already have a Slack Bot Token (xoxb-...), App-Level Token (xapp-...), and Signing Secret
  2. Automatic — I have a Slack Refresh Token (xoxe-...) and want the CLI to create the app for me

Which path would you like to use?"

5b. Collect credentials

Manual path

Ask for each credential separately and validate the format before proceeding:

  1. Slack Bot Token — must start with xoxb- and be at least 20 characters. Found at: Basic Information → OAuth & Permissions → Bot User OAuth Token on api.slack.com/apps.

  2. Slack App-Level Token — must start with xapp- and be at least 20 characters. Found at: Basic Information → App-Level Tokens → Generate Token and Scopes (add scope connections:write). This token enables Socket Mode (no public URL needed).

  3. Slack Signing Secret — any non-empty string at least 10 characters. Found at: Basic Information → App Credentials → Signing Secret.

Tell the user: "Please paste credentials one at a time. Do not include multiple tokens in a single message."

Automatic path

Ask in order:

  1. Slack app name — display name for the app (default: "General Agent"). Confirm before proceeding — renaming later requires visiting api.slack.com/apps.

  2. Slack app description (optional) — one-line description shown in the workspace app directory.

  3. Slack Refresh Token — must start with xoxe- and be at least 20 characters.

    • To generate: api.slack.com/apps → Your Apps → Refresh tokens.
    • Warn: "⚠️ This will open a browser window for OAuth authorization and may take up to 5 minutes."
    • Warn: "⚠️ The refresh token is invalidated after use. The CLI saves the new refresh token to .env automatically."

Phase 6 — Execute the CLI command

Once all phases are complete, call ach init slack --non-interactive with all collected credentials as inline environment variables. Never pass credentials as CLI flags — inline env vars keep them out of process listings.

Manual path command

ANTHROPIC_API_KEY='<api_key>' \
CLAUDE_AGENT_ID='<agent_id>' \
CLAUDE_ENVIRONMENT_ID='<env_id>' \
SLACK_BOT_TOKEN='<bot_token>' \
SLACK_APP_TOKEN='<app_token>' \
SLACK_SIGNING_SECRET='<signing_secret>' \
ach init slack --non-interactive

With optional vault IDs:

ANTHROPIC_API_KEY='<api_key>' \
CLAUDE_AGENT_ID='<agent_id>' \
CLAUDE_ENVIRONMENT_ID='<env_id>' \
CLAUDE_VAULT_IDS='<vault_ids>' \
SLACK_BOT_TOKEN='<bot_token>' \
SLACK_APP_TOKEN='<app_token>' \
SLACK_SIGNING_SECRET='<signing_secret>' \
ach init slack --non-interactive

Automatic path command

ANTHROPIC_API_KEY='<api_key>' \
CLAUDE_AGENT_ID='<agent_id>' \
CLAUDE_ENVIRONMENT_ID='<env_id>' \
SLACK_REFRESH_TOKEN='<refresh_token>' \
ach init slack --non-interactive \
  --app-name '<app_name>' \
  --app-description '<app_description>'

With optional vault IDs:

ANTHROPIC_API_KEY='<api_key>' \
CLAUDE_AGENT_ID='<agent_id>' \
CLAUDE_ENVIRONMENT_ID='<env_id>' \
CLAUDE_VAULT_IDS='<vault_ids>' \
SLACK_REFRESH_TOKEN='<refresh_token>' \
ach init slack --non-interactive \
  --app-name '<app_name>' \
  --app-description '<app_description>'

Omit --app-description if the user didn't provide one. If no name was supplied, omit --app-name too — the CLI defaults to "General Agent".

If ach is not found in PATH: try npx agentchannels init slack --non-interactive or ./node_modules/.bin/ach init slack --non-interactive as fallbacks.


Phase 7 — Report results

On success (exit code 0)

Confirm that all credentials were saved to .env:

✅ Setup complete! The following were written to .env:

  • ANTHROPIC_API_KEY — Anthropic API key confirmed
  • CLAUDE_AGENT_ID — Agent: <name> (<id>)
  • CLAUDE_ENVIRONMENT_ID — Environment: <name> (<id>)
  • CLAUDE_VAULT_IDS — <vault_ids> (if provided)
  • SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_SIGNING_SECRET — Slack credentials

Next step: Run /ach:serve to start the bridge, or ach deploy railway to deploy to Railway.

On failure (non-zero exit code)

Show the error output and diagnose:

Error patternRemediation
Token format errorRe-prompt for the specific credential that failed (return to Phase 5)
ANTHROPIC_API_KEY invalidRe-run Phase 1
Agent / environment not foundRe-run Phase 2 or Phase 3 to select a valid ID
OAuth timeout (automatic path)Explain the browser window must be completed within 5 minutes; offer to retry Phase 5
Insufficient credentialsClarify which tokens are missing and re-prompt

Edge cases and warnings

  • Existing .env: The CLI automatically backs up the existing .env before writing. Inform the user their previous credentials are preserved in .env.bak.
  • Stale IDs in .env: If an existing CLAUDE_AGENT_ID or CLAUDE_ENVIRONMENT_ID is no longer accessible via the API, warn the user explicitly. Never silently overwrite or discard the stale ID without informing the user.
  • Token security: Never echo raw token or API key values back to the user in plain text. Show only the prefix or final four characters (e.g., xoxb-... confirmed, sk-ant-... ending Xk3Q).
  • Empty agent / environment lists: If the API returns an empty list, skip selection and jump directly to the create step. Do not render a blank menu.
  • Vault creation out of scope: Vaults can only be selected in this wizard, not created. If the user needs a new vault, direct them to the Anthropic Console before rerunning this skill.
  • Socket Mode requirement: The Slack app must have Socket Mode enabled. For manual path users who may have missed this: Settings → Socket Mode → Enable Socket Mode. Ensure an App-Level Token with connections:write scope exists.
  • Guided Slack path: The guided path (step-by-step manifest display) is only available via ach init slack run directly in a terminal (without --non-interactive). If a user wants that experience, instruct them to run ach init slack in their terminal instead.

/ach:serve

Start the agentchannels bridge server, connecting Slack to Claude Managed Agents via Socket Mode.

Overview

This skill starts the ach serve process in the background. It bridges incoming Slack messages to a Claude Managed Agent session and streams responses back into the Slack thread.

Before starting the server, verify that all required credentials are available by reading the .env file in the current directory and checking the current environment. The user must have completed /ach:init-slack (which handles agent, environment, and Slack setup in one flow) before running this skill.

Step 1 — Verify CLAUDE_AGENT_ID and CLAUDE_ENVIRONMENT_ID

Use the Read tool to check the .env file in the current directory for the following required variables:

VariableDescription
CLAUDE_AGENT_IDClaude Managed Agent ID
CLAUDE_ENVIRONMENT_IDClaude Environment ID

How to verify:

  1. Read the .env file (it is at .env relative to the project root, i.e. read <cwd>/.env)
  2. Check whether CLAUDE_AGENT_ID and CLAUDE_ENVIRONMENT_ID are both present and non-empty
  3. If the .env file does not exist, the variables are missing

If either CLAUDE_AGENT_ID or CLAUDE_ENVIRONMENT_ID is missing or empty, stop immediately and respond:

❌ Cannot start the server — missing required configuration:

  • CLAUDE_AGENT_ID — [present ✓ / missing ✗]
  • CLAUDE_ENVIRONMENT_ID — [present ✓ / missing ✗]

Please run /ach:init-slack to create a Claude Agent, Environment, and Slack credentials. Once that completes, run /ach:serve again.

Do not proceed past Step 1 if either variable is missing.

Step 2 — Verify remaining required credentials

After confirming CLAUDE_AGENT_ID and CLAUDE_ENVIRONMENT_ID are present, check the .env file (already read in Step 1) for these additional required variables:

VariableDescription
ANTHROPIC_API_KEYAnthropic API key (starts with sk-ant-)
SLACK_BOT_TOKENSlack Bot Token (starts with xoxb-)
SLACK_APP_TOKENSlack App-Level Token (starts with xapp-)

SLACK_SIGNING_SECRET and CLAUDE_VAULT_IDS are optional.

If any of the three remaining required variables are missing, stop and inform the user:

❌ Missing additional required configuration: [list missing variables]

Please run /ach:init-slack to configure your Slack credentials, then try again.

Step 3 — Check for optional configuration

Ask the user if they need any optional settings:

"Everything looks good — all required credentials are present. Do you need any optional settings before starting?

  • Vault IDs — comma-separated vault IDs for MCP tool OAuth credentials (e.g., vault_abc123,vault_def456)
  • Credential overrides — only needed if you want to use different credentials than those in your .env file

Press Enter to skip and start now with your .env defaults."

If the user has vault IDs or wants to override specific credentials, collect them before proceeding.

Step 4 — Check for an already-running instance

Before launching, run the following Bash command to detect any existing ach serve / agentchannels process:

ps aux | grep -E 'ach serve|agentchannels' | grep -v grep

Alternatively, if pgrep is available (macOS / most Linux distributions):

pgrep -la -f 'ach serve|agentchannels' 2>/dev/null || echo "no match"

Interpreting the output:

OutputMeaning
Empty / no matchNo bridge process is running — safe to proceed
One or more lines containing ach serve or agentchannels serveAn instance is already running

If an instance is already running, stop and ask the user:

⚠️ An agentchannels bridge process appears to already be running:

<paste matching ps line(s) here>

Starting a second instance may cause duplicate responses in Slack.

What would you like to do?

  1. Kill the existing process and restart — I'll run kill <PID> for you, then start fresh.
  2. Keep the existing process — Skip startup; the bridge is already listening.
  3. Start anyway — Launch a second instance (not recommended).

Obtain the PID from the ps output (second column in ps aux). If the user chooses option 1, run kill <PID> (or kill -9 <PID> if the process does not respond), confirm it has stopped by re-running the check command, then proceed to Step 5.

If no running instance is found, proceed directly to Step 5.

Step 5 — Execute the serve command

Run ach serve using the Bash tool. This is a long-running process — always use run_in_background: true so it does not block the conversation.

Basic command (uses .env for all credentials)

ach serve

With vault IDs

CLAUDE_VAULT_IDS='<vault_ids>' ach serve

With credential overrides (inline env vars for security, not visible in ps)

ANTHROPIC_API_KEY='<api_key>' \
CLAUDE_AGENT_ID='<agent_id>' \
CLAUDE_ENVIRONMENT_ID='<env_id>' \
SLACK_BOT_TOKEN='<bot_token>' \
SLACK_APP_TOKEN='<app_token>' \
ach serve

Note: If ach is not found in PATH (e.g. package not globally installed), try npx agentchannels serve or ./node_modules/.bin/ach serve as fallbacks.

Pass credentials as inline environment variables rather than CLI flags to keep them out of process listings (ps aux).

Always set run_in_background: true when executing this Bash command.

Step 6 — Confirm startup and monitor output

After launching, watch the initial output lines for confirmation of successful startup:

Expected success output:

[serve] Starting agentchannels server...
[serve]   Agent:       <agent_id>
[serve]   Environment: <env_id>
[serve] ⚡️ Bolt app is running! (development, socket mode)
[serve] Bot is running. Press Ctrl+C to stop.

Report the result to the user:

  • On successful start: Confirm the server is running and explain that it is listening for Slack messages. Remind them the process runs in the background and can be stopped with Ctrl+C in the terminal or by killing the process.

  • On startup failure (non-zero exit / error in output): Show the error and diagnose:

    • Configuration validation failed → one or more required env vars are missing; guide the user to run the relevant init command
    • invalid_auth or token_revoked → Slack tokens are invalid; suggest re-running /ach:init-slack
    • ECONNREFUSED or network errors → check internet connectivity
    • CLAUDE_AGENT_ID / CLAUDE_ENVIRONMENT_ID not found → run /ach:init-slack first to create the agent and environment

Edge cases and warnings

  • Already running: If the user suspects the server is already running (e.g., from a previous session), warn them: running a second instance may cause duplicate responses in Slack. They should kill the existing process before starting a new one.

  • Socket Mode requirement: ach serve uses Slack Socket Mode — no public URL or port forwarding is required. The app token (xapp-) enables the WebSocket connection.

  • Session persistence: Sessions are held in memory only. Restarting the server loses all active Slack conversation sessions, and users will start fresh conversations.

  • Vault IDs: If the agent uses MCP tools requiring OAuth credentials (e.g., Google Drive, GitHub), pass CLAUDE_VAULT_IDS with the appropriate vault IDs. These are created via the Anthropic Console.

  • Graceful shutdown: The server handles SIGINT and SIGTERM — it aborts in-flight Slack responses cleanly before exiting. Users can stop it safely with Ctrl+C.

  • Railway / production deployment: For persistent hosting, guide the user to run ach deploy railway instead of running ach serve locally.

Sponsors

Details

Marketplace
agentchannels/agentchannels-archived
Category
Development
License
Apache-2.0
Keywords
claude, slack, agent, chatbot, managed-agents, anthropic, agentchannels