Quick Start

From zero to your first AI agent responding in Slack - in under 10 minutes.

This guide takes you from a fresh machine to a working SlackHive setup with a live agent in your Slack workspace.

Before you begin, you’ll need:

• Node.js 20 or later - node --version to check
• Claude Code installed (the agents run on top of it)
• A Slack workspace where you can install apps (admin, or permission to install apps)
• One of:
  • An Anthropic API key - pay per token, best for teams
  • A Claude Pro or Max subscription - already signed in via claude login

Install SlackHive

The slackhive CLI handles everything - checks your environment, clones the repo, walks you through configuration, and starts the services.

1. Install the CLI

   npm install -g slackhive
   

   EACCES: permission denied? If you installed Node from nodejs.org on macOS/Linux, /usr/local/lib/node_modules is root-owned. Point npm at a user-owned prefix once:

   mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
   source ~/.zshrc
   

   Then retry npm install -g slackhive. Full troubleshooting in Install the CLI.

2. Run the setup wizard

   slackhive init
   

   The wizard asks a few questions:

   Prompt	What to enter
   Install directory	Where to put SlackHive (default: ./slackhive)
   Admin username	Your login name for the dashboard
   Admin password	A strong password
   Claude auth	Pick API key or OAuth from Claude Code

   Everything else (encryption keys, ports) is generated automatically. First run takes 2–3 minutes while dependencies install and the apps build.

3. Open the dashboard

   Navigate to:

   http://localhost:3001
   

   Log in with the admin credentials you set. You’ll see the SlackHive dashboard.

See Install with the CLI for more detail.

Create your first agent

Click New Agent in the sidebar. This opens a 5-step wizard.

1. Name & Description

   • Name - shown in Slack (e.g. “Data Analyst” or “Ava”)
   • Description - what this agent does, in one sentence. Boss uses this to know who to delegate to.
   • Model - claude-sonnet-4-6 is a good default

   Leave the Boss toggle off for now.

2. Pick a Persona

   Browse the Persona Library - 26 research-backed starters (Data Analyst, Backend Engineer, Product Manager, Technical Writer, and more). Pick one that fits.

   The persona seeds the agent’s system prompt, skills, and recommended MCPs. You can customize everything later with Coach. If none fit, pick Blank.

3. Create a Slack App

   Each SlackHive agent needs its own Slack app. The wizard generates everything you need.

   1. Click Generate Manifest in the wizard
   2. Open api.slack.com/apps in a new tab
   3. Click Create New App → From an app manifest
   4. Select your Slack workspace
   5. Paste the manifest JSON from the wizard
   6. Click Create
   7. On the next screen, click Install to Workspace → Allow
4. Enter Credentials

   You need three values from your Slack app:

   Bot Token - OAuth & Permissions → Bot User OAuth Token (starts with xoxb-)

   App Token - Basic Information → App-Level Tokens → Generate Token and Scopes → add connections:write → copy (starts with xapp-)

   Signing Secret - Basic Information → App Credentials → Signing Secret → Show → copy

   Paste all three and click Verify Connection. See Slack app setup if verification fails.

5. Tools & Review

   Assign any MCP servers you’ve added to the catalog. You can skip this and add them later.

   Review the summary and click Create Agent. The runner picks up the new agent within a few seconds - status flips to Active on the dashboard.

Test your agent in Slack

1. Invite the bot to a channel

   /invite @your-agent-name
   
2. Send a message

   @your-agent-name hello, what can you help me with?
   

   You should see a typing indicator, then a reply in the thread.

You can also DM the bot directly - open a new DM in Slack, find the agent by name, start chatting.

Before posting in a live channel, try Test Mode - it’s a sandboxed conversation pane with real MCPs.

What’s next

Tune with Coach

Interactive prompt, skill, and knowledge tuning.

Knowledge Library

Shared wiki folders. Anyone can build one; agents are assigned the folders they need.

Boss Agents

Set up an orchestrator that routes to the right specialist.

Connect MCP Servers

Give your agent real tools - query databases, read files, call APIs.