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
• A Slack workspace where you can install apps
• One AI backend:
  • OpenAI Codex / ChatGPT - use codex login or an OpenAI API key
  • Claude Code / Anthropic - use claude login or an Anthropic API key

Install SlackHive

The slackhive CLI 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.

2. Run the setup wizard

   slackhive init
   

   The wizard asks for an install directory and admin login. Backend credentials are connected after first launch in Settings → AI Backend.

3. Open the dashboard

   Navigate to:

   http://localhost:3001
   

   Log in with the admin credentials you set.

Connect an AI backend

Open Settings → AI Backend and choose the runtime your agents should use.

Backend	Best path	Also supported
OpenAI Codex	ChatGPT login / device auth	OPENAI_API_KEY, CODEX_AUTH_JSON, CODEX_PATH
Claude Code	claude login	ANTHROPIC_API_KEY, CLAUDE_CREDENTIALS_JSON, CLAUDE_BIN

The dashboard header shows the active backend status. If the badge is disconnected or expired, open Settings, run Detect, or paste fresh credentials.

See AI Backends for the full reference.

Create your first agent

Click New Agent. The current flow is two steps:

1. Identity

   Give the agent a name, choose whether it is a Specialist or Boss, optionally assign it to a Boss, and add tags for dashboard filtering.

2. Profile

   Pick a persona, start from a blank brief, or import an existing agent config. Persona templates seed the system prompt and starter skills.

Slack, tools, model choice, permissions, wiki folders, and deeper instructions are configured after creation from the agent page.

Do not try to get the whole prompt perfect in the creation flow. After creation, open Coach and describe what you want in plain English. Coach can draft and refine system prompts, skills, memory, evaluation cases, and operating rules.

Connect Slack

After creation, SlackHive opens the agent page with Slack setup ready.

1. Create a Slack app from the generated manifest.
2. Install it to your workspace.
3. Paste the bot token, app-level token, and signing secret.
4. Save, then start or reload the agent.

See Slack App Setup for detailed Slack-side instructions.

Test your agent

Before posting in a live channel, use Test Mode from the agent page. It runs the real agent with its real tools without sending anything to Slack.

When ready, invite the bot to a Slack channel:

/invite @your-agent-name

Then mention it:

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

What’s next

AI Backends

Choose Codex/OpenAI or Claude/Anthropic and understand auth modes.

Tune with Coach

Build and refine prompts, skills, memory, and operating rules.

Knowledge Library

Build shared wiki folders from repos, files, or URLs.

Observability

Inspect sessions, traces, tool calls, tokens, replay, and sensitive-access signals.