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

# Developer Setup

> Complete guide to setting up Hitler for local development

## Prerequisites

Before you begin, ensure you have the following installed:

<CardGroup cols={2}>
  <Card title="Node.js 20+" icon="node-js">
    Download from [nodejs.org](https://nodejs.org)
  </Card>

  <Card title="pnpm 8+" icon="npm">
    Install: `npm install -g pnpm`
  </Card>

  <Card title="Docker Desktop" icon="docker">
    Download from [docker.com](https://docker.com)
  </Card>

  <Card title="Git" icon="git">
    Download from [git-scm.com](https://git-scm.com)
  </Card>
</CardGroup>

## Step 1: Clone and Install

```bash theme={null}
git clone https://github.com/dev-inagiffy/mako.git
cd hitler
pnpm install
```

<Info>
  pnpm will install dependencies for all packages in the monorepo. This may take a few minutes the
  first time.
</Info>

## Step 2: Environment Configuration

Copy the example environment file:

```bash theme={null}
cp .env.example .env
```

### Minimal Configuration (Required)

Edit `.env` with at least these values:

```bash theme={null}
# Database - Docker provides these defaults
DATABASE_URL=postgres://hitler:hitler@localhost:5432/hitler
REDIS_URL=redis://localhost:6379

# Security - Change this to a random string (min 32 characters)
JWT_SECRET=your-super-secret-key-change-me-please
```

<Warning>
  Never commit your `.env` file or share your secrets. The `.gitignore` already excludes `.env`
  files.
</Warning>

<Card title="Complete Environment Variables Guide" icon="gear" href="/development/environment-variables">
  See the full guide for how to get API keys, generate secrets, and configure all options.
</Card>

### LLM Configuration (Optional but Recommended)

For AI-powered task parsing to work, add one of:

<Tabs>
  <Tab title="Anthropic (Claude)">
    `bash ANTHROPIC_API_KEY=sk-ant-your-api-key LLM_MODEL_ANTHROPIC=claude-3-haiku-20240307 `
    Get an API key at [console.anthropic.com](https://console.anthropic.com)
  </Tab>

  <Tab title="OpenAI (GPT)">
    `bash OPENAI_API_KEY=sk-your-api-key LLM_MODEL_OPENAI=gpt-4o-mini ` Get an API key at
    [platform.openai.com](https://platform.openai.com)
  </Tab>
</Tabs>

<Note>
  Without an LLM key, the API will use mock responses. This is fine for UI development but task
  parsing won't work realistically.
</Note>

## Step 3: Start Database Services

Start PostgreSQL and Redis using Docker:

```bash theme={null}
make db-up
```

Or using docker-compose directly:

```bash theme={null}
docker-compose up -d postgres redis
```

Verify they're running:

```bash theme={null}
docker-compose ps
```

You should see both `postgres` and `redis` with status "Up".

## Step 4: Run Database Migrations

Initialize the database schema:

```bash theme={null}
pnpm db:migrate
```

<Accordion title="Optional: Seed sample data">
  `bash pnpm db:seed ` This creates a sample organization, users, and tasks for testing.
</Accordion>

## Step 5: Start Development Servers

Start all services in development mode:

```bash theme={null}
pnpm dev
```

This starts:

| Service   | URL                                                      | Description             |
| --------- | -------------------------------------------------------- | ----------------------- |
| API       | [http://localhost:3000](http://localhost:3000)           | NestJS backend          |
| API Docs  | [http://localhost:3000/docs](http://localhost:3000/docs) | Swagger documentation   |
| Web       | [http://localhost:3005](http://localhost:3005)           | Next.js admin dashboard |
| Slack Bot | [http://localhost:3002](http://localhost:3002)           | Slack adapter           |

<Check>
  Open [http://localhost:3000/health](http://localhost:3000/health) to verify the API is running. You should see `{"status":"ok"}`.
</Check>

## Slack Integration Setup (Local Dev)

The Hitler Slack bot uses **Socket Mode** (WebSocket), so you don't need ngrok or a public URL for local development. We recommend a separate "Hitler Dev" Slack app — see [Slack Setup](/integrations/slack-setup) for the full two-app guide.

### 1. Create a Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click **Create New App** → **From scratch**
3. Name it `Hitler Dev` and select your dev workspace

### 2. Enable Socket Mode

1. Go to **Settings → Socket Mode** → Enable
2. Generate an **App-Level Token** with `connections:write` scope
3. Copy the token (`xapp-1-...`)

### 3. Add Bot Token Scopes

Go to **OAuth & Permissions → Bot Token Scopes** and add:

| Scope               | Purpose                                         |
| ------------------- | ----------------------------------------------- |
| `app_mentions:read` | View messages that directly mention the bot     |
| `channels:history`  | View messages in public channels the bot is in  |
| `chat:write`        | Send messages as the bot                        |
| `commands`          | Add slash commands (e.g. `/hitler`)             |
| `groups:history`    | View messages in private channels the bot is in |
| `im:history`        | View messages in DMs with the bot               |
| `im:read`           | View basic info about DMs the bot is in         |
| `im:write`          | Start direct messages with people               |
| `mpim:history`      | View messages in group DMs the bot is in        |
| `team:read`         | View workspace name, email domain, and icon     |
| `users:read`        | View people in the workspace                    |

### 4. Subscribe to Events

Go to **Event Subscriptions → Subscribe to bot events** and add:

| Event Name         | Description                                             | Required Scope      |
| ------------------ | ------------------------------------------------------- | ------------------- |
| `app_home_opened`  | User opened the bot's App Home tab                      | —                   |
| `app_mention`      | Someone mentions the bot in a channel                   | `app_mentions:read` |
| `message.channels` | A message was posted in a public channel the bot is in  | `channels:history`  |
| `message.groups`   | A message was posted in a private channel the bot is in | `groups:history`    |
| `message.im`       | A message was posted in a DM with the bot               | `im:history`        |
| `message.mpim`     | A message was posted in a group DM the bot is in        | `mpim:history`      |

### 5. Set OAuth Redirect URL

Go to **OAuth & Permissions → Redirect URLs** and add:

```
http://localhost:3000/api/auth/slack/callback
```

### 6. Install to Workspace and Add Credentials

1. Click **Install to Workspace** and authorize
2. Copy credentials to your `.env`:

```bash theme={null}
SLACK_APP_TOKEN=xapp-1-your-app-level-token    # From Socket Mode settings
SLACK_SIGNING_SECRET=your-signing-secret        # From Basic Information
SLACK_CLIENT_ID=your-client-id                  # From Basic Information
SLACK_CLIENT_SECRET=your-client-secret          # From Basic Information
```

Now start the dev servers (`pnpm dev`) and DM the bot in Slack!

## Running Specific Services

Instead of running everything, you can start individual services:

```bash theme={null}
# API only
pnpm --filter @hitler/api dev

# Web dashboard only
pnpm --filter @hitler/web dev

# Slack bot only
pnpm --filter @hitler/bot-slack dev
```

## Common Commands

| Command            | Description                            |
| ------------------ | -------------------------------------- |
| `pnpm dev`         | Start all services in dev mode         |
| `pnpm build`       | Build all packages                     |
| `pnpm test`        | Run all tests                          |
| `pnpm test:watch`  | Run tests in watch mode                |
| `pnpm type-check`  | TypeScript type checking               |
| `pnpm lint`        | Run type checking across all packages  |
| `pnpm format`      | Format code with Prettier              |
| `pnpm db:generate` | Generate migration from schema changes |
| `pnpm db:migrate`  | Run database migrations                |
| `pnpm db:studio`   | Open Drizzle Studio (DB browser)       |

## Project Structure

```
/apps
  api/              # NestJS backend (port 3000)
  web/              # Next.js dashboard (port 3005)
  bot-slack/        # Slack adapter (port 3002)

/packages
  db/               # Database schemas and migrations
  sdk/              # Typed API client
  rules/            # Business rules engine
  prompts/          # LLM prompts
  shared/           # Shared types and schemas
  observability/    # Logging and tracing
  secrets/          # Secrets management
  adapters/         # Platform adapters

/tests              # Test utilities and integration tests
/docs               # Documentation (Mintlify)
```

## Slack Slash Commands

After installing the Slack app, register these slash commands under **Slash Commands** in your app settings.

### Direct Commands (No LLM)

| Command             | Short Description                    | Usage Hint                         |
| ------------------- | ------------------------------------ | ---------------------------------- |
| `/tasks`            | List your current tasks              | `[open\|today\|overdue]`           |
| `/done`             | Mark a task as completed             | `<task number or title>`           |
| `/blocked`          | Report a blocker on a task           | `#<id> <reason>`                   |
| `/unblocked`        | Resolve a blocker on a task          | `#<id> [note]`                     |
| `/status`           | Show your task completion summary    |                                    |
| `/mood`             | Log your mood or view trends         | `[1-5] [note] \| history \| stats` |
| `/journal`          | Create or list journal entries       | `[text to journal]`                |
| `/help`             | Show available commands and help     | `[topic]`                          |
| `/log-intervention` | Log work you picked up for someone   | `<user> <description>`             |
| `/clear-dms`        | Clear all bot messages from your DMs |                                    |

### Admin/Manager Commands (No LLM)

| Command     | Short Description                 | Usage Hint        |
| ----------- | --------------------------------- | ----------------- |
| `/red-card` | Manually issue an escalation card | `<user> <reason>` |

### LLM-Powered Commands

| Command   | Short Description                      | Usage Hint                   |
| --------- | -------------------------------------- | ---------------------------- |
| `/hitler` | Talk to the bot using natural language | `<anything you want to say>` |

<Info>
  The `/hitler` command routes through Claude which has access to 30+ tools including: create/update/complete tasks, set reminders, log mood, check KPI, manage checklists, move pipeline stages, reassign tasks, browse URLs, and more.
</Info>

<Note>
  **Total: 12 slash commands** — 10 direct (no LLM), 1 admin-only, 1 LLM-powered.
  Direct commands respond instantly. The `/hitler` command uses Claude for natural language understanding.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database connection refused">
    Ensure Docker containers are running:

    ```bash theme={null}
    docker-compose ps
    docker-compose logs postgres
    ```

    If needed, restart:

    ```bash theme={null}
    docker-compose down
    docker-compose up -d postgres redis
    ```
  </Accordion>

  <Accordion title="Port already in use">
    Another process is using port 3000, 3005, or 3002. Find and kill it:

    ```bash theme={null}
    lsof -i :3000
    kill -9 <PID>
    ```
  </Accordion>

  <Accordion title="pnpm install fails">
    Clear the cache and reinstall: `bash rm -rf node_modules rm -rf .pnpm-store pnpm install `
  </Accordion>

  <Accordion title="Migrations fail">
    Ensure the database is running and `DATABASE_URL` is correct: `bash docker-compose logs postgres
          psql $DATABASE_URL -c "SELECT 1" `
  </Accordion>

  <Accordion title="Slack bot not receiving events">
    1. Verify Socket Mode is enabled in your Slack app settings
    2. Check that `SLACK_APP_TOKEN` is set in your `.env` (starts with `xapp-`)
    3. Verify Event Subscriptions has `message.im` and `app_mention` subscribed
    4. Check `SLACK_SIGNING_SECRET` matches your app
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the API endpoints
  </Card>

  <Card title="Architecture" icon="sitemap" href="/concepts">
    Understand the system design
  </Card>

  <Card title="Testing Guide" icon="flask-vial" href="/development/testing">
    Write and run tests
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="/development/contributing">
    Contribution guidelines
  </Card>
</CardGroup>