### Setup OpenCrabs Project

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Instructions for cloning the repository, building the project, and running tests. Ensure you have Rust and Cargo installed.

```bash
git clone https://github.com/adolfousier/opencrabs.git
cd opencrabs
cargo build
cargo test
```

--------------------------------

### Install and Start OpenCrabs as a System Service

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Installs and starts a specific OpenCrabs profile as a system service. This is recommended for everyday users to ensure OpenCrabs starts on boot and runs reliably.

```bash
# Install as system service (macOS launchd / Linux systemd)
opencrabs -p hermes service install
opencrabs -p hermes service start
```

--------------------------------

### Run OpenCrabs CLI Onboarding Wizard

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/start/ONBOARDING_OVERVIEW.md

Use the CLI wizard for full control over the Gateway, workspace, channels, and skills. This command initiates the guided setup process in your terminal.

```bash
opencrabs onboard
```

--------------------------------

### Install Qwen Code CLI

Source: https://github.com/adolfousier/opencrabs/blob/main/CHANGELOG.md

Instructions for installing the Qwen Code CLI using Homebrew or npm.

```bash
brew install qwen-code
```

```bash
npm install -g @qwen-code/qwen-code
```

--------------------------------

### Clone and Build SocialCrabs

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

These commands are used to clone the SocialCrabs repository, navigate into the directory, install dependencies, and build the project. This is the initial setup required before using SocialCrabs.

```bash
git clone https://github.com/adolfousier/socialcrabs.git
cd socialcrabs && npm install && npm run build
```

--------------------------------

### Install and Start OpenCrabs Service

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/reference/templates/BOOT.md

Use these commands to install OpenCrabs as a system service and start it. The installation process automatically configures systemd on Linux or launchd on macOS.

```bash
opencrabs service install   # systemd unit on Linux, launchd plist on macOS
opencrabs service start
```

--------------------------------

### Install Qwen Code CLI

Source: https://github.com/adolfousier/opencrabs/blob/main/CHANGELOG.md

Install the Qwen Code CLI provider globally using npm or Homebrew.

```bash
npm install -g @qwen-code/qwen-code
```

```bash
brew install qwen-code
```

--------------------------------

### Example Minimal Plan JSON

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/reference/plans/plan-json-spec.md

A complete example of a minimal Plan JSON file, demonstrating the structure for a multi-task plan.

```json
{
  "title": "Add user authentication",
  "description": "Implement login/logout flow with session management",
  "tasks": [
    { "title": "Research auth patterns", "description": "Look at existing auth code and pick a pattern", "task_type": "research" },
    { "title": "Write login handler", "description": "POST /auth/login with password verification", "task_type": "create", "dependencies": [1] },
    { "title": "Add session middleware", "description": "Attach user context to requests", "task_type": "configuration", "dependencies": [2] },
    { "title": "Write auth tests", "description": "Test login, logout, and session expiry", "task_type": "test", "dependencies": [3], "complexity": 2 }
  ]
}
```

--------------------------------

### Setup Agent Workspace

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/start/OPENCRABS.md

Initializes the agent workspace, creating default files like AGENTS.md, SOUL.md, and TOOLS.md if they don't exist. This command also auto-initializes git if installed.

```bash
opencrabs setup
```

--------------------------------

### Install Windows Build Dependencies

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Provides options for installing build tools on Windows, either directly or via WSL2.

```bash
# Option 1: Install build tools
# - CMake (add to PATH)
# - NASM (add to PATH)
# - Visual Studio Build Tools ("Desktop development with C++")

# Option 2: Use WSL2 (recommended)
sudo apt-get install build-essential pkg-config libssl-dev
```

--------------------------------

### Full Example: Shell Executor with Parameters

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/reference/templates/skills/dynamic-tools/SKILL.md

A comprehensive example of a shell executor tool named `search_index`. It includes parameters for query, limit, and source, demonstrating required and optional fields with defaults.

```toml
[[tools]]
name = "search_index"
description = "Search indexed documents by query"
executor = "shell"
enabled = true
requires_approval = false
timeout_secs = 60
command = "/usr/local/bin/doc-search --params-file \"$OPENCRABS_PARAMS\" 2>&1"

[[tools.params]]
name = "query"
type = "string"
description = "Search text"
required = true

[[tools.params]]
name = "limit"
type = "integer"
description = "Max results to return"
required = false
default = "50"

[[tools.params]]
name = "source"
type = "string"
description = "Document source filter"
required = false
default = ""
```

--------------------------------

### Run OpenCrabs Onboarding Wizard

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/start/GETTING_STARTED.md

Starts the wizard to configure authentication, gateway settings, and optional channels. Use --install-daemon to set up the service.

```bash
opencrabs onboard --install-daemon
```

--------------------------------

### Install OpenCrabs systemd service on Linux

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Creates and enables a systemd user service for OpenCrabs. Ensure the ExecStart path is correct for your installation. This setup is for the default profile; named profiles require different service names and arguments.

```bash
mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/opencrabs.service << 'EOF'
[Unit]
Description=OpenCrabs AI Agent
After=network.target

[Service]
ExecStart=%h/.cargo/bin/opencrabs daemon
Restart=on-failure
RestartSec=5
Environment=OPENCRABS_HOME=%h/.opencrabs

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable opencrabs
systemctl --user start opencrabs

# Check status
systemctl --user status opencrabs

# View logs
journalctl --user -u opencrabs -f
```

--------------------------------

### Setup OpenCrabs Dependencies with One-Liner Script

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

A convenient script to automatically detect your platform, install all necessary dependencies, and set up the Rust toolchain for building OpenCrabs from source.

```bash
bash <(curl -sL https://raw.githubusercontent.com/adolfousier/opencrabs/main/src/scripts/setup.sh)
```

--------------------------------

### README.md Cron Jobs CLI Example

Source: https://github.com/adolfousier/opencrabs/blob/main/CHANGELOG.md

Example CLI command for managing cron jobs, as documented in the 'Cron Jobs & Heartbeats' section of README.md.

```bash
opencrabs cron --help
```

--------------------------------

### commands.toml.example Chat and History Commands

Source: https://github.com/adolfousier/opencrabs/blob/main/CHANGELOG.md

Example configuration for chat and history commands in commands.toml.example, demonstrating usage for `/chats` and `/history`.

```toml
[commands.chat]
command = "/chats"
description = "List all available chats"

[commands.history]
command = "/history"
description = "Show chat history"
```

--------------------------------

### Verify mcp CLI Installation

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Verifies that the 'mcp' CLI has been installed correctly by checking its help output.

```bash
mcp --help
```

--------------------------------

### Install Linux Build Dependencies

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Installs essential build tools and libraries for Debian/Ubuntu, Fedora/RHEL, and Arch Linux.

```bash
# Debian/Ubuntu
sudo apt-get install build-essential pkg-config libssl-dev cmake
```

```bash
# Fedora/RHEL
sudo dnf install gcc gcc-c++ make pkg-config openssl-devel cmake
```

```bash
# Arch
sudo pacman -S base-devel pkg-config openssl cmake
```

--------------------------------

### Configure MCP Servers

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Example configuration for the 'mcp' CLI, defining a 'github' server with its URL and authorization headers. This file is typically located at '~/.config/mcp/servers.json'.

```json
{
  "mcpServers": {
    "github": {
      "url": "https://api.mcp.github.com",
      "headers": {
        "Authorization": "Bearer ghp_YOUR_GITHUB_PAT"
      }
    }
  }
}
```

--------------------------------

### TUI Autostart on Linux Desktop

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Configuration for automatically starting the OpenCrabs TUI on login for Linux desktop environments. Requires creating a .desktop file.

```bash
# Linux desktop:
drop a .desktop file in ~/.config/autostart/ with Exec=x-terminal-emulator -e opencrabs.
```

--------------------------------

### Configure Google Gemini API Key

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Add your Gemini API key to the `keys.toml` file to enable access. Get your key from aistudio.google.com.

```toml
[providers.gemini]
api_key = "AIza..."
```

--------------------------------

### Document Qwen cache auto-enable for custom providers

Source: https://github.com/adolfousier/opencrabs/blob/main/CHANGELOG.md

Documentation added to explain the zero-configuration auto-enablement of the cache for Qwen providers when used with custom provider setups.

```Markdown
docs(qwen): document zero-config Qwen cache auto-enable for custom providers
```

--------------------------------

### Gate custom_provider_no_models_test to Unix

Source: https://github.com/adolfousier/opencrabs/blob/main/CHANGELOG.md

This test is gated to Unix environments because the Windows implementation relies on the Win32 API, which is not available in the Unix test setup.

```Shell
fix(test): gate `custom_provider_no_models_test` to Unix (Windows uses Win32 API)
```

--------------------------------

### Direct API Call Example

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/reference/templates/skills/multi-agent/SKILL.md

Use this bash command to call a provider's API directly when model switching is not available. Ensure you replace 'model-name' and provide your API key.

```bash
curl -s https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"model-name","messages":[{"role":"user","content":"task here"}]}'
```

--------------------------------

### Install OpenCrabs (macOS/Linux)

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/start/GETTING_STARTED.md

Installs OpenCrabs using a curl script. Ensure Rust 1.85.0 or later is installed.

```bash
curl -fsSL https://opencrabs.com/install.sh | bash
```

--------------------------------

### Install OpenCrabs (Windows PowerShell)

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/start/GETTING_STARTED.md

Installs OpenCrabs using a PowerShell script. Ensure Rust 1.85.0 or later is installed.

```powershell
iwr -useb https://opencrabs.com/install.ps1 | iex
```

--------------------------------

### Register Provider in UI

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/reference/ADDING_NEW_PROVIDERS.md

Add your provider's information to the `PROVIDERS` array in `src/tui/onboarding/types.rs`. Ensure the `id` matches the `session_id` in the factory. The order in this array dictates UI presentation.

```rust
pub const PROVIDERS: &[ProviderInfo] = &[
    // ... existing providers
    ProviderInfo {
        id: "yourprovider",  // Must match session_id in factory
        name: "YourProvider",
        models: &[],  // Empty = fetched from API at runtime
        key_label: "API Key",
        help_lines: &
            [
            "Get key from yourprovider.com",
            "Or paste from your dashboard",
        ],
    },
];
```

--------------------------------

### Install OpenCrabs via Cargo

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Installs the OpenCrabs binary using Cargo. Ensure Rust and Cargo are installed. For systems with limited space, specify a custom target directory.

```bash
cargo install opencrabs
```

```bash
CARGO_TARGET_DIR=~/.cargo/target cargo install opencrabs
```

--------------------------------

### Install macOS Build Dependencies

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Installs CMake and pkg-config using Homebrew for macOS development.

```bash
# Install build dependencies
brew install cmake pkg-config
```

--------------------------------

### Go Build and Test Commands

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/reference/templates/CODE.md

Commands for static analysis, testing, and building Go projects. Clean up the binary artifact by removing it.

```bash
go vet ./...
go test ./...
go build -o binary .
# clean: rm binary
```

--------------------------------

### Install OpenCrabs with Specific Features via Cargo

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Installs OpenCrabs with a custom set of features by disabling default features and specifying desired ones. This allows for a tailored installation, reducing build time and binary size.

```bash
cargo install opencrabs --no-default-features --features "telegram,discord"
```

```bash
cargo install opencrabs --no-default-features --features "telegram,whatsapp,discord,slack,trello,local-stt,local-tts"
```

--------------------------------

### Make OpenCrabs Available System-Wide

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Install the OpenCrabs binary system-wide by creating a symbolic link or copying it to a directory in your PATH, such as `/usr/local/bin/`. This allows running `opencrabs` from any project directory.

```bash
# Symlink (recommended — always points to latest build)
sudo ln -sf $(pwd)/target/release/opencrabs /usr/local/bin/opencrabs

# Or copy
sudo cp target/release/opencrabs /usr/local/bin/
```

--------------------------------

### Configure Dynamic Shell Tools with TOML

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Define dynamic tools that execute shell commands in `tools.toml`. This example configures a `deploy_staging` tool using the `shell` executor, which runs a deployment script. It includes a `timeout_secs` and `requires_approval` setting, along with a parameter for the git branch.

```toml
[[tools]]
name = "deploy_staging"
description = "Deploy the current branch to staging"
executor = "shell"
command = "cd ~/project && ./deploy.sh {{branch}} staging"
timeout_secs = 120
requires_approval = true

[[tools.params]]
name = "branch"
type = "string"
description = "Git branch to deploy"
required = true

```

--------------------------------

### Build a Release Binary

Source: https://github.com/adolfousier/opencrabs/blob/main/CONTRIBUTING.md

Build a release binary only when testing optimized performance or preparing to replace the installed binary. This process involves pulling the latest changes, building the release version, and copying it to the appropriate location.

```bash
git pull origin main
cargo build --release --all-features
# macOS / Linux: replace ~/.cargo/bin/opencrabs (or wherever your install lives)
cp target/release/opencrabs ~/.cargo/bin/opencrabs
```

--------------------------------

### Install mcp CLI

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Installs the 'mcp' CLI tool using a curl script. This tool is required to connect OpenCrabs to remote MCP servers.

```bash
curl -sSL https://raw.githubusercontent.com/avelino/mcp/main/install.sh | sh
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/adolfousier/opencrabs/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification. Use these to clearly indicate the type and scope of your changes.

```text
feat: add voice message support for Discord channel
```

```text
fix: prevent duplicate message rendering for CLI providers
```

```text
refactor: simplify tool loop iteration tracking
```

--------------------------------

### Configure Qwen Code CLI Provider

Source: https://github.com/adolfousier/opencrabs/blob/main/CHANGELOG.md

Enable the Qwen Code CLI provider in the configuration file.

```toml
[providers.qwen_code_cli]
enabled = true
```

--------------------------------

### Parameter Coercion Example

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/reference/templates/skills/dynamic-tools/SKILL.md

This example defines a string parameter with `coerce_empty_to = "null"`, ensuring that empty values are converted to JSON `null` before being written to `$OPENCRABS_PARAMS`.

```toml
[[tools.params]]
name = "query"
type = "string"
required = false
default = "null"
coerce_empty_to = "null"
```

--------------------------------

### Enable Qwen Code CLI Provider

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Enable the Qwen Code CLI as a local LLM backend. Set the 'default_model' to your preferred Qwen model.

```toml
[providers.qwen_code_cli]
enabled = true
default_model = "qwen3-coder-plus"
```

--------------------------------

### Install OpenCrabs without Default Features

Source: https://github.com/adolfousier/opencrabs/blob/main/README.md

Use this command to install OpenCrabs while excluding local STT and TTS capabilities, useful for reducing binary size or when only specific integrations are needed.

```bash
cargo install opencrabs --no-default-features --features telegram,whatsapp,discord,slack,trello
```

--------------------------------

### Unit Tests for a New Provider

Source: https://github.com/adolfousier/opencrabs/blob/main/src/docs/reference/ADDING_NEW_PROVIDERS.md

Add unit tests in the `src/tests/` directory for your new provider. Ensure tests cover creation with valid configurations and graceful handling of missing API keys.

```rust
// src/tests/yourprovider_test.rs

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_yourprovider_creation() {
        // Test provider creation with valid config
    }

    #[test]
    fn test_yourprovider_missing_key() {
        // Test graceful handling of missing API key
    }
}
```