Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

First Session

When you launch OpenCrabs for the first time, the onboarding wizard walks you through setup.

Onboarding Flow

The wizard is a keyboard-driven TUI with 8 steps. Navigate with arrow keys, Tab to advance, Esc to go back.

StepScreenWhat you do
1Mode SelectChoose QuickStart (skip channels) or Advanced
2WorkspacePick a working directory for file operations
3Provider & AuthSelect provider → paste API key → pick model (fetched live)
4ChannelsSpace to toggle channels on/off → Enter on each to configure
5VoiceSTT provider (Groq, local Whisper, or off) + TTS voice
6ImageVision toggle + generation model + API key
7DaemonInstall background daemon (optional)
8Brain SetupAuto-generate SOUL.md, IDENTITY.md from your profile

Channel Setup (Step 4)

The channels screen lists 5 integrations: Telegram, Discord, WhatsApp, Slack, Trello.

  • Space toggles a channel on/off
  • Enter on an enabled channel opens its setup screen (token, IDs, allowlists)
  • Enter on Continue or Tab skips to the next step
  • Each channel setup screen has a Test Connection button

See Channels Overview for the full navigation guide.

Re-running Setup

You can jump to any step without re-running the full wizard:

CommandStep
/onboardFull wizard
/onboard:providerProvider & model selection
/onboard:channelsChannel picker
/onboard:voiceVoice setup
/onboard:imageImage setup
/onboard:brainBrain file generation

After onboarding, your agent boots up and introduces itself. It reads its brain files (SOUL.md, IDENTITY.md, AGENTS.md, TOOLS.md) and starts a conversation.

Bootstrap

On the very first run, the agent goes through a bootstrap phase:

  • Gets to know you (name, preferences, work style)
  • Establishes its identity (name, personality, emoji)
  • Opens SOUL.md together to discuss values
  • Sets up USER.md with your profile

The bootstrap file (BOOTSTRAP.md) deletes itself when complete.

Key Commands

CommandDescription
/helpShow all available commands
/modelsSwitch provider or model
/newCreate a new session
/sessionsSwitch between sessions
/cdChange working directory
/compactManually compact context
/evolveDownload latest version
/rebuildBuild from source
/approveSet approval policy

Approval Modes

Control how much autonomy the agent has:

ModeBehavior
/approveAsk before every tool use (default)
/approve autoAuto-approve for this session
/approve yoloAuto-approve always (persists)

Working Directory

The agent operates within a working directory for file operations. Change it with:

  • /cd command in chat
  • Directory picker in the TUI (Tab to select)
  • config_manager set_working_directory tool

The working directory is persisted per-session — switching sessions restores the directory automatically.