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

# Slack Agent Reference

> Every @tasksmind command, permission scope, and troubleshooting step for the Slack agent.

tasksmind lives in your Slack workspace, right where customers report issues. Mention
`@tasksmind` in any channel it's in to investigate a reported bug, review PRs, fix CI failures,
and open pull requests, without leaving Slack.

## Installation

<Steps>
  <Step title="Add tasksmind to Slack">
    Install from your dashboard so the workspace links to your organization. Sign in, then go to
    **Settings → Integrations** and click **Add to Slack** there. This runs the authenticated
    OAuth flow, so no manual token configuration is needed. (Installing from a public
    page can't detect your organization, so it isn't offered there.)

    The following permissions are requested:

    | Scope               | What it's for                             |
    | ------------------- | ----------------------------------------- |
    | `chat:write`        | Post messages and thread replies          |
    | `app_mentions:read` | Respond to @tasksmind mentions            |
    | `channels:read`     | Read channel names for routing            |
    | `channels:join`     | Join a public channel when you connect it |
    | `im:write`          | Send direct messages (approvals)          |
  </Step>

  <Step title="Add tasksmind to a channel, before you connect it">
    The connect commands below run inside the channel they configure, so tasksmind has to be a
    member of that channel first.

    ```
    /invite @tasksmind
    ```

    Or open the channel name → **Integrations** → **Add apps** → tasksmind. For a public channel,
    tasksmind adds itself when you connect it; a private channel must invite it (agents can't
    self-add). If you connect before it's in the channel, nothing is saved, it'll ask you to add
    it first.
  </Step>

  <Step title="Link a channel to a GitHub repo">
    Link a repo to the current channel. tasksmind uses this repo as context for all agent commands
    run in this channel.

    ```
    @tasksmind connect github your-org/your-repo
    ```

    Repeat this in each channel to connect different repos. One channel can have one active repo.
  </Step>

  <Step title="Connect a customer-support channel (optional)">
    In a channel your customers post to, an org owner or admin maps it to an on-call project's
    repo. Reports here become incidents and fix PRs automatically. Customers only see friendly
    updates, never code, logs, or stack traces.

    ```
    @tasksmind connect support your-org/your-repo
    ```

    The repo must already have an on-call project in your dashboard.
  </Step>

  <Step title="Designate a dev channel for incident detail (optional)">
    In your team's internal engineering channel (never your customer support channel), route the
    full technical detail for incidents, root cause, file paths, PR links:

    ```
    @tasksmind set dev channel here
    ```

    The agent refuses to designate a channel already marked as a support channel, so this can't
    accidentally leak technical detail to customers.
  </Step>

  <Step title="Verify setup">
    ```
    @tasksmind ping
    # Expected: pong | backend=connected | sdk=loaded

    @tasksmind status
    # Expected: lists your connected repo
    ```
  </Step>
</Steps>

## Commands

Every command works as an `@tasksmind …` mention in a channel the agent is in, or in a DM with
the agent. Agent commands stream progress updates in a thread and may ask for approval before
taking action.

### Setup

| Command                               | What it does                                                                              |
| ------------------------------------- | ----------------------------------------------------------------------------------------- |
| `@tasksmind connect github org/repo`  | Link a GitHub repo to this channel                                                        |
| `@tasksmind connect support org/repo` | Make this a customer-support channel (owner/admin)                                        |
| `@tasksmind set dev channel here`     | Route root cause, file paths, and PR links to this channel (refuses on a support channel) |
| `@tasksmind status`                   | Show repos connected to this channel                                                      |
| `@tasksmind setup`                    | Post the full step-by-step setup guide                                                    |
| `@tasksmind ping`                     | Health check, confirms backend and SDK are reachable                                      |

### Status & info

Instant replies, no agent job started.

| Command                        | What it does                           |
| ------------------------------ | -------------------------------------- |
| `@tasksmind status PR #214`    | PR status, review state, and CI checks |
| `@tasksmind status TICKET-123` | Ticket status and execution history    |
| `@tasksmind changes PR #214`   | File changes and diff summary for a PR |

### Agent commands

These start a background job. tasksmind posts progress steps in a thread and asks for approval
before committing or opening a PR.

| Command                                                  | What it does                                                        |
| -------------------------------------------------------- | ------------------------------------------------------------------- |
| `@tasksmind review https://github.com/org/repo/pull/214` | Full code review: findings, risks, suggestions                      |
| `@tasksmind review PR #214`                              | Same as above using PR number (repo must be connected)              |
| `@tasksmind fix CI for PR 214`                           | Fetch failing check logs, identify root cause, propose fix          |
| `@tasksmind fix bug <description>`                       | Investigate a bug report, find root cause, propose fix              |
| `@tasksmind implement <feature>`                         | Plan and implement a feature, requires approval before committing   |
| `@tasksmind summarize this repo`                         | Index the connected repo and generate an architecture summary       |
| `@tasksmind investigate <topic>`                         | Pull Slack, logs, and recent commits to root-cause a customer issue |

Replies are posted in a thread on your message so the channel stays clean.

<Card title="The approval & safety gate" icon="shield-check" href="/use-cases/approval-and-safety">
  Full detail on the four approval buttons, risk classification, and who can approve.
</Card>

## Enterprise & self-hosted

If your team uses a self-hosted or enterprise Slack App, configure the following URLs in your
Slack App manifest under **Event Subscriptions** and **Interactivity**:

```
Events URL:        https://<your-host>/slack/events
Interactivity URL: https://<your-host>/slack/interactions
```

Under **Event Subscriptions → Subscribe to bot events**, add: `app_mention`, `message.channels`,
`message.im`.

Then invite the agent to your channels with `/invite @tasksmind`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="@tasksmind requests fail with a signature error">
    **Cause:** `SLACK_SIGNING_SECRET` is missing or wrong in the agent configuration.

    **Fix:** Verify the signing secret matches the value in your Slack App → Basic Information →
    App Credentials.
  </Accordion>

  <Accordion title="@tasksmind mentions get no response">
    **Cause:** The agent is not in the channel, or the `app_mention` event is not subscribed.

    **Fix:** Run `/invite @tasksmind` in the channel. Then check Slack App → Event Subscriptions
    and confirm `app_mention` is listed under bot events.
  </Accordion>

  <Accordion title="connect github returns &#x22;workspace is not registered&#x22;">
    **Cause:** The workspace was not installed via the OAuth flow, only a direct token was added.

    **Fix:** Re-install via the **Add to Slack** button on the Integrations page to complete the
    OAuth install and register the workspace.
  </Accordion>

  <Accordion title="Agent returns &#x22;Repository appears to be empty or inaccessible&#x22;">
    **Cause:** The GitHub token does not have access to the repository (common with fine-grained
    tokens).

    **Fix:** Use a classic GitHub Personal Access Token (`ghp_...`) with `repo` scope, or ensure
    your fine-grained token explicitly includes the target repository.
  </Accordion>

  <Accordion title="fix CI / review PR returns a 404 error">
    **Cause:** The GitHub token lacks read access to the repository, or the PR number does not
    exist.

    **Fix:** Confirm the token has `repo` scope and the PR number is correct. Merged PRs are still
    accessible via the API.
  </Accordion>

  <Accordion title="ping returns sdk=not loaded">
    **Cause:** The tasksmind SDK module failed to import, usually a missing dependency or env
    var.

    **Fix:** Check that `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` are set in your deployment
    secrets.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Your setup guide" icon="rocket" href="/getting-started">
    The full account-to-first-fix walkthrough.
  </Card>

  <Card title="API keys" icon="key" href="/reference/api-keys">
    Programmatic access for webhooks and custom integrations.
  </Card>
</CardGroup>