
agentchannels
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@agentchannelsRun it inside Claude Code after adding the marketplace with /plugin marketplace add agentchannels/agentchannels-archived.
Contents
Discovered from sourceSkills 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:
- API Key — Validate
ANTHROPIC_API_KEYagainst the Anthropic API - Agent — Select an existing Claude Managed Agent or create a new one
- Environment — Select an existing Claude Environment or create a new one
- Vaults — Optionally attach Vault IDs for MCP OAuth credentials (skippable)
- 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_KEYCLAUDE_AGENT_IDCLAUDE_ENVIRONMENT_IDCLAUDE_VAULT_IDSSLACK_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:
<name>(<id>)<name>(<id>) ... N. Create a new agentWhich would you like to use?"
2c. Create a new agent
Ask:
- Name — default:
agentchannels-bot - Description (optional — press Enter to skip)
- System prompt (optional — can be configured later in the Anthropic Console)
- 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:
- Name — default:
<agent-name>-env - 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_IDSis 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_IDSis 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?
- Manual — I already have a Slack Bot Token (
xoxb-...), App-Level Token (xapp-...), and Signing Secret- Automatic — I have a Slack Refresh Token (
xoxe-...) and want the CLI to create the app for meWhich path would you like to use?"
5b. Collect credentials
Manual path
Ask for each credential separately and validate the format before proceeding:
-
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. -
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 scopeconnections:write). This token enables Socket Mode (no public URL needed). -
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:
-
Slack app name — display name for the app (default:
"General Agent"). Confirm before proceeding — renaming later requires visiting api.slack.com/apps. -
Slack app description (optional) — one-line description shown in the workspace app directory.
-
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
.envautomatically."
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
achis not found in PATH: trynpx agentchannels init slack --non-interactiveor./node_modules/.bin/ach init slack --non-interactiveas 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 confirmedCLAUDE_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 credentialsNext step: Run
/ach:serveto start the bridge, orach deploy railwayto deploy to Railway.
On failure (non-zero exit code)
Show the error output and diagnose:
| Error pattern | Remediation |
|---|---|
| Token format error | Re-prompt for the specific credential that failed (return to Phase 5) |
ANTHROPIC_API_KEY invalid | Re-run Phase 1 |
| Agent / environment not found | Re-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 credentials | Clarify which tokens are missing and re-prompt |
Edge cases and warnings
- Existing
.env: The CLI automatically backs up the existing.envbefore writing. Inform the user their previous credentials are preserved in.env.bak. - Stale IDs in
.env: If an existingCLAUDE_AGENT_IDorCLAUDE_ENVIRONMENT_IDis 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-...endingXk3Q). - 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:writescope exists. - Guided Slack path: The guided path (step-by-step manifest display) is only available via
ach init slackrun directly in a terminal (without--non-interactive). If a user wants that experience, instruct them to runach init slackin 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:
| Variable | Description |
|---|---|
CLAUDE_AGENT_ID | Claude Managed Agent ID |
CLAUDE_ENVIRONMENT_ID | Claude Environment ID |
How to verify:
- Read the
.envfile (it is at.envrelative to the project root, i.e. read<cwd>/.env) - Check whether
CLAUDE_AGENT_IDandCLAUDE_ENVIRONMENT_IDare both present and non-empty - If the
.envfile 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-slackto create a Claude Agent, Environment, and Slack credentials. Once that completes, run/ach:serveagain.
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:
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY | Anthropic API key (starts with sk-ant-) |
SLACK_BOT_TOKEN | Slack Bot Token (starts with xoxb-) |
SLACK_APP_TOKEN | Slack 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-slackto 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
.envfilePress Enter to skip and start now with your
.envdefaults."
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:
| Output | Meaning |
|---|---|
Empty / no match | No bridge process is running — safe to proceed |
One or more lines containing ach serve or agentchannels serve | An 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?
- Kill the existing process and restart — I'll run
kill <PID>for you, then start fresh.- Keep the existing process — Skip startup; the bridge is already listening.
- 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
achis not found in PATH (e.g. package not globally installed), trynpx agentchannels serveor./node_modules/.bin/ach serveas 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 commandinvalid_authortoken_revoked→ Slack tokens are invalid; suggest re-running/ach:init-slackECONNREFUSEDor network errors → check internet connectivityCLAUDE_AGENT_ID/CLAUDE_ENVIRONMENT_IDnot found → run/ach:init-slackfirst 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 serveuses 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_IDSwith 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 railwayinstead of runningach servelocally.
Sponsors
Details
- Marketplace
- agentchannels/agentchannels-archived
- Category
- Development
- License
- Apache-2.0
- Keywords
- claude, slack, agent, chatbot, managed-agents, anthropic, agentchannels