colibri/.agent/skills/setup/SKILL.md

name	description
setup	Run initial Clawdie setup on FreeBSD 15 + Lumina desktop. Use when installing dependencies, configuring pi agent, authenticating Telegram, registering the main group, or starting the background service. Triggers on "setup", "install", "configure clawdie", or first-time setup requests.

Clawdie Setup

Run setup steps automatically. Only pause when user action is required (channel authentication, configuration choices). Steps emit structured status blocks to stdout. Verbose logs go to logs/setup.log.

Principle: When something needs repair, handle it. Don't tell the user to go fix it themselves unless it genuinely requires their manual action (e.g. authenticating a channel, pasting a secret token). If a dependency is missing, install it. If a service needs diagnosis, investigate and resolve. Ask the user for permission when needed, then do the work.

UX Note: Use AskUserQuestion for all user-facing questions.

Jail-based runtime. Clawdie runs agents inside a FreeBSD bastille jail ({agent}-controlplane). No Docker, no bhyve. The pi subprocess runs inside that jail. clawdie-iso firstboot prepares the host and jails.

0. Git & Fork Setup

Check the git remote configuration.

Run: git remote -v

Case A — origin points to Clawdie/Clawdie-AI on Codeberg (user cloned directly):

AskUserQuestion: "You cloned Clawdie-AI directly. We recommend forking so you can push your customizations. Would you like to set up a fork?"

• Fork now: instruct the user to fork Clawdie/Clawdie-AI on Codeberg, then ask for their Codeberg username. Run:

  git remote rename origin upstream
  git remote add origin git@codeberg.org:<username>/Clawdie-AI.git
  git push --force origin main
  

• Continue without fork: add upstream so they can still pull updates:

  git remote add upstream git@codeberg.org:Clawdie/Clawdie-AI.git
  

Case B — origin is user's fork, no upstream:

git remote add upstream git@codeberg.org:Clawdie/Clawdie-AI.git

Case C — both origin and upstream exist: Already configured. Continue.

1. Bootstrap (Node.js + Dependencies)

Run bash setup.sh and parse the status block.

• If NODE_OK=false → Node.js is missing or too old. Use AskUserQuestion: Would you like me to install Node.js 24?. If confirmed:

  sudo pkg install -y node24 npm
  

  After installing, re-run bash setup.sh.
• If DEPS_OK=false → Read logs/setup.log. Delete node_modules and re-run bash setup.sh.
• If NATIVE_OK=false → pg native bindings need build tools:

  sudo pkg install -y gmake gcc python311
  

  Then retry.
• Note: clawdie-iso firstboot installs node24, npm, tmux, and pi — most of these will already be present.

2. Check Environment

Run npx tsx setup/index.ts --step environment and parse the status block.

• If HAS_AUTH=true → Telegram is already configured, note for step 5.
• If HAS_REGISTERED_GROUPS=true → note existing config, offer to skip or reconfigure.
• Check if .env was generated by clawdie-iso firstboot (shell-env.sh). If present, read it and skip asking for secrets already set.

3. Verify Pi Agent

No container runtime needed. Verify pi is installed and accessible.

which pi && pi --version

• If pi is missing: install it:

  npm install -g @earendil-works/pi-coding-agent
  

• Verify pi can reach the configured LLM provider. Check ~/.pi/agent/auth.json and ~/.pi/agent/settings.json:

  cat ~/.pi/agent/auth.json
  cat ~/.pi/agent/settings.json
  

  Important: Never overwrite these files — always append/merge. A bad overwrite previously lost API keys. If keys are missing, append only the missing provider entry.
• Run a quick test: pi --print "Reply with just: OK" --no-session — if it fails, check provider balance and key.

4. LLM Provider Authentication

If .env already has ZAI_API_KEY (from clawdie-iso firstboot), confirm with user: keep or reconfigure?

AskUserQuestion: Using ZAI (default) or a different provider?

ZAI (default): Confirm ZAI_API_KEY is set. The ISO firstboot seeds ZAI_API_BASE automatically.

Anthropic API key: Tell user to add ANTHROPIC_API_KEY=<key> to .env.

Claude Code subscription: Tell user to run claude setup-token in another terminal, copy the token, add CLAUDE_CODE_OAUTH_TOKEN=<token> to .env. Do NOT collect the token in chat.

5. Set Up Channels

AskUserQuestion (multiSelect): Which messaging channels do you want to enable?

• Telegram (authenticates via bot token from @BotFather)
• Discord (authenticates via Discord bot token)
• Slack (authenticates via Slack app with Socket Mode)

Delegate to each selected channel's own skill:

• Telegram: Invoke /add-telegram
• Discord: Invoke /add-discord
• Slack: Invoke /add-slack

Each skill handles its own token collection, registration, and JID resolution.

After all channel skills complete:

npm install && npm run build

Note: if TELEGRAM_BOT_TOKEN is already in .env (written by clawdie-iso firstboot), Telegram auto-enables without re-entering credentials. Confirm with the user before running /add-telegram in that case.

6. Mount Allowlist

AskUserQuestion: Should the agent have access to external directories beyond the project?

No: npx tsx setup/index.ts --step mounts -- --empty

Yes: Collect paths/permissions. npx tsx setup/index.ts --step mounts -- --json '{"allowedRoots":[...],"blockedPatterns":[],"nonMainReadOnly":true}'

7. Start Service

If service already running, stop it first:

sudo service clawdie stop 2>/dev/null || true

Run npx tsx setup/index.ts --step service and parse the status block.

Non-root fallback: If running without root, the step generates start-clawdie.sh / stop-clawdie.sh wrappers. Tell the user to run bash start-clawdie.sh to start manually, and use cron @reboot for auto-start.

If SERVICE_LOADED=false:

• Read logs/setup.log for the error.
• Check: sudo service clawdie status
• What to check: missing .env, Node.js path incorrect, build not yet run.
• Run npm run build first, then retry the service step.

8. Verify

Run npx tsx setup/index.ts --step verify and parse the status block.

If STATUS=failed, resolve each:

• SERVICE=stopped → npm run build, then sudo service clawdie start
• SERVICE=not_found → re-run step 7
• CREDENTIALS=missing → re-run step 4
• CHANNEL_AUTH shows not_found for any channel → re-invoke that channel's skill
• REGISTERED_GROUPS=0 → re-invoke the channel skills from step 5
• MOUNT_ALLOWLIST=missing → npx tsx setup/index.ts --step mounts -- --empty

Tell user to test by sending a message in their registered chat. Show logs: tail -f logs/clawdie.log

Troubleshooting

Service not starting: Check logs/clawdie.error.log. Common: wrong Node path (re-run step 7), missing .env (step 4), missing channel credentials (re-invoke channel skill).

Pi agent fails: Check groups/*/logs/agent-*.log. Ensure pi is in PATH and the provider in ~/.pi/agent/settings.json has a valid key with balance. For z.ai (glm-4-plus): recharge at https://open.bigmodel.cn if getting 429 errors.

No response to messages: Check trigger pattern. Main group doesn't need prefix. Check DB: npx tsx setup/index.ts --step verify. Check logs/clawdie.log.

Channel not connecting: Verify credentials in .env. Channels auto-enable when their env var is present (TELEGRAM_BOT_TOKEN, etc.). Restart the service after any .env change: sudo service clawdie restart.

Stop service: sudo service clawdie stop or bash stop-clawdie.sh (non-root).