setup

name	setup
description	Walk through first-time setup of everclaw — prerequisites, config, database, and verification

/setup — everclaw first-time setup

Guide the developer through a complete, working everclaw setup. Be autonomous: detect what's already done, fix problems yourself, and only ask questions when a real choice is needed.

Instructions

Work through each phase in order. Use TaskCreate to track progress. Verify each phase before moving to the next. If a step fails, diagnose and fix it — don't just report the error.

---

Phase 1: Prerequisites

Check the following tools are available. Run the checks in parallel.

1. Node.js 22.18+ — run node --version and parse the semver. If missing or too old, stop and tell the user to install Node 22.18+ (link to https://nodejs.org). This is not something we can install for them.

2. pnpm — run pnpm --version. If missing, run corepack enable then corepack prepare pnpm@latest --activate to install it.

3. Docker & Docker Compose — run docker --version and docker compose version. Note availability but don't fail here — the user may choose bare metal.

4. PostgreSQL client — run psql --version. Note availability for bare metal path.

Report what was found and what was installed.

---

Phase 2: Choose deployment method

Use AskUserQuestion to ask:

How do you want to run PostgreSQL?

• Docker Compose (Recommended) — Postgres runs in a container alongside the app. Simplest setup.
• Bare metal — You manage your own PostgreSQL instance. Requires psql and a running Postgres server.

If Docker is not installed and user picks Docker, help them understand they need to install Docker first and link to https://docs.docker.com/get-docker/.

---

Phase 3: Install dependencies

pnpm install

Verify it succeeds (exit code 0, node_modules/ exists). If it fails:

• Check if pnpm-lock.yaml exists — if not, this is expected for a fresh clone
• Check for network errors and retry once
• Check for Node version incompatibility in the error output

---

Phase 4: Configure .env

Check if .env already exists in the project root.

If it exists, use AskUserQuestion:

A .env file already exists. What would you like to do?

• Keep it — Skip configuration, use existing values
• Reconfigure — Create a new .env file

If creating/reconfiguring, collect secrets using AskUserQuestion — one question per secret. NEVER echo secrets to the terminal or pass them as bash arguments. Write the file using the Write tool.

1. ANTHROPIC_API_KEY (required) — Ask for their API key. Mention https://console.anthropic.com/settings/keys.

2. BRAVE_SEARCH_API_KEY (optional) — Use AskUserQuestion to ask if they want web search:

   Enable web search? Requires a free Brave Search API key (2000 queries/month free).

   • Skip for now
   • Add API key

   If yes, ask for the key. Mention https://brave.com/search/api/.

3. OPENAI_API_KEY (optional) — Use AskUserQuestion to ask if they want voice transcription:

   Enable voice message transcription? When configured, the bot transcribes voice messages (Telegram, WhatsApp) using OpenAI Whisper (~$0.006/min of audio).

   • Skip for now
   • Add API key

   If yes, ask for the key. Mention https://platform.openai.com/api-keys.

Write the .env file with collected values. No channel configuration here — that comes in Phase 8. Format:

ANTHROPIC_API_KEY=<key>
# Optional: enables the web_search tool (free tier: 2000 queries/month)
# BRAVE_SEARCH_API_KEY=BSA...
# Optional: enables voice message transcription (~$0.006/min of audio)
# OPENAI_API_KEY=sk-...
# Chat ID allowlist — configured during channel setup
# ALLOWED_CHAT_IDS=

Uncomment lines for keys that were provided.

---

Phase 5: Database setup (bare metal only)

Skip this phase entirely if the user chose Docker — Docker Compose auto-initializes the database via sql/ mount to /docker-entrypoint-initdb.d.

For bare metal:

1. Check the DATABASE_URL environment variable. Default is postgresql://localhost/absurd. Ask the user if this is correct or if they want a custom URL.

2. Check if the database exists:

   psql "$DATABASE_URL" -c "SELECT 1" 2>&1
   

   If it doesn't exist, try to create it:

   createdb absurd
   

3. Run the schema migrations:

   psql "$DATABASE_URL" -f sql/001-absurd.sql
   psql "$DATABASE_URL" -f sql/002-assistant.sql
   psql "$DATABASE_URL" -f sql/003-channel-abstraction.sql
   

4. Verify tables were created:

   psql "$DATABASE_URL" -c "SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema IN ('absurd', 'assistant')"
   

If any step fails, show the error and help diagnose (wrong credentials, Postgres not running, etc).

---

Phase 6: Ensure writable directories

Create these directories if they don't exist:

mkdir -p data/notes data/auth skills scripts servers

These are where the agent stores notes, auth state, skill files, tool scripts, and MCP server configs at runtime.

---

Phase 7: Run tests

pnpm test

All tests should pass. If tests fail:

• Read the test output carefully
• Check if it's a dependency issue (re-run pnpm install)
• Check if it's a TypeScript version issue
• Fix the issue if possible, or report it clearly

---

Phase 8: Pick first channel

Use AskUserQuestion to ask:

Which messaging channel do you want to set up first?

• Telegram — Chat bot via BotFather. Simplest to set up.
• Discord — Server/DM bot via Discord Developer Portal.
• Slack — Workspace bot via Slack API (Socket Mode).
• WhatsApp — Personal messaging via QR code scan.
• Gmail — Email via Google OAuth2. Most complex setup.

You can add more channels later with /add-channel-*.

Based on their choice, tell the user:

• Telegram → "Run /add-channel-telegram to set up Telegram."
• Discord → "Run /add-channel-discord to set up Discord."
• Slack → "Run /add-channel-slack to set up Slack."
• WhatsApp → "Run /add-channel-whatsapp to set up WhatsApp."
• Gmail → "Run /add-channel-gmail to set up Gmail."

---

Phase 9: Wrap up

Tell the user:

Core setup is complete. Run the channel setup command from Phase 8 to connect your first messaging channel. That skill will walk you through configuration, first start, and verification.

Provide these useful commands:

• Run tests: pnpm test
• Type check: npx tsc --noEmit
• Start (Docker): docker compose up --build
• Start (bare metal): node src/index.ts
• Stop (Docker): docker compose down
• Stop (bare metal): Ctrl+C

Adding more channels later:

• /add-channel-telegram — Telegram
• /add-channel-discord — Discord
• /add-channel-slack — Slack
• /add-channel-whatsapp — WhatsApp
• /add-channel-gmail — Gmail