Developer Setup

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 20+

Download from nodejs.org

pnpm 8+

Install: npm install -g pnpm

Docker Desktop

Download from docker.com

Git

Download from git-scm.com

Step 1: Clone and Install

git clone https://github.com/dev-inagiffy/mako.git
cd hitler
pnpm install

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

Step 2: Environment Configuration

Copy the example environment file:

cp .env.example .env

Minimal Configuration (Required)

Edit .env with at least these values:

# 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

Never commit your .env file or share your secrets. The .gitignore already excludes .env files.

Complete Environment Variables Guide

See the full guide for how to get API keys, generate secrets, and configure all options.

LLM Configuration (Optional but Recommended)

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

Anthropic (Claude)
OpenAI (GPT)

bash ANTHROPIC_API_KEY=sk-ant-your-api-key LLM_MODEL_ANTHROPIC=claude-3-haiku-20240307 Get an API key at console.anthropic.com

bash OPENAI_API_KEY=sk-your-api-key LLM_MODEL_OPENAI=gpt-4o-mini Get an API key at platform.openai.com

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

Step 3: Start Database Services

Start PostgreSQL and Redis using Docker:

make db-up

Or using docker-compose directly:

docker-compose up -d postgres redis

Verify they’re running:

docker-compose ps

You should see both postgres and redis with status “Up”.

Step 4: Run Database Migrations

Initialize the database schema:

pnpm db:migrate

Optional: Seed sample data

bash pnpm db:seed This creates a sample organization, users, and tasks for testing.

Step 5: Start Development Servers

Start all services in development mode:

pnpm dev

This starts:

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

Open http://localhost:3000/health to verify the API is running. You should see {"status":"ok"}.

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 for the full two-app guide.

1. Create a Slack App

Go to api.slack.com/apps
Click Create New App → From scratch
Name it Hitler Dev and select your dev workspace

2. Enable Socket Mode

Go to Settings → Socket Mode → Enable
Generate an App-Level Token with connections:write scope
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

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

Click Install to Workspace and authorize
Copy credentials to your .env:

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:

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

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.

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.

Troubleshooting

Database connection refused

Ensure Docker containers are running:

docker-compose ps
docker-compose logs postgres

If needed, restart:

docker-compose down
docker-compose up -d postgres redis

Port already in use

Another process is using port 3000, 3005, or 3002. Find and kill it:

lsof -i :3000
kill -9 <PID>

pnpm install fails

Clear the cache and reinstall: bash rm -rf node_modules rm -rf .pnpm-store pnpm install

Migrations fail

Ensure the database is running and DATABASE_URL is correct: bash docker-compose logs postgres psql $DATABASE_URL -c "SELECT 1"

Slack bot not receiving events

Verify Socket Mode is enabled in your Slack app settings
Check that SLACK_APP_TOKEN is set in your .env (starts with xapp-)
Verify Event Subscriptions has message.im and app_mention subscribed
Check SLACK_SIGNING_SECRET matches your app

Next Steps

API Reference

Explore the API endpoints

Architecture

Understand the system design

Testing Guide

Write and run tests

Contributing

Contribution guidelines

Getting Started

Roadmap

Development

Integrations

Guides

Developer Setup

Prerequisites

Node.js 20+

pnpm 8+

Docker Desktop

Git

Step 1: Clone and Install

Step 2: Environment Configuration

Minimal Configuration (Required)

Complete Environment Variables Guide

LLM Configuration (Optional but Recommended)

Step 3: Start Database Services

Step 4: Run Database Migrations

Step 5: Start Development Servers

Slack Integration Setup (Local Dev)

1. Create a Slack App

2. Enable Socket Mode

3. Add Bot Token Scopes

5. Set OAuth Redirect URL

6. Install to Workspace and Add Credentials

Running Specific Services

Common Commands

Project Structure

Slack Slash Commands

Direct Commands (No LLM)

Admin/Manager Commands (No LLM)

LLM-Powered Commands

Troubleshooting

Next Steps

API Reference

Architecture

Testing Guide

Contributing

Getting Started

Roadmap

Development

Integrations

Guides

​Prerequisites

Node.js 20+

pnpm 8+

Docker Desktop

Git

​Step 1: Clone and Install

​Step 2: Environment Configuration

​Minimal Configuration (Required)

Complete Environment Variables Guide

​LLM Configuration (Optional but Recommended)

​Step 3: Start Database Services

​Step 4: Run Database Migrations

​Step 5: Start Development Servers

​Slack Integration Setup (Local Dev)

​1. Create a Slack App

​2. Enable Socket Mode

​3. Add Bot Token Scopes

​4. Subscribe to Events

​5. Set OAuth Redirect URL

​6. Install to Workspace and Add Credentials

​Running Specific Services

​Common Commands

​Project Structure

​Slack Slash Commands

​Direct Commands (No LLM)

​Admin/Manager Commands (No LLM)

​LLM-Powered Commands

​Troubleshooting

​Next Steps

API Reference

Architecture

Testing Guide

Contributing

Prerequisites

Step 1: Clone and Install

Step 2: Environment Configuration

Minimal Configuration (Required)

LLM Configuration (Optional but Recommended)

Step 3: Start Database Services

Step 4: Run Database Migrations

Step 5: Start Development Servers

Slack Integration Setup (Local Dev)

1. Create a Slack App

2. Enable Socket Mode

3. Add Bot Token Scopes

4. Subscribe to Events

5. Set OAuth Redirect URL

6. Install to Workspace and Add Credentials

Running Specific Services

Common Commands

Project Structure

Slack Slash Commands

Direct Commands (No LLM)

Admin/Manager Commands (No LLM)

LLM-Powered Commands

Troubleshooting

Next Steps