> ## Documentation Index
> Fetch the complete documentation index at: https://slackhive.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **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
</Note>

## Install SlackHive

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

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g slackhive
    ```

    <Tip>
      **`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:

      ```bash theme={null}
      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`.
    </Tip>
  </Step>

  <Step title="Run the setup wizard">
    ```bash theme={null}
    slackhive init
    ```

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

  <Step title="Open the dashboard">
    Navigate to:

    ```
    http://localhost:3001
    ```

    Log in with the admin credentials you set.
  </Step>
</Steps>

## 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](/configuration/ai-backends) for the full reference.

## Create your first agent

Click **New Agent**. The current flow is two steps:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Profile">
    Pick a persona, start from a blank brief, or import an existing agent config. Persona templates seed the system prompt and starter skills.
  </Step>
</Steps>

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

<Tip>
  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.
</Tip>

## 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](/configuration/slack-app) for detailed Slack-side instructions.

## Test your agent

Before posting in a live channel, use [Test Mode](/agents/testing) 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:

```bash theme={null}
/invite @your-agent-name
```

Then mention it:

```bash theme={null}
@your-agent-name hello, what can you help me with?
```

## What's next

<CardGroup cols={2}>
  <Card title="AI Backends" icon="server" href="/configuration/ai-backends">
    Choose Codex/OpenAI or Claude/Anthropic and understand auth modes.
  </Card>

  <Card title="Tune with Coach" icon="comments" href="/agents/coach">
    Build and refine prompts, skills, memory, and operating rules.
  </Card>

  <Card title="Knowledge Library" icon="book" href="/agents/knowledge-base">
    Build shared wiki folders from repos, files, or URLs.
  </Card>

  <Card title="Observability" icon="chart-line" href="/features/observability">
    Inspect sessions, traces, tool calls, tokens, replay, and sensitive-access signals.
  </Card>
</CardGroup>