Tool Reference

read_file Core

Read the contents of a file at the given path. Includes path traversal protection to prevent access outside the workspace.

write_file Core

Write content to a file at the given path. Creates parent directories if needed. Saves versioned backups (up to 14) in ~/.oxicrab/backups/ before overwriting existing files.

edit_file Core

Edit a file by replacing old_text with new_text. The old_text must exist exactly in the file. Useful for surgical edits without rewriting entire files.

list_dir Core

List the contents of a directory. Returns file names, sizes, and types.

exec Core

Execute a shell command and return its output. Secured with configurable command allowlists. Dangerous patterns (rm -rf, raw device access, redirects) are blocked.

Configuration

{
  "tools": {
    "exec": {
      "timeout": 60,
      "allowedCommands": ["ls", "grep", "git", "cargo", "node", "python3"]
    },
    "restrictToWorkspace": true
  }
}

The default allowlist includes 50+ commands: file ops (ls, find, tree), text processing (grep, awk, sed, jq), dev tools (git, cargo, npm, python3), and networking (curl, wget, dig). Override with your own list in config.

Set restrictToWorkspace: true to restrict filesystem access to the workspace directory.

tmux Core

Manage persistent tmux shell sessions. Create long-running sessions, send commands, and read output. Ideal for processes that outlive a single tool call (dev servers, builds, etc.).

web_search Core

Search the web. Returns titles, URLs, and snippets. Uses Brave Search if an API key is configured, otherwise falls back to DuckDuckGo (no key required).

Optional: Brave Search API

1. Get an API key from api.search.brave.com
2. Set in config:

{
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "apiKey": "your-brave-search-api-key",
        "maxResults": 5
      }
    }
  }
}

web_fetch Core

Fetch a URL and extract readable content. Converts HTML to markdown/text. Binary responses (images, PDFs) are saved to ~/.oxicrab/media/.

http Core

Make HTTP requests (GET, POST, PUT, PATCH, DELETE). For REST APIs, webhooks, and external services. Supports custom headers and JSON bodies. Binary responses are saved to disk.

reddit Core

Browse Reddit. Get hot, new, or top posts from a subreddit, or search within a subreddit. Read-only, no authentication required.

message Core

Send a message to a user on any connected channel. Defaults to the current conversation's channel and chat. Specify channel and chat_id to target a different destination. Use the media parameter to attach file paths (screenshots, images).

spawn Core

Spawn a subagent to handle a task in the background. Subagents have access to filesystem, shell, and web tools but cannot message users or spawn more subagents. Concurrency is limited by a semaphore (default: 5 concurrent subagents).

subagent_control Core

List running subagents, check capacity, or cancel a subagent by ID.

cron Core

Schedule recurring or one-shot tasks. Two job types: agent (default) processes the message as a full LLM turn with all tools; echo delivers the message directly to channels without invoking the LLM.

Schedule types

• cron_expr — Standard 5-field cron expression (e.g. 0 9 * * *)
• every_seconds — Run every N seconds
• at_time — One-shot at an ISO 8601 datetime

Actions

Optional limits: expires_at (auto-disable after datetime), max_runs (auto-disable after N executions).

memory_search Core

Search long-term memory and daily notes. Recall user preferences, past conversations, and important facts. Uses SQLite FTS5 full-text search, with optional hybrid vector+keyword search via local ONNX embeddings.

Memory configuration

{
  "agents": {
    "defaults": {
      "memory": {
        "archiveAfterDays": 30,
        "purgeAfterDays": 90,
        "embeddingsEnabled": false,
        "embeddingsModel": "BAAI/bge-small-en-v1.5",
        "hybridWeight": 0.5
      }
    }
  }
}

Set embeddingsEnabled: true for hybrid vector+keyword search. The embeddings model is downloaded automatically on first use.

google_mail Requires config

Interact with Gmail. Search, read, send, reply, list labels, and apply labels.

Actions

Setup

1. Create a Google Cloud project at console.cloud.google.com
2. Enable the Gmail API
3. Create OAuth 2.0 credentials (Desktop application)
4. Copy Client ID and Client Secret to config
5. Run ./oxicrab auth google to complete the OAuth flow

{
  "tools": {
    "google": {
      "enabled": true,
      "clientId": "your-google-client-id",
      "clientSecret": "your-google-client-secret"
    }
  }
}

OAuth tokens are stored in ~/.oxicrab/google_tokens.json and auto-refresh.

google_calendar Requires config

Interact with Google Calendar. List, create, update, and delete events across calendars.

Actions

Setup

Uses the same Google OAuth config as google_mail. Enable the Google Calendar API in your Cloud project.

github Requires config

Interact with GitHub. List and create issues, view pull requests, and check notifications.

Actions

Setup

1. Create a Personal Access Token at github.com/settings/tokens
2. Select scopes: repo, read:user
3. Add to config:

{
  "tools": {
    "github": {
      "enabled": true,
      "token": "ghp_your-github-token"
    }
  }
}

weather Requires config

Get current weather or forecast for a location. Uses the OpenWeatherMap API.

Setup

1. Sign up at openweathermap.org/api (free tier available)
2. Copy your API key
3. Add to config:

{
  "tools": {
    "weather": {
      "enabled": true,
      "apiKey": "your-openweathermap-api-key"
    }
  }
}

todoist Requires config

Manage Todoist tasks and projects.

Actions

Setup

1. Get your API token from todoist.com/app/settings/account
2. Add to config:

{
  "tools": {
    "todoist": {
      "enabled": true,
      "token": "your-todoist-api-token"
    }
  }
}

media Requires config

Manage movies and TV series via Radarr (movies) and Sonarr (TV).

Actions

Setup

1. Install Radarr and/or Sonarr
2. Get API keys: Settings > General > API Key (in each app)
3. Add to config:

{
  "tools": {
    "media": {
      "enabled": true,
      "radarr": {
        "url": "http://localhost:7878",
        "apiKey": "your-radarr-api-key"
      },
      "sonarr": {
        "url": "http://localhost:8989",
        "apiKey": "your-sonarr-api-key"
      }
    }
  }
}

obsidian Requires config

Read, write, search, and list notes in an Obsidian vault via the Local REST API plugin.

Actions

Setup

1. Install the Local REST API plugin in Obsidian (Community Plugins > search "Local REST API")
2. Enable the plugin
3. Copy the API key from the plugin settings
4. Add to config:

{
  "tools": {
    "obsidian": {
      "enabled": true,
      "apiUrl": "http://localhost:27123",
      "apiKey": "your-obsidian-local-rest-api-key",
      "vaultName": "MyVault",
      "syncInterval": 300,
      "timeout": 15
    }
  }
}

browser Requires config

Control a headless browser for web automation via Chrome DevTools Protocol. Open pages, click elements, type text, take screenshots, and execute JavaScript.

Setup

1. Install Chrome or Chromium: sudo apt install chromium-browser
2. Enable in config:

{
  "tools": {
    "browser": {
      "enabled": true,
      "headless": true,
      "chromePath": null,
      "timeout": 30
    }
  }
}

Set headless: false to see the browser window. Set chromePath if Chrome is not in the default location. Screenshots are saved to ~/.oxicrab/media/.

image_gen Requires config

Generate images from text prompts. Supports OpenAI gpt-image-1 (DALL-E) and Google Imagen 3.

Setup

Uses API keys from the providers section. At least one provider key is required:

• OpenAI: Set providers.openai.apiKey
• Google: Set providers.gemini.apiKey

{
  "tools": {
    "imageGen": {
      "enabled": true,
      "defaultProvider": "openai"
    }
  }
}

MCP External

Connect external tool servers via the Model Context Protocol. Tools are auto-discovered at startup from child processes and registered as native tools with full middleware pipeline support.

Configuration

{
  "tools": {
    "mcp": {
      "servers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"],
          "enabled": true
        },
        "git": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-git"],
          "env": { "GIT_DIR": "/path/to/repo" },
          "enabled": true
        }
      }
    }
  }
}

Server config fields

Voice Transcription

Voice messages from channels are automatically transcribed to text. Not a tool itself, but a service that feeds into the agent. Supports dual backends with automatic fallback.

Local backend (whisper.cpp)

On-device inference. Requires ffmpeg and a GGML model file:

# Install ffmpeg
sudo apt install ffmpeg

# Download the model (~574 MB)
mkdir -p ~/.oxicrab/models
wget -O ~/.oxicrab/models/ggml-large-v3-turbo-q5_0.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin

Cloud backend (Whisper API)

Uses Groq, OpenAI, or any OpenAI-compatible transcription endpoint. Groq offers free inference and is recommended.

Configuration

{
  "voice": {
    "transcription": {
      "enabled": true,
      "localModelPath": "~/.oxicrab/models/ggml-large-v3-turbo-q5_0.bin",
      "preferLocal": true,
      "threads": 4,
      "apiKey": "your-groq-or-openai-api-key",
      "apiBase": "https://api.groq.com/openai/v1/audio/transcriptions",
      "model": "whisper-large-v3-turbo"
    }
  }
}

preferLocal: true (default) tries local first, falls back to cloud. Set to false to prefer cloud. Either backend alone is sufficient.