# AGENTS
Source: https://docs.profclaw.ai/AGENTS



> **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project.
> For Mintlify product knowledge (components, configuration, writing standards),
> install the Mintlify skill: `npx skills add https://mintlify.com/docs`

# Documentation project instructions

## About this project

* This is a documentation site built on [Mintlify](https://mintlify.com)
* Pages are MDX files with YAML frontmatter
* Configuration lives in `docs.json`
* Run `mint dev` to preview locally
* Run `mint broken-links` to check links

## Terminology

## Style preferences

* Use active voice and second person ("you")
* Keep sentences concise — one idea per sentence
* Use sentence case for headings
* Bold for UI elements: Click **Settings**
* Code formatting for file names, commands, paths, and code references

## Content boundaries


# INSTALLATION
Source: https://docs.profclaw.ai/INSTALLATION



# Installation Guide

This guide covers multiple ways to install and run profClaw.

## Table of Contents

* [npm Install (Recommended)](#npm-install-recommended)
* [Docker Installation](#docker-installation)
* [One-Line Install](#one-line-install)
* [From Source (Development)](#from-source-development)
* [Production Deployment](#production-deployment)
* [Environment Configuration](#environment-configuration)
* [First-Time Setup](#first-time-setup)
* [Troubleshooting](#troubleshooting)
* [FAQ](#faq)

***

## npm Install (Recommended)

Requires Node 22+.

1. Install the package globally:

```bash theme={null}
npm install -g profclaw@latest
# or: pnpm add -g profclaw@latest
```

2. Run the setup wizard (configures AI provider, admin account, and registration mode):

```bash theme={null}
profclaw setup
```

3. Start the server:

```bash theme={null}
profclaw serve
```

The server starts at `http://localhost:3000`.

**Verify it works:**

```bash theme={null}
curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}
```

***

## One-Line Install

Auto-detects npm/pnpm or Docker and installs accordingly:

1. Run the install script:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/profclaw/profclaw/main/install.sh | bash
```

2. Follow the prompts, then start the server as directed by the script output.

3. Verify the server is up:

```bash theme={null}
curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}
```

***

## From Source (Development)

### Prerequisites

* Node.js 22+ — [Download](https://nodejs.org/)
* pnpm — installed via corepack
* Redis — for the job queue (optional in development)

### Steps

1. Clone and install dependencies:

```bash theme={null}
git clone https://github.com/profclaw/profclaw.git
cd profclaw

corepack enable
pnpm install
```

2. Configure your environment:

```bash theme={null}
cp .env.example .env
# Edit .env — add at least one AI provider key
```

3. Start the dev server:

```bash theme={null}
pnpm dev
```

The server starts at `http://localhost:3000` with hot reload enabled.

**Verify it works:**

```bash theme={null}
curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}
```

***

## Docker Installation

### Using Docker Compose (Recommended)

1. Clone the repository:

```bash theme={null}
git clone https://github.com/profclaw/profclaw.git
cd profclaw
```

2. Create and configure your environment file:

```bash theme={null}
cp .env.example .env
# Edit .env with your API keys
```

3. Start all services:

```bash theme={null}
docker compose up -d
```

4. Verify the server is up:

```bash theme={null}
curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}
```

Other useful commands:

```bash theme={null}
# View logs
docker compose logs -f profclaw

# Stop services
docker compose down
```

### Available Profiles

```bash theme={null}
# Default: profClaw + Redis
docker compose up -d

# With local AI (Ollama)
docker compose --profile ai up -d

# With monitoring (Prometheus + Grafana)
docker compose --profile monitoring up -d

# With development tools (Redis Commander)
docker compose --profile tools up -d

# All profiles
docker compose --profile ai --profile monitoring --profile tools up -d
```

### Using Pre-built Image

1. Pull the image:

```bash theme={null}
docker pull ghcr.io/profclaw/profclaw:latest
```

2. Run the container (requires Redis):

```bash theme={null}
docker run -d \
  --name profclaw \
  -p 3000:3000 \
  -e REDIS_URL=redis://your-redis-host:6379 \
  -e ANTHROPIC_API_KEY=sk-ant-xxx \
  --env-file .env \
  ghcr.io/profclaw/profclaw:latest
```

3. Verify it works:

```bash theme={null}
curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}
```

***

## Production Deployment

### Requirements

* Redis — required for the job queue
* Persistent storage — for the SQLite database
* Reverse proxy — Nginx or Cloudflare for HTTPS

### Docker Compose Production

1. Set environment variables in `.env`:

```bash theme={null}
NODE_ENV=production
PORT=3000
REDIS_URL=redis://redis:6379
CORS_ORIGIN=https://your-domain.com

# AI Provider (at least one required)
ANTHROPIC_API_KEY=sk-ant-xxx

# Storage
STORAGE_TIER=libsql
LIBSQL_URL=libsql://your-db.turso.io
LIBSQL_AUTH_TOKEN=xxx
```

2. Deploy:

```bash theme={null}
docker compose -f docker-compose.yml up -d
```

3. Verify the deployment:

```bash theme={null}
curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}
```

Docker Compose includes automatic health checks with restart on failure.

### Cloudflare Tunnel

For secure exposure without port forwarding:

1. Install cloudflared:

```bash theme={null}
brew install cloudflare/cloudflare/cloudflared  # macOS
# or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation
```

2. Authenticate and create a tunnel:

```bash theme={null}
cloudflared tunnel login
cloudflared tunnel create profclaw
```

3. Create a config file (`~/.cloudflared/config.yml`):

```yaml theme={null}
tunnel: <TUNNEL_ID>
credentials-file: /root/.cloudflared/<TUNNEL_ID>.json
ingress:
  - hostname: profclaw.yourdomain.com
    service: http://localhost:3000
  - service: http_status:404
```

4. Start the tunnel:

```bash theme={null}
cloudflared tunnel run profclaw
```

5. In the Cloudflare dashboard, create a DNS CNAME record pointing `profclaw.yourdomain.com` to `<TUNNEL_ID>.cfargotunnel.com`.

***

## Environment Configuration

### Required Variables

| Variable                     | Description                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| At least one AI provider key | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, or `GROQ_API_KEY` |

### Recommended Variables

| Variable       | Default       | Description                                 |
| -------------- | ------------- | ------------------------------------------- |
| `PORT`         | `3000`        | HTTP server port                            |
| `NODE_ENV`     | `development` | Environment mode                            |
| `REDIS_URL`    | —             | Redis URL for job queue                     |
| `STORAGE_TIER` | `file`        | Storage backend: `memory`, `file`, `libsql` |

### AI Providers

Configure at least one:

```bash theme={null}
# Anthropic Claude
ANTHROPIC_API_KEY=sk-ant-xxx

# OpenAI
OPENAI_API_KEY=sk-xxx

# Google Gemini
GOOGLE_GENERATIVE_AI_API_KEY=xxx

# Groq (fast inference)
GROQ_API_KEY=gsk_xxx

# Ollama (local models, no API key needed)
OLLAMA_BASE_URL=http://localhost:11434
```

### Integrations

```bash theme={null}
# GitHub
GITHUB_TOKEN=ghp_xxx
GITHUB_CLIENT_ID=xxx
GITHUB_CLIENT_SECRET=xxx
GITHUB_WEBHOOK_SECRET=xxx

# Jira
JIRA_CLIENT_ID=xxx
JIRA_CLIENT_SECRET=xxx

# Linear
LINEAR_API_KEY=lin_api_xxx

# Slack
SLACK_BOT_TOKEN=xoxb-xxx
SLACK_SIGNING_SECRET=xxx

# Discord
DISCORD_BOT_TOKEN=xxx
DISCORD_APPLICATION_ID=xxx
DISCORD_PUBLIC_KEY=xxx

# Telegram
TELEGRAM_BOT_TOKEN=xxx

# WhatsApp
WHATSAPP_ACCESS_TOKEN=xxx
WHATSAPP_PHONE_NUMBER_ID=xxx
```

See [`.env.example`](../.env.example) for the complete list.

***

## First-Time Setup

After starting the server, create your admin account using the setup wizard.

### Option 1: Docker CLI (Recommended)

```bash theme={null}
# Interactive setup wizard
docker exec -it profclaw profclaw setup

# Or non-interactive (CI/automation)
docker exec profclaw profclaw setup \
  --non-interactive \
  --admin-email admin@profclaw.dev \
  --admin-password YourSecurePass123 \
  --admin-name "Admin" \
  --ai-provider skip \
  --registration-mode invite
```

The wizard configures:

* AI provider (Anthropic, OpenAI, Ollama, or skip)
* Admin account with recovery codes
* Registration mode (invite-only or open)
* GitHub OAuth (optional)

### Option 2: Local CLI

```bash theme={null}
# If running via Node.js
pnpm profclaw setup

# Or individual commands:
pnpm profclaw auth create-admin --email admin@example.com --name "Admin"
pnpm profclaw auth set-mode invite
```

### Option 3: Web UI

Visit `http://localhost:3000/setup` and follow the on-screen wizard.

***

## Low-Memory Devices (Raspberry Pi Zero, 512MB VPS)

On devices with 512MB RAM or less, `npm install -g profclaw` will get killed by the OOM killer before it finishes. Three options:

### Option 1: Docker pico image (recommended)

The pico image is pre-built and skips npm install entirely. It runs the agent engine, tools, and one chat channel in roughly 140MB RAM with no UI and no Redis.

1. Pull and run the pico image:

```bash theme={null}
docker run -d \
  --name profclaw \
  -p 3000:3000 \
  -e PROFCLAW_MODE=pico \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v profclaw-data:/app/data \
  ghcr.io/profclaw/profclaw:pico
```

2. Or build locally from `Dockerfile.pico`:

```bash theme={null}
docker build -f Dockerfile.pico -t profclaw:pico .
docker run -d --name profclaw -p 3000:3000 -e PROFCLAW_MODE=pico profclaw:pico
```

3. Verify it works:

```bash theme={null}
curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}
```

### Option 2: Add swap before npm install

1. Extend swap to 1GB so npm has enough memory:

```bash theme={null}
sudo dphys-swapfile swapoff
sudo sed -i 's/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=1024/' /etc/dphys-swapfile
sudo dphys-swapfile setup
sudo dphys-swapfile swapon
```

2. Install and start in pico mode:

```bash theme={null}
npm install -g profclaw@latest

# Start in pico mode
PROFCLAW_MODE=pico profclaw serve
```

3. Verify it works:

```bash theme={null}
curl http://localhost:3000/health
# {"status":"ok","timestamp":"..."}
```

### Option 3: Cross-install from another machine

1. Install on a machine with more RAM:

```bash theme={null}
npm install -g profclaw@latest
INSTALL_PATH=$(npm root -g)/profclaw
```

2. Copy to the target device and run:

```bash theme={null}
scp -r $INSTALL_PATH pi@raspberry.local:~/profclaw
ssh pi@raspberry.local "cd ~/profclaw && PROFCLAW_MODE=pico node dist/server.js"
```

### Hardware requirements by mode

| Mode | Min RAM | Swap needed? | What you get                              |
| ---- | ------- | ------------ | ----------------------------------------- |
| pico | 256MB   | Yes (512MB+) | Agent + tools + 1 channel, no UI          |
| mini | 512MB   | Recommended  | Dashboard, integrations, 3 channels       |
| pro  | 1GB+    | No           | Everything including Redis, browser tools |

***

## Troubleshooting

### Redis Connection Issues

```bash theme={null}
# Check Redis is running
redis-cli ping

# In Docker, check network connectivity
docker network inspect profclaw-network
```

### Database Errors

```bash theme={null}
# File-based storage (development)
ls -la data/

# Reset database
rm -rf data/*.db
pnpm dev
```

### AI Provider Errors

Check that your API keys are valid:

```bash theme={null}
# Test Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-haiku-20240307","max_tokens":1,"messages":[{"role":"user","content":"Hi"}]}'
```

### Port Already in Use

```bash theme={null}
# Find which process is using port 3000
lsof -i :3000 | grep LISTEN

# Kill it by PID
kill -9 <PID>
```

### Docker Build Issues

```bash theme={null}
# Clean build
docker compose build --no-cache

# Check logs
docker compose logs profclaw
```

***

## Upgrading

### Docker

```bash theme={null}
# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d
```

### Manual Installation

```bash theme={null}
git pull
pnpm install
pnpm build
pnpm start
```

***

## FAQ

**npm install gets killed on low-memory devices**

The OOM killer terminates `npm install` when RAM runs out. Two fixes: add 1GB of swap before installing (see [Option 2 in the low-memory guide](#option-2-add-swap-before-npm-install)), or skip npm install entirely by using the Docker pico image (see [Option 1](#option-1-docker-pico-image-recommended)).

**Port 3000 is already in use**

Find what is listening on it:

```bash theme={null}
lsof -i :3000 | grep LISTEN
```

Then kill that process by PID, or start profClaw on a different port by setting `PORT=3001` in your `.env`.

**No AI provider configured**

Set at least one of these environment variables before starting the server:

```bash theme={null}
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
GOOGLE_GENERATIVE_AI_API_KEY=xxx
OLLAMA_BASE_URL=http://localhost:11434
```

See [Environment Configuration](#environment-configuration) for the full list.

**How do I use a local AI model?**

1. Install [Ollama](https://ollama.com) on your machine.
2. Pull a model:

```bash theme={null}
ollama pull llama3.2
```

3. Set `OLLAMA_BASE_URL` in your `.env`:

```bash theme={null}
OLLAMA_BASE_URL=http://localhost:11434
```

4. Restart profClaw. The Ollama provider shows up automatically in the model list.

If you are running profClaw inside Docker, use `http://host.docker.internal:11434` instead of `localhost`.

***

## Getting Help

* [GitHub Issues](https://github.com/profclaw/profclaw/issues)
* [API Documentation](http://localhost:3000/api/docs) (Swagger UI)
* [Discord Community](#) (coming soon)


# Amazon Bedrock
Source: https://docs.profclaw.ai/ai-providers/amazon-bedrock

Access Claude, Llama, Titan, and other foundation models via AWS Bedrock. Enterprise-grade with VPC support and AWS IAM auth.

AWS Bedrock provides managed access to foundation models from Anthropic, Meta, Amazon, and others. It integrates with AWS IAM, VPC, CloudWatch, and other AWS services for enterprise deployments.

## Supported Models

| Model                | Bedrock ID                                  | Provider  | Notes       |
| -------------------- | ------------------------------------------- | --------- | ----------- |
| Claude Sonnet 3.5 v2 | `anthropic.claude-3-5-sonnet-20241022-v2:0` | Anthropic | Default     |
| Claude Haiku 3.5     | `anthropic.claude-3-5-haiku-20241022-v1:0`  | Anthropic | Fast/cheap  |
| Llama 3.1 70B        | `meta.llama3-1-70b-instruct-v1:0`           | Meta      | Open-source |
| Titan Text G1        | `amazon.titan-text-express-v1`              | Amazon    | Native AWS  |

## Setup

<Steps>
  <Step title="Enable models in AWS Console">
    Go to **AWS Console > Bedrock > Model access** and request access to the models you need.
  </Step>

  <Step title="Create IAM credentials">
    Create an IAM user or role with the `AmazonBedrockFullAccess` policy (or a scoped policy for specific models).
  </Step>

  <Step title="Set environment variables">
    ```bash theme={null}
    export AWS_ACCESS_KEY_ID=AKIA...
    export AWS_SECRET_ACCESS_KEY=...
    export AWS_REGION=us-east-1
    ```

    Or use an IAM role (EC2 instance profile, ECS task role, etc.) - no keys needed.
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    # profClaw auto-detects AWS credentials from environment
    profclaw config provider add bedrock
    profclaw doctor --provider bedrock
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  AWS access key ID. Not needed when using IAM roles.
</ParamField>

<ParamField type="string">
  AWS secret access key. Not needed when using IAM roles.
</ParamField>

<ParamField type="string">
  AWS region where your Bedrock models are available (e.g., `us-east-1`, `eu-west-1`). Defaults to `us-east-1`.
</ParamField>

<ParamField type="string">
  Temporary session token for STS-based credentials.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env (IAM user)">
    ```bash theme={null}
    AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
    AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    AWS_REGION=us-east-1
    ```
  </Tab>

  <Tab title="IAM Role (EC2/ECS)">
    ```bash theme={null}
    # No credentials needed - profClaw uses the instance/task role
    AWS_REGION=us-east-1
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      bedrock:
        region: "${AWS_REGION}"
        # API keys not needed if using IAM roles
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias           | Bedrock Model ID                          |
| --------------- | ----------------------------------------- |
| `bedrock`       | anthropic.claude-3-5-sonnet-20241022-v2:0 |
| `bedrock-haiku` | anthropic.claude-3-5-haiku-20241022-v1:0  |
| `bedrock-llama` | meta.llama3-1-70b-instruct-v1:0           |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  profclaw chat --model bedrock "Review this security policy"
  profclaw chat --model bedrock-haiku "Quick summarization task"
  profclaw chat --model bedrock-llama "Open-source model analysis"

  # Use any Bedrock model directly
  profclaw chat --model bedrock/amazon.titan-text-express-v1 "Hello"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Analyze this CloudFormation template", {
    model: "bedrock",
  });
  ```
</CodeGroup>

## Notes

* Bedrock is stable and recommended for enterprise AWS-native deployments.
* Bedrock pricing is per-token, similar to direct API pricing, plus AWS fees.
* Supports VPC endpoints for fully private traffic (no internet required).
* Use AWS SCP (Service Control Policies) to restrict which models are accessible.
* Cross-region inference is supported - specify a different region per request if needed.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Azure OpenAI](/ai-providers/azure-openai) - Microsoft Azure alternative for enterprise
* [Anthropic](/ai-providers/anthropic) - Direct Anthropic API for lower complexity
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Anthropic
Source: https://docs.profclaw.ai/ai-providers/anthropic

Use Claude models - Opus, Sonnet, and Haiku - via the Anthropic API. Best-in-class tool calling, coding, and reasoning.

Anthropic's Claude models are the default recommended provider in profClaw. They offer native tool calling, vision support, and large context windows up to 1M tokens.

## Supported Models

| Model             | ID                           | Context | Max Output | Tools | Vision | Input \$/1M | Output \$/1M |
| ----------------- | ---------------------------- | ------- | ---------- | ----- | ------ | ----------- | ------------ |
| Claude Opus 4.6   | `claude-opus-4-6`            | 1M      | 128K       | Yes   | Yes    | \$5.00      | \$25.00      |
| Claude Sonnet 4.5 | `claude-sonnet-4-5-20250929` | 200K    | 16K        | Yes   | Yes    | \$3.00      | \$15.00      |
| Claude Haiku 4.5  | `claude-haiku-4-5-20251001`  | 200K    | 8K         | Yes   | Yes    | \$0.25      | \$1.25       |

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [console.anthropic.com](https://console.anthropic.com) and create an API key.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export ANTHROPIC_API_KEY=sk-ant-api03-...
    ```

    Or add it to your `.env` file.
  </Step>

  <Step title="Verify configuration">
    ```bash theme={null}
    profclaw doctor --provider anthropic
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Anthropic API key. Format: `sk-ant-api03-...`
</ParamField>

<ParamField type="string">
  Override the API base URL. Useful for proxies or custom endpoints. Defaults to `https://api.anthropic.com`.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    ANTHROPIC_API_KEY=sk-ant-api03-...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      default: anthropic
      anthropic:
        api_key: "${ANTHROPIC_API_KEY}"
        # Optional: custom endpoint
        # base_url: "https://your-proxy.example.com"
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    profclaw config provider add anthropic --key sk-ant-api03-...
    profclaw config provider set-default anthropic
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias    | Model                      |
| -------- | -------------------------- |
| `opus`   | claude-opus-4-6            |
| `sonnet` | claude-sonnet-4-5-20250929 |
| `haiku`  | claude-haiku-4-5-20251001  |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Use default model (auto-selected)
  profclaw chat "Explain async/await in JavaScript"

  # Use a specific alias
  profclaw chat --model opus "Review this architecture"

  # Use full model ID
  profclaw chat --model claude-haiku-4-5-20251001 "Quick question"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Write a test for this function", {
    model: "opus",
    systemPrompt: "You are a senior TypeScript engineer.",
    temperature: 0.3,
  });
  ```

  ```bash Agent theme={null}
  profclaw agent run --model sonnet --task "Review PR #42 in profclaw/profclaw"
  ```
</CodeGroup>

## Notes

* Anthropic is the top-priority provider in profClaw's auto-selection order.
* All Claude models support native function calling - tools work reliably without fallback prompting.
* Opus has a 1M token context window, suitable for large codebases.
* Claude Haiku 4.5 is the recommended model for high-throughput, cost-sensitive workloads.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [OpenAI](/ai-providers/openai) - GPT-4o and o-series reasoning models
* [profclaw provider](/cli/provider) - Add and test providers from the CLI
* [profclaw models](/cli/models) - List and manage model aliases


# Azure OpenAI
Source: https://docs.profclaw.ai/ai-providers/azure-openai

Use GPT-4o and other OpenAI models via Azure OpenAI Service. Enterprise SLAs, private networking, and data residency.

Azure OpenAI Service provides access to OpenAI's models through Microsoft's Azure infrastructure. It offers enterprise features including private networking, compliance certifications, and data residency guarantees.

## Overview

Azure OpenAI differs from the standard OpenAI API:

* Models are deployed to your own Azure resource
* Access via your Azure resource endpoint, not `api.openai.com`
* Models are referenced by deployment names you define
* Supports both standard resource mode and Azure AI Foundry (custom base URL)

## Supported Models

Any OpenAI model available in Azure can be deployed. Common deployments:

| Deployment    | Model       | Notes          |
| ------------- | ----------- | -------------- |
| `gpt-4o`      | GPT-4o      | Most common    |
| `gpt-4o-mini` | GPT-4o Mini | Cost-efficient |
| `o1`          | o1          | Reasoning      |
| `gpt-4-turbo` | GPT-4 Turbo | Legacy         |

All Azure-deployed models support native tool calling - profClaw assumes tool support for all Azure models.

## Setup

<Steps>
  <Step title="Create an Azure OpenAI resource">
    In the Azure Portal, create an Azure OpenAI resource and deploy a model.
  </Step>

  <Step title="Get your credentials">
    From your Azure OpenAI resource, copy:

    * API key (under **Keys and Endpoint**)
    * Endpoint URL or Resource Name
    * Deployment name
  </Step>

  <Step title="Set environment variables">
    **Option A - Resource Name mode (standard):**

    ```bash theme={null}
    AZURE_OPENAI_API_KEY=your-key
    AZURE_OPENAI_RESOURCE_NAME=your-resource-name
    AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
    ```

    **Option B - Base URL mode (AI Foundry / custom endpoint):**

    ```bash theme={null}
    AZURE_OPENAI_API_KEY=your-key
    AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
    AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider azure
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Azure OpenAI API key.
</ParamField>

<ParamField type="string">
  Your Azure OpenAI resource name (e.g., `my-openai-resource`). Used in standard mode.
</ParamField>

<ParamField type="string">
  Full endpoint URL (e.g., `https://my-resource.openai.azure.com`). Used in AI Foundry / custom endpoint mode. Takes precedence over `AZURE_OPENAI_RESOURCE_NAME`.
</ParamField>

<ParamField type="string">
  Alias for `AZURE_OPENAI_BASE_URL`.
</ParamField>

<ParamField type="string">
  Default deployment name to use when no model is specified.
</ParamField>

<ParamField type="string">
  API version to use. Defaults to `2024-10-21`.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title="Resource Name mode">
    ```bash theme={null}
    AZURE_OPENAI_API_KEY=abc123
    AZURE_OPENAI_RESOURCE_NAME=my-openai
    AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
    AZURE_OPENAI_API_VERSION=2024-10-21
    ```
  </Tab>

  <Tab title="Base URL mode">
    ```bash theme={null}
    AZURE_OPENAI_API_KEY=abc123
    AZURE_OPENAI_BASE_URL=https://my-openai.openai.azure.com
    AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      azure:
        api_key: "${AZURE_OPENAI_API_KEY}"
        resource_name: "${AZURE_OPENAI_RESOURCE_NAME}"
        deployment_name: "${AZURE_OPENAI_DEPLOYMENT_NAME}"
        api_version: "2024-10-21"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias       | Resolves To                |
| ----------- | -------------------------- |
| `azure`     | Your configured deployment |
| `azure-gpt` | Your configured deployment |

When using the `azure` or `azure-gpt` alias, profClaw uses the deployment name from `AZURE_OPENAI_DEPLOYMENT_NAME`.

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Uses your configured deployment
  profclaw chat --model azure "Review this architecture"

  # Specific deployment by name
  profclaw chat --model azure/gpt-4o "Explain this code"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Analyze this data", {
    model: "azure",
  });
  ```
</CodeGroup>

## Notes

* Azure is ranked 3rd in auto-selection priority after Anthropic and OpenAI.
* All Azure GPT-4+ deployments support native tool calling.
* For private network setups, configure a custom base URL pointing to your private endpoint.
* API version `2024-10-21` is the minimum supported for function calling with structured outputs.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [OpenAI](/ai-providers/openai) - Direct OpenAI API without Azure infrastructure
* [Amazon Bedrock](/ai-providers/amazon-bedrock) - AWS-native alternative for enterprise deployments
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Cerebras
Source: https://docs.profclaw.ai/ai-providers/cerebras

Extremely fast inference via Cerebras Wafer-Scale Engine hardware. Run Llama 3.1 70B at speeds over 2000 tokens/second.

Cerebras uses custom wafer-scale processors to achieve inference speeds that far exceed GPU-based providers. Llama 3.1 70B runs at over 2000 tokens/second - roughly 20x faster than typical cloud GPU inference.

## Supported Models

| Model         | ID             | Context | Max Output | Tools | Notes                 |
| ------------- | -------------- | ------- | ---------- | ----- | --------------------- |
| Llama 3.1 70B | `llama3.1-70b` | 128K    | 8K         | Yes   | Fastest 70B available |
| Llama 3.1 8B  | `llama3.1-8b`  | 128K    | 8K         | Yes   | Extreme speed         |

## Setup

<Steps>
  <Step title="Get API access">
    Sign up at [inference.cerebras.ai](https://inference.cerebras.ai). Currently in limited access.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export CEREBRAS_API_KEY=csk-...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider cerebras
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Cerebras API key.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    CEREBRAS_API_KEY=csk-...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      cerebras:
        api_key: "${CEREBRAS_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias      | Model        |
| ---------- | ------------ |
| `cerebras` | llama3.1-70b |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Ultra-fast streaming response
  profclaw chat --model cerebras "Stream this long document analysis"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  // Best for latency-sensitive applications
  const response = await chat("Generate test cases rapidly", {
    model: "cerebras",
    temperature: 0.7,
  });
  ```
</CodeGroup>

## Notes

* API endpoint: `https://api.cerebras.ai/v1` (OpenAI-compatible)
* Status: Experimental - hardware-specific availability, may have capacity constraints.
* Best use case: real-time streaming, bulk generation tasks, low-latency chat.
* Cerebras does not support vision or image inputs.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Groq](/ai-providers/groq) - LPU-based inference, another ultra-fast hardware provider
* [SambaNova](/ai-providers/sambanova) - High-throughput RDU-based inference
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Cohere
Source: https://docs.profclaw.ai/ai-providers/cohere

Use Command R+ and Command R models via the Cohere API. Strong retrieval-augmented generation and enterprise search capabilities.

Cohere specializes in enterprise search and retrieval-augmented generation (RAG). Command R+ is their flagship model with grounding and citation support.

## Supported Models

| Model      | ID               | Context | Tools | Notes                          |
| ---------- | ---------------- | ------- | ----- | ------------------------------ |
| Command R+ | `command-r-plus` | 128K    | Yes   | Best capability, RAG-optimized |
| Command R  | `command-r`      | 128K    | Yes   | Balanced cost/performance      |
| Command    | `command`        | 4K      | No    | Legacy                         |

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [dashboard.cohere.com](https://dashboard.cohere.com). Free tier available.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export COHERE_API_KEY=...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider cohere
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Cohere API key.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    COHERE_API_KEY=...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      cohere:
        api_key: "${COHERE_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias       | Model          |
| ----------- | -------------- |
| `command`   | command-r-plus |
| `command-r` | command-r      |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  profclaw chat --model command "Summarize this document with citations"
  profclaw chat --model command-r "Answer based on this context"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("What are the key findings?", {
    model: "command",
    temperature: 0.3,
  });
  ```
</CodeGroup>

## Notes

* API endpoint: `https://api.cohere.ai/v1` (OpenAI-compatible mode)
* Status: Beta - API behavior may differ slightly from other OpenAI-compatible providers.
* Command R+ excels at document summarization and retrieval tasks with grounding.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Perplexity](/ai-providers/perplexity) - Real-time web-search-augmented responses
* [Memory Tools](/tools/memory) - Combine Cohere's RAG strengths with profClaw memory search
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# DeepSeek
Source: https://docs.profclaw.ai/ai-providers/deepseek

Use DeepSeek Chat, DeepSeek Coder, and DeepSeek R1 (reasoning) via the DeepSeek API. Highly competitive pricing.

DeepSeek offers some of the best price-to-performance ratios available. DeepSeek R1 is a state-of-the-art reasoning model competitive with o1. DeepSeek Coder excels at programming tasks.

## Supported Models

| Model          | ID                  | Context | Tools | Notes                      |
| -------------- | ------------------- | ------- | ----- | -------------------------- |
| DeepSeek Chat  | `deepseek-chat`     | 64K     | Yes   | General purpose            |
| DeepSeek Coder | `deepseek-coder`    | 128K    | Yes   | Code-optimized             |
| DeepSeek R1    | `deepseek-reasoner` | 64K     | No    | Chain-of-thought reasoning |

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [platform.deepseek.com](https://platform.deepseek.com).
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export DEEPSEEK_API_KEY=sk-...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider deepseek
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your DeepSeek API key.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    DEEPSEEK_API_KEY=sk-...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      deepseek:
        api_key: "${DEEPSEEK_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias            | Model                       |
| ---------------- | --------------------------- |
| `deepseek`       | deepseek-chat               |
| `deepseek-coder` | deepseek-coder              |
| `deepseek-r1`    | deepseek-reasoner           |
| `deepseek-local` | deepseek-r1:7b (via Ollama) |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # General chat
  profclaw chat --model deepseek "Explain microservices"

  # Code generation
  profclaw chat --model deepseek-coder "Write a Redis client in TypeScript"

  # Reasoning
  profclaw chat --model deepseek-r1 "Prove that sqrt(2) is irrational"

  # Local (via Ollama)
  profclaw chat --model deepseek-local "Quick local query"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const code = await chat("Implement a LRU cache in Go", {
    model: "deepseek-coder",
    temperature: 0.1,
  });
  ```
</CodeGroup>

## Notes

* API endpoint: `https://api.deepseek.com/v1` (OpenAI-compatible)
* Status: Beta
* DeepSeek R1 uses extended chain-of-thought reasoning similar to OpenAI o1.
* `deepseek-reasoner` (R1) does not support tool calling.
* For local/offline use, run `ollama pull deepseek-r1:7b` and use the `deepseek-local` alias.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Ollama](/ai-providers/ollama) - Run DeepSeek models locally via Ollama
* [OpenAI](/ai-providers/openai) - o1 and o3 reasoning models for comparison
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Fireworks AI
Source: https://docs.profclaw.ai/ai-providers/fireworks

Fast open-source model inference via Fireworks AI. Llama, Mixtral, and more at competitive speeds and pricing.

Fireworks AI specializes in fast inference for open-source models with serverless and dedicated deployment options.

## Supported Models

| Model         | ID                                                  | Context | Notes      |
| ------------- | --------------------------------------------------- | ------- | ---------- |
| Llama 3.1 70B | `accounts/fireworks/models/llama-v3p1-70b-instruct` | 128K    | Default    |
| Llama 3.1 8B  | `accounts/fireworks/models/llama-v3p1-8b-instruct`  | 128K    | Fast/cheap |
| Mixtral 8x22B | `accounts/fireworks/models/mixtral-8x22b-instruct`  | 65K     | Large MoE  |
| DeepSeek R1   | `accounts/fireworks/models/deepseek-r1`             | 64K     | Reasoning  |

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [fireworks.ai](https://fireworks.ai). Free trial credits available.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export FIREWORKS_API_KEY=fw_...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider fireworks
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Fireworks AI API key. Format: `fw_...`
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    FIREWORKS_API_KEY=fw_...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      fireworks:
        api_key: "${FIREWORKS_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias       | Model                                             |
| ----------- | ------------------------------------------------- |
| `fireworks` | accounts/fireworks/models/llama-v3p1-70b-instruct |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  profclaw chat --model fireworks "Analyze this log file"

  # Full model ID
  profclaw chat --model fireworks/accounts/fireworks/models/llama-v3p1-8b-instruct "Quick summary"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Explain this error", {
    model: "fireworks",
  });
  ```
</CodeGroup>

## Notes

* API endpoint: `https://api.fireworks.ai/inference/v1` (OpenAI-compatible)
* Status: Beta
* Fireworks supports fine-tuned model deployment and dedicated instances.
* Model IDs use the `accounts/fireworks/models/` prefix format.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Together AI](/ai-providers/together) - Similar open-source model hosting option
* [Groq](/ai-providers/groq) - Ultra-fast LPU inference for low-latency workloads
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Google Gemini
Source: https://docs.profclaw.ai/ai-providers/google

Use Gemini 1.5 Pro, Gemini 1.5 Flash, and Gemini 2.0 models via the Google AI API. Best-in-class context windows and multimodal support.

Google Gemini models offer some of the largest context windows available - up to 2M tokens for Gemini 1.5 Pro. All Gemini models support native function calling and vision.

## Supported Models

| Model                     | ID                              | Context | Max Output | Tools | Vision | Input \$/1M | Output \$/1M |
| ------------------------- | ------------------------------- | ------- | ---------- | ----- | ------ | ----------- | ------------ |
| Gemini 1.5 Pro            | `gemini-1.5-pro`                | 2M      | 65K        | Yes   | Yes    | \$1.25      | \$5.00       |
| Gemini 1.5 Flash          | `gemini-1.5-flash`              | 1M      | 8K         | Yes   | Yes    | \$0.075     | \$0.30       |
| Gemini 2.0 Flash Thinking | `gemini-2.0-flash-thinking-exp` | 1M      | 8K         | Yes   | Yes    | \$0.075     | \$0.30       |

## Setup

<Steps>
  <Step title="Get an API key">
    Go to [aistudio.google.com](https://aistudio.google.com) and create an API key (free tier available).
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    # Either variable name works:
    export GOOGLE_API_KEY=AIza...
    export GOOGLE_GENERATIVE_AI_API_KEY=AIza...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider google
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Google AI API key. Either `GOOGLE_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` is accepted.
</ParamField>

<ParamField type="string">
  Alternative variable name for the Google API key. Takes precedence over `GOOGLE_API_KEY` if both are set.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    GOOGLE_API_KEY=AIzaSy...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      google:
        api_key: "${GOOGLE_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias             | Model                         |
| ----------------- | ----------------------------- |
| `gemini`          | gemini-1.5-pro                |
| `gemini-flash`    | gemini-1.5-flash              |
| `gemini-thinking` | gemini-2.0-flash-thinking-exp |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Large context analysis
  profclaw chat --model gemini "Analyze this entire codebase"

  # Fast and cheap
  profclaw chat --model gemini-flash "Write a quick summary"

  # Thinking model
  profclaw chat --model gemini-thinking "Walk me through this proof"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Process this large document", {
    model: "gemini",
    temperature: 0.5,
  });
  ```
</CodeGroup>

## Notes

* Gemini 1.5 Pro has a 2M token context window - the largest of any profClaw provider.
* Gemini 1.5 Flash is very cheap at \$0.075/1M input tokens, good for high-volume tasks.
* Free tier is available via Google AI Studio with rate limits.
* For Google Workspace / enterprise use, see the Vertex AI option via a custom `base_url`.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Anthropic](/ai-providers/anthropic) - Claude models with native tool calling
* [OpenRouter](/ai-providers/openrouter) - Access Gemini via OpenRouter for routing flexibility
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Groq
Source: https://docs.profclaw.ai/ai-providers/groq

Ultra-fast LLM inference via Groq's LPU hardware. Llama 3.3 70B at speeds up to 10x faster than GPU cloud providers.

Groq's Language Processing Units (LPUs) deliver the fastest inference available. Llama 3.3 70B runs at hundreds of tokens per second - ideal for real-time chat and low-latency agentic workflows.

## Supported Models

| Model                | ID                        | Context | Max Output | Tools | Input \$/1M | Output \$/1M |
| -------------------- | ------------------------- | ------- | ---------- | ----- | ----------- | ------------ |
| Llama 3.3 70B        | `llama-3.3-70b-versatile` | 128K    | 32K        | Yes   | \$0.59      | \$0.79       |
| Llama 3.1 8B Instant | `llama-3.1-8b-instant`    | 128K    | 8K         | Yes   | \$0.05      | \$0.08       |
| Mixtral 8x7B         | `mixtral-8x7b-32768`      | 32K     | 8K         | Yes   | \$0.24      | \$0.24       |

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [console.groq.com](https://console.groq.com). Free tier available.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export GROQ_API_KEY=gsk_...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider groq
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Groq API key. Format: `gsk_...`
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    GROQ_API_KEY=gsk_...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      groq:
        api_key: "${GROQ_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias          | Model                   |
| -------------- | ----------------------- |
| `groq`         | llama-3.3-70b-versatile |
| `groq-fast`    | llama-3.1-8b-instant    |
| `groq-mixtral` | mixtral-8x7b-32768      |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Fast general purpose
  profclaw chat --model groq "Explain this error message"

  # Fastest (8B model)
  profclaw chat --model groq-fast "One-line summary of this PR"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  // Groq for low-latency responses
  const response = await chat("Is this code thread-safe?", {
    model: "groq",
    temperature: 0.1,
  });
  ```
</CodeGroup>

## Notes

* Groq is ranked 5th in auto-selection priority after Anthropic, OpenAI, Azure, and Google.
* `llama-3.1-8b-instant` is one of the cheapest available models at \$0.05/1M input tokens.
* Groq has a generous free tier with rate limits per day.
* API is OpenAI-compatible - endpoint: `https://api.groq.com/openai/v1`

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Cerebras](/ai-providers/cerebras) - Wafer-scale inference for even faster token speeds
* [Together AI](/ai-providers/together) - Hundreds of open-source models via one API
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# LM Studio
Source: https://docs.profclaw.ai/ai-providers/lmstudio

Run local models via LM Studio's built-in OpenAI-compatible server. GUI-based model management with hardware acceleration.

LM Studio provides a user-friendly desktop application for downloading and running local AI models. Its built-in server exposes an OpenAI-compatible API that profClaw connects to.

## Overview

LM Studio is a GUI application for macOS, Windows, and Linux that:

* Downloads models from HuggingFace with one click
* Provides hardware-accelerated inference (Metal, CUDA, CPU)
* Runs a local OpenAI-compatible API server
* Works without an internet connection after model download

## Setup

<Steps>
  <Step title="Download LM Studio">
    Download from [lmstudio.ai](https://lmstudio.ai) and install.
  </Step>

  <Step title="Download a model">
    Open LM Studio, search for a model (e.g., `lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF`), and download it.
  </Step>

  <Step title="Start the local server">
    In LM Studio: go to **Local Server** tab, select a model, and click **Start Server**.

    The server runs at `http://localhost:1234` by default.
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    export LM_STUDIO_BASE_URL=http://localhost:1234/v1
    # Or configure as an OpenAI-compatible endpoint:
    export OPENAI_BASE_URL=http://localhost:1234/v1
    export OPENAI_API_KEY=lm-studio
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider openai
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  LM Studio server URL. Defaults to `http://localhost:1234/v1`. Configure via `OPENAI_BASE_URL`.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    # LM Studio uses the OpenAI provider with a local base URL
    OPENAI_API_KEY=lm-studio
    OPENAI_BASE_URL=http://localhost:1234/v1
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      openai:
        api_key: "lm-studio"
        base_url: "http://localhost:1234/v1"
        default_model: "local-model"
    ```
  </Tab>

  <Tab title="Remote LM Studio">
    ```bash theme={null}
    # Access LM Studio on another machine
    OPENAI_API_KEY=lm-studio
    OPENAI_BASE_URL=http://192.168.1.100:1234/v1
    ```
  </Tab>
</Tabs>

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Use whatever model is loaded in LM Studio
  profclaw chat --model local-model "Explain dependency injection"

  # Reference LM Studio model by name
  profclaw chat --model "Meta-Llama-3.1-8B-Instruct-Q4_K_M" "Quick question"
  ```
</CodeGroup>

## Differences from Ollama

| Feature      | LM Studio         | Ollama                     |
| ------------ | ----------------- | -------------------------- |
| Interface    | GUI desktop app   | CLI/headless               |
| Model format | GGUF              | GGUF                       |
| API          | OpenAI-compatible | Custom + OpenAI-compatible |
| Best for     | Desktop users     | Servers, Docker            |
| Auto-start   | No (manual)       | Yes (systemd/launchd)      |

## Notes

* LM Studio's API key field accepts any non-empty string - use `lm-studio` as a placeholder.
* Tool calling support depends on the loaded model - check the model's capabilities.
* LM Studio supports Metal (Apple Silicon), CUDA, and Vulkan acceleration.
* For headless/server deployments, Ollama is recommended over LM Studio.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Ollama](/ai-providers/ollama) - Recommended local provider for headless deployments
* [Local LLM Guide](/guides/local-llm) - Run profClaw fully offline with local models
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Mistral AI
Source: https://docs.profclaw.ai/ai-providers/mistral

Use Mistral Large, Mistral Medium, and Codestral via the Mistral AI API. Strong coding and European data residency options.

Mistral AI provides high-quality models with European data residency. Codestral is particularly well-suited for code generation tasks.

## Supported Models

| Model          | ID                      | Context | Tools | Notes           |
| -------------- | ----------------------- | ------- | ----- | --------------- |
| Mistral Large  | `mistral-large-latest`  | 128K    | Yes   | Best capability |
| Mistral Medium | `mistral-medium-latest` | 32K     | Yes   | Balanced        |
| Codestral      | `codestral-latest`      | 32K     | Yes   | Code-optimized  |
| Mistral Small  | `mistral-small-latest`  | 32K     | Yes   | Cost-efficient  |

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [console.mistral.ai](https://console.mistral.ai).
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export MISTRAL_API_KEY=...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider mistral
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Mistral AI API key.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    MISTRAL_API_KEY=...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      mistral:
        api_key: "${MISTRAL_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias            | Model                   |
| ---------------- | ----------------------- |
| `mistral`        | mistral-large-latest    |
| `mistral-medium` | mistral-medium-latest   |
| `codestral`      | codestral-latest        |
| `mistral-local`  | mistral:7b (via Ollama) |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  profclaw chat --model mistral "Review this API design"
  profclaw chat --model codestral "Generate unit tests for this function"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const code = await chat("Write a binary search in TypeScript", {
    model: "codestral",
    temperature: 0.1,
  });
  ```
</CodeGroup>

## Notes

* API endpoint: `https://api.mistral.ai/v1` (OpenAI-compatible)
* Mistral offers EU data residency - useful for GDPR-sensitive workloads.
* `codestral-latest` is optimized for code completion and generation.
* The local `mistral-local` alias runs via Ollama at no API cost.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Ollama](/ai-providers/ollama) - Run Mistral models locally at no API cost
* [Cohere](/ai-providers/cohere) - Another European-headquartered provider option
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Ollama
Source: https://docs.profclaw.ai/ai-providers/ollama

Run local AI models with Ollama. Zero API costs, full privacy, works offline. Default provider when no cloud keys are set.

Ollama lets you run open-source models locally. profClaw connects to Ollama automatically - it's always enabled and is the fallback when no cloud API keys are configured.

## Supported Models

Ollama supports hundreds of models. Popular choices in profClaw:

| Alias             | Model          | Best For        |
| ----------------- | -------------- | --------------- |
| `local` / `llama` | llama3.2       | General purpose |
| `deepseek-local`  | deepseek-r1:7b | Reasoning tasks |
| `qwen`            | qwen2.5:14b    | Multilingual    |
| `mistral-local`   | mistral:7b     | Fast inference  |

Any model available in `ollama list` can be used by its full name.

<Note>
  Most local Ollama models do not support native tool calling. profClaw automatically falls back to manual tool prompting for these models.
</Note>

## Setup

<Steps>
  <Step title="Install Ollama">
    ```bash theme={null}
    # macOS
    brew install ollama

    # Linux
    curl -fsSL https://ollama.com/install.sh | sh

    # Windows: download from https://ollama.com
    ```
  </Step>

  <Step title="Pull a model">
    ```bash theme={null}
    ollama pull llama3.2
    ollama pull deepseek-r1:7b
    ollama pull qwen2.5:14b
    ```
  </Step>

  <Step title="Start the Ollama server">
    ```bash theme={null}
    ollama serve
    # Runs at http://localhost:11434 by default
    ```
  </Step>

  <Step title="profClaw connects automatically">
    No API key needed. profClaw connects to Ollama at `http://localhost:11434`.

    ```bash theme={null}
    profclaw doctor --provider ollama
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Ollama server URL. Defaults to `http://localhost:11434`. Override for remote Ollama instances.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env (remote Ollama)">
    ```bash theme={null}
    OLLAMA_BASE_URL=http://192.168.1.100:11434
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      ollama:
        base_url: "${OLLAMA_BASE_URL}"
        default_model: "llama3.2"
    ```
  </Tab>

  <Tab title="Docker Compose">
    ```yaml theme={null}
    services:
      profclaw:
        image: profclaw/profclaw:latest
        environment:
          OLLAMA_BASE_URL: "http://ollama:11434"
      ollama:
        image: ollama/ollama:latest
        volumes:
          - ollama_data:/root/.ollama
    volumes:
      ollama_data:
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias            | Model          |
| ---------------- | -------------- |
| `local`          | llama3.2       |
| `llama`          | llama3.2       |
| `deepseek-local` | deepseek-r1:7b |
| `qwen`           | qwen2.5:14b    |
| `mistral-local`  | mistral:7b     |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Use default local model
  profclaw chat --model local "What is dependency injection?"

  # Use a specific model by name
  profclaw chat --model llama3.2 "Explain this code"

  # Use any installed model
  profclaw chat --model codellama:13b "Write a binary search"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Summarize this text", {
    model: "local",
  });
  ```
</CodeGroup>

## Notes

* Ollama is always lowest priority in auto-selection. If any cloud key is set, it takes precedence.
* Local models work without internet access - useful for air-gapped environments.
* GPU acceleration significantly improves performance. Ollama auto-detects CUDA/Metal.
* Tool calling is available via manual prompting fallback for models that don't support it natively.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [LM Studio](/ai-providers/lmstudio) - Alternative local model runner with a GUI
* [Local LLM Guide](/guides/local-llm) - Run profClaw with fully local models
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# OpenAI
Source: https://docs.profclaw.ai/ai-providers/openai

Use GPT-4o, o1, and o3 models via the OpenAI API. Strong tool calling support and broad model variety.

OpenAI is the second-priority provider in profClaw's auto-selection. GPT-4o and newer models support native function calling, vision, and streaming.

## Supported Models

| Model       | ID            | Context | Max Output | Tools | Vision | Input \$/1M | Output \$/1M |
| ----------- | ------------- | ------- | ---------- | ----- | ------ | ----------- | ------------ |
| GPT-4o      | `gpt-4o`      | 128K    | 16K        | Yes   | Yes    | \$2.50      | \$10.00      |
| GPT-4o Mini | `gpt-4o-mini` | 128K    | 16K        | Yes   | Yes    | \$0.15      | \$0.60       |
| o1          | `o1`          | 200K    | 100K       | Yes   | No     | \$15.00     | \$60.00      |
| o1 Mini     | `o1-mini`     | 128K    | 65K        | Yes   | No     | \$1.10      | \$4.40       |
| o3 Mini     | `o3-mini`     | 200K    | 100K       | Yes   | No     | \$1.10      | \$4.40       |

<Note>
  o1 and o3 models use internal chain-of-thought reasoning. They do not support streaming.
</Note>

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [platform.openai.com](https://platform.openai.com) and create an API key.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export OPENAI_API_KEY=sk-...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider openai
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your OpenAI API key. Format: `sk-...`
</ParamField>

<ParamField type="string">
  Override the base URL. Use this for custom proxies or OpenAI-compatible endpoints.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    OPENAI_API_KEY=sk-proj-...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      openai:
        api_key: "${OPENAI_API_KEY}"
        # Optional: override base URL for proxies
        # base_url: "https://your-proxy.example.com/v1"
    ```
  </Tab>

  <Tab title="Compatible endpoints">
    ```bash theme={null}
    # Any OpenAI-compatible API
    OPENAI_API_KEY=your-key
    OPENAI_BASE_URL=https://your-compatible-endpoint/v1
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias      | Model       |
| ---------- | ----------- |
| `gpt`      | gpt-4o      |
| `gpt-mini` | gpt-4o-mini |
| `o1`       | o1          |
| `o1-mini`  | o1-mini     |
| `o3-mini`  | o3-mini     |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  profclaw chat --model gpt "Summarize these release notes"
  profclaw chat --model o3-mini "Solve this algorithm problem"
  profclaw chat --model gpt-mini "Generate a commit message"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Debug this TypeScript error", {
    model: "gpt",
    temperature: 0.2,
  });
  ```
</CodeGroup>

## Notes

* `OPENAI_BASE_URL` can point to any OpenAI-compatible API (LiteLLM, LocalAI, etc.).
* GPT-4o is the default alias `gpt` - a good balance of capability and cost.
* o1/o3 models are reasoning models - use them for complex problem solving. They do not stream.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Anthropic](/ai-providers/anthropic) - Claude models for best-in-class tool calling
* [Azure OpenAI](/ai-providers/azure-openai) - OpenAI models via Azure with enterprise SLAs
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# OpenRouter
Source: https://docs.profclaw.ai/ai-providers/openrouter

Access 200+ models from a single API key via OpenRouter. Route to Claude, GPT-4, Gemini, Llama, and more through one endpoint.

OpenRouter is a model gateway that provides access to 200+ models from dozens of providers through a single OpenAI-compatible API. Useful for model experimentation and fallback routing.

## Overview

OpenRouter acts as a proxy in front of all major AI providers. Configure one API key and access any model:

* All Anthropic Claude models
* All OpenAI GPT and o-series models
* All Google Gemini models
* Open-source models (Llama, Mistral, Qwen, DeepSeek, etc.)
* Automatic fallback if a provider is down

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [openrouter.ai](https://openrouter.ai). Free credits on signup.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export OPENROUTER_API_KEY=sk-or-...
    ```
  </Step>

  <Step title="Use any model">
    Reference models by their OpenRouter IDs (e.g., `anthropic/claude-opus-4-6`).
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your OpenRouter API key. Format: `sk-or-...`
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    OPENROUTER_API_KEY=sk-or-...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      openrouter:
        api_key: "${OPENROUTER_API_KEY}"
    ```
  </Tab>
</Tabs>

## Using Models via OpenRouter

Reference models using the `openrouter/` prefix or the full provider/model path:

```bash theme={null}
# These all work:
profclaw chat --model openrouter/anthropic/claude-opus-4-6 "Hello"
profclaw chat --model openrouter/openai/gpt-4o "Hello"
profclaw chat --model openrouter/meta-llama/llama-3.3-70b-instruct "Hello"
profclaw chat --model openrouter/google/gemini-pro-1.5 "Hello"
```

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Access Claude via OpenRouter (useful when direct Anthropic key not set)
  profclaw chat --model openrouter/anthropic/claude-sonnet-4-5 "Review this PR"

  # Model auto-routing
  profclaw chat --model openrouter/auto "Use the best available model"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Explain this codebase", {
    model: "openrouter/anthropic/claude-opus-4-6",
  });
  ```
</CodeGroup>

## Notes

* API endpoint: `https://openrouter.ai/api/v1` (OpenAI-compatible)
* Status: Stable
* OpenRouter adds a small markup over provider prices (typically 10-15%).
* Supports the `X-Title` and `HTTP-Referer` headers for app attribution.
* Good for organizations that want one vendor relationship instead of managing many keys.
* OpenRouter's "auto" model routes to the best available model for your prompt.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Anthropic](/ai-providers/anthropic) - Direct Anthropic API for lower latency
* [Together AI](/ai-providers/together) - Direct open-source model hosting alternative
* [profclaw models](/cli/models) - Browse and alias available models


# AI Providers Overview
Source: https://docs.profclaw.ai/ai-providers/overview

profClaw supports 37 AI providers. Mix cloud and local models, configure fallbacks, and use model aliases for concise references.

profClaw routes requests to the right AI provider based on configured API keys. Every provider is lazily loaded - unused providers add zero startup cost.

## Provider List

| Provider                                    | Type    | Status       | Key Variable            |
| ------------------------------------------- | ------- | ------------ | ----------------------- |
| [Anthropic](/ai-providers/anthropic)        | Cloud   | Stable       | `ANTHROPIC_API_KEY`     |
| [OpenAI](/ai-providers/openai)              | Cloud   | Stable       | `OPENAI_API_KEY`        |
| [Azure OpenAI](/ai-providers/azure-openai)  | Cloud   | Stable       | `AZURE_OPENAI_API_KEY`  |
| [Google Gemini](/ai-providers/google)       | Cloud   | Stable       | `GOOGLE_API_KEY`        |
| [Ollama](/ai-providers/ollama)              | Local   | Stable       | `OLLAMA_BASE_URL`       |
| [OpenRouter](/ai-providers/openrouter)      | Gateway | Stable       | `OPENROUTER_API_KEY`    |
| [Groq](/ai-providers/groq)                  | Cloud   | Stable       | `GROQ_API_KEY`          |
| [Mistral](/ai-providers/mistral)            | Cloud   | Stable       | `MISTRAL_API_KEY`       |
| [DeepSeek](/ai-providers/deepseek)          | Cloud   | Beta         | `DEEPSEEK_API_KEY`      |
| [xAI / Grok](/ai-providers/xai)             | Cloud   | Beta         | `XAI_API_KEY`           |
| [Cohere](/ai-providers/cohere)              | Cloud   | Beta         | `COHERE_API_KEY`        |
| [Perplexity](/ai-providers/perplexity)      | Cloud   | Beta         | `PERPLEXITY_API_KEY`    |
| [Together AI](/ai-providers/together)       | Cloud   | Beta         | `TOGETHER_API_KEY`      |
| [Fireworks AI](/ai-providers/fireworks)     | Cloud   | Beta         | `FIREWORKS_API_KEY`     |
| [Cerebras](/ai-providers/cerebras)          | Cloud   | Experimental | `CEREBRAS_API_KEY`      |
| [AWS Bedrock](/ai-providers/amazon-bedrock) | Cloud   | Stable       | `AWS_ACCESS_KEY_ID`     |
| [LM Studio](/ai-providers/lmstudio)         | Local   | Beta         | `LM_STUDIO_BASE_URL`    |
| Zhipu AI                                    | Cloud   | Beta         | `ZHIPU_API_KEY`         |
| Moonshot (Kimi)                             | Cloud   | Beta         | `MOONSHOT_API_KEY`      |
| Qwen                                        | Cloud   | Beta         | `QWEN_API_KEY`          |
| Replicate                                   | Cloud   | Beta         | `REPLICATE_API_KEY`     |
| GitHub Models                               | Cloud   | Beta         | `GITHUB_TOKEN`          |
| Volcengine (Doubao)                         | Cloud   | Beta         | `VOLCENGINE_API_KEY`    |
| BytePlus                                    | Cloud   | Beta         | `BYTEPLUS_API_KEY`      |
| Baidu Qianfan                               | Cloud   | Beta         | `QIANFAN_API_KEY`       |
| ModelStudio                                 | Cloud   | Experimental | `MODELSTUDIO_API_KEY`   |
| Minimax                                     | Cloud   | Beta         | `MINIMAX_API_KEY`       |
| Xiaomi MiLM                                 | Cloud   | Experimental | `XIAOMI_API_KEY`        |
| HuggingFace                                 | Cloud   | Beta         | `HUGGINGFACE_API_TOKEN` |
| NVIDIA NIM                                  | Cloud   | Beta         | `NVIDIA_NIM_API_KEY`    |
| Venice AI                                   | Cloud   | Beta         | `VENICE_API_KEY`        |
| Kilocode                                    | Cloud   | Beta         | `KILOCODE_API_KEY`      |
| Vercel AI Gateway                           | Gateway | Beta         | `VERCEL_AI_API_KEY`     |
| Cloudflare AI                               | Gateway | Beta         | `CLOUDFLARE_AI_API_KEY` |
| IBM Watsonx                                 | Cloud   | Beta         | `WATSONX_API_KEY`       |
| GitHub Copilot                              | Proxy   | Experimental | `COPILOT_API_URL`       |
| SambaNova                                   | Cloud   | Beta         | `SAMBANOVA_API_KEY`     |

<Note>
  "Stable" providers are fully tested and used in production deployments. "Beta" providers work but may have edge cases. "Experimental" providers are early integrations that may change.
</Note>

## Auto-Selection

When multiple providers are configured, profClaw picks the best available one based on a priority order. Cloud providers with tool-calling support are preferred over local models for full tool tier access.

```bash theme={null}
# Default priority order (first configured wins):
# anthropic -> openai -> azure -> google -> groq -> xai -> mistral
# -> deepseek -> cohere -> perplexity -> together -> fireworks
# -> bedrock -> openrouter -> ... -> ollama (always last)
```

Override the default at any time:

```bash theme={null}
profclaw config set provider anthropic
```

Or per-session with the `--model` flag:

```bash theme={null}
profclaw chat --model groq
```

## Configuration

<Tabs>
  <Tab title="Environment Variables">
    Set API keys in your environment or `.env` file. profClaw reads these at startup and configures each provider:

    ```bash theme={null}
    ANTHROPIC_API_KEY=sk-ant-...
    OPENAI_API_KEY=sk-...
    GOOGLE_API_KEY=AIza...
    GROQ_API_KEY=gsk_...
    ```

    See [Environment Variables](/configuration/environment-variables) for the complete list.
  </Tab>

  <Tab title="settings.yml">
    Reference env vars in your `settings.yml` for explicit per-provider config:

    ```yaml theme={null}
    providers:
      default: anthropic
      anthropic:
        api_key: "${ANTHROPIC_API_KEY}"
      openai:
        api_key: "${OPENAI_API_KEY}"
      ollama:
        base_url: "http://localhost:11434"
        default_model: "llama3.2"
    ```

    See [settings.yml Reference](/configuration/settings-yml) for all options.
  </Tab>

  <Tab title="CLI">
    Add and manage providers interactively:

    ```bash theme={null}
    profclaw config provider add anthropic --key sk-ant-...
    profclaw config provider list
    profclaw config provider set-default openai
    ```
  </Tab>
</Tabs>

## Model Aliases

Model aliases let you reference models by short names instead of full IDs:

```bash theme={null}
# These are equivalent:
profclaw chat --model opus
profclaw chat --model claude-opus-4-6

# Provider/model shorthand also works:
profclaw chat --model anthropic/claude-opus-4-6
```

Common aliases:

| Alias      | Provider  | Model                   |
| ---------- | --------- | ----------------------- |
| `opus`     | Anthropic | claude-opus-4-6         |
| `sonnet`   | Anthropic | claude-sonnet-4-5       |
| `haiku`    | Anthropic | claude-haiku-4-5        |
| `gpt`      | OpenAI    | gpt-4o                  |
| `gemini`   | Google    | gemini-1.5-pro          |
| `groq`     | Groq      | llama-3.3-70b-versatile |
| `local`    | Ollama    | llama3.2                |
| `grok`     | xAI       | grok-2                  |
| `mistral`  | Mistral   | mistral-large-latest    |
| `deepseek` | DeepSeek  | deepseek-chat           |

## Local Models

For fully offline usage without API costs, profClaw supports [Ollama](/ai-providers/ollama) and [LM Studio](/ai-providers/lmstudio). Both run models locally on your hardware.

<Tip>
  Local models receive the Essential tool tier (10 tools) by default. Model-aware routing ensures small models are not overwhelmed with too many tool choices. See [Tools Overview](/tools/overview) for details on tier routing.
</Tip>

See the [Local LLM guide](/guides/local-llm) for setup instructions.

## Resilience

All providers include automatic retry with exponential backoff for transient errors (429, 503, network timeouts):

```bash theme={null}
AI_MAX_RETRIES=2               # Default: 2 retries
AI_PROVIDER_TIMEOUT_MS=120000  # Default: 120 seconds
```

## Health Check

```bash theme={null}
profclaw doctor --providers
```

This checks connectivity for all configured providers and reports latency. Any provider that fails to respond within the timeout is flagged.

## Related

* [profclaw provider](/cli/provider) - Add, remove, and test AI providers from the CLI
* [profclaw models](/cli/models) - List available models and manage aliases
* [Configuration Overview](/configuration/overview) - settings.yml and environment variables
* [Local LLM Guide](/guides/local-llm) - Run profClaw fully offline with Ollama or LM Studio


# Perplexity
Source: https://docs.profclaw.ai/ai-providers/perplexity

Use Perplexity's online models for real-time web search-augmented responses. Models with built-in internet access.

Perplexity's online models have built-in internet access and return grounded answers with citations. Unlike standard LLMs, they can answer questions about current events.

## Supported Models

| Model       | ID                                  | Context | Web Search | Notes            |
| ----------- | ----------------------------------- | ------- | ---------- | ---------------- |
| Sonar Huge  | `llama-3.1-sonar-huge-128k-online`  | 128K    | Yes        | Best quality     |
| Sonar Large | `llama-3.1-sonar-large-128k-online` | 128K    | Yes        | Balanced         |
| Sonar Small | `llama-3.1-sonar-small-128k-online` | 128K    | Yes        | Fastest/cheapest |

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [perplexity.ai](https://www.perplexity.ai) and go to API settings.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export PERPLEXITY_API_KEY=pplx-...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider perplexity
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Perplexity API key. Format: `pplx-...`
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    PERPLEXITY_API_KEY=pplx-...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      perplexity:
        api_key: "${PERPLEXITY_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias        | Model                             |
| ------------ | --------------------------------- |
| `perplexity` | llama-3.1-sonar-huge-128k-online  |
| `pplx-fast`  | llama-3.1-sonar-small-128k-online |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # Current events / web search
  profclaw chat --model perplexity "What are the latest changes to the TypeScript spec?"

  # Fast web lookup
  profclaw chat --model pplx-fast "Current Node.js LTS version?"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("What broke in the latest React release?", {
    model: "perplexity",
  });
  ```
</CodeGroup>

## Notes

* Status: Beta - Perplexity models have unique behavior (web search, citations) that differs from standard chat models.
* API endpoint: `https://api.perplexity.ai` (OpenAI-compatible)
* All Sonar Online models have real-time internet access built in.
* Responses include source citations automatically.
* Not recommended for tasks requiring deterministic, non-web outputs.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Web Search Tool](/tools/web-search) - Explicit web search for any provider via Brave, Serper, or Tavily
* [xAI / Grok](/ai-providers/xai) - Another provider with real-time data access
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# SambaNova
Source: https://docs.profclaw.ai/ai-providers/sambanova

High-throughput inference on SambaNova's Reconfigurable Dataflow Units (RDUs). Fast open-source model hosting.

SambaNova provides enterprise-grade inference on their custom RDU hardware. They host Llama and other open-source models with high throughput and competitive pricing.

## Supported Models

SambaNova hosts various open-source models. Common options:

| Model                         | Notes              |
| ----------------------------- | ------------------ |
| Meta-Llama-3.1-70B-Instruct   | General purpose    |
| Meta-Llama-3.1-405B-Instruct  | Largest open model |
| Llama-3.2-90B-Vision-Instruct | Multimodal         |

Check the [SambaNova model catalog](https://cloud.sambanova.ai/models) for the current list.

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [cloud.sambanova.ai](https://cloud.sambanova.ai).
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export SAMBANOVA_API_KEY=...
    ```
  </Step>

  <Step title="Configure in profClaw">
    SambaNova uses an OpenAI-compatible endpoint. Configure it as a custom OpenAI provider:

    ```bash theme={null}
    OPENAI_API_KEY=your-sambanova-key
    OPENAI_BASE_URL=https://api.sambanova.ai/v1
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your SambaNova Cloud API key. Configure via the `OPENAI_API_KEY` + `OPENAI_BASE_URL` pattern.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env (via OpenAI-compatible)">
    ```bash theme={null}
    # Use the openai provider with SambaNova's endpoint
    OPENAI_API_KEY=your-sambanova-api-key
    OPENAI_BASE_URL=https://api.sambanova.ai/v1
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      openai:
        api_key: "${SAMBANOVA_API_KEY}"
        base_url: "https://api.sambanova.ai/v1"
    ```
  </Tab>
</Tabs>

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  # After configuring via OPENAI_BASE_URL
  profclaw chat --model Meta-Llama-3.1-70B-Instruct "Explain this architecture"
  profclaw chat --model Meta-Llama-3.1-405B-Instruct "Complex analysis task"
  ```
</CodeGroup>

## Notes

* SambaNova's API is OpenAI-compatible. Configure it using the `openai` provider with a custom base URL.
* Best suited for enterprise batch inference and high-throughput workloads.
* Contact SambaNova for dedicated instance pricing.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Cerebras](/ai-providers/cerebras) - Wafer-scale inference for ultra-fast token speeds
* [Groq](/ai-providers/groq) - LPU-based inference at competitive speeds
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Together AI
Source: https://docs.profclaw.ai/ai-providers/together

Run open-source models at scale via Together AI. Access Llama, Qwen, Mixtral, and hundreds more through a single API.

Together AI hosts hundreds of open-source models with fast inference. It's a good choice when you need specific open-source models without running them locally.

## Supported Models

| Model               | ID                                        | Context | Tools | Notes                |
| ------------------- | ----------------------------------------- | ------- | ----- | -------------------- |
| Llama 3.3 70B Turbo | `meta-llama/Llama-3.3-70B-Instruct-Turbo` | 128K    | Yes   | Best general-purpose |
| Qwen 2.5 72B Turbo  | `Qwen/Qwen2.5-72B-Instruct-Turbo`         | 32K     | Yes   | Multilingual         |
| DeepSeek R1         | `deepseek-ai/DeepSeek-R1`                 | 128K    | No    | Reasoning model      |
| Mixtral 8x22B       | `mistralai/Mixtral-8x22B-Instruct-v0.1`   | 65K     | Yes   | Large MoE model      |

Any model on the [Together AI catalog](https://docs.together.ai/docs/inference-models) can be referenced by its full ID.

## Setup

<Steps>
  <Step title="Get an API key">
    Sign up at [api.together.xyz](https://api.together.xyz). Free credits on signup.
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export TOGETHER_API_KEY=...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider together
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Together AI API key.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    TOGETHER_API_KEY=...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      together:
        api_key: "${TOGETHER_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias           | Model                                   |
| --------------- | --------------------------------------- |
| `together`      | meta-llama/Llama-3.3-70B-Instruct-Turbo |
| `together-qwen` | Qwen/Qwen2.5-72B-Instruct-Turbo         |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  profclaw chat --model together "Explain this algorithm"
  profclaw chat --model together-qwen "Translate this to Chinese"

  # Use any Together AI model directly
  profclaw chat --model together/deepseek-ai/DeepSeek-R1 "Solve this math problem"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Write a REST API in Go", {
    model: "together",
  });
  ```
</CodeGroup>

## Notes

* API endpoint: `https://api.together.xyz/v1` (OpenAI-compatible)
* Status: Beta
* Together AI offers serverless and dedicated inference options.
* Great for accessing models not available on other providers (e.g., specific fine-tuned variants).

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Fireworks AI](/ai-providers/fireworks) - Similar open-source model hosting with fast inference
* [OpenRouter](/ai-providers/openrouter) - Access 200+ models from a single API key
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# xAI / Grok
Source: https://docs.profclaw.ai/ai-providers/xai

Use Grok-2 and Grok-3 via the xAI API. Large context, strong reasoning, and real-time X/Twitter knowledge.

xAI's Grok models have access to real-time data from X (Twitter) and provide large context windows with strong reasoning capabilities.

## Supported Models

| Model       | ID            | Context | Tools | Notes          |
| ----------- | ------------- | ------- | ----- | -------------- |
| Grok 2      | `grok-2`      | 131K    | Yes   | Latest stable  |
| Grok 3      | `grok-3`      | 131K    | Yes   | Most capable   |
| Grok 2 Mini | `grok-2-mini` | 131K    | Yes   | Faster/cheaper |

## Setup

<Steps>
  <Step title="Get an API key">
    Apply for API access at [x.ai](https://x.ai/api).
  </Step>

  <Step title="Set the environment variable">
    ```bash theme={null}
    export XAI_API_KEY=xai-...
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider xai
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your xAI API key. Format: `xai-...`
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    XAI_API_KEY=xai-...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    providers:
      xai:
        api_key: "${XAI_API_KEY}"
    ```
  </Tab>
</Tabs>

## Model Aliases

| Alias    | Model  |
| -------- | ------ |
| `grok`   | grok-2 |
| `grok-3` | grok-3 |

## Usage Examples

<CodeGroup>
  ```bash CLI theme={null}
  profclaw chat --model grok "What is trending in AI right now?"
  profclaw chat --model grok-3 "Complex reasoning task"
  ```

  ```typescript SDK theme={null}
  import { chat } from 'profclaw';

  const response = await chat("Analyze this technical decision", {
    model: "grok",
  });
  ```
</CodeGroup>

## Notes

* API endpoint: `https://api.x.ai/v1` (OpenAI-compatible)
* Status: Beta
* Grok has access to real-time X/Twitter data, making it useful for current events queries.
* xAI access is invitation-based and may have waitlist requirements.

## Related

* [AI Providers Overview](/ai-providers/overview) - Compare all 37 supported providers
* [Perplexity](/ai-providers/perplexity) - Another provider with real-time web search
* [OpenRouter](/ai-providers/openrouter) - Access Grok via OpenRouter as an alternative
* [profclaw provider](/cli/provider) - Add and test providers from the CLI


# Agent Sessions API
Source: https://docs.profclaw.ai/api-reference/agent-sessions

profClaw Agent Sessions API - start, monitor, cancel, and inspect autonomous execution sessions. View tool call history, token usage, and session state.

Agent sessions represent a single autonomous execution run - from receiving a task to completing it. Sessions are created implicitly when agentic chat is started, but you can also inspect and manage them directly.

## Session Lifecycle

```
created -> queued -> running -> completed | failed | cancelled
```

A session maps to a `Task` in the queue, an agentic SSE stream in the chat API, and an audit log of all tool calls made during execution.

## Starting a Session

The primary way to start an agentic session is through the chat API:

```bash theme={null}
curl -X POST http://localhost:3000/api/chat/conversations/conv_01/messages/agentic \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<token>" \
  -d '{
    "content": "Add unit tests for the auth module",
    "model": "claude-sonnet-4-6",
    "effort": "high",
    "maxSteps": 50
  }'
```

This returns an SSE stream. See [Chat Stream](/api-reference/chat-stream) for the full event reference.

## Session Configuration

| Parameter      | Type    | Default  | Description                                                 |
| -------------- | ------- | -------- | ----------------------------------------------------------- |
| `effort`       | string  | `medium` | `low` \| `medium` \| `high` \| `max` - controls step budget |
| `maxSteps`     | number  | Varies   | Hard cap on autonomous steps (1-200)                        |
| `maxBudget`    | number  | None     | Token budget for the session                                |
| `showThinking` | boolean | `true`   | Stream reasoning blocks                                     |
| `securityMode` | string  | `full`   | Tool permission mode for agentic runs                       |

Agentic mode always uses `securityMode: full` - all tools are pre-approved. For interactive approval, use the `with-tools` endpoint instead.

## Session Timeout

Sessions have a hard timeout of **3 minutes**. When reached, an `error` SSE event is sent with `code: "TIMEOUT"` and the stream closes. Long-running tasks should be broken into smaller steps.

## Viewing Session History

Each agentic session saves tool calls and the final summary as a conversation message. Retrieve them via:

```bash theme={null}
GET /api/chat/conversations/:id
```

The `assistantMessage` in the response includes `toolCalls` with each tool call, its arguments, result, and `status: "success" | "error"`.

## Memory Session Integration

Agentic sessions optionally link to a memory session for context persistence:

```bash theme={null}
POST /api/memory/sessions
```

```json theme={null}
{
  "name": "auth-refactor session",
  "conversationId": "conv_01"
}
```

Call `POST /api/memory/warm` before starting an agentic session to pre-load relevant memory into context.

## Execution Engine

Under the hood, `streamAgenticChat()` from `src/chat/index.ts` drives the agentic loop:

1. Builds system prompt with `agentMode: true` (appends `AGENT_MODE_SUFFIX`)
2. Calls the AI model with all available tools
3. Executes each tool call via the `ChatToolHandler`
4. Repeats until the model stops calling tools or `maxSteps` is reached
5. Emits typed SSE events at each step for real-time UI updates

The tool handler uses `securityMode: full` in agentic mode, meaning all tools execute without approval prompts. This matches the behavior of autonomous agent runners like Claude Code.

## Related

* [Chat Streaming](/api-reference/chat-stream) - SSE event format for session progress
* [Chat API](/api-reference/chat) - Start agentic execution via conversations
* [Memory API](/api-reference/memory) - Pre-load context for sessions
* [Security Overview](/security/overview) - Security modes and tool permission controls


# Agents API
Source: https://docs.profclaw.ai/api-reference/agents

profClaw Agents API - list and inspect registered AI agent adapters, check health status, capabilities, and runtime statistics per adapter type.

The agents API surfaces the registered AI agent adapters and their runtime status. Agents are the execution backends that process tasks - each adapter type (Claude Code, custom, etc.) exposes capabilities, health, and stats.

## GET /api/agents

List all active agent adapters with health and execution statistics.

```bash theme={null}
curl http://localhost:3000/api/agents \
  --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "agents": [
    {
      "type": "claude-code",
      "name": "Claude Code",
      "description": "Autonomous coding agent powered by Claude",
      "capabilities": ["code", "git", "terminal", "file-ops"],
      "configured": true,
      "healthy": true,
      "lastActivity": "2026-03-12T10:30:00Z",
      "stats": {
        "completed": 142,
        "failed": 3,
        "avgDuration": 45230
      }
    }
  ]
}
```

**Response fields**

| Field               | Type       | Description                       |
| ------------------- | ---------- | --------------------------------- |
| `type`              | string     | Adapter type identifier           |
| `name`              | string     | Display name                      |
| `description`       | string     | Human-readable description        |
| `capabilities`      | string\[]  | List of capability tags           |
| `configured`        | boolean    | Adapter has required config       |
| `healthy`           | boolean    | Last health check passed          |
| `lastActivity`      | ISO string | Timestamp of last task completion |
| `stats.completed`   | number     | Total tasks completed             |
| `stats.failed`      | number     | Total tasks failed                |
| `stats.avgDuration` | number     | Average execution time in ms      |

***

## GET /api/agents/types

List registered adapter type identifiers.

```bash theme={null}
curl http://localhost:3000/api/agents/types
```

**Response `200`**

```json theme={null}
{
  "types": ["claude-code", "openai-assistant", "custom"]
}
```

***

## Agent Adapter Interface

Adapters are registered via `getAgentRegistry()` from `src/adapters/registry.ts`. Each adapter implements:

```typescript theme={null}
interface AgentAdapter {
  type: string;
  name: string;
  description: string;
  capabilities: string[];
  healthCheck(): Promise<{ healthy: boolean; latencyMs?: number; message?: string }>;
  execute(task: Task): Promise<TaskResult>;
}
```

***

## Health Checks

Agent health is checked on demand when `GET /api/agents` is called. Each adapter runs its own `healthCheck()` which typically:

1. Verifies API key is present
2. Makes a lightweight probe request to the underlying AI service
3. Returns `healthy: boolean` and `latencyMs`

If all adapters are unhealthy, the overall system health degrades to `degraded` or `unhealthy` (visible at `GET /api/health`).

***

## Registering Custom Adapters

Custom adapters are registered programmatically at startup:

```typescript theme={null}
import { getAgentRegistry } from './adapters/registry.js';

const registry = getAgentRegistry();
registry.register({
  type: 'my-agent',
  name: 'My Custom Agent',
  description: 'Handles specialized tasks',
  capabilities: ['custom-domain'],
  async healthCheck() {
    return { healthy: true };
  },
  async execute(task) {
    // process task
    return { success: true, output: '...' };
  },
});
```

## Related

* [Agent Sessions API](/api-reference/agent-sessions) - Start and monitor execution sessions
* [Tasks API](/api-reference/tasks) - Create tasks that agents process
* [Health API](/api-reference/health) - System-wide health including agent status
* [profclaw agent](/cli/agent) - Inspect agents from the CLI


# Authentication API
Source: https://docs.profclaw.ai/api-reference/auth

profClaw Authentication API - sign up, log in, OAuth flows for GitHub and Jira, session management, access keys, and user profile endpoints.

## POST /api/auth/signup

Create a new account with email and password.

**Rate limit**: 5 requests / 60 seconds

```bash theme={null}
curl -X POST http://localhost:3000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword1",
    "name": "Alice",
    "inviteCode": "abc123"
  }'
```

**Request body**

| Field        | Type   | Required | Notes                                        |
| ------------ | ------ | -------- | -------------------------------------------- |
| `email`      | string | Yes      | Valid email, max 255 chars                   |
| `password`   | string | Yes      | Min 8 chars, must contain letter and number  |
| `name`       | string | Yes      | Max 100 chars                                |
| `inviteCode` | string | No       | Required when `registrationMode` is `invite` |

**Response `200`**

```json theme={null}
{
  "user": { "id": "usr_01", "email": "user@example.com", "name": "Alice", "role": "user" },
  "message": "Account created successfully"
}
```

Sets `profclaw_session` cookie (httpOnly, 30-day expiry).

***

## POST /api/auth/login

Sign in with email and password.

**Rate limit**: 10 requests / 60 seconds

```bash theme={null}
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePassword1"}'
```

**Response `200`**

```json theme={null}
{
  "user": { "id": "usr_01", "email": "user@example.com", "name": "Alice" },
  "message": "Logged in successfully"
}
```

***

## POST /api/auth/logout

Invalidate the current session.

```bash theme={null}
curl -X POST http://localhost:3000/api/auth/logout --cookie "profclaw_session=<token>"
```

**Response `200`**: `{ "message": "Logged out successfully" }`

***

## GET /api/auth/me

Get the current authenticated user.

```bash theme={null}
curl http://localhost:3000/api/auth/me --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "authenticated": true,
  "authMode": "cloud",
  "user": {
    "id": "usr_01",
    "email": "user@example.com",
    "name": "Alice",
    "role": "user",
    "connectedAccounts": ["github"],
    "hasGitHubToken": true
  }
}
```

**Response `401`** (unauthenticated):

```json theme={null}
{ "authenticated": false, "authMode": "local" }
```

***

## PATCH /api/auth/me

Update the current user's profile.

```bash theme={null}
curl -X PATCH http://localhost:3000/api/auth/me \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<token>" \
  -d '{"name": "Alice B.", "timezone": "America/New_York"}'
```

**Request body** (all fields optional): `name`, `avatarUrl`, `bio`, `timezone`, `locale`, `onboardingCompleted`

***

## GitHub OAuth

```
GET /api/auth/github           # Redirect to GitHub
GET /api/auth/github/callback  # OAuth callback (sets session cookie)
GET /api/auth/github/url       # Get authorization URL for SPA
POST /api/auth/github/token    # Exchange code for session (SPA)
```

***

## Jira / Linear OAuth

```
GET /api/auth/jira             # Redirect to Jira
GET /api/auth/jira/callback    # Jira OAuth callback
GET /api/auth/linear           # Redirect to Linear
GET /api/auth/linear/callback  # Linear OAuth callback
```

***

## POST /api/auth/verify-access-key

Verify an access key in `local` auth mode to create a session.

```bash theme={null}
curl -X POST http://localhost:3000/api/auth/verify-access-key \
  -H "Content-Type: application/json" \
  -d '{"key": "your-access-key"}'
```

**Response `200`**: `{ "success": true, "message": "Access verified" }`

***

## PUT /api/auth/access-key

Set or clear the access key (admin only, local mode only).

```bash theme={null}
curl -X PUT http://localhost:3000/api/auth/access-key \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<admin-token>" \
  -d '{"key": "new-access-key"}'
```

Pass `"key": null` to remove the access key requirement.

## Related

* [API Overview](/api-reference/overview) - Base URL, authentication modes, and error format
* [Devices API](/api-reference/devices) - Passwordless device pairing flow
* [Security Overview](/security/overview) - Auth modes and permission system
* [profclaw auth](/cli/auth) - Manage users and invite codes from the CLI


# Chat API
Source: https://docs.profclaw.ai/api-reference/chat

profClaw Chat API - send messages, manage multi-turn conversations, list providers and models, and trigger agentic execution with tool support.

The chat API provides endpoints for single-turn completions, multi-turn conversations, tool-enabled chat, and agentic (autonomous) execution.

## POST /api/chat/completions

Single-turn chat completion. Supports streaming.

```bash theme={null}
curl -X POST http://localhost:3000/api/chat/completions \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<token>" \
  -d '{
    "messages": [{"role": "user", "content": "Explain async/await in TypeScript"}],
    "model": "claude-sonnet-4-6",
    "temperature": 0.7
  }'
```

**Request body**

| Field            | Type                     | Notes                                      |
| ---------------- | ------------------------ | ------------------------------------------ |
| `messages`       | `Array<{role, content}>` | `user`, `assistant`, or `system`           |
| `model`          | string                   | Optional, uses default provider if omitted |
| `systemPrompt`   | string                   | Optional override                          |
| `temperature`    | number                   | 0-2                                        |
| `maxTokens`      | number                   | Positive integer                           |
| `stream`         | boolean                  | Enable SSE streaming                       |
| `conversationId` | string                   | Link to a conversation                     |
| `taskId`         | string                   | Inject task context                        |
| `ticketId`       | string                   | Inject ticket context                      |

**Response `200`**

```json theme={null}
{
  "id": "resp_abc123",
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "message": { "role": "assistant", "content": "Async/await is..." },
  "finishReason": "stop",
  "usage": { "promptTokens": 42, "completionTokens": 150, "totalTokens": 192 },
  "duration": 1234
}
```

***

## POST /api/chat/quick

Simplified single-prompt endpoint.

```bash theme={null}
curl -X POST http://localhost:3000/api/chat/quick \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is 2+2?"}'
```

***

## POST /api/chat/smart

Context-aware chat that automatically injects task or ticket context.

```bash theme={null}
curl -X POST http://localhost:3000/api/chat/smart \
  -d '{"messages": [...], "taskId": "task_01", "presetId": "profclaw-assistant"}'
```

***

## Conversation Management

### GET /api/chat/conversations

List conversations with optional filters.

```
GET /api/chat/conversations?limit=20&offset=0&taskId=task_01
```

### POST /api/chat/conversations

Create a conversation.

```json theme={null}
{ "title": "Bug fix session", "presetId": "code-review", "taskId": "task_01" }
```

### GET /api/chat/conversations/:id

Get a conversation with its message history.

### DELETE /api/chat/conversations/:id

Delete a conversation and all its messages.

### POST /api/chat/conversations/:id/messages

Send a message in a conversation (full context + history).

```json theme={null}
{ "content": "What should I fix first?", "model": "gpt-4o" }
```

**Response** includes `userMessage`, `assistantMessage`, `usage`, and optional `compaction` info.

### POST /api/chat/conversations/:id/messages/with-tools

Send a message with native tool calling enabled (up to 5 tool roundtrips).

```json theme={null}
{
  "content": "Read the README and summarize it",
  "enableTools": true,
  "securityMode": "ask"
}
```

Security modes: `deny` | `sandbox` | `allowlist` | `ask` | `full`

### POST /api/chat/conversations/:id/messages/agentic

Run agentic (autonomous) execution via SSE. See [Chat Stream](/api-reference/chat-stream) for the event format.

***

## Models and Providers

```
GET /api/chat/models                       # All models across providers
GET /api/chat/models?provider=anthropic    # Models for one provider
GET /api/chat/providers                    # Provider status + health
GET /api/chat/providers/:type/models       # Dynamic model discovery (Ollama, OpenRouter)
POST /api/chat/providers/:type/configure   # Configure a provider
POST /api/chat/providers/:type/health      # Check provider health
POST /api/chat/providers/default           # Set default provider
```

### Provider types

`anthropic` | `openai` | `azure` | `google` | `ollama` | `openrouter` | `groq` | `xai` | `mistral` | `cohere` | `perplexity` | `deepseek` | `together` | `cerebras` | `fireworks`

***

## Tool Approval

```
POST /api/chat/tools/approve
```

```json theme={null}
{
  "conversationId": "conv_01",
  "approvalId": "approval_01",
  "decision": "allow-once"
}
```

Decisions: `allow-once` | `allow-always` | `deny`

## Related

* [Chat Streaming](/api-reference/chat-stream) - SSE event format for agentic execution
* [Agent Sessions API](/api-reference/agent-sessions) - Monitor and cancel execution sessions
* [Tools Overview](/tools/overview) - Tools the agent can call during execution
* [AI Providers Overview](/ai-providers/overview) - Configure providers and models


# Chat Streaming
Source: https://docs.profclaw.ai/api-reference/chat-stream

profClaw chat streaming via SSE - real-time token delivery for agentic execution. Event types, tool call streaming, and error handling for Server-Sent Events.

profClaw supports two streaming mechanisms: SSE (Server-Sent Events) for agentic execution, and inline SSE for streaming completions.

## Agentic SSE Stream

**Endpoint**: `POST /api/chat/conversations/:id/messages/agentic`

The response uses `Content-Type: text/event-stream`. Each line follows the SSE format:

```
data: {"type": "...", "data": {...}, "timestamp": 1710000000000}\n\n
```

### Request body

```json theme={null}
{
  "content": "Refactor the auth module to use async/await",
  "model": "claude-sonnet-4-6",
  "provider": "anthropic",
  "temperature": 0.3,
  "showThinking": true,
  "maxSteps": 50,
  "maxBudget": 100000,
  "effort": "high"
}
```

| Field          | Type    | Notes                                |
| -------------- | ------- | ------------------------------------ |
| `content`      | string  | The user message                     |
| `model`        | string  | Optional model override              |
| `provider`     | string  | Optional provider override           |
| `showThinking` | boolean | Stream thinking/reasoning blocks     |
| `maxSteps`     | number  | 1-200, default depends on effort     |
| `maxBudget`    | number  | Token budget (min 1000)              |
| `effort`       | string  | `low` \| `medium` \| `high` \| `max` |

### Event Types

#### `user_message`

Sent immediately with the saved user message.

```json theme={null}
{
  "type": "user_message",
  "data": {
    "id": "msg_01",
    "content": "Refactor the auth module...",
    "compactionApplied": false,
    "messageCount": 5
  }
}
```

#### `session:start`

Agent session initialized.

#### `thinking:start` / `thinking:update` / `thinking:end`

Reasoning process events (when `showThinking: true` and the model supports extended thinking).

#### `step:start` / `step:complete`

Each autonomous step the agent takes.

#### `tool:call`

```json theme={null}
{
  "type": "tool:call",
  "data": {
    "toolCallId": "tc_01",
    "name": "read_file",
    "arguments": { "path": "src/auth/auth-service.ts" }
  }
}
```

#### `tool:result`

```json theme={null}
{
  "type": "tool:result",
  "data": {
    "toolCallId": "tc_01",
    "result": { "success": true, "content": "..." }
  }
}
```

#### `summary`

```json theme={null}
{
  "type": "summary",
  "data": { "summary": "Refactored 3 files in the auth module..." }
}
```

#### `complete`

```json theme={null}
{
  "type": "complete",
  "data": {
    "totalTokens": 4820,
    "inputTokens": 3100,
    "outputTokens": 1720,
    "model": "claude-sonnet-4-6",
    "provider": "anthropic",
    "toolCalls": [...]
  }
}
```

#### `message_saved`

```json theme={null}
{ "type": "message_saved", "data": { "id": "msg_02" } }
```

#### `error`

```json theme={null}
{
  "type": "error",
  "data": { "message": "Tool execution failed", "code": "TOOL_ERROR" }
}
```

The special code `TIMEOUT` is sent when the 3-minute session timeout is reached.

***

## Streaming Completions (SSE)

For `POST /api/chat/completions` with `"stream": true`, each chunk is:

```
data: {"content": "Hello"}\n\n
data: {"content": " world"}\n\n
data: {"done": true, "usage": {...}, "finishReason": "stop"}\n\n
```

***

## JavaScript Example

```javascript theme={null}
const response = await fetch('/api/chat/conversations/conv_01/messages/agentic', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ content: 'Fix all TypeScript errors', effort: 'high' }),
  credentials: 'include',
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const lines = decoder.decode(value).split('\n');
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      console.log(event.type, event.data);
    }
  }
}
```

## Related

* [Chat API](/api-reference/chat) - Send messages and trigger agentic execution
* [Agent Sessions API](/api-reference/agent-sessions) - Monitor and cancel sessions
* [Tools Overview](/tools/overview) - Tools the agent emits during execution
* [Security Overview](/security/overview) - Tool approval and execution policies


# Devices API
Source: https://docs.profclaw.ai/api-reference/devices

profClaw Devices API - Ed25519 device identity, pairing codes, QR-based pairing flow, and multi-device trust management for passwordless access.

The devices API manages the Ed25519-based device identity system and the pairing code flow for authorizing new devices without a username/password.

## Device Identity

Each profClaw instance generates a unique Ed25519 key pair on first run (`src/auth/device-identity.ts`). The public key serves as the device's identity for attestations and pairing.

### GET /api/devices/identity

Get the current device's public identity.

```bash theme={null}
curl http://localhost:3000/api/devices/identity
```

**Response `200`**

```json theme={null}
{
  "deviceId": "dev_01a2b3c4",
  "publicKey": "base64-encoded-ed25519-public-key",
  "fingerprint": "sha256:abc123..."
}
```

### POST /api/devices/attest

Create a signed attestation for the current device.

```bash theme={null}
curl -X POST http://localhost:3000/api/devices/attest \
  -d '{"data": {"purpose": "pairing"}}'
```

**Response `200`**

```json theme={null}
{
  "attestation": {
    "deviceId": "dev_01",
    "publicKey": "...",
    "attestation": {
      "timestamp": "2026-03-12T10:00:00Z",
      "nonce": "random-nonce",
      "data": { "purpose": "pairing" },
      "signature": "base64-signature"
    }
  }
}
```

### POST /api/devices/verify

Verify an attestation from another device.

```bash theme={null}
curl -X POST http://localhost:3000/api/devices/verify \
  -d '{
    "attestation": { "deviceId": "...", "publicKey": "...", "attestation": {...} },
    "maxAgeMs": 60000
  }'
```

***

## Pairing Codes

Pairing codes let a new device (phone, second computer) connect to profClaw without password entry.

### POST /api/devices/pairing/request

Request a pairing code from the new device side.

```bash theme={null}
curl -X POST http://localhost:3000/api/devices/pairing/request \
  -d '{"requesterId": "mobile-app-id", "meta": {"platform": "ios"}}'
```

**Response `200`**

```json theme={null}
{
  "requestId": "pair_01",
  "code": "ABC-123-XYZ",
  "formatted": "ABC 123 XYZ",
  "expiresAt": "2026-03-12T10:10:00Z"
}
```

Codes expire after 10 minutes.

### POST /api/devices/pairing/approve

Approve a pending pairing request (from the already-trusted device).

```bash theme={null}
curl -X POST http://localhost:3000/api/devices/pairing/approve \
  -d '{"code": "ABC-123-XYZ", "approvedBy": "usr_01"}'
```

### POST /api/devices/pairing/reject

Reject a pairing request.

### GET /api/devices/pairing/status/:requestId

Check if a pairing request has been approved.

```bash theme={null}
curl http://localhost:3000/api/devices/pairing/status/pair_01
```

**Response `200`**

```json theme={null}
{
  "status": "approved",
  "token": "session-token-for-new-device",
  "approvedAt": "2026-03-12T10:01:00Z"
}
```

### GET /api/devices/pairing/pending

List all pending pairing requests (admin only).

***

## QR Pairing

For mobile/desktop onboarding without typing codes:

### GET /api/devices/pairing/qr

Generate a QR code for the pairing flow.

```bash theme={null}
curl http://localhost:3000/api/devices/pairing/qr
```

**Response `200`**

```json theme={null}
{
  "qrSvg": "<svg>...</svg>",
  "pairingUrl": "profclaw://pair?code=ABC-123-XYZ&host=my-server.local",
  "requestId": "pair_01",
  "expiresAt": "2026-03-12T10:10:00Z"
}
```

Display the SVG to the user and poll `GET /api/devices/pairing/status/:requestId` until `approved`.

***

## Cleanup

```bash theme={null}
POST /api/devices/pairing/cleanup
```

Remove expired pairing requests. Run periodically or call after your own cleanup schedule.

## Related

* [Authentication API](/api-reference/auth) - Session and OAuth-based authentication
* [Security Device Pairing](/security/device-pairing) - How device pairing works and security model
* [profclaw device](/cli/device) - Manage paired devices from the CLI
* [Security Overview](/security/overview) - Auth modes and trust management


# Gateway API
Source: https://docs.profclaw.ai/api-reference/gateway

profClaw Gateway API - unified entry point for dispatching work to AI agents. Route tasks to agent adapters and trigger workflows with Bearer token auth.

The gateway is profClaw's unified entry point for dispatching work to AI agents. It accepts structured requests and routes them to the appropriate agent adapter, workflow, or task queue.

Authentication uses Bearer token (`tokenAuthMiddleware` from `src/auth/api-tokens.ts`).

## POST /api/gateway

Submit a request to the gateway.

```bash theme={null}
curl -X POST http://localhost:3000/api/gateway \
  -H "Authorization: Bearer <api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "title": "Review PR #42",
      "description": "Check for security issues and code quality",
      "source": "api",
      "priority": 2
    },
    "workflow": "code-review",
    "options": {
      "synchronous": false,
      "notifyUrl": "https://your-service.com/callback"
    }
  }'
```

**Request body**

| Field                 | Type    | Required | Description                              |
| --------------------- | ------- | -------- | ---------------------------------------- |
| `task`                | object  | Yes      | Task definition (see `CreateTaskSchema`) |
| `workflow`            | string  | No       | Named workflow type to execute           |
| `options.synchronous` | boolean | No       | Wait for completion (default: `false`)   |
| `options.notifyUrl`   | string  | No       | Webhook URL for completion notification  |
| `options.timeout`     | number  | No       | Max wait time in ms (synchronous mode)   |

**Response `202`** (async)

```json theme={null}
{
  "requestId": "gw_01",
  "taskId": "task_01",
  "status": "queued",
  "estimatedWait": 30000,
  "statusUrl": "http://localhost:3000/api/gateway/gw_01/status"
}
```

**Response `200`** (synchronous, `options.synchronous: true`)

```json theme={null}
{
  "requestId": "gw_01",
  "taskId": "task_01",
  "status": "completed",
  "result": {
    "output": "Code review complete. Found 2 issues...",
    "duration": 45230,
    "model": "claude-sonnet-4-6"
  }
}
```

***

## GET /api/gateway/:requestId/status

Poll the status of a gateway request.

```bash theme={null}
curl http://localhost:3000/api/gateway/gw_01/status \
  -H "Authorization: Bearer <api-token>"
```

**Response `200`**

```json theme={null}
{
  "requestId": "gw_01",
  "taskId": "task_01",
  "status": "in_progress",
  "progress": 65,
  "startedAt": "2026-03-12T10:00:00Z",
  "updatedAt": "2026-03-12T10:00:30Z"
}
```

***

## Workflow Types

| `workflow`        | Description                             |
| ----------------- | --------------------------------------- |
| `code-review`     | Analyze code changes, check for issues  |
| `ticket-resolve`  | Work a ticket end-to-end                |
| `test-generation` | Generate tests for specified code       |
| `refactor`        | Apply a refactoring pattern             |
| `summarize`       | Summarize a document or conversation    |
| `custom`          | Free-form task, no workflow scaffolding |

***

## API Token Management

API tokens are scoped to the gateway and integration webhooks. Generate tokens in the settings UI or via:

```bash theme={null}
POST /api/tokens
{ "name": "CI/CD pipeline", "scopes": ["gateway:write"] }
```

**Response `201`**

```json theme={null}
{
  "token": "pct_...",
  "name": "CI/CD pipeline",
  "createdAt": "2026-03-12T10:00:00Z"
}
```

The token is shown once. Store it securely.

***

## Rate Limits

Gateway requests are rate-limited per token:

* Default: 60 requests / minute
* Burst: 10 requests / second

Configure via `GATEWAY_RATE_LIMIT_RPM` environment variable.

***

## Gateway Context

The `GatewayContext` type (`src/gateway/types.ts`) carries metadata through the request pipeline:

```typescript theme={null}
interface GatewayContext {
  requestId: string;
  tokenId: string;
  workflow?: WorkflowType;
  task: CreateTaskInput;
  options: GatewayOptions;
  receivedAt: Date;
}
```

## Related

* [Tasks API](/api-reference/tasks) - Direct task creation without workflow routing
* [Agents API](/api-reference/agents) - View available agent adapters
* [Chat Streaming](/api-reference/chat-stream) - SSE streaming for interactive execution
* [Webhooks API](/api-reference/webhooks) - Configure callback URLs for task completion


# Health API
Source: https://docs.profclaw.ai/api-reference/health

profClaw Health API - liveness probe, readiness probe, and detailed per-component diagnostics for providers, queue, and storage. Docker and Kubernetes ready.

profClaw exposes two health endpoints: a simple liveness probe and a detailed diagnostic endpoint with per-component status.

## GET /api/health

Simple health check for load balancers and container orchestrators.

```bash theme={null}
curl http://localhost:3000/api/health
```

**Response `200`**

```json theme={null}
{
  "status": "ok",
  "timestamp": "2026-03-12T10:30:00Z"
}
```

Always returns `200` if the server is running, regardless of internal component health.

***

## GET /api/health/detailed

Full diagnostic health check including queue depth, adapter status, circuit breakers, and system metrics.

```bash theme={null}
curl http://localhost:3000/api/health/detailed
```

**Response `200`** (healthy)

```json theme={null}
{
  "status": "healthy",
  "version": "0.2.0",
  "timestamp": "2026-03-12T10:30:00Z",
  "uptime": 86400,
  "components": {
    "queue": {
      "status": "healthy",
      "message": "Queue operating normally",
      "details": {
        "pending": 5,
        "queued": 2,
        "inProgress": 1,
        "failed": 0,
        "totalActive": 8
      },
      "lastChecked": "2026-03-12T10:30:00Z"
    },
    "adapters": {
      "status": "healthy",
      "message": "All 2 adapters healthy",
      "adapters": [
        { "type": "claude-code", "name": "Claude Code", "healthy": true, "latencyMs": 230 }
      ],
      "lastChecked": "2026-03-12T10:30:00Z"
    },
    "circuitBreakers": {
      "status": "healthy",
      "message": "All circuit breakers closed",
      "breakers": [
        { "name": "github-api", "state": "CLOSED", "failures": 0, "successes": 142 }
      ],
      "lastChecked": "2026-03-12T10:30:00Z"
    },
    "deadLetterQueue": {
      "status": "healthy",
      "message": "DLQ empty",
      "details": { "pending": 0, "resolved": 12, "discarded": 1, "total": 13 },
      "lastChecked": "2026-03-12T10:30:00Z"
    }
  },
  "system": {
    "platform": "darwin",
    "nodeVersion": "v22.0.0",
    "memory": { "used": 128, "total": 512, "percentage": 25 },
    "cpu": { "loadAverage": [0.5, 0.4, 0.3] }
  }
}
```

### Health status values

| Status      | HTTP Code | Meaning                                              |
| ----------- | --------- | ---------------------------------------------------- |
| `healthy`   | `200`     | All components operating normally                    |
| `degraded`  | `200`     | Some components degraded but service still running   |
| `unhealthy` | `503`     | Critical failure, service may not function correctly |

### Queue health thresholds

| Total active tasks | Status                                 |
| ------------------ | -------------------------------------- |
| 0-100              | healthy                                |
| 101-500            | degraded - "High queue depth detected" |
| 501+               | unhealthy - "Critical queue depth"     |

### DLQ health thresholds

| DLQ pending | Status                                     |
| ----------- | ------------------------------------------ |
| 0-9         | healthy                                    |
| 10-49       | degraded - "review recommended"            |
| 50+         | unhealthy - "immediate attention required" |

***

## GET /api/health/ready

Readiness probe - returns `200` only when the server is fully initialized and ready to serve requests.

```bash theme={null}
curl http://localhost:3000/api/health/ready
```

Use this for Kubernetes `readinessProbe` and similar container checks.

***

## Metrics

```bash theme={null}
GET /api/health/metrics
```

Returns a `MetricsSummary` with request rates, error rates, and p95 latencies per endpoint. Used by the health detailed endpoint and available for external monitoring tools.

## Related

* [Task Queue API](/api-reference/task-queue) - Inspect queue depth that affects health status
* [Agents API](/api-reference/agents) - Per-adapter health checks included in detailed health
* [profclaw doctor](/cli/doctor) - Run system diagnostics from the CLI
* [Monitoring Guide](/guides/monitoring) - Set up health check dashboards and alerts


# Integrations API
Source: https://docs.profclaw.ai/api-reference/integrations-api

profClaw Integrations API - configure GitHub, Jira, Linear, and web search connections. Store credentials, check connectivity, and manage integration status.

The integrations API manages external service configuration - storing credentials, checking connectivity, and providing status information to the UI.

## Web Search

### GET /api/integrations/web-search

Get web search configuration and provider status.

```bash theme={null}
curl http://localhost:3000/api/integrations/web-search \
  --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "config": {
    "enabled": true,
    "provider": "brave",
    "brave": { "apiKey": "sk-*****" }
  },
  "status": {
    "available": true,
    "provider": "brave",
    "reason": null
  },
  "providers": [
    { "id": "brave", "name": "Brave Search", "description": "Fast, privacy-focused", "configFields": ["apiKey"] },
    { "id": "serper", "name": "Serper (Google)", "description": "Google results via API", "configFields": ["apiKey"] },
    { "id": "searxng", "name": "SearXNG", "description": "Self-hosted metasearch", "configFields": ["baseUrl", "apiKey"] },
    { "id": "tavily", "name": "Tavily", "description": "AI-optimized search", "configFields": ["apiKey"] }
  ]
}
```

API keys are masked in responses (shown as `sk-*****`).

### PUT /api/integrations/web-search

Update web search configuration.

```bash theme={null}
curl -X PUT http://localhost:3000/api/integrations/web-search \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "provider": "brave",
    "brave": { "apiKey": "your-brave-api-key" }
  }'
```

***

## GitHub Integration Status

### GET /api/integrations/github

Get GitHub connection status and OAuth details.

```bash theme={null}
curl http://localhost:3000/api/integrations/github --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "connected": true,
  "username": "alice",
  "avatarUrl": "https://github.com/avatars/alice",
  "scopes": ["repo", "read:user"],
  "webhookConfigured": true,
  "aiTaskLabel": "ai-task"
}
```

***

## Jira Integration Status

### GET /api/integrations/jira

```bash theme={null}
curl http://localhost:3000/api/integrations/jira --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "connected": true,
  "cloudId": "abc-123",
  "siteName": "your-org.atlassian.net",
  "scopes": ["read:jira-work", "write:jira-work"],
  "tokenExpiry": "2026-04-12T00:00:00Z"
}
```

***

## Linear Integration Status

### GET /api/integrations/linear

```bash theme={null}
curl http://localhost:3000/api/integrations/linear --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "connected": true,
  "workspaceName": "Acme Corp",
  "workspaceId": "workspace_01",
  "teams": [
    { "id": "team_01", "name": "Engineering", "key": "ENG" }
  ]
}
```

***

## Disconnect an Integration

```bash theme={null}
# Disconnect GitHub
DELETE /api/integrations/github

# Disconnect Jira
DELETE /api/integrations/jira

# Disconnect Linear
DELETE /api/integrations/linear
```

These endpoints revoke OAuth tokens and remove stored credentials.

***

## Webhook Status

Check if webhooks are correctly configured and receiving events:

```bash theme={null}
GET /api/integrations/webhooks/status
```

**Response**

```json theme={null}
{
  "github": {
    "configured": true,
    "lastEvent": "2026-03-12T10:00:00Z",
    "eventCount": 42
  },
  "jira": { "configured": false },
  "linear": { "configured": true, "lastEvent": "2026-03-12T09:00:00Z", "eventCount": 15 }
}
```

## Related

* [Webhooks API](/api-reference/webhooks) - Inbound and outbound webhook management
* [GitHub Integration](/integrations/github) - Set up the GitHub integration
* [Jira Integration](/integrations/jira) - Connect Jira projects and configure automation
* [Linear Integration](/integrations/linear) - Connect Linear workspaces and sync issues


# Memory API
Source: https://docs.profclaw.ai/api-reference/memory

profClaw Memory API - semantic search over memory files and chat history, manage memory chunks and experiences, and view per-session context storage.

The memory system provides semantic search over markdown files, persistent session context, and an experience store for learning from past tool chains and user preferences.

## POST /api/memory/search

Search memory chunks by semantic similarity.

```bash theme={null}
curl -X POST http://localhost:3000/api/memory/search \
  -H "Content-Type: application/json" \
  -d '{"query": "how to configure Redis", "maxResults": 6}'
```

**Request body**

| Field        | Type   | Default  | Description                   |
| ------------ | ------ | -------- | ----------------------------- |
| `query`      | string | Required | Search query                  |
| `maxResults` | number | 6        | Max results to return         |
| `minScore`   | number | -        | Minimum relevance score (0-1) |

**Response `200`**

```json theme={null}
{
  "query": "how to configure Redis",
  "method": "bm25",
  "totalCandidates": 42,
  "chunks": [
    {
      "id": "chunk_01",
      "path": "docs/configuration.md",
      "startLine": 12,
      "endLine": 28,
      "text": "Set REDIS_URL to...",
      "score": 0.87
    }
  ],
  "autoSynced": true
}
```

***

## POST /api/memory/sync

Sync memory files from disk into the database.

```bash theme={null}
curl -X POST http://localhost:3000/api/memory/sync \
  -d '{"basePath": "/home/user/notes"}'
```

**Response**: `{ "synced": 42, "added": 5, "updated": 2, "removed": 0 }`

***

## GET /api/memory/stats

Get memory statistics (file count, chunk count, last sync time).

***

## GET /api/memory/files

List all indexed memory files.

***

## GET /api/memory/files/:path/chunks

List all chunks for a specific file (URL-encode the path).

***

## DELETE /api/memory/chunks/:id

Delete a specific chunk by ID.

***

## DELETE /api/memory/files/:path

Delete all chunks for a file.

***

## DELETE /api/memory/all

Clear all memory chunks and files.

***

## Memory Sessions

```bash theme={null}
# List sessions
GET /api/memory/sessions?status=active&limit=20

# Create a session
POST /api/memory/sessions
{"name": "bug hunt", "conversationId": "conv_01", "userId": "usr_01"}

# Archive a session
POST /api/memory/sessions/:id/archive

# Warm session (sync before starting)
POST /api/memory/warm
```

***

## Experience Store

The experience store (`src/memory/experience-store.ts`) learns from past tool chains and user preferences.

**Experience types**: `tool_chain` | `user_preference` | `task_solution` | `error_recovery`

### Record an experience

```bash theme={null}
curl -X POST http://localhost:3000/api/memory/experiences \
  -d '{
    "type": "tool_chain",
    "intent": "read and summarize a file",
    "solution": ["read_file", "web_fetch"],
    "successScore": 0.9,
    "tags": ["file-ops"],
    "sourceConversationId": "conv_01"
  }'
```

### Search similar experiences

```bash theme={null}
GET /api/memory/experiences/search?q=summarize+file&limit=5
```

### Other experience endpoints

```
GET  /api/memory/experiences          # List with filters
GET  /api/memory/experiences/:id      # Get single
POST /api/memory/experiences/:id/use  # Mark as used (boosts weight)
DELETE /api/memory/experiences/:id    # Delete

POST /api/memory/experiences/decay    # Apply time decay (halfLifeDays)
POST /api/memory/experiences/prune    # Remove low-weight entries (minWeight)

POST /api/memory/preferences          # Track a user preference
GET  /api/memory/preferences/:userId  # Get user preferences
```

***

## Watcher Status

The memory watcher monitors files for changes and auto-syncs:

```bash theme={null}
GET /api/memory/watcher/status
```

```json theme={null}
{
  "enabled": true,
  "state": {
    "dirty": false,
    "syncing": false,
    "lastSyncAt": "2026-03-12T10:00:00Z",
    "watchedFiles": 42,
    "watching": true
  }
}
```

## Related

* [Memory Tools](/tools/memory) - How agents search and recall memory during execution
* [profclaw memory](/cli/memory) - Sync and inspect the memory index from the CLI
* [Agent Sessions API](/api-reference/agent-sessions) - Warm memory before agentic execution
* [Configuration Overview](/configuration/overview) - Memory settings and base paths


# API Overview
Source: https://docs.profclaw.ai/api-reference/overview

profClaw REST API reference. Base URL, authentication modes (session cookie, access key, Bearer token), rate limits, error format, and pagination.

The profClaw API is a JSON REST API built with [Hono](https://hono.dev/). All endpoints are served on the same port as the UI (default `3000`).

## Base URL

```
http://localhost:3000/api
```

For production deployments, replace `localhost:3000` with your server's hostname. All routes are prefixed with `/api`.

## Authentication

profClaw supports three authentication modes configured via `system.authMode` in settings:

<Tabs>
  <Tab title="Session Cookie">
    After calling `POST /api/auth/login` or completing an OAuth flow, a `profclaw_session` cookie is set automatically. Include it with every request.

    ```bash theme={null}
    curl http://localhost:3000/api/chat/completions \
      -H "Content-Type: application/json" \
      --cookie "profclaw_session=<token>" \
      -d '{"messages": [{"role": "user", "content": "Hello"}]}'
    ```
  </Tab>

  <Tab title="Access Key (local mode)">
    In `local` auth mode, verify an access key to create a session:

    ```bash theme={null}
    curl -X POST http://localhost:3000/api/auth/verify-access-key \
      -H "Content-Type: application/json" \
      -d '{"key": "your-access-key"}'
    ```
  </Tab>

  <Tab title="API Token">
    Gateway and some integration routes accept a Bearer token:

    ```bash theme={null}
    curl http://localhost:3000/api/gateway \
      -H "Authorization: Bearer <api-token>"
    ```
  </Tab>
</Tabs>

## Rate Limits

| Endpoint                           | Limit                        |
| ---------------------------------- | ---------------------------- |
| `POST /api/auth/login`             | 10 requests / 60 seconds     |
| `POST /api/auth/signup`            | 5 requests / 60 seconds      |
| `POST /api/auth/verify-access-key` | 10 requests / 60 seconds     |
| All other endpoints                | No hard limit (configurable) |

Rate limit responses return HTTP `429` with:

```json theme={null}
{ "error": "Too many login attempts. Try again in a minute." }
```

## Error Format

All errors follow a consistent shape:

```json theme={null}
{
  "error": "Human-readable error message",
  "details": { }  // optional, present for validation errors
}
```

Common HTTP status codes:

| Code  | Meaning                                       |
| ----- | --------------------------------------------- |
| `400` | Validation failed or bad request body         |
| `401` | Not authenticated or invalid session          |
| `403` | Authenticated but insufficient permissions    |
| `404` | Resource not found                            |
| `429` | Rate limit exceeded                           |
| `500` | Internal server error                         |
| `501` | Feature not available in current mode/storage |
| `503` | Service unavailable (queue or adapter down)   |

## Pagination

List endpoints support both offset-based and cursor-based pagination:

```bash theme={null}
# Offset-based (simple)
GET /api/tasks?limit=50&offset=100

# Cursor-based (efficient for large datasets)
GET /api/tasks?limit=50&cursor=<base64url-cursor>
```

Responses include `nextCursor` when more results are available. Cursor values are opaque base64url-encoded strings encoding `{ createdAt, id }`.

## Content Types

All request and response bodies use `application/json`. Streaming endpoints use `text/event-stream` (SSE).

## Versioning

The API is currently unversioned. Breaking changes will be announced in the changelog and migration guides provided.

## Related

* [Authentication API](/api-reference/auth) - Sign up, log in, and manage sessions
* [Chat API](/api-reference/chat) - Send messages and trigger agentic execution
* [Tasks API](/api-reference/tasks) - Create and track agentic task lifecycle
* [profclaw serve](/cli/serve) - Start the HTTP server that exposes this API


# Security API
Source: https://docs.profclaw.ai/api-reference/security-api

profClaw Security API - manage security modes, set tool permission policies, retrieve the audit log, and approve pending tool execution requests.

The security API manages profClaw's permission system - controlling which tools agents can use, setting security modes, and retrieving the audit trail of all agent actions.

## Security Modes

profClaw has five security levels for tool execution:

| Mode        | Description                                     |
| ----------- | ----------------------------------------------- |
| `deny`      | No tools allowed                                |
| `sandbox`   | Only read-only tools                            |
| `allowlist` | Only explicitly allowed tools                   |
| `ask`       | Prompt for approval before sensitive operations |
| `full`      | All tools pre-approved (agentic mode default)   |

***

## GET /api/security/policy

Get the current security policy configuration.

```bash theme={null}
curl http://localhost:3000/api/security/policy --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "defaultMode": "ask",
  "allowedTools": ["read_file", "web_fetch", "web_search"],
  "blockedTools": ["execute_command"],
  "requireApprovalFor": ["write_file", "run_tests", "git_commit"],
  "auditAll": true
}
```

***

## PUT /api/security/policy

Update the security policy.

```bash theme={null}
curl -X PUT http://localhost:3000/api/security/policy \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<admin-token>" \
  -d '{
    "defaultMode": "ask",
    "allowedTools": ["read_file", "web_fetch"],
    "requireApprovalFor": ["write_file", "git_commit"]
  }'
```

***

## GET /api/security/audit

Retrieve the audit log of agent tool executions.

```bash theme={null}
curl "http://localhost:3000/api/security/audit?limit=50&offset=0" \
  --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "entries": [
    {
      "id": "audit_01",
      "timestamp": "2026-03-12T10:30:00Z",
      "conversationId": "conv_01",
      "taskId": "task_01",
      "tool": "write_file",
      "arguments": { "path": "src/auth.ts", "content": "..." },
      "result": "success",
      "userId": "usr_01",
      "approved": true,
      "approvalDecision": "allow-once"
    }
  ],
  "total": 420,
  "limit": 50,
  "offset": 0
}
```

**Query parameters**: `limit`, `offset`, `tool`, `userId`, `conversationId`, `from`, `to`

***

## GET /api/security/audit/:id

Get a single audit entry with full argument and result details.

***

## Tool Approval Queue

When `securityMode` is `ask`, tool calls requiring approval are queued until a user decision is made.

### GET /api/security/approvals

List pending tool approvals.

```json theme={null}
{
  "approvals": [
    {
      "id": "approval_01",
      "conversationId": "conv_01",
      "toolName": "write_file",
      "params": { "path": "src/auth.ts" },
      "requestedAt": "2026-03-12T10:30:00Z",
      "securityLevel": "moderate"
    }
  ]
}
```

### POST /api/security/approvals/:id

Submit an approval decision.

```json theme={null}
{ "decision": "allow-once" }
```

Decisions: `allow-once` | `allow-always` | `deny`

`allow-always` adds the tool to the session allowlist so subsequent calls proceed without prompting.

***

## Guard Configuration

Guards are pre-execution checks that block unsafe tool calls regardless of security mode:

```bash theme={null}
GET /api/security/guards        # List active guards
PUT /api/security/guards/:name  # Enable/disable a guard
```

Built-in guards:

| Guard                 | Blocks                                                   |
| --------------------- | -------------------------------------------------------- |
| `path-traversal`      | Paths containing `../` or absolute paths outside workdir |
| `shell-injection`     | Shell metacharacters in command arguments                |
| `secret-exfiltration` | Reads of `.env`, credential files                        |
| `rate-limit`          | Tool calls exceeding configured rate                     |

## Related

* [Security Overview](/security/overview) - Security modes, guards, and audit architecture
* [profclaw security](/cli/security) - Manage security policies from the CLI
* [profclaw audit](/cli/audit) - View the audit log from the CLI
* [Tools Overview](/tools/overview) - Tool security levels and execution pipeline


# Task Queue API
Source: https://docs.profclaw.ai/api-reference/task-queue

profClaw Task Queue API - inspect queue depth, drain queues, manage dead-letter entries, and configure retry behavior for BullMQ and in-memory backends.

profClaw ships with two queue backends: **BullMQ** (Redis-backed, for `pro` mode) and an **in-memory queue** (for `pico`/`mini` mode). Both expose the same HTTP API.

## Queue Architecture

```
Task Created
    |
    v
[pending] ---> [queued] ---> [in_progress] ---> [completed]
                                  |
                                  v (on failure)
                             [failed] ---> DLQ (after maxRetries)
```

* BullMQ queue name: `ai-tasks` (configurable via `queue.name` in `settings.yml`)
* Notification queue: `ai-task-notifications`
* Redis URL: `REDIS_URL` env var or `settings.yml`
* Retry: exponential backoff, configurable attempts

## GET /api/queue/status

Get current queue depth and worker status.

```bash theme={null}
curl http://localhost:3000/api/queue/status --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "mode": "bullmq",
  "queues": {
    "tasks": {
      "pending": 5,
      "queued": 2,
      "inProgress": 1,
      "completed": 142,
      "failed": 3
    }
  },
  "workers": {
    "tasks": { "running": true, "concurrency": 10 },
    "notifications": { "running": true, "concurrency": 5 }
  },
  "deadLetterQueue": {
    "pending": 0,
    "resolved": 12,
    "discarded": 1,
    "total": 13
  }
}
```

## GET /api/dlq

List tasks in the dead letter queue.

```bash theme={null}
curl "http://localhost:3000/api/dlq?limit=20" --cookie "profclaw_session=<token>"
```

**Response**

```json theme={null}
{
  "items": [
    {
      "id": "dlq_01",
      "taskId": "task_05",
      "title": "Failing task",
      "attempts": 3,
      "lastError": "Connection timeout",
      "createdAt": "2026-03-12T08:00:00Z",
      "status": "pending"
    }
  ],
  "total": 1
}
```

## POST /api/dlq/:id/retry

Move a DLQ item back to the active queue for re-processing.

```bash theme={null}
curl -X POST http://localhost:3000/api/dlq/dlq_01/retry
```

## POST /api/dlq/:id/discard

Mark a DLQ item as discarded (won't be retried automatically).

```bash theme={null}
curl -X POST http://localhost:3000/api/dlq/dlq_01/discard
```

## Queue Configuration

Configure via `settings.yml`:

```yaml theme={null}
queue:
  name: ai-tasks
  notificationName: ai-task-notifications
  concurrency: 10
  notificationConcurrency: 5
  redis:
    url: redis://localhost:6379
  retry:
    attempts: 3
    backoff: 1000
    type: exponential   # or "fixed"
```

Or via environment variables:

```bash theme={null}
REDIS_URL=redis://localhost:6379
POOL_MAX_CONCURRENT=50
POOL_TIMEOUT_MS=300000
```

## In-Memory Queue

When Redis is not available, profClaw falls back to an in-memory queue (`src/queue/memory-queue.ts`). The in-memory queue:

* Supports the same `TaskStatus` lifecycle
* Does not persist across restarts
* Has no cursor-based pagination (offset only)
* Suitable for `pico` and `mini` deployment modes

## Failure Handler

The `FailureHandler` (`src/queue/failure-handler.ts`) intercepts task failures and:

1. Increments the retry counter
2. Applies exponential backoff delay
3. Re-queues the task if `attempts < maxRetries`
4. Moves the task to the DLQ after `maxRetries` exhausted
5. Sends an in-app notification for DLQ entries

## Webhook Queue

The webhook queue (`src/queue/webhook-queue.ts`) handles outbound webhook delivery with automatic retry on failure. Configure delivery endpoints via `POST /api/webhooks`.

## Related

* [Tasks API](/api-reference/tasks) - Create and manage tasks in the queue
* [profclaw queue](/cli/queue) - Inspect queue status from the CLI
* [Deployment Modes](/getting-started/deployment-modes) - When to use BullMQ vs in-memory
* [Configuration Overview](/configuration/overview) - Queue settings in settings.yml


# Tasks API
Source: https://docs.profclaw.ai/api-reference/tasks

profClaw Tasks API - create, list, filter by status, cancel, and retry agentic tasks. Track task lifecycle from pending through completion or failure.

Tasks are the core work unit in profClaw. They are created from webhooks, the API, or the UI, queued for agent execution, and tracked through their lifecycle.

## Task Status

```
pending -> queued -> in_progress -> completed | failed | cancelled
```

## GET /api/tasks

List tasks with optional status filter and pagination.

```bash theme={null}
curl "http://localhost:3000/api/tasks?status=pending&limit=20" \
  --cookie "profclaw_session=<token>"
```

**Query parameters**

| Param    | Type    | Description                                    |
| -------- | ------- | ---------------------------------------------- |
| `status` | string  | Filter by status                               |
| `limit`  | number  | Max results (default 50)                       |
| `offset` | number  | Offset for pagination                          |
| `cursor` | string  | Cursor for cursor-based pagination (preferred) |
| `fields` | string  | Comma-separated sparse fieldset                |
| `full`   | boolean | Return full objects (disables sparse fieldset) |

**Response `200`**

```json theme={null}
{
  "tasks": [
    {
      "id": "task_01",
      "title": "Fix login bug",
      "status": "pending",
      "priority": 2,
      "source": "github",
      "sourceId": "42",
      "sourceUrl": "https://github.com/org/repo/issues/42",
      "labels": ["bug"],
      "assignedAgent": "claude-code",
      "createdAt": "2026-03-12T10:00:00Z"
    }
  ],
  "total": 142,
  "count": 20,
  "limit": 20,
  "nextCursor": "eyJjcmVhdGVkQXQiOjE3MDAwMDAwMDAsImlkIjoiMDEifQ"
}
```

***

## POST /api/tasks

Create a new task.

```bash theme={null}
curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<token>" \
  -d '{
    "title": "Add dark mode",
    "description": "Implement dark mode for the settings page",
    "prompt": "Add a dark mode toggle to the settings page using Tailwind CSS",
    "priority": 3,
    "source": "api",
    "labels": ["ui", "feature"]
  }'
```

**Request body** (validated with `CreateTaskSchema`)

| Field           | Type      | Required | Notes                                             |
| --------------- | --------- | -------- | ------------------------------------------------- |
| `title`         | string    | Yes      |                                                   |
| `description`   | string    | No       |                                                   |
| `prompt`        | string    | No       | Detailed instructions for the agent               |
| `priority`      | number    | No       | 1 (critical) - 4 (low)                            |
| `source`        | string    | No       | `github` \| `jira` \| `linear` \| `api` \| `cron` |
| `sourceId`      | string    | No       | External ID                                       |
| `sourceUrl`     | string    | No       | Link back to source                               |
| `repository`    | string    | No       | `owner/repo`                                      |
| `branch`        | string    | No       | Git branch                                        |
| `labels`        | string\[] | No       |                                                   |
| `assignedAgent` | string    | No       | Force a specific adapter                          |

**Response `201`**: `{ "message": "Task created", "task": {...} }`

***

## GET /api/tasks/:id

Fetch a single task by ID.

***

## POST /api/tasks/:id/cancel

Cancel a pending or in-progress task.

```bash theme={null}
curl -X POST http://localhost:3000/api/tasks/task_01/cancel
```

**Response `200`**: `{ "message": "Task cancelled", "task": {...} }`

***

## POST /api/tasks/:id/retry

Retry a failed or completed task. Creates a new task with the same parameters.

```bash theme={null}
curl -X POST http://localhost:3000/api/tasks/task_01/retry
```

**Response `200`**: `{ "message": "Task queued for retry", "task": {...}, "originalTaskId": "task_01" }`

***

## GET /api/tasks/:id/events

Retrieve the audit event log for a task (requires `storage.getTaskEvents`).

***

## Advanced Filtering

```
GET /api/tasks/filter?status=failed,completed&priority=1,2&source=github&q=login
```

Supported params: `status`, `priority`, `source`, `agent`, `labels`, `createdAfter`, `createdBefore`, `completedAfter`, `completedBefore`, `repository`, `q`, `sortBy`, `sortOrder`

***

## Analytics

```
GET /api/tasks/analytics
```

Returns aggregated statistics: counts by status, average durations, failure rates, and source breakdown.

***

## Export / Import

```bash theme={null}
# Export all tasks as JSON
GET /api/tasks/export

# Import from a previous export
POST /api/tasks/import
Content-Type: application/json
{ "version": "1.0", "tasks": [...] }
```

## Related

* [Task Queue API](/api-reference/task-queue) - Inspect queue depth and manage dead-letter entries
* [Agent Sessions API](/api-reference/agent-sessions) - Monitor task execution sessions
* [profclaw task](/cli/task) - Create and manage tasks from the CLI
* [Webhooks API](/api-reference/webhooks) - Receive tasks from GitHub, Jira, and Linear


# Webhooks API
Source: https://docs.profclaw.ai/api-reference/webhooks

profClaw Webhooks API - register outbound endpoints, inspect inbound delivery from GitHub and Jira, view delivery history, and test webhook signatures.

profClaw handles webhooks in two directions: **inbound** (from GitHub, Jira, Linear to create tasks) and **outbound** (from profClaw to notify your systems when tasks complete).

## Inbound Webhooks

Register these URLs in your external service dashboards:

| Service | URL                         | Signature Header      |
| ------- | --------------------------- | --------------------- |
| GitHub  | `POST /api/webhooks/github` | `X-Hub-Signature-256` |
| Jira    | `POST /api/webhooks/jira`   | `X-Hub-Signature`     |
| Linear  | `POST /api/webhooks/linear` | `Linear-Signature`    |

All inbound webhooks are signature-verified. Set `GITHUB_WEBHOOK_SECRET`, `JIRA_WEBHOOK_SECRET`, or `LINEAR_WEBHOOK_SECRET` as appropriate.

### Verification failure

Requests that fail signature verification return:

```json theme={null}
HTTP 403
{ "error": "Invalid webhook signature" }
```

***

## Outbound Webhook Registration

### GET /api/webhooks

List registered outbound webhook endpoints.

```bash theme={null}
curl http://localhost:3000/api/webhooks --cookie "profclaw_session=<token>"
```

**Response `200`**

```json theme={null}
{
  "webhooks": [
    {
      "id": "wh_01",
      "url": "https://your-service.com/webhook",
      "events": ["task.completed", "task.failed"],
      "active": true,
      "secret": "wh_sec_*****",
      "createdAt": "2026-03-01T00:00:00Z",
      "lastDelivery": "2026-03-12T10:00:00Z",
      "deliveryCount": 42,
      "failureCount": 0
    }
  ]
}
```

### POST /api/webhooks

Register a new outbound webhook.

```bash theme={null}
curl -X POST http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  --cookie "profclaw_session=<token>" \
  -d '{
    "url": "https://your-service.com/webhook",
    "events": ["task.completed", "task.failed"],
    "secret": "optional-signing-secret"
  }'
```

### DELETE /api/webhooks/:id

Remove a webhook registration.

***

## Outbound Event Types

| Event            | Payload Fields                      |
| ---------------- | ----------------------------------- |
| `task.created`   | `id`, `title`, `status`, `source`   |
| `task.completed` | `id`, `title`, `result`, `duration` |
| `task.failed`    | `id`, `title`, `error`, `attempts`  |
| `task.cancelled` | `id`, `title`                       |
| `agent.started`  | `taskId`, `agentType`               |
| `agent.finished` | `taskId`, `agentType`, `output`     |

### Delivery Format

```json theme={null}
{
  "id": "delivery_01",
  "event": "task.completed",
  "timestamp": "2026-03-12T10:30:00Z",
  "payload": {
    "id": "task_01",
    "title": "Fix login bug",
    "result": "Fixed the session cookie bug in auth-service.ts",
    "duration": 45230
  }
}
```

Outbound webhooks are signed with `X-ProfClaw-Signature: sha256=<hmac>` when a secret is provided.

***

## Retry Policy

Failed deliveries are retried with exponential backoff:

| Attempt | Delay      |
| ------- | ---------- |
| 1       | 30 seconds |
| 2       | 5 minutes  |
| 3       | 30 minutes |
| 4       | 2 hours    |
| 5       | 12 hours   |

After 5 failed attempts, the webhook is marked as `failing` and deliveries pause. Re-activate with `PATCH /api/webhooks/:id` setting `active: true`.

***

## Delivery Log

```bash theme={null}
GET /api/webhooks/:id/deliveries?limit=20
```

Returns recent delivery attempts with status codes and response bodies.

### Redeliver

```bash theme={null}
POST /api/webhooks/:id/deliveries/:deliveryId/redeliver
```

Manually trigger redelivery of a specific event.

## Related

* [profclaw webhooks](/cli/webhooks) - Manage webhook endpoints from the CLI
* [Tasks API](/api-reference/tasks) - Tasks trigger outbound webhook events
* [Integrations Overview](/integrations/overview) - Configure inbound GitHub, Jira, and Linear webhooks
* [Security API](/api-reference/security-api) - Audit log of inbound webhook processing


# TEST STATUS
Source: https://docs.profclaw.ai/api-testing/TEST_STATUS



# profClaw API Testing Status

Last Updated: 2026-02-05 19:30 CST

## Test Results Summary

### Architecture Change: SDK-Managed Multi-Step (v3)

Executor refactored from manual `while` loop (`maxSteps: 1` + manual message accumulation) to **AI SDK native multi-step** (`generateText` with `stopWhen` + `onStepFinish`). Tool chaining now handled entirely by the SDK.

### Quick Tests (Core)

| Test                    | Status | Notes                                 |
| ----------------------- | ------ | ------------------------------------- |
| `test-simple-chat.sh`   | PASS   | Text-only response, proper AI summary |
| `test-tools.sh`         | PASS   | Tool calling endpoint works           |
| `test-create-ticket.sh` | PASS   | Single-step tool call                 |

### Agentic Multi-Step Tests

| Test                          | Status | Tools Used                                                   | Notes                                                |
| ----------------------------- | ------ | ------------------------------------------------------------ | ---------------------------------------------------- |
| `test-agentic.sh`             | PASS   | list\_projects, create\_ticket                               | 3 steps, proper ticket link in summary               |
| `test-project-ticket-flow.sh` | PASS   | create\_project, create\_ticket, update\_ticket, get\_ticket | 4-tool CRUD chain, step-by-step summary              |
| `test-git-workflow.sh`        | PASS   | git\_status, git\_log                                        | Parallel in 1 step, detailed git state summary       |
| `test-file-ops-chain.sh`      | PASS   | search\_files, read\_file, grep                              | 3-tool chain, file content summary                   |
| `test-error-recovery.sh`      | PASS   | read\_file x2                                                | Failed on nonexistent file, recovered with real file |
| `test-cron-lifecycle.sh`      | PASS   | cron\_create, cron\_list, cron\_trigger                      | Full lifecycle with IDs and timestamps in summary    |
| `test-web-search.sh`          | PASS   | web\_fetch, list\_projects, create\_ticket                   | 3-tool chain with ticket link                        |

### Full Suite (`./run-all.sh`)

| Mode                | Passed | Failed | Warnings |
| ------------------- | ------ | ------ | -------- |
| `--quick`           | 3/3    | 0      | 0        |
| Full (sequential)   | 10/10  | 0      | 0        |
| Full (`--parallel`) | 10/10  | 0      | 0        |

### Unit Tests

| Suite  | Passed | Skipped | Total |
| ------ | ------ | ------- | ----- |
| Vitest | 442    | 5       | 447   |

## SDK Multi-Step Refactor (v3)

### What Changed

* **Removed**: Manual `while` loop, `executeStep()`, `processToolCalls()`, `injectContext()`, `buildStepContext()`, manual message accumulation, manual tool result formatting
* **Added**: `wrapToolsWithExecute()`, `onStepFinish` callback, `stopWhen: [stepCountIs(N), hasToolCall('complete_task')]`
* **Result**: \~150 lines deleted, \~40 lines added. SDK handles message format and result feeding internally.

### Key Improvements

* **Tool chaining works natively**: SDK feeds tool results back as properly formatted messages
* **Proper AI summaries**: Model generates contextual summaries (no more "Agent completed after N steps" fallbacks)
* **3-tier summary priority**: 1) `complete_task` tool summary, 2) AI's last text response, 3) descriptive fallback from tool history
* **Custom stop conditions via abort**: Consecutive failures, same tool repeated, timeout checked in `onStepFinish`

## Improvements Applied (v2)

### Performance

* **Parallel execution**: `./run-all.sh --parallel` runs all tests concurrently (\~3x faster)
* **Timeout handling**: All curl calls have `--max-time` limits (30s API, 90s agentic, 120s per-test)
* **Per-test timing**: Results table shows duration for each test
* **Suite timing**: Total wall-clock time reported at end

### Reliability

* **`agentic_request()` helper**: Centralized SSE request function with built-in timeout
* **Test isolation**: `--isolated` flag creates fresh conversation per test (no state pollution)
* **Timeout detection**: Tests killed after timeout reported as TIMEOUT (exit code 124)
* **Cron test fixed**: Updated prompt to name tools explicitly (cron tools now available via `getAllChatTools()`)
* **Web search test fixed**: More explicit prompt enforces tool chaining

### Code Quality

* **Reduced duplication**: All agentic tests use `agentic_request()` helper from config.sh
* **Reusable SSE parser**: `parse_sse_stream()` and `check_expected_tools()` in config.sh
* **Timing helpers**: `now_ms()` and `format_duration()` (macOS compatible)
* **New CLI flags**: `--parallel`, `--isolated`, `--verbose`, `--timeout N`

## Key Findings

### Working Well

* Multi-step tool chains work correctly (project -> ticket -> update -> get)
* Parallel tool calls in single step (git\_status + git\_log)
* Error recovery: model retries with different approach after tool failure
* AI SDK v6 native multi-step with `stopWhen` + `onStepFinish`
* Cron tools accessible in agentic mode (getAllChatTools fix confirmed)
* Proper AI-generated summaries with ticket links, step details, and context

### Known Behaviors

* Model sometimes uses `web_fetch` instead of `web_search` (gpt4o-mini preference)
* Cron trigger may return "no job found" if job name doesn't match exactly

## Test Environment

* Server: `pnpm dev` running on localhost:3000
* Model: Azure GPT-4o (fallback from Anthropic - no ANTHROPIC\_API\_KEY set)
* `PROFCLAW_MODEL=gpt4o-mini` (default in config.sh)
* Conversation persistence: Working via `.test-state.json`

## Usage

```bash theme={null}
# Quick smoke test (3 tests, ~10s)
./run-all.sh --quick

# Full sequential (10 tests, ~2-3 min)
./run-all.sh

# Full parallel (~40-60s)
./run-all.sh --parallel

# Parallel + isolated conversations
./run-all.sh --parallel --isolated

# Verbose sequential (see test output)
./run-all.sh --verbose

# Custom timeout
./run-all.sh --timeout 60
```

## Test Scripts

```
docs/api-testing/
├── config.sh                    # Shared config, helpers, timeouts, SSE parser
├── setup.sh                     # Create test conversation
├── run-all.sh                   # Master test runner (parallel, timing, timeouts)
├── test-simple-chat.sh          # Basic chat (core)
├── test-tools.sh                # Tool calling (core)
├── test-create-ticket.sh        # Single-step ticket creation (core)
├── test-agentic.sh              # Multi-step agentic (generic)
├── test-project-ticket-flow.sh  # Project + ticket CRUD chain
├── test-git-workflow.sh         # Git status + log
├── test-file-ops-chain.sh       # File search/read/grep
├── test-cron-lifecycle.sh       # Cron create/list/trigger
├── test-error-recovery.sh       # Deliberate failure + recovery
├── test-web-search.sh           # Web search + ticket creation
├── debug-tool-loop.sh           # Debug tool repetition issues
├── glinr_test.py                   # Python test framework
└── README.md                    # Documentation
```


# Execution Engine
Source: https://docs.profclaw.ai/architecture/execution-engine

Agentic execution, tool routing, self-correction, and the agentic loop

The execution engine (`src/chat/execution/`) drives profClaw's autonomous agent behavior. It wraps the AI SDK in a loop that calls tools, tracks state, enforces security, and streams real-time events.

```mermaid theme={null}
flowchart TD
  Entry["streamAgenticChat()"]
  Executor["AgenticExecutor\none step per AI call"]
  ModelCap["Model Capability\nDetection"]
  ToolRouter["Tool Router\nfilter by model + security mode"]
  ToolHandler["ChatToolHandler\nenforce SecurityMode"]
  Tools["Tool Implementations\nfile-ops / web-fetch / git\nmemory / profclaw-ops"]
  SelfCorrect["Self-Correction\nup to 3 retry cycles"]
  SSE["SSE Event Stream\n→ client"]
  SmartPrompt["Smart Prompts\ncontext-aware system prompt"]
  SessionMgr["Session Manager\nper-conversation model override"]

  Entry --> SmartPrompt
  Entry --> SessionMgr
  Entry --> Executor
  Executor --> ModelCap
  ModelCap --> ToolRouter
  ToolRouter --> ToolHandler
  ToolHandler --> Tools
  Tools -- "success: false" --> SelfCorrect
  SelfCorrect --> Executor
  Tools -- "success: true" --> Executor
  Executor -- "step complete" --> SSE
  Executor -- "maxSteps reached" --> SSE
```

## Components

```
streamAgenticChat()
    |
    v
AgenticExecutor  <-- executes one "step" (AI call + tool calls)
    |
    v
ChatToolHandler  <-- routes tool calls, enforces security mode
    |
    v
Tool implementations (file-ops, web-fetch, git, memory, profclaw-ops...)
    |
    v
SSE event stream --> client
```

## `streamAgenticChat()`

The main agentic loop entry point from `src/chat/index.ts`:

```typescript theme={null}
async function* streamAgenticChat(options: {
  conversationId: string;
  messages: ChatMessage[];
  systemPrompt: string;
  model?: string;
  provider?: string;
  temperature?: number;
  toolHandler: ChatToolHandler;
  tools: ToolSchema[];
  showThinking?: boolean;
  maxSteps?: number;
  maxBudget?: number;
  effort?: 'low' | 'medium' | 'high' | 'max';
}): AsyncGenerator<AgenticEvent>
```

The generator yields typed `AgenticEvent` objects that map directly to the SSE events documented in [Chat Stream](/api-reference/chat-stream).

## Effort Levels

The `effort` parameter controls the step budget:

| Effort   | Max Steps | Behavior                          |
| -------- | --------- | --------------------------------- |
| `low`    | 5         | Quick tasks, minimal tool use     |
| `medium` | 20        | Default, balanced                 |
| `high`   | 50        | Complex tasks, thorough execution |
| `max`    | 200       | Exhaustive, use sparingly         |

`maxSteps` overrides the effort-derived default.

## Tool Router

`src/chat/execution/tool-router.ts` selects which tools to offer the model based on:

1. **Model capabilities**: Some models don't support all tool types
2. **Security mode**: `sandbox` limits to read-only tools; `allowlist` uses an explicit set
3. **Context**: Agentic mode includes all tools; interactive mode uses the default subset

```typescript theme={null}
// src/chat/index.ts
function getChatToolsForModel(
  modelId: string,
  options: { conversationId?: string; includeAll?: boolean }
): ToolSchema[]
```

## Security Modes

The `ChatToolHandler` (`src/chat/execution/`) enforces the active security mode on every tool call:

```typescript theme={null}
type SecurityMode = 'deny' | 'sandbox' | 'allowlist' | 'ask' | 'full';
```

* `deny`: All tool calls rejected with an error
* `sandbox`: Only tools tagged `readonly: true` are allowed
* `allowlist`: Tool name must appear in `allowedTools` list
* `ask`: Creates a `PendingApproval` and waits for user decision
* `full`: All tools execute immediately (used in agentic mode)

```mermaid theme={null}
flowchart TD
  Call["Tool Call from Model"]
  Mode{"SecurityMode"}
  Deny["reject with error"]
  Sandbox{"readonly: true?"}
  Allowlist{"in allowedTools?"}
  Ask["create PendingApproval\nwait for user"]
  Full["execute immediately"]
  Exec["Tool Executes"]

  Call --> Mode
  Mode -- deny --> Deny
  Mode -- sandbox --> Sandbox
  Sandbox -- "no" --> Deny
  Sandbox -- "yes" --> Exec
  Mode -- allowlist --> Allowlist
  Allowlist -- "no" --> Deny
  Allowlist -- "yes" --> Exec
  Mode -- ask --> Ask
  Ask -- "approved" --> Exec
  Ask -- "rejected" --> Deny
  Mode -- full --> Full
  Full --> Exec
```

## Self-Correction

`src/chat/execution/self-correction.ts` implements automatic retry on tool failure:

* Tool returns `{ success: false, error: "..." }`
* Self-correction sends the error back to the model with a correction prompt
* Model attempts an alternative approach
* Up to 3 correction cycles before the step is marked failed

## Model Capability Detection

`src/chat/execution/model-capability.ts` tracks which models support:

* Native tool calling
* Extended thinking / reasoning tokens
* Large context windows (1M+ token models)
* Streaming

The tool set offered to the model is filtered based on these capabilities to avoid sending tool schemas that the model cannot use.

## Session Manager

`src/chat/execution/session-manager.ts` tracks per-conversation model overrides. When a user selects a different model mid-conversation, `getSessionModel(conversationId)` returns the override which is respected by `streamAgenticChat` and the conversation message endpoints.

## Smart Prompts

`src/chat/execution/smart-prompts.ts` builds context-aware system prompts that include:

* Current task description and status (when `taskId` is linked)
* Linked ticket title and description
* Recent activity stats (completed/pending task counts)
* Runtime model info (`provider/model`)
* Agent mode suffix (for agentic execution)


# MCP Integration
Source: https://docs.profclaw.ai/architecture/mcp

Model Context Protocol server for Claude Code and other MCP-compatible clients

profClaw includes a standalone MCP (Model Context Protocol) server that lets Claude Code and other MCP clients report task progress, track files modified, and interact with the profClaw task queue.

```mermaid theme={null}
sequenceDiagram
  participant CC as Claude Code
  participant MCP as MCP Server\n(stdio)
  participant API as profClaw API\nlocalhost:3000
  participant Q as Task Queue
  participant DB as LibSQL

  CC->>MCP: tools/list
  MCP-->>CC: report_progress, get_task,\ncomplete_task, fail_task, ...

  CC->>MCP: report_progress(taskId, 65%)
  MCP->>API: PATCH /api/tasks/:id/progress
  API->>DB: update task

  CC->>MCP: complete_task(taskId, output, files)
  MCP->>API: POST /api/tasks/:id/complete
  API->>Q: dispatch notifications
  API->>DB: store result
  MCP-->>CC: ok
```

## What is MCP?

The Model Context Protocol is a standard for AI tools to expose capabilities to AI models. profClaw's MCP server exposes profClaw's task management and session tracking as MCP tools.

## Running the MCP Server

The MCP server runs as a separate process communicating over stdio:

```bash theme={null}
# Via npx
npx @profclaw/task-manager-mcp

# Or directly
node dist/mcp/server.js
```

Configure `PROFCLAW_API_URL` to point at your running profClaw instance:

```bash theme={null}
PROFCLAW_API_URL=http://localhost:3000 npx @profclaw/task-manager-mcp
```

## Claude Code Integration

Add to `~/.claude/settings.json` (or `.claude/settings.json` in your project):

```json theme={null}
{
  "mcpServers": {
    "profclaw": {
      "command": "npx",
      "args": ["@profclaw/task-manager-mcp"],
      "env": {
        "PROFCLAW_API_URL": "http://localhost:3000"
      }
    }
  }
}
```

After adding, run `/mcp` in Claude Code to verify the tools are available.

## Available MCP Tools

The MCP server (`src/mcp/server.ts`) exposes these tools to MCP clients:

### `report_progress`

Report task execution progress back to profClaw.

```json theme={null}
{
  "taskId": "task_01",
  "progress": 65,
  "message": "Running tests...",
  "filesModified": ["src/auth.ts", "src/auth.test.ts"]
}
```

### `get_task`

Fetch task details from the profClaw queue.

```json theme={null}
{ "taskId": "task_01" }
```

### `complete_task`

Mark a task as completed with a result summary.

```json theme={null}
{
  "taskId": "task_01",
  "output": "Fixed the session expiry bug in auth-service.ts. Added test coverage.",
  "filesCreated": ["src/auth.test.ts"],
  "filesModified": ["src/auth.ts"]
}
```

### `fail_task`

Mark a task as failed with an error message.

```json theme={null}
{ "taskId": "task_01", "error": "Tests failed: 3 assertions failed" }
```

### `get_session_state`

Get the current MCP session state (token usage, files modified, active task).

### Browser Tools

The MCP server also exposes browser automation tools (`src/mcp/browser-tools.ts`) for screenshot capture, navigation, and DOM interaction - useful for visual testing and web scraping tasks.

## Session State

Each MCP server process maintains in-memory session state:

```typescript theme={null}
interface SessionState {
  sessionId: string;    // mcp-<timestamp>-<random>
  startTime: Date;
  filesModified: string[];
  filesCreated: string[];
  tokenUsage: { input: number; output: number };
  currentTask?: { id: string; title: string; startedAt: Date };
}
```

Session state persists for the lifetime of the stdio connection.

## MCP Server Configuration

```typescript theme={null}
const server = new Server(
  { name: 'profclaw', version: '1.0.0' },
  { capabilities: { tools: { listChanged: true } } }
);
```

The server uses `StdioServerTransport` - it reads from stdin and writes to stdout. This is the standard transport for Claude Code MCP integrations.

## Tool Adapter

`src/mcp/tool-adapter.ts` converts profClaw's internal tool format (`PluginToolDefinition`) to the MCP tool schema format, allowing all installed profClaw tools to be exposed via MCP if desired.

```mermaid theme={null}
flowchart LR
  Plugin["PluginToolDefinition\n(profClaw internal)"]
  Adapter["tool-adapter.ts\nformat conversion"]
  MCPSchema["MCP Tool Schema\n(JSON Schema)"]
  Client["MCP Client\nClaude Code / other"]

  Plugin --> Adapter
  Adapter --> MCPSchema
  MCPSchema --> Client
```

## REST API for MCP

The MCP route (`src/routes/mcp.ts`) provides HTTP endpoints for managing MCP server configuration and viewing connected MCP clients:

```
GET /api/mcp/servers     # List configured MCP servers
POST /api/mcp/servers    # Add an MCP server config
DELETE /api/mcp/servers/:id
GET /api/mcp/tools       # List all tools from connected servers
```


# Memory System
Source: https://docs.profclaw.ai/architecture/memory

File-based memory, semantic search, context management, and experience store

profClaw's memory system has two layers: **file memory** (markdown files indexed for semantic search) and the **experience store** (learned tool chains and user preferences).

```mermaid theme={null}
graph TD
  Files["Markdown Files on Disk\n*.md / *.mdx / *.txt"]
  Watcher["Memory Watcher\nchokidar auto-sync"]
  Chunks["memory_chunks table\nLibSQL"]
  Search["searchMemory(query)\nBM25 / vector similarity"]
  TopK["Top-K Chunks\ninjected into context"]

  Experiences["Experience Store\ntool_chain / user_preference\ntask_solution / error_recovery"]
  ExpSearch["findSimilarExperiences()\nBM25 on intent field"]
  Decay["applyDecay()\nweight by recency"]
  Prompt["System Prompt\ncontext injection"]

  Files --> Watcher
  Watcher --> Chunks
  Chunks --> Search
  Search --> TopK
  TopK --> Prompt

  Experiences --> Decay
  Experiences --> ExpSearch
  ExpSearch --> Prompt
```

## File Memory

The file memory layer (`src/memory/`) indexes markdown files into chunks stored in LibSQL. At query time, it uses BM25 full-text search (or vector search when available) to find relevant context.

### Architecture

```
Markdown files on disk
        |
        v
syncMemoryFiles(basePath)  <-- chunkifies each file
        |
        v
memory_chunks table (LibSQL)
  - id, path, startLine, endLine, text, hash
        |
        v
searchMemory(query)  <-- BM25 or vector similarity
        |
        v
Top-K chunks returned to caller
```

### Chunking

Files are split into overlapping chunks of configurable size (`DEFAULT_MEMORY_CONFIG.chunking`). Each chunk stores:

* `path`: relative file path
* `startLine` / `endLine`: line range in the source file
* `text`: raw chunk content
* `hash`: content hash for change detection (avoids re-indexing unchanged chunks)

### Auto-Sync (Memory Watcher)

`src/memory/memory-watcher.ts` watches the configured paths with `chokidar` and triggers incremental re-sync when files change:

```typescript theme={null}
interface MemoryWatcherState {
  dirty: boolean;       // Files changed since last sync
  syncing: boolean;     // Sync in progress
  lastSyncAt: Date | null;
  watchedFiles: number;
  watching: boolean;
}
```

When `dirty` is true, the next `searchMemory()` call automatically triggers a sync before returning results (`autoSynced: true` in the response).

### Memory Config

```typescript theme={null}
const DEFAULT_MEMORY_CONFIG = {
  sources: ['local'],
  provider: 'libsql',
  chunking: {
    maxChunkSize: 1500,
    overlapSize: 200,
    splitOnHeaders: true,
  },
  query: {
    maxResults: 6,
    minScore: 0.1,
  },
  sync: {
    onSessionStart: true,
    onSearch: true,
    watch: true,
    watchDebounceMs: 2000,
  },
  paths: {
    include: ['**/*.md', '**/*.mdx', '**/*.txt'],
    exclude: ['node_modules/**', 'dist/**', '.git/**'],
  },
};
```

## Memory Sessions

Memory sessions (`createMemorySession`, `archiveSession`) track which knowledge base was loaded for a given conversation. This enables:

* Session replay (re-load same context)
* Auditing which files influenced a response
* Session isolation (different projects use different memory sets)

## Experience Store

`src/memory/experience-store.ts` records patterns the agent learns from execution:

### Experience Types

```typescript theme={null}
type ExperienceType =
  | 'tool_chain'        // Sequence of tools that solved a problem
  | 'user_preference'   // User's formatting or style preferences
  | 'task_solution'     // Successful approach to a type of task
  | 'error_recovery';   // How a past error was fixed
```

### Schema

Each experience has:

* `intent`: what the user was trying to do (text for similarity search)
* `solution`: the approach that worked (arbitrary JSON)
* `successScore`: 0-1, quality of the solution
* `weight`: decays over time (updated by `applyDecay()`)
* `useCount`: incremented each time the experience is retrieved and used

### Retrieval

`findSimilarExperiences(query, tags?, limit?)` uses BM25 search on the `intent` field to find past experiences relevant to the current task. The result is injected into the system prompt when available.

```mermaid theme={null}
flowchart LR
  Exec["Agent Execution\nsolves a task"]
  Record["Record Experience\nintent + solution\nsuccessScore"]
  Retrieve["findSimilarExperiences()\non next similar task"]
  Use["inject into\nsystem prompt"]
  Decay["applyDecay()\nweight * 0.5^days/halfLife"]
  Prune["pruneExpired()\nremove below minWeight"]

  Exec --> Record
  Record --> Retrieve
  Retrieve --> Use
  Use -- "increments useCount" --> Record
  Record --> Decay
  Decay --> Prune
```

### Decay

Experiences are weighted by recency. `applyDecay(halfLifeDays)` reduces the weight of old experiences:

```
weight = weight * 0.5^(daysSinceLastUse / halfLifeDays)
```

`pruneExpired(minWeight)` removes experiences below the minimum weight threshold to keep the store lean.

## Context Management

`getMemoryStats()` and `needsCompaction()` (from `src/chat/index.ts`) track token usage and trigger conversation compaction before the context window fills:

```typescript theme={null}
function needsCompaction(messages: ConversationMessage[], model?: string): boolean
async function compactMessages(messages: ConversationMessage[], model?: string): Promise<CompactionResult>
```

Compaction summarizes older messages into a single summary block, preserving context while reducing token count.


# Architecture Overview
Source: https://docs.profclaw.ai/architecture/overview

System components, data flow, and deployment topology of profClaw

profClaw is a monorepo with a Hono-based API backend and a React 19 frontend. It runs as a single Node.js process (or serverless on Cloudflare Workers) and stores data in LibSQL/SQLite.

```mermaid theme={null}
graph TD
  Client["Client (WebChat / CLI / MCP)"]
  Hono["Hono Router\n/api/*"]
  Auth["Auth Middleware\nsession / Bearer"]
  Chat["Chat Engine\nchat/providers/"]
  Exec["Execution Engine\nchat/execution/"]
  Queue["Task Queue\nBullMQ / in-memory"]
  Memory["Memory System\nmemory/"]
  Plugins["Plugin System\nplugins/"]
  Integrations["Integrations\nGitHub / Jira / Linear"]
  MCP["MCP Server\nmcp/"]
  LibSQL["LibSQL / SQLite"]
  Redis["Redis\n(pro mode)"]

  Client --> Hono
  Hono --> Auth
  Auth --> Chat
  Auth --> Queue
  Chat --> Exec
  Exec --> Memory
  Exec --> Plugins
  Queue --> Exec
  Hono --> Integrations
  Hono --> MCP
  Exec --> LibSQL
  Queue --> LibSQL
  Memory --> LibSQL
  Queue --> Redis
```

## Component Map

```
┌─────────────────────────────────────────────────────────┐
│                    profClaw Server                       │
│                                                          │
│  ┌──────────┐   ┌──────────────┐   ┌─────────────────┐ │
│  │  Hono    │   │  Chat Engine │   │  Execution       │ │
│  │  Router  │──>│  (providers/ │──>│  Engine          │ │
│  │  /api/*  │   │   index.ts)  │   │  (chat/          │ │
│  └──────────┘   └──────────────┘   │  execution/)     │ │
│       │                            └─────────────────┘ │
│       │         ┌──────────────┐                        │
│       ├────────>│  Task Queue  │   BullMQ / In-memory   │
│       │         │  (queue/)    │                        │
│       │         └──────────────┘                        │
│       │                                                  │
│       │         ┌──────────────┐   ┌─────────────────┐ │
│       ├────────>│  Memory      │   │  Plugin System  │ │
│       │         │  (memory/)   │   │  (plugins/)     │ │
│       │         └──────────────┘   └─────────────────┘ │
│       │                                                  │
│       │         ┌──────────────┐   ┌─────────────────┐ │
│       └────────>│  Integrations│   │  MCP Server     │ │
│                 │  (github/    │   │  (mcp/)         │ │
│                 │   jira/      │   └─────────────────┘ │
│                 │   linear/)   │                        │
│                 └──────────────┘                        │
└─────────────────────────────────────────────────────────┘
         │                   │
         v                   v
   LibSQL / SQLite        Redis (optional)
   (storage/)             (pro mode only)
```

## Deployment Modes

```typescript theme={null}
// src/types/index.ts
type DeploymentMode = 'pico' | 'mini' | 'pro';
```

| Mode   | Queue          | Storage         | Features                      |
| ------ | -------------- | --------------- | ----------------------------- |
| `pico` | In-memory      | LibSQL file     | Single user, local only       |
| `mini` | In-memory      | LibSQL file     | Multi-user, no Redis          |
| `pro`  | BullMQ + Redis | LibSQL or Turso | Full features, multi-instance |

## Request Flow

1. HTTP request arrives at Hono router (`src/server.ts`)
2. Auth middleware validates session cookie or Bearer token
3. Route handler validates input with Zod schemas
4. For chat: lazy-loaded runtime (`ensureChatRuntime()`) processes with AI SDK
5. For tasks: `addTask()` enqueues to BullMQ or in-memory queue
6. Queue worker picks up task, routes to agent adapter via `AgentRegistry`
7. Agent executes tools via `ChatToolHandler` (respecting security mode)
8. Result stored in LibSQL, notifications dispatched asynchronously

```mermaid theme={null}
sequenceDiagram
  participant C as Client
  participant H as Hono Router
  participant A as Auth Middleware
  participant R as Route Handler
  participant Q as Task Queue
  participant E as Execution Engine
  participant DB as LibSQL

  C->>H: HTTP request
  H->>A: validate session / token
  A-->>H: authorized
  H->>R: Zod-validated input
  alt chat request
    R->>E: ensureChatRuntime()
    E-->>C: SSE stream (AgenticEvents)
  else task request
    R->>Q: addTask()
    Q->>E: worker picks up job
    E->>DB: store result
    E-->>C: async notification
  end
```

## Storage Layer

All persistence goes through the storage adapter (`src/storage/`):

* **Schema**: Drizzle ORM with LibSQL/SQLite backend
* **Tables**: `users`, `sessions`, `tasks`, `conversations`, `messages`, `memory_chunks`, `experiences`, `provider_configs`, `invite_codes`
* **Migrations**: `src/storage/migrations.ts`

## Key Module Boundaries

| Path                  | Responsibility                                       |
| --------------------- | ---------------------------------------------------- |
| `src/server.ts`       | Hono app creation, route mounting, server startup    |
| `src/routes/`         | HTTP route handlers (thin, delegate to services)     |
| `src/chat/`           | Chat engine, conversation management, system prompts |
| `src/chat/execution/` | Agentic executor, tool handler, session manager      |
| `src/providers/`      | AI SDK provider registry (15+ providers)             |
| `src/queue/`          | Task queue (BullMQ + in-memory), failure handler     |
| `src/memory/`         | Memory sync, search, experience store                |
| `src/plugins/`        | Plugin registry, SDK, sandbox, ClawHub client        |
| `src/integrations/`   | GitHub, Jira, Linear, Cloudflare, Tailscale clients  |
| `src/mcp/`            | MCP server for Claude Code integration               |
| `src/sync/`           | Bidirectional sync engine for ticket platforms       |
| `src/auth/`           | Session management, OAuth, device identity, pairing  |


# Queue System
Source: https://docs.profclaw.ai/architecture/queue-system

BullMQ and in-memory queue, job lifecycle, failure handling, and DLQ

profClaw uses a dual-mode queue: **BullMQ** (Redis-backed) in `pro` mode and an **in-memory queue** in `pico`/`mini` mode. Both implement the same `addTask / getTask / cancelTask / retryTask` interface.

```mermaid theme={null}
flowchart TD
  Env{"REDIS_URL set?"}
  BullMQ["BullMQ Queue\nRedis-backed\n(pro mode)"]
  MemQ["In-Memory Queue\nMap backed\n(pico / mini)"]
  API["Unified Queue API\naddTask / getTask\ncancelTask / retryTask"]

  Env -- "yes" --> BullMQ
  Env -- "no" --> MemQ
  BullMQ --> API
  MemQ --> API
```

## Task Lifecycle

```
addTask()
    |
    v
[pending] ──────────── BullMQ.add() ───────────> [queued]
                                                      |
                                               Worker picks up
                                                      |
                                                      v
                                               [in_progress]
                                              /             \
                                    adapter.execute()  throws/rejects
                                          |                  |
                                          v                  v
                                    [completed]          [failed]
                                                             |
                                                    retryCount < maxRetries?
                                                    /                \
                                                  Yes                No
                                                   |                  |
                                              Re-queue           Dead Letter Queue
```

```mermaid theme={null}
flowchart TD
  Add["addTask()"]
  Pending["pending"]
  Queued["queued"]
  InProgress["in_progress"]
  Success["completed"]
  Failed["failed"]
  Retry{"retryCount\n< maxRetries?"}
  Backoff["re-queue with\nexponential backoff"]
  DLQ["Dead Letter Queue"]
  Notify["Notification Queue\nasync delivery"]

  Add --> Pending
  Pending --> Queued
  Queued -- "worker picks up" --> InProgress
  InProgress -- "adapter.execute() ok" --> Success
  InProgress -- "throws / rejects" --> Failed
  Success --> Notify
  Failed --> Retry
  Retry -- "yes" --> Backoff
  Backoff --> Queued
  Retry -- "no" --> DLQ
```

## BullMQ Configuration

```typescript theme={null}
// src/queue/task-queue.ts
const QUEUE_NAME = settings.queue?.name || 'ai-tasks';
const REDIS_URL = process.env.REDIS_URL || settings.queue?.redis?.url;

// Connection
const connection = {
  host: new URL(REDIS_URL).hostname,
  port: parseInt(new URL(REDIS_URL).port || '6379'),
  password: new URL(REDIS_URL).password || undefined,
};
```

The BullMQ queue uses priority-based processing. Tasks with `priority: 1` (critical) are processed before `priority: 4` (low).

## In-Memory Queue

`src/queue/memory-queue.ts` provides a `Map<string, Task>` backed queue with:

* Immediate execution (no separate worker process)
* Same `TaskStatus` state machine
* No persistence across restarts
* Cursor-based iteration not supported (offset only)

The in-memory queue is auto-selected when `REDIS_URL` is not set.

## Queue Index

`src/queue/index.ts` exposes the unified API:

```typescript theme={null}
export async function addTask(input: CreateTaskInput): Promise<Task>
export function getTask(id: string): Task | undefined
export function getTasks(options?: {
  status?: TaskStatusType;
  limit?: number;
  offset?: number;
}): Task[]
export async function cancelTask(id: string): Promise<boolean>
export async function retryTask(id: string): Promise<Task | null>
```

## Failure Handler

`src/queue/failure-handler.ts` implements the retry and DLQ logic:

```typescript theme={null}
export async function handleTaskFailure(
  task: Task,
  error: Error,
  attempt: number
): Promise<void>
```

On each failure:

1. Increments `retryCount` on the task
2. If `retryCount < maxRetries` (default 3): re-queues with exponential backoff delay (`backoff * 2^attempt`)
3. If exhausted: moves to DLQ via `initDeadLetterQueue()`
4. Creates an in-app notification for DLQ entries

## Dead Letter Queue

The DLQ (`src/queue/failure-handler.ts` + route `src/routes/dlq.ts`) holds tasks that have exhausted retries:

```typescript theme={null}
export async function getDeadLetterQueueStats(): Promise<{
  pending: number;
  resolved: number;
  discarded: number;
  total: number;
}>
```

Operators can inspect DLQ entries at `GET /api/dlq`, retry them with `POST /api/dlq/:id/retry`, or discard with `POST /api/dlq/:id/discard`.

## Notification Queue

A separate BullMQ queue (`ai-task-notifications`) handles async notifications after task completion. This keeps notification delivery off the critical path - a slow webhook target doesn't delay the next task from starting.

```typescript theme={null}
// After task completes:
await notificationQueue.add('notify', { task, result }, { attempts: 3 });

// Worker posts to:
// 1. GitHub/Jira/Linear (result comment on source issue)
// 2. Registered outbound webhooks
// 3. In-app notification store
```

```mermaid theme={null}
flowchart LR
  TaskDone["Task Completed"]
  NQ["ai-task-notifications\nqueue"]
  GH["GitHub / Jira / Linear\nresult comment"]
  WH["Outbound Webhooks"]
  InApp["In-App Notification\nstore"]

  TaskDone --> NQ
  NQ --> GH
  NQ --> WH
  NQ --> InApp
```

## Webhook Queue

`src/queue/webhook-queue.ts` manages outbound webhook delivery with:

* Per-endpoint retry with backoff
* Deduplication (no double-delivery on restart)
* Delivery log stored in LibSQL
* Health tracking (mark endpoint as failing after N failures)

## Task Store Sync

In BullMQ mode, the in-memory `taskStore` Map acts as a cache. It is populated from the database on startup and kept in sync by the worker event handlers:

```typescript theme={null}
taskWorker.on('completed', (job, result) => {
  const task = taskStore.get(job.id);
  if (task) {
    task.status = 'completed';
    taskStore.set(job.id, task);
  }
  storage.updateTask(job.id, { status: 'completed', ...result });
});
```


# Sync System
Source: https://docs.profclaw.ai/architecture/sync

Bidirectional sync engine, conflict resolution, and multi-platform ticket management

The sync engine (`src/sync/`) provides bidirectional synchronization between profClaw's internal ticket store and external platforms: GitHub Issues, Jira, and Linear.

```mermaid theme={null}
graph LR
  ProfClaw["profClaw\nTicket Store\n(LibSQL)"]
  Engine["Sync Engine\nconflict resolution\nqueue + retry"]
  GH["GitHub\nSyncAdapter"]
  Jira["Jira\nSyncAdapter"]
  Linear["Linear\nSyncAdapter"]
  P2P["profClaw (remote)\nSyncAdapter"]

  ProfClaw <--> Engine
  Engine <--> GH
  Engine <--> Jira
  Engine <--> Linear
  Engine <--> P2P
```

## Core Types

```typescript theme={null}
// src/sync/types.ts

export type SyncDirection = 'push' | 'pull' | 'bidirectional';

export type SyncOperationType =
  | 'create' | 'update' | 'delete'
  | 'comment_add' | 'comment_update' | 'status_change';

export type ConflictStrategy =
  | 'local_wins' | 'remote_wins' | 'latest_wins' | 'manual';
```

## SyncAdapter Interface

Each platform implements `SyncAdapter`:

```typescript theme={null}
export interface SyncAdapter {
  readonly platform: string;
  readonly config: SyncAdapterConfig;

  connect(): Promise<void>;
  disconnect(): Promise<void>;
  isConnected(): boolean;
  healthCheck(): Promise<{ healthy: boolean; latencyMs: number }>;

  createTicket(ticket: Ticket): Promise<ExternalTicket>;
  updateTicket(externalId: string, updates: Partial<Ticket>): Promise<ExternalTicket>;
  deleteTicket(externalId: string): Promise<boolean>;
  getTicket(externalId: string): Promise<ExternalTicket | null>;
  listTickets(options?: ListTicketsOptions): Promise<{
    tickets: ExternalTicket[];
    cursor?: string;
  }>;

  addComment(externalTicketId: string, content: string): Promise<ExternalComment>;
  getComments(externalTicketId: string): Promise<ExternalComment[]>;

  mapStatusToExternal(status: TicketStatus): string;
  mapStatusFromExternal(externalStatus: string): TicketStatus;
  mapPriorityToExternal(priority: TicketPriority): string | number | undefined;
  mapPriorityFromExternal(externalPriority: string | number): TicketPriority;

  parseWebhook?(payload: unknown): WebhookEvent | null;
}
```

## Sync Engine Config

```typescript theme={null}
export interface SyncEngineConfig {
  conflictStrategy: ConflictStrategy;  // default: 'latest_wins'
  syncIntervalMs: number;               // default: 60000 (1 minute)
  maxRetries: number;                   // default: 3
  retryDelayMs: number;                 // default: 1000
  enableWebhooks: boolean;              // default: true
  platforms: Record<string, SyncAdapterConfig>;
}
```

## Conflict Resolution

When the same ticket is modified locally and remotely between sync cycles, the `ConflictStrategy` determines which value wins:

| Strategy      | Behavior                                       |
| ------------- | ---------------------------------------------- |
| `local_wins`  | profClaw value always overwrites remote        |
| `remote_wins` | Remote value always overwrites profClaw        |
| `latest_wins` | Whichever has the most recent `updatedAt` wins |
| `manual`      | Conflict stored for user resolution            |

A `SyncConflict` record is created for every conflict:

```typescript theme={null}
export interface SyncConflict {
  ticketId: string;
  platform: string;
  field: string;
  localValue: unknown;
  remoteValue: unknown;
  localTimestamp: Date;
  remoteTimestamp: Date;
  resolution?: 'local' | 'remote' | 'merged';
  mergedValue?: unknown;
}
```

```mermaid theme={null}
flowchart TD
  Conflict["Ticket modified\nlocally AND remotely"]
  Strategy{"ConflictStrategy"}
  LW["local_wins\nprofClaw value wins"]
  RW["remote_wins\nremote value wins"]
  Latest{"latest updatedAt?"}
  Manual["manual\nstore SyncConflict\nfor user resolution"]
  Apply["apply winning value\nto both sides"]

  Conflict --> Strategy
  Strategy -- "local_wins" --> LW
  Strategy -- "remote_wins" --> RW
  Strategy -- "latest_wins" --> Latest
  Strategy -- "manual" --> Manual
  Latest -- "local newer" --> LW
  Latest -- "remote newer" --> RW
  LW --> Apply
  RW --> Apply
```

## Sync Queue

Operations are queued and processed with retry:

```typescript theme={null}
export interface SyncQueueItem {
  id: string;
  operation: SyncOperation;
  priority: number;
  createdAt: Date;
  scheduledFor: Date;
  attempts: number;
  maxAttempts: number;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  result?: SyncResult;
}
```

```mermaid theme={null}
sequenceDiagram
  participant Ext as External Platform\n(GitHub / Jira / Linear)
  participant WH as Webhook Route\n/api/webhooks/:platform
  participant Adapter as SyncAdapter\nparseWebhook()
  participant Engine as Sync Engine
  participant DB as LibSQL

  Ext->>WH: webhook POST
  WH->>Adapter: parseWebhook(payload)
  Adapter-->>Engine: WebhookEvent
  Engine->>DB: update local ticket
  Engine-->>WH: 200 OK

  note over Engine,DB: immediate sync (no poll delay)
```

## Webhook-Driven Sync

When webhooks are enabled (`enableWebhooks: true`), inbound webhook events from GitHub/Jira/Linear trigger immediate sync operations instead of waiting for the polling interval:

1. Webhook arrives at `/api/webhooks/:platform`
2. Adapter calls `parseWebhook(payload)` to extract a `WebhookEvent`
3. Sync engine processes the event immediately
4. Local ticket state updated within seconds of the external change

## Pull Sync

On each polling cycle, the engine calls `adapter.listTickets({ updatedAfter: lastSyncAt })` with the cursor from the previous sync. This fetches only changed tickets, minimizing API quota usage.

## Push Sync

When a local ticket is created or updated, a `SyncOperation` is added to the queue. The adapter's `createTicket` or `updateTicket` method is called asynchronously.

## Status and Priority Mapping

Each adapter implements bidirectional mapping functions. For example, the GitHub adapter maps:

```
open issue    <--> TicketStatus.open
closed issue  <--> TicketStatus.closed
```

The Linear adapter maps workflow states by `stateType` (triage, backlog, started, completed, cancelled) to profClaw's `TicketStatus` enum.

## Multi-Device Sync

The sync system also handles profClaw-to-profClaw synchronization for multi-instance setups. Two profClaw instances can sync their task and conversation state over Tailscale or direct HTTP, using the same `SyncAdapter` interface with a `profclaw` platform adapter.


# Custom Chat Providers
Source: https://docs.profclaw.ai/chat-providers/custom

Build your own chat provider for profClaw. Implement the ChatProvider interface to integrate any messaging platform.

profClaw's provider system is fully extensible. You can create a custom provider to integrate any messaging platform that isn't built-in.

## Overview

Every chat provider in profClaw implements the same `ChatProvider` interface. Custom providers have the same capabilities as built-in ones:

* Inbound message handling
* Outbound message sending
* Status and health checks
* Multi-account support

## Interface

A chat provider consists of four adapters:

```typescript theme={null}
interface ChatProvider {
  meta: ChatProviderMeta;
  capabilities: ChatProviderCapabilities;

  // Adapters
  outbound: OutboundAdapter;     // Send messages
  inbound?: InboundAdapter;      // Receive messages
  auth?: AuthAdapter;            // OAuth flows
  status: StatusAdapter;         // Health checks
}
```

## Building a Provider

<Steps>
  <Step title="Create the provider file">
    ```typescript theme={null}
    // src/chat/providers/my-platform/index.ts
    import type {
      ChatProvider,
      ChatProviderMeta,
      ChatProviderCapabilities,
    } from '../types.js';

    const meta: ChatProviderMeta = {
      id: 'my-platform' as ChatProviderId,
      name: 'My Platform',
      description: 'Integration with My Platform messaging',
      icon: '💬',
      order: 100,
    };

    const capabilities: ChatProviderCapabilities = {
      chatTypes: ['direct', 'group'],
      send: true,
      receive: true,
      slashCommands: false,
      interactiveComponents: false,
      reactions: false,
      edit: false,
      delete: false,
      threads: false,
      media: true,
      richBlocks: false,
      oauth: false,
      webhooks: true,
      realtime: false,
    };

    export const myPlatformProvider: ChatProvider = {
      meta,
      capabilities,
      outbound: { /* see below */ },
      inbound: { /* see below */ },
      status: { /* see below */ },
    };
    ```
  </Step>

  <Step title="Implement the outbound adapter">
    ```typescript theme={null}
    const outbound: OutboundAdapter = {
      async send(message: OutgoingMessage, account: ChatAccountConfig): Promise<SendResult> {
        const config = account as MyPlatformAccountConfig;

        const response = await fetch(`${config.apiUrl}/messages`, {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${config.apiKey}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            to: message.channelId,
            text: message.text,
          }),
        });

        if (!response.ok) {
          return { success: false, error: `API error: ${response.status}` };
        }

        const data = await response.json();
        return { success: true, messageId: data.id };
      },
    };
    ```
  </Step>

  <Step title="Implement the inbound adapter">
    ```typescript theme={null}
    const inbound: InboundAdapter = {
      // Called when a webhook is received
      async handleWebhook(
        req: Request,
        account: ChatAccountConfig
      ): Promise<IncomingMessage[]> {
        const body = await req.json();

        return body.messages.map((msg: unknown) => ({
          id: msg.id,
          provider: 'my-platform' as ChatProviderId,
          accountId: account.id,
          channelId: msg.channelId,
          senderId: msg.userId,
          senderName: msg.userName,
          text: msg.text,
          timestamp: new Date(msg.timestamp).toISOString(),
          raw: msg,
        }));
      },
    };
    ```
  </Step>

  <Step title="Register the provider">
    ```typescript theme={null}
    // In your server setup or plugin
    import { getChatRegistry } from '../chat/providers/registry.js';
    import { myPlatformProvider } from './chat/providers/my-platform/index.js';

    getChatRegistry().register(myPlatformProvider);
    ```
  </Step>
</Steps>

## Account Configuration

Define a typed config for your provider's credentials:

```typescript theme={null}
interface MyPlatformAccountConfig extends ChatAccountConfigBase {
  provider: 'my-platform';
  apiUrl?: string;
  apiKey?: string;
  webhookSecret?: string;
}
```

## Webhook Registration

Register your provider's webhook route with Hono:

```typescript theme={null}
app.post('/webhooks/my-platform', async (c) => {
  const body = await c.req.json();
  const registry = getChatRegistry();
  const provider = registry.get('my-platform');

  const messages = await provider.inbound?.handleWebhook(c.req.raw, account);
  // Process messages...

  return c.json({ ok: true });
});
```

## Plugin Distribution

Wrap your custom provider as a profClaw plugin for easy distribution:

```typescript theme={null}
// plugin.ts
import type { ProfClawPlugin } from 'profclaw/sdk';

export const plugin: ProfClawPlugin = {
  name: 'my-platform',
  version: '1.0.0',
  setup(ctx) {
    ctx.registerChatProvider(myPlatformProvider);
  },
};
```

## Notes

* Custom providers have the same capabilities as built-in providers.
* The `id` field must be unique across all registered providers.
* Account configuration is stored in profClaw's settings and can include multiple accounts.
* For distributing providers to others, use the Plugin SDK and publish to ClawHub.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 built-in supported channels
* [Plugins Overview](/plugins/overview) - Package and publish your custom provider as a plugin
* [Plugin SDK](/plugins/sdk) - TypeScript SDK for building profClaw plugins
* [profclaw channels](/cli/channels) - Enable and test chat provider connections from the CLI


# Discord
Source: https://docs.profclaw.ai/chat-providers/discord

Deploy profClaw as a Discord bot. Supports slash commands, interactive components, guild and DM support.

profClaw's Discord integration registers as a bot on your server and responds to slash commands, direct messages, and @mentions.

## Capabilities

| Feature             | Supported                |
| ------------------- | ------------------------ |
| Direct messages     | Yes                      |
| Server channels     | Yes (on mention/command) |
| Slash commands      | Yes                      |
| Interactive buttons | Yes                      |
| File attachments    | Yes                      |
| Threads             | Yes                      |
| Reactions           | Yes                      |
| OAuth app install   | Yes                      |

## Setup

<Steps>
  <Step title="Create a Discord Application">
    Go to [discord.com/developers](https://discord.com/developers/applications) and create a new application.
  </Step>

  <Step title="Create a Bot">
    Under **Bot**, click **Add Bot**. Copy the bot token.

    Enable these Privileged Gateway Intents:

    * **Message Content Intent** (required to read messages)
    * **Server Members Intent** (optional, for member lookup)
  </Step>

  <Step title="Register Slash Commands">
    Under **OAuth2 > URL Generator**, select scopes:

    * `bot`
    * `applications.commands`

    Select bot permissions:

    * Send Messages
    * Read Message History
    * Use Slash Commands
    * Add Reactions
  </Step>

  <Step title="Invite the bot">
    Use the generated OAuth2 URL to invite the bot to your server.
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    DISCORD_BOT_TOKEN=...
    DISCORD_APPLICATION_ID=...
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Discord bot token from the Developer Portal.
</ParamField>

<ParamField type="string">
  Your Discord application ID.
</ParamField>

<ParamField type="string">
  Application public key for webhook verification (required for HTTP interaction mode).
</ParamField>

<ParamField type="string">
  Restrict to a single guild/server. Leave empty for multi-server support.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    DISCORD_BOT_TOKEN=MTI...
    DISCORD_APPLICATION_ID=1234567890
    # Optional: single-server mode
    DISCORD_GUILD_ID=9876543210
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      discord:
        bot_token: "${DISCORD_BOT_TOKEN}"
        application_id: "${DISCORD_APPLICATION_ID}"
        guild_id: "${DISCORD_GUILD_ID}"
    ```
  </Tab>
</Tabs>

## Slash Commands

profClaw registers these slash commands automatically:

```
/ask [question]     - Ask a question
/run [skill]        - Run a skill
/status             - Agent status
```

## Usage Examples

```
# In any channel
@profclaw Review the last 5 commits

# Slash command
/ask What is the status of deployment #42?

# DM the bot directly
Any message in DMs is treated as a question
```

## Notes

* Bot connects via Discord's Gateway (WebSocket) for real-time events - no public webhook URL needed.
* For large servers, use `DISCORD_GUILD_ID` to scope the bot to one server for faster slash command registration.
* Global slash command registration can take up to 1 hour to propagate; guild-scoped commands are instant.
* Multi-server support works without additional configuration.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Slack](/chat-providers/slack) - Workspace messaging with Socket Mode
* [Notifications Tool](/tools/notifications) - Send proactive messages to Discord channels from agents
* [profclaw channels](/cli/channels) - Enable and test the Discord connection from the CLI


# IRC
Source: https://docs.profclaw.ai/chat-providers/irc

Connect profClaw to IRC networks. Classic IRC protocol with TLS support, NickServ auth, and multi-channel support.

profClaw can join IRC networks as a bot, responding to direct messages and channel mentions. Supports TLS connections and NickServ authentication.

## Capabilities

| Feature          | Supported        |
| ---------------- | ---------------- |
| Direct messages  | Yes              |
| Channel messages | Yes (on mention) |
| TLS connections  | Yes              |
| NickServ auth    | Yes              |
| Multi-channel    | Yes              |
| CTCP             | No               |
| DCC              | No               |

## Setup

<Steps>
  <Step title="Choose a network">
    Pick an IRC network (Libera.Chat, OFTC, Freenode successor, etc.).
  </Step>

  <Step title="Choose a nickname">
    Pick a unique bot nickname. Register it with NickServ if the network supports it:

    ```
    /msg NickServ REGISTER password email@example.com
    ```
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    IRC_SERVER=irc.libera.chat
    IRC_PORT=6697
    IRC_NICK=profclaw-bot
    IRC_PASSWORD=nickserv-password
    IRC_CHANNELS=#your-channel,#another-channel
    IRC_USE_TLS=true
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  IRC server hostname (e.g., `irc.libera.chat`).
</ParamField>

<ParamField type="number">
  IRC server port. Defaults to `6667`. Use `6697` for TLS.
</ParamField>

<ParamField type="string">
  Bot nickname.
</ParamField>

<ParamField type="string">
  NickServ or server password.
</ParamField>

<ParamField type="string">
  Comma-separated list of channels to join (e.g., `#general,#dev`).
</ParamField>

<ParamField type="boolean">
  Enable TLS. Defaults to `true`.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    IRC_SERVER=irc.libera.chat
    IRC_PORT=6697
    IRC_NICK=profclaw
    IRC_PASSWORD=my-nickserv-password
    IRC_CHANNELS=#dev,#ai-bots
    IRC_USE_TLS=true
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      irc:
        server: "${IRC_SERVER}"
        port: 6697
        nick: "${IRC_NICK}"
        password: "${IRC_PASSWORD}"
        channels:
          - "#dev"
          - "#ai-bots"
        use_tls: true
    ```
  </Tab>
</Tabs>

## Bot Trigger

In channels, the bot responds when mentioned:

```
<user> profclaw: what is the weather in London?
<profclaw> According to current data, London is 12°C and cloudy.
```

In private messages, all messages are processed.

## Notes

* Status: Beta
* IRC is connectionless - profClaw maintains a persistent TCP connection.
* If the connection drops, profClaw automatically reconnects.
* TLS port 6697 is strongly recommended over plaintext 6667.
* NickServ registration prevents nick squatting on public networks.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Matrix](/chat-providers/matrix) - Modern federated messaging as an IRC alternative
* [Rocket.Chat](/chat-providers/rocket-chat) - Self-hosted modern chat for developer communities
* [profclaw channels](/cli/channels) - Enable and test the IRC connection from the CLI


# LINE
Source: https://docs.profclaw.ai/chat-providers/line

Connect profClaw to LINE Messaging API. Popular in Japan, Taiwan, and Southeast Asia.

LINE is the dominant messaging platform across Japan, Taiwan, Thailand, and Indonesia. profClaw integrates via the LINE Messaging API for bot interactions.

## Capabilities

| Feature             | Supported |
| ------------------- | --------- |
| 1:1 messages        | Yes       |
| Group messages      | Yes       |
| Quick reply buttons | Yes       |
| Flex messages       | Yes       |
| File/image send     | Yes       |
| Webhook             | Yes       |
| Channel access      | Yes       |

## Setup

<Steps>
  <Step title="Create a LINE Developers account">
    Sign up at [developers.line.biz](https://developers.line.biz).
  </Step>

  <Step title="Create a Messaging API channel">
    Create a new provider and channel. Choose **Messaging API** as the channel type.
  </Step>

  <Step title="Get credentials">
    Under **Messaging API** tab:

    * **Channel access token** (long-lived)
    * **Channel secret**
  </Step>

  <Step title="Set webhook URL">
    Under **Messaging API > Webhook settings**, set:
    `https://your-domain.com/webhooks/line`

    Enable **Use webhook**.
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    LINE_CHANNEL_ACCESS_TOKEN=your-channel-access-token
    LINE_CHANNEL_SECRET=your-channel-secret
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  LINE Messaging API channel access token (long-lived).
</ParamField>

<ParamField type="string">
  Channel secret for webhook signature verification.
</ParamField>

<ParamField type="string">
  Webhook URL. Required to be set in LINE Developer Console.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    LINE_CHANNEL_ACCESS_TOKEN=xxxxxxxxxxxxxxxxxxx
    LINE_CHANNEL_SECRET=abcdef1234567890
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      line:
        channel_access_token: "${LINE_CHANNEL_ACCESS_TOKEN}"
        channel_secret: "${LINE_CHANNEL_SECRET}"
    ```
  </Tab>
</Tabs>

## Flex Messages

profClaw can send LINE Flex Messages for rich layouts:

```json theme={null}
{
  "type": "flex",
  "altText": "Task completed",
  "contents": {
    "type": "bubble",
    "body": {
      "type": "box",
      "layout": "vertical",
      "contents": [
        { "type": "text", "text": "Result", "weight": "bold" }
      ]
    }
  }
}
```

## Notes

* Status: Beta
* LINE requires a public HTTPS webhook URL.
* LINE's free tier allows 500 messages/month. Paid plans remove the limit.
* The webhook URL must be verified in the LINE Developer Console.
* LINE's Messaging API uses POST webhooks - profClaw verifies the `X-Line-Signature` header.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Zalo](/chat-providers/zalo) - Leading messaging platform in Vietnam
* [Viber](/chat-providers/viber) - Messaging app popular in Southeast Asia and Eastern Europe
* [profclaw channels](/cli/channels) - Enable and test the LINE connection from the CLI


# Matrix
Source: https://docs.profclaw.ai/chat-providers/matrix

Connect profClaw to Matrix/Element. Federated, open-source messaging with optional end-to-end encryption.

Matrix is an open-source, federated communication protocol. profClaw connects as a Matrix bot user, joining rooms and responding to messages across any Matrix homeserver.

## Capabilities

| Feature               | Supported            |
| --------------------- | -------------------- |
| Direct messages       | Yes                  |
| Room messages         | Yes                  |
| End-to-end encryption | Optional             |
| File uploads          | Yes                  |
| Reactions             | Yes                  |
| Federation            | Yes (any homeserver) |
| Room allowlist        | Yes                  |

## Setup

<Steps>
  <Step title="Register a Matrix account">
    Create a bot account on your Matrix homeserver (or matrix.org). Use a dedicated account, not your personal one.
  </Step>

  <Step title="Get an access token">
    Log in and retrieve the access token:

    ```bash theme={null}
    curl -X POST https://matrix.org/_matrix/client/r0/login \
      -H "Content-Type: application/json" \
      -d '{"type":"m.login.password","user":"profclaw-bot","password":"your-password"}'
    # Copy the access_token from the response
    ```
  </Step>

  <Step title="Get your User ID">
    User ID format: `@profclaw-bot:matrix.org`
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    MATRIX_HOMESERVER_URL=https://matrix.org
    MATRIX_ACCESS_TOKEN=syt_...
    MATRIX_USER_ID=@profclaw-bot:matrix.org
    ```
  </Step>

  <Step title="Invite the bot to rooms">
    In Element or any Matrix client, invite `@profclaw-bot:matrix.org` to your room.
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Matrix homeserver URL (e.g., `https://matrix.org` or `https://your-homeserver.com`).
</ParamField>

<ParamField type="string">
  Bot user access token. Format: `syt_...`
</ParamField>

<ParamField type="string">
  Bot user ID. Format: `@username:homeserver.com`
</ParamField>

<ParamField type="string">
  Device ID for E2EE sessions. Auto-generated if not set.
</ParamField>

<ParamField type="boolean">
  Enable end-to-end encryption. Defaults to `false`. Requires additional setup.
</ParamField>

<ParamField type="string">
  Comma-separated list of room IDs the bot will respond in. Leave empty to allow all rooms.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    MATRIX_HOMESERVER_URL=https://matrix.org
    MATRIX_ACCESS_TOKEN=syt_cHJvZmNsYXc_...
    MATRIX_USER_ID=@profclaw:matrix.org
    # Optional: restrict to specific rooms
    MATRIX_ALLOWED_ROOM_IDS=!roomid1:matrix.org,!roomid2:matrix.org
    ```
  </Tab>

  <Tab title="Self-hosted homeserver">
    ```bash theme={null}
    MATRIX_HOMESERVER_URL=https://matrix.yourdomain.com
    MATRIX_ACCESS_TOKEN=syt_...
    MATRIX_USER_ID=@profclaw:yourdomain.com
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      matrix:
        homeserver_url: "${MATRIX_HOMESERVER_URL}"
        access_token: "${MATRIX_ACCESS_TOKEN}"
        user_id: "${MATRIX_USER_ID}"
        enable_encryption: false
    ```
  </Tab>
</Tabs>

## Notes

* Matrix uses long-polling (`/sync`) by default - no public webhook URL required.
* E2EE requires the bot's device to exchange keys with room members. Enable only if needed.
* The bot joins rooms automatically when invited.
* For Synapse homeservers, you can register the bot with admin-level access using the registration token.
* Works with any Matrix client: Element, FluffyChat, Nheko, etc.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Rocket.Chat](/chat-providers/rocket-chat) - Another self-hosted open-source messaging option
* [Signal](/chat-providers/signal) - End-to-end encrypted messaging via signald bridge
* [profclaw channels](/cli/channels) - Enable and test the Matrix connection from the CLI


# Facebook Messenger
Source: https://docs.profclaw.ai/chat-providers/messenger

Connect profClaw to Facebook Messenger via the Meta Messenger Platform. Requires a Facebook Page.

profClaw integrates with Facebook Messenger through the Meta Messenger Platform. The bot is attached to a Facebook Page and responds to messages sent to that page.

## Capabilities

| Feature           | Supported |
| ----------------- | --------- |
| 1:1 messaging     | Yes       |
| Quick replies     | Yes       |
| Persistent menu   | Yes       |
| Generic templates | Yes       |
| Media messages    | Yes       |
| Webhook           | Yes       |
| Page subscription | Yes       |

## Setup

<Steps>
  <Step title="Create a Facebook App">
    Go to [developers.facebook.com](https://developers.facebook.com) and create a new app. Choose **Business** type.
  </Step>

  <Step title="Add Messenger Product">
    Under your app, add the **Messenger** product.
  </Step>

  <Step title="Link to a Facebook Page">
    Under **Messenger > Settings**, generate a **Page Access Token** for your Facebook Page.
  </Step>

  <Step title="Configure webhook">
    Set webhook URL to: `https://your-domain.com/webhooks/messenger`

    Set a verify token (any string you choose) and subscribe to `messages` and `messaging_postbacks`.
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    MESSENGER_PAGE_ACCESS_TOKEN=EAABwzLixnjYBO...
    MESSENGER_VERIFY_TOKEN=my-verify-token
    MESSENGER_APP_SECRET=your-app-secret
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Facebook Page access token (from Meta Developer portal).
</ParamField>

<ParamField type="string">
  Your custom verify token for webhook setup.
</ParamField>

<ParamField type="string">
  App secret for request signature verification.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    MESSENGER_PAGE_ACCESS_TOKEN=EAABwzLixnjYBO...
    MESSENGER_VERIFY_TOKEN=my-verify-token
    MESSENGER_APP_SECRET=abc123def456
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      messenger:
        page_access_token: "${MESSENGER_PAGE_ACCESS_TOKEN}"
        verify_token: "${MESSENGER_VERIFY_TOKEN}"
        app_secret: "${MESSENGER_APP_SECRET}"
    ```
  </Tab>
</Tabs>

## Message Templates

profClaw can send rich templates:

```json theme={null}
{
  "recipient": { "id": "user-psid" },
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "button",
        "text": "What would you like to do?",
        "buttons": [
          { "type": "postback", "title": "Get Status", "payload": "STATUS" }
        ]
      }
    }
  }
}
```

## Notes

* Status: Beta
* Requires a public HTTPS webhook URL.
* Messenger Platform requires App Review for production use with more than 5 testers.
* After App Review, the bot can message any Facebook user who messages the page.
* GDPR compliance: Users can opt-out via the standard Messenger controls.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [WhatsApp](/chat-providers/whatsapp) - Meta's other messaging platform for business
* [Viber](/chat-providers/viber) - Similar audience in Eastern Europe and Southeast Asia
* [profclaw channels](/cli/channels) - Enable and test the Messenger connection from the CLI


# Microsoft Teams
Source: https://docs.profclaw.ai/chat-providers/microsoft-teams

Deploy profClaw as a Microsoft Teams bot. Supports Adaptive Cards, Bot Framework, and Azure AD auth.

profClaw integrates with Microsoft Teams via the Bot Framework. It responds to messages, mentions, and commands in chats and channels.

## Capabilities

| Feature          | Supported |
| ---------------- | --------- |
| 1:1 chat         | Yes       |
| Channel messages | Yes       |
| Adaptive Cards   | Yes       |
| Slash commands   | Yes       |
| File uploads     | Yes       |
| Teams meetings   | No        |
| OAuth install    | Yes       |
| Multi-tenant     | Yes       |

## Setup

<Steps>
  <Step title="Register an Azure Bot">
    Go to [portal.azure.com](https://portal.azure.com) and create an **Azure Bot** resource.

    * Set the messaging endpoint to: `https://your-domain.com/webhooks/teams`
    * Choose **Multi-tenant** for use across multiple organizations
  </Step>

  <Step title="Get Bot credentials">
    Under **Configuration**, copy the **Microsoft App ID** and **Password** (client secret).
  </Step>

  <Step title="Create a Teams App">
    Use [Teams Developer Portal](https://dev.teams.microsoft.com) or App Studio to create a Teams app manifest:

    ```json theme={null}
    {
      "bots": [{
        "botId": "your-microsoft-app-id",
        "scopes": ["team", "personal", "groupchat"]
      }]
    }
    ```
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    TEAMS_APP_ID=your-microsoft-app-id
    TEAMS_APP_PASSWORD=your-client-secret
    TEAMS_TENANT_ID=your-tenant-id
    ```
  </Step>

  <Step title="Deploy the app">
    Upload the app package to Teams Admin Center or install via sideloading.
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Microsoft App ID (Bot Framework Application ID).
</ParamField>

<ParamField type="string">
  Microsoft App Password (client secret).
</ParamField>

<ParamField type="string">
  Azure AD Tenant ID. Use `common` for multi-tenant apps.
</ParamField>

<ParamField type="string">
  Comma-separated Team IDs to restrict access.
</ParamField>

<ParamField type="string">
  Comma-separated Channel IDs to restrict access.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    TEAMS_APP_ID=00000000-0000-0000-0000-000000000000
    TEAMS_APP_PASSWORD=your-client-secret
    TEAMS_TENANT_ID=common
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      msteams:
        app_id: "${TEAMS_APP_ID}"
        app_password: "${TEAMS_APP_PASSWORD}"
        tenant_id: "${TEAMS_TENANT_ID}"
    ```
  </Tab>
</Tabs>

## Adaptive Cards

profClaw sends Adaptive Cards for rich interactive responses:

```json theme={null}
{
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    { "type": "TextBlock", "text": "Task completed", "weight": "Bolder" }
  ],
  "actions": [
    { "type": "Action.Submit", "title": "Acknowledge", "data": { "action": "ack" } }
  ]
}
```

## Notes

* Requires a public HTTPS webhook URL - no socket/polling mode available.
* Bot Framework handles authentication with Microsoft's OAuth.
* `TEAMS_TENANT_ID=common` allows the bot to work across any Microsoft 365 organization.
* Single-tenant mode: set `TEAMS_TENANT_ID` to your organization's tenant ID.
* The bot must be in the same Teams app as the channel for it to respond.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Slack](/chat-providers/slack) - Slack is the recommended alternative for teams not on Microsoft 365
* [profclaw tunnel](/cli/tunnel) - Expose your local server for development webhook testing
* [profclaw channels](/cli/channels) - Enable and test the Teams connection from the CLI


# Chat Providers Overview
Source: https://docs.profclaw.ai/chat-providers/overview

Connect your AI agent to 27 chat channels. Covers Slack, Discord, Telegram, WhatsApp, Teams, Matrix, and more - with multi-account support and webhook setup.

profClaw's chat provider system provides a unified abstraction across all messaging platforms. One agent, every channel.

## Supported Channels

| Provider                                           | Type          | Status       | Key Capability                         |
| -------------------------------------------------- | ------------- | ------------ | -------------------------------------- |
| [WebChat](/chat-providers/webchat)                 | Built-in      | Stable       | Zero-setup browser widget              |
| [Slack](/chat-providers/slack)                     | Work          | Stable       | Socket Mode, Block Kit, slash commands |
| [Discord](/chat-providers/discord)                 | Community     | Stable       | Slash commands, components             |
| [Telegram](/chat-providers/telegram)               | Messaging     | Stable       | Webhooks, inline buttons               |
| [WhatsApp](/chat-providers/whatsapp)               | Messaging     | Stable       | WhatsApp Business API                  |
| [Matrix](/chat-providers/matrix)                   | Open Protocol | Stable       | E2EE, federated                        |
| [Microsoft Teams](/chat-providers/microsoft-teams) | Work          | Stable       | Adaptive Cards, Bot Framework          |
| [Rocket.Chat](/chat-providers/rocket-chat)         | Self-hosted   | Beta         | Open-source Slack alternative          |
| [IRC](/chat-providers/irc)                         | Legacy        | Beta         | Classic IRC protocol                   |
| [Signal](/chat-providers/signal)                   | Secure        | Beta         | E2EE, signald bridge                   |
| [LINE](/chat-providers/line)                       | Asia          | Beta         | LINE Messaging API                     |
| [Zalo](/chat-providers/zalo)                       | Vietnam       | Beta         | Zalo OA API                            |
| [Viber](/chat-providers/viber)                     | Messaging     | Beta         | Viber Bot API                          |
| [Facebook Messenger](/chat-providers/messenger)    | Social        | Beta         | Meta Messenger Platform                |
| [WeChat](/chat-providers/wechat)                   | China         | Beta         | WeChat Official Account                |
| [Tlon/Urbit](/chat-providers/tlon)                 | Decentralized | Experimental | Urbit network                          |
| [Custom](/chat-providers/custom)                   | DIY           | Stable       | Build your own provider                |
| Google Chat                                        | Work          | Beta         | Google Workspace                       |
| Mattermost                                         | Self-hosted   | Beta         | Open-source Teams alternative          |
| DingTalk                                           | China         | Beta         | Alibaba DingTalk                       |
| WeCom                                              | China         | Beta         | Tencent WeCom                          |
| Feishu/Lark                                        | Work          | Beta         | ByteDance enterprise                   |
| QQ                                                 | Social        | Beta         | Tencent QQ                             |
| Nostr                                              | Decentralized | Experimental | Nostr protocol                         |
| Twitch                                             | Streaming     | Beta         | Twitch chat integration                |
| Nextcloud Talk                                     | Self-hosted   | Beta         | Nextcloud messaging                    |
| Synology Chat                                      | Self-hosted   | Beta         | Synology NAS chat                      |

<Note>
  WebChat is enabled by default with no credentials required. It is always available at `http://localhost:3000`. All other providers require credential setup.
</Note>

## Capabilities Comparison

| Feature         | WebChat | Slack | Discord | Telegram | WhatsApp | Teams |
| --------------- | ------- | ----- | ------- | -------- | -------- | ----- |
| Direct Messages | Yes     | Yes   | Yes     | Yes      | Yes      | Yes   |
| Group/Channel   | No      | Yes   | Yes     | Yes      | No       | Yes   |
| Slash Commands  | No      | Yes   | Yes     | No       | No       | Yes   |
| Buttons/Menus   | No      | Yes   | Yes     | Yes      | Limited  | Yes   |
| File Uploads    | No      | Yes   | Yes     | Yes      | Yes      | Yes   |
| Reactions       | No      | Yes   | Yes     | No       | No       | No    |
| Threads         | No      | Yes   | Yes     | No       | No       | Yes   |
| Rich Blocks     | No      | Yes   | No      | No       | No       | Yes   |
| E2E Encryption  | No      | No    | No      | No       | Yes      | No    |
| OAuth Install   | No      | Yes   | Yes     | No       | No       | Yes   |

## Multi-Account Support

profClaw supports multiple accounts per provider. Each account is independently configured and can be assigned to different channels or teams:

```yaml theme={null}
# settings.yml
chat:
  slack:
    accounts:
      - id: work
        bot_token: xoxb-work-...
        is_default: true
      - id: community
        bot_token: xoxb-community-...
```

## Architecture

All providers implement the same interface, allowing the execution engine and security layer to treat all channels uniformly:

* **Inbound**: Receive messages via webhooks or long-polling
* **Outbound**: Send messages and structured responses
* **Status**: Health checks and connection monitoring
* **Auth**: OAuth flows or manual token configuration

```
User Message
    |
    v
[Chat Provider]  ----incoming----> [Message Handler]
                                         |
                                    [AI Executor]
                                    [Tool Pipeline]
                                         |
[Chat Provider]  <---outbound-----  [Response]
```

## Webhook Setup

Most providers require a public HTTPS webhook URL to deliver events. Use `profclaw serve` to start the server, then expose it with a tunnel during development or configure your domain for production.

<Tabs>
  <Tab title="Development (tunnel)">
    Use a tunnel tool to expose your local server:

    ```bash theme={null}
    # Using cloudflared (recommended, free, no account needed for quick tunnels)
    brew install cloudflared
    cloudflared tunnel --url http://localhost:3000

    # Or using ngrok
    ngrok http 3000
    ```

    Use the generated HTTPS URL as your webhook base URL in the provider's developer portal.
  </Tab>

  <Tab title="Production">
    Set your domain as the webhook base URL:

    ```bash theme={null}
    WEBHOOK_BASE_URL=https://profclaw.yourdomain.com
    ```

    profClaw appends provider-specific paths automatically. For example, the Slack webhook becomes:
    `https://profclaw.yourdomain.com/api/webhooks/slack`
  </Tab>
</Tabs>

<Warning>
  All webhook endpoints validate request signatures from the provider. Never disable signature verification in production.
</Warning>

## Configuration Pattern

All providers follow the same environment variable pattern - enable a provider by setting its credentials:

```bash theme={null}
# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...

# Discord
DISCORD_BOT_TOKEN=...

# Telegram
TELEGRAM_BOT_TOKEN=...
```

Providers with no credentials set are simply not loaded. There is no need to explicitly disable them.

## Security Considerations

Chat providers inherit the global [security mode](/security/overview). Restrict which channels or users the agent responds to:

```yaml theme={null}
chat:
  channels:
    slack:
      allowedChannels:
        - C0123456789  # #engineering
        - C9876543210  # #devops
      allowedUsers:
        - U012345678   # Specific user IDs only
```

## Health Check

```bash theme={null}
profclaw doctor --chat
```

Shows connection status for all configured chat providers, including last event received and any authentication errors.

## Popular Guides

<CardGroup>
  <Card title="Slack Bot Setup" icon="slack" href="/guides/slack-bot">
    Step-by-step guide to creating a Slack app and connecting profClaw.
  </Card>

  <Card title="WhatsApp Bot" icon="whatsapp" href="/guides/whatsapp-bot">
    Connect profClaw to WhatsApp Business API.
  </Card>

  <Card title="Self-Hosted Deployment" icon="server" href="/guides/self-hosted">
    Configure public webhooks for production deployments.
  </Card>

  <Card title="Custom Provider" icon="wrench" href="/chat-providers/custom">
    Implement your own chat provider using the provider SDK.
  </Card>
</CardGroup>

## Related

* [profclaw channels](/cli/channels) - Enable, disable, and test chat providers from the CLI
* [Security Overview](/security/overview) - Restrict which channels and users the agent responds to
* [profclaw tunnel](/cli/tunnel) - Expose your local server for webhook delivery
* [Configuration Overview](/configuration/overview) - settings.yml reference for channel configuration


# Rocket.Chat
Source: https://docs.profclaw.ai/chat-providers/rocket-chat

Connect profClaw to your self-hosted Rocket.Chat instance. Supports slash commands, channels, and direct messages.

Rocket.Chat is an open-source Slack alternative. profClaw connects via Rocket.Chat's bot API to respond in channels, DMs, and via slash commands.

## Capabilities

| Feature         | Supported |
| --------------- | --------- |
| Direct messages | Yes       |
| Channels        | Yes       |
| Threads         | Yes       |
| Slash commands  | Yes       |
| File uploads    | Yes       |
| Reactions       | Yes       |
| Webhooks        | Yes       |
| REST API        | Yes       |

## Setup

<Steps>
  <Step title="Create a bot user">
    In Rocket.Chat Admin: **Administration > Users > New User**

    * Set role to **bot**
    * Generate a random password
    * Enable the account
  </Step>

  <Step title="Get credentials">
    Log in as the bot user via REST API:

    ```bash theme={null}
    curl -X POST https://your-rocketchat.com/api/v1/login \
      -d "user=profclaw-bot&password=your-password"
    # Copy authToken and userId
    ```
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    ROCKETCHAT_URL=https://your-rocketchat.com
    ROCKETCHAT_BOT_TOKEN=your-auth-token
    ROCKETCHAT_BOT_USER_ID=your-user-id
    ```
  </Step>

  <Step title="Configure webhook (optional)">
    For incoming webhooks, go to **Administration > Integrations > New Integration > Incoming WebHook**.
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Your Rocket.Chat server URL (e.g., `https://chat.yourdomain.com`).
</ParamField>

<ParamField type="string">
  Bot user auth token from REST API login.
</ParamField>

<ParamField type="string">
  Bot user ID from REST API login.
</ParamField>

<ParamField type="string">
  Incoming webhook URL for outbound messages.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    ROCKETCHAT_URL=https://chat.example.com
    ROCKETCHAT_BOT_TOKEN=authToken123
    ROCKETCHAT_BOT_USER_ID=userId456
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      rocketchat:
        url: "${ROCKETCHAT_URL}"
        bot_token: "${ROCKETCHAT_BOT_TOKEN}"
        bot_user_id: "${ROCKETCHAT_BOT_USER_ID}"
    ```
  </Tab>
</Tabs>

## Notes

* Status: Beta
* Rocket.Chat uses real-time API (WebSocket) for message events.
* Slash commands require a Rocket.Chat admin to register them under **Administration > Integrations**.
* Self-hosted Rocket.Chat requires no external dependencies for profClaw to connect.
* Compatible with Rocket.Chat Community Edition (open-source) and Enterprise.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Slack](/chat-providers/slack) - Slack is the cloud-hosted alternative to Rocket.Chat
* [Matrix](/chat-providers/matrix) - Another open-source self-hosted messaging option
* [Self-Hosted Guide](/guides/self-hosted) - Deploy profClaw alongside self-hosted chat tools


# Signal
Source: https://docs.profclaw.ai/chat-providers/signal

Connect profClaw to Signal via the signald bridge. End-to-end encrypted messaging for maximum privacy.

profClaw connects to Signal via [signald](https://signald.org), an unofficial Signal daemon that exposes a local UNIX socket API. All messages are end-to-end encrypted by Signal's protocol.

## Capabilities

| Feature                | Supported             |
| ---------------------- | --------------------- |
| Direct messages        | Yes                   |
| Group messages         | Yes                   |
| End-to-end encryption  | Yes (Signal protocol) |
| Media messages         | Yes                   |
| Voice/video calls      | No                    |
| Phone number allowlist | Yes                   |

## Requirements

* A dedicated phone number for the bot
* [signald](https://signald.org) running on the same machine as profClaw

## Setup

<Steps>
  <Step title="Install signald">
    ```bash theme={null}
    # Ubuntu/Debian
    apt install signald

    # Or run via Docker
    docker run -v /var/run/signald:/var/run/signald signald/signald
    ```
  </Step>

  <Step title="Register a phone number">
    ```bash theme={null}
    signaldctl account register +1234567890
    # Receive SMS verification code
    signaldctl account verify +1234567890 CODE
    ```
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    SIGNAL_SOCKET_PATH=/var/run/signald/signald.sock
    SIGNAL_PHONE_NUMBER=+1234567890
    # Optional: restrict to specific numbers
    SIGNAL_ALLOWED_NUMBERS=+0987654321,+1122334455
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider signal
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Path to the signald UNIX socket. Default: `/var/run/signald/signald.sock`
</ParamField>

<ParamField type="string">
  Bot phone number in E.164 format (e.g., `+12125551234`).
</ParamField>

<ParamField type="string">
  Comma-separated allowlist of phone numbers that can interact with the bot.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    SIGNAL_SOCKET_PATH=/var/run/signald/signald.sock
    SIGNAL_PHONE_NUMBER=+12125551234
    SIGNAL_ALLOWED_NUMBERS=+19876543210
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      signal:
        socket_path: "${SIGNAL_SOCKET_PATH}"
        phone_number: "${SIGNAL_PHONE_NUMBER}"
        allowed_numbers:
          - "+19876543210"
    ```
  </Tab>

  <Tab title="Docker Compose">
    ```yaml theme={null}
    services:
      profclaw:
        image: profclaw/profclaw:latest
        volumes:
          - signald_socket:/var/run/signald
        environment:
          SIGNAL_SOCKET_PATH: /var/run/signald/signald.sock
          SIGNAL_PHONE_NUMBER: "+12125551234"
      signald:
        image: signald/signald:latest
        volumes:
          - signald_socket:/var/run/signald
          - signald_data:/signald
    volumes:
      signald_socket:
      signald_data:
    ```
  </Tab>
</Tabs>

## Notes

* Status: Beta
* signald is an unofficial Signal client - it may break when Signal updates its protocol.
* The `SIGNAL_ALLOWED_NUMBERS` allowlist is strongly recommended for security.
* Signal requires a real phone number capable of receiving SMS.
* signald stores Signal keys locally - keep `signald_data` secure.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Matrix](/chat-providers/matrix) - Federated E2EE messaging with official protocol support
* [Telegram](/chat-providers/telegram) - Simpler bot setup without the signald dependency
* [Security Overview](/security/overview) - Protecting your profClaw deployment


# Slack
Source: https://docs.profclaw.ai/chat-providers/slack

Deploy profClaw as a Slack bot. Supports Socket Mode for zero-port-forwarding setup, Block Kit messages, and slash commands.

profClaw's Slack integration supports both Socket Mode (recommended, no public URL needed) and HTTP webhook mode. It handles slash commands, direct messages, app mentions, and interactive components.

## Capabilities

| Feature                   | Supported        |
| ------------------------- | ---------------- |
| Direct messages           | Yes              |
| Channel messages          | Yes (on mention) |
| Slash commands            | Yes              |
| Block Kit messages        | Yes              |
| Interactive buttons/menus | Yes              |
| Message reactions         | Yes              |
| Message threads           | Yes              |
| File sharing              | Yes              |
| Socket Mode               | Yes              |
| OAuth app installation    | Yes              |

## Setup

<Tabs>
  <Tab title="Socket Mode (Recommended)">
    <Steps>
      <Step title="Create a Slack App">
        Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app from scratch.
      </Step>

      <Step title="Enable Socket Mode">
        Under **Settings > Socket Mode**, enable Socket Mode and generate an App-Level Token with `connections:write` scope.
      </Step>

      <Step title="Add Bot Token Scopes">
        Under **OAuth & Permissions > Bot Token Scopes**, add:

        * `app_mentions:read`
        * `chat:write`
        * `commands`
        * `im:history`
        * `im:read`
        * `im:write`
        * `reactions:write`
      </Step>

      <Step title="Enable Events">
        Under **Event Subscriptions**, enable and subscribe to:

        * `app_mention`
        * `message.im`
      </Step>

      <Step title="Install and configure">
        Install the app to your workspace, then set:

        ```bash theme={null}
        SLACK_BOT_TOKEN=xoxb-...
        SLACK_APP_TOKEN=xapp-...
        SLACK_MODE=socket
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="HTTP Mode">
    <Steps>
      <Step title="Create a Slack App">
        Create a new Slack app at [api.slack.com/apps](https://api.slack.com/apps).
      </Step>

      <Step title="Set Request URLs">
        Under **Event Subscriptions**, set the Request URL to:
        `https://your-domain.com/webhooks/slack/events`
      </Step>

      <Step title="Configure">
        ```bash theme={null}
        SLACK_BOT_TOKEN=xoxb-...
        SLACK_SIGNING_SECRET=...
        SLACK_MODE=http
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Environment Variables

<ParamField type="string">
  Bot OAuth token. Format: `xoxb-...`
</ParamField>

<ParamField type="string">
  App-level token for Socket Mode. Format: `xapp-...` Required when `SLACK_MODE=socket`.
</ParamField>

<ParamField type="string">
  Signing secret for webhook verification. Required when `SLACK_MODE=http`.
</ParamField>

<ParamField type="string">
  Connection mode: `socket` or `http`. Defaults to `http`.
</ParamField>

<ParamField type="string">
  Incoming webhook URL for simple outbound messages (optional).
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env (Socket Mode)">
    ```bash theme={null}
    SLACK_BOT_TOKEN=xoxb-1234567890-...
    SLACK_APP_TOKEN=xapp-1-...
    SLACK_MODE=socket
    ```
  </Tab>

  <Tab title=".env (HTTP Mode)">
    ```bash theme={null}
    SLACK_BOT_TOKEN=xoxb-1234567890-...
    SLACK_SIGNING_SECRET=abc123...
    SLACK_MODE=http
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      slack:
        mode: socket
        bot_token: "${SLACK_BOT_TOKEN}"
        app_token: "${SLACK_APP_TOKEN}"
    ```
  </Tab>
</Tabs>

## Slash Commands

Register slash commands in your Slack app and profClaw will handle them:

```
/ask [question]        - Ask the AI a question
/run [skill] [args]    - Run a profClaw skill
/status                - Check agent status
```

Custom slash commands can be registered via the CLI:

```bash theme={null}
profclaw slack commands add /deploy "Deploy to production" "run deploy"
```

## Block Kit Messages

profClaw sends structured Block Kit messages for rich responses:

```json theme={null}
{
  "blocks": [
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "Here's what I found:" }
    },
    {
      "type": "actions",
      "elements": [
        { "type": "button", "text": { "type": "plain_text", "text": "Approve" }, "action_id": "approve" }
      ]
    }
  ]
}
```

## Notes

* Socket Mode is strongly recommended for development and behind-firewall deployments.
* In Socket Mode, profClaw connects outbound to Slack's servers - no inbound ports needed.
* The bot responds to `@mention` in channels and to all DMs by default.
* Multiple Slack workspaces are supported via multi-account configuration.

## Related

* [Slack Bot Setup Guide](/guides/slack-bot) - Step-by-step walkthrough with screenshots
* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Notifications Tool](/tools/notifications) - Send proactive messages to Slack channels from agents
* [profclaw channels](/cli/channels) - Enable and test the Slack connection from the CLI


# Telegram
Source: https://docs.profclaw.ai/chat-providers/telegram

Deploy profClaw as a Telegram bot. Supports webhook and long-polling modes, inline keyboards, and group chats.

profClaw's Telegram integration creates a bot that responds to messages in private chats, groups, and supergroups. Supports both webhook and long-polling connection modes.

## Capabilities

| Feature             | Supported        |
| ------------------- | ---------------- |
| Private chats       | Yes              |
| Group chats         | Yes              |
| Supergroups         | Yes              |
| Inline keyboards    | Yes              |
| File/media messages | Yes              |
| Commands            | Yes (`/command`) |
| Webhook mode        | Yes              |
| Long-polling mode   | Yes              |

## Setup

<Steps>
  <Step title="Create a bot with BotFather">
    Open Telegram and message [@BotFather](https://t.me/BotFather):

    ```
    /newbot
    # Follow prompts to set name and username
    # BotFather gives you a token: 1234567890:ABCdef...
    ```
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    TELEGRAM_BOT_TOKEN=1234567890:ABCdef...
    ```
  </Step>

  <Step title="Set webhook (optional)">
    For webhook mode, also set:

    ```bash theme={null}
    TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhooks/telegram
    TELEGRAM_WEBHOOK_SECRET=your-random-secret
    ```

    If no webhook URL is set, profClaw uses long-polling automatically.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    profclaw doctor --provider telegram
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Bot token from BotFather. Format: `1234567890:ABCdef...`
</ParamField>

<ParamField type="string">
  Public webhook URL. If not set, long-polling is used instead.
</ParamField>

<ParamField type="string">
  Secret token for webhook verification. Recommended for webhook mode.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env (long-polling)">
    ```bash theme={null}
    TELEGRAM_BOT_TOKEN=1234567890:ABCdef...
    # No webhook URL = auto long-polling
    ```
  </Tab>

  <Tab title=".env (webhook)">
    ```bash theme={null}
    TELEGRAM_BOT_TOKEN=1234567890:ABCdef...
    TELEGRAM_WEBHOOK_URL=https://profclaw.example.com/webhooks/telegram
    TELEGRAM_WEBHOOK_SECRET=my-secret-token
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      telegram:
        bot_token: "${TELEGRAM_BOT_TOKEN}"
        webhook_url: "${TELEGRAM_WEBHOOK_URL}"
        webhook_secret: "${TELEGRAM_WEBHOOK_SECRET}"
    ```
  </Tab>
</Tabs>

## Bot Commands

Set up commands in BotFather for better UX:

```
/ask - Ask a question
/run - Run a skill
/status - Check status
/help - Show help
```

## Usage in Groups

Add the bot to a group and it responds when:

* Directly mentioned: `@your_bot_name What is...`
* Bot commands used: `/ask What is...`

For private groups, ensure the bot has message read permissions.

## Notes

* Long-polling is simpler for development and doesn't require a public URL.
* Webhook mode is recommended for production - lower latency and no missed messages.
* Telegram's Bot API supports MarkdownV2 formatting for rich responses.
* Group bots require explicit permission to read all messages (or use commands only).

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [WhatsApp](/chat-providers/whatsapp) - Business messaging via Meta's Cloud API
* [Signal](/chat-providers/signal) - End-to-end encrypted messaging alternative
* [profclaw channels](/cli/channels) - Enable and test the Telegram connection from the CLI


# Tlon / Urbit
Source: https://docs.profclaw.ai/chat-providers/tlon

Connect profClaw to the Urbit network via Tlon. Experimental support for decentralized, peer-to-peer messaging.

profClaw includes experimental support for the Urbit network via Tlon. Urbit is a decentralized OS and network where each user controls their own server (a ship). Tlon is the primary messaging client for Urbit.

## Overview

Urbit messaging works differently from traditional chat platforms:

* Each user runs their own "ship" (server node)
* Identity is based on cryptographic keys, not accounts
* Messages are peer-to-peer
* No central server or account required

## Capabilities

| Feature                | Supported            |
| ---------------------- | -------------------- |
| Direct messages (DMs)  | Yes                  |
| Group chats (Channels) | Yes                  |
| Encrypted transit      | Yes (Urbit built-in) |
| Long-form posts        | Yes                  |
| Notebooks              | No                   |
| Collections            | No                   |

## Requirements

* A running Urbit ship (comet, planet, or star)
* Urbit HTTP API accessible
* Tlon installed on the ship

## Setup

<Steps>
  <Step title="Set up an Urbit ship">
    Follow [urbit.org/getting-started](https://urbit.org/getting-started) to boot a ship. A comet (free, temporary identity) works for testing.

    ```bash theme={null}
    # Boot a comet
    urbit -c mycomet
    ```
  </Step>

  <Step title="Get your ship's URL and code">
    Once running, note your ship's HTTP port (usually 8080) and access code:

    ```
    # In the Urbit dojo:
    +code
    ```
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    TLON_SHIP_URL=http://localhost:8080
    TLON_ACCESS_CODE=sampel-palnet-sampel-palnet
    TLON_SHIP_NAME=~sampel-palnet
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  HTTP URL of your Urbit ship (e.g., `http://localhost:8080`).
</ParamField>

<ParamField type="string">
  Ship access code from `+code` in the dojo.
</ParamField>

<ParamField type="string">
  Your ship's Urbit name (e.g., `~sampel-palnet`).
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    TLON_SHIP_URL=http://localhost:8080
    TLON_ACCESS_CODE=sampel-palnet-sampel-palnet
    TLON_SHIP_NAME=~sampel-palnet
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      tlon:
        ship_url: "${TLON_SHIP_URL}"
        access_code: "${TLON_ACCESS_CODE}"
        ship_name: "${TLON_SHIP_NAME}"
    ```
  </Tab>
</Tabs>

## Notes

* Status: Experimental
* Urbit/Tlon has a small but dedicated community. Best for privacy-focused deployments.
* Ship names come in the form `~sampel-palnet` (planets) or `~sampel-palnet-sampel-palnet` (comets).
* Comets are free to boot but are anonymous. Planets are NFT-style identities.
* The Tlon provider uses Urbit's Eyre HTTP API for subscription-based message delivery.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Matrix](/chat-providers/matrix) - Another decentralized federated messaging protocol
* [Signal](/chat-providers/signal) - End-to-end encrypted private messaging
* [Custom Chat Providers](/chat-providers/custom) - Build your own provider integration


# Viber
Source: https://docs.profclaw.ai/chat-providers/viber

Connect profClaw to Viber via the Viber Bot API. Popular in Eastern Europe and Southeast Asia.

Viber is a messaging app with strong presence in Eastern Europe, the Middle East, and Southeast Asia. profClaw connects via Viber's Bot API for business interactions.

## Capabilities

| Feature          | Supported |
| ---------------- | --------- |
| 1:1 messages     | Yes       |
| Group messages   | Yes       |
| Rich media       | Yes       |
| Keyboard buttons | Yes       |
| File attachments | Yes       |
| Webhook          | Yes       |

## Setup

<Steps>
  <Step title="Create a Viber Bot">
    Go to [partners.viber.com](https://partners.viber.com) and create a bot account.
    You'll receive an **Authentication Token**.
  </Step>

  <Step title="Set webhook">
    Viber requires a webhook to receive messages. Set it via the API:

    ```bash theme={null}
    curl -X POST https://chatapi.viber.com/pa/set_webhook \
      -H "X-Viber-Auth-Token: your-token" \
      -d '{"url": "https://your-domain.com/webhooks/viber"}'
    ```
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    VIBER_AUTH_TOKEN=your-authentication-token
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Viber Bot authentication token from partners.viber.com.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    VIBER_AUTH_TOKEN=4a8e6b5c-...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      viber:
        auth_token: "${VIBER_AUTH_TOKEN}"
    ```
  </Tab>
</Tabs>

## Message Format

profClaw sends Viber text messages with optional keyboard buttons:

```json theme={null}
{
  "receiver": "user-id",
  "type": "text",
  "text": "How can I help you?",
  "keyboard": {
    "Type": "keyboard",
    "Buttons": [
      { "ActionType": "reply", "ActionBody": "help", "Text": "Help" }
    ]
  }
}
```

## Notes

* Status: Beta
* Viber requires a public HTTPS webhook URL.
* The webhook must be set programmatically via the API (not a dashboard).
* Viber bots can only message users who have subscribed or messaged the bot first.
* Message broadcasting requires Viber partner approval for large audiences.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [LINE](/chat-providers/line) - Dominant messaging platform in Japan and Taiwan
* [Messenger](/chat-providers/messenger) - Facebook Messenger for Western audiences
* [profclaw channels](/cli/channels) - Enable and test the Viber connection from the CLI


# WebChat
Source: https://docs.profclaw.ai/chat-providers/webchat

Built-in browser chat widget. Zero setup - access profClaw from any browser via Server-Sent Events. Available instantly after install.

WebChat is profClaw's built-in browser interface. It requires no third-party accounts or webhooks - just start profClaw and open a browser.

## Overview

WebChat uses Server-Sent Events (SSE) for real-time streaming responses. Sessions are managed server-side with configurable timeouts.

* Streaming responses in real time
* Anonymous access optional
* Rate limiting per IP
* Session-based (30 min timeout by default)
* No JavaScript framework dependency

## Setup

WebChat is enabled automatically when profClaw starts. No configuration required.

```bash theme={null}
profclaw serve
# Open http://localhost:3000 in your browser
```

## Environment Variables

<ParamField type="boolean">
  Allow unauthenticated sessions. Defaults to `false`. Set to `true` for open access.
</ParamField>

<ParamField type="number">
  Maximum concurrent sessions per IP address. Defaults to `5`.
</ParamField>

<ParamField type="number">
  Session expiry in milliseconds. Defaults to `1800000` (30 minutes).
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    WEBCHAT_ALLOW_ANONYMOUS=false
    WEBCHAT_MAX_SESSIONS_PER_IP=5
    WEBCHAT_SESSION_TIMEOUT_MS=1800000
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      webchat:
        allow_anonymous: false
        max_sessions_per_ip: 5
        session_timeout_ms: 1800000
    ```
  </Tab>
</Tabs>

## Embedding the Widget

You can embed the WebChat widget in your own web application:

```html theme={null}
<!-- Add to your HTML -->
<script src="https://profclaw.yourdomain.com/widget.js"></script>
<profclaw-chat
  server="https://profclaw.yourdomain.com"
  title="AI Assistant"
  theme="dark"
></profclaw-chat>
```

## API Endpoints

WebChat exposes these HTTP endpoints:

| Endpoint                     | Method | Description              |
| ---------------------------- | ------ | ------------------------ |
| `/chat/sessions`             | POST   | Create a new session     |
| `/chat/sessions/:id/stream`  | GET    | SSE stream for a session |
| `/chat/sessions/:id/message` | POST   | Send a message           |
| `/chat/sessions/:id`         | DELETE | End a session            |

## Capabilities

| Feature             | Supported    |
| ------------------- | ------------ |
| Direct messages     | Yes          |
| Streaming responses | Yes          |
| Anonymous access    | Configurable |
| File upload         | No           |
| Slash commands      | No           |
| Rate limiting       | Yes (per IP) |
| Session management  | Yes          |

## Notes

* WebChat sessions auto-expire after inactivity to free server resources.
* Sessions run cleanup every 5 minutes.
* The SSE stream format is compatible with standard `EventSource` API.
* WebChat is always available on port `3000` (configurable via `PORT`).

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Chat API](/api-reference/chat) - Build a custom UI using the REST API and SSE streaming
* [Getting Started](/getting-started/first-run) - Access WebChat on your first run
* [profclaw serve](/cli/serve) - Start the server that powers WebChat


# WeChat
Source: https://docs.profclaw.ai/chat-providers/wechat

Connect profClaw to WeChat via the WeChat Official Account API. Required for reaching users in China.

WeChat is China's dominant super-app. profClaw integrates via the WeChat Official Account (OA) platform for business messaging and automated responses.

## Capabilities

| Feature           | Supported |
| ----------------- | --------- |
| 1:1 messages      | Yes       |
| Passive response  | Yes       |
| Text messages     | Yes       |
| Rich media        | Yes       |
| Menu buttons      | Yes       |
| Template messages | Yes       |
| Webhook           | Yes       |

## Requirements

* WeChat Official Account (Subscription or Service Account)
* Business verification for advanced features
* Server with public HTTPS URL

## Setup

<Steps>
  <Step title="Register a WeChat Official Account">
    Apply at [mp.weixin.qq.com](https://mp.weixin.qq.com). Service Accounts have more API access than Subscription Accounts.
  </Step>

  <Step title="Enable developer mode">
    Go to **Settings > Official Account Settings > Features > Developer** and enable the developer mode.
  </Step>

  <Step title="Configure server settings">
    Set:

    * **Server URL**: `https://your-domain.com/webhooks/wechat`
    * **Token**: your custom token
    * **EncodingAESKey**: generate or use the random one provided
    * **Message encryption**: Recommended (EncodingAESKey required)
  </Step>

  <Step title="Get App credentials">
    Under **Development > Basic Configuration**, copy **AppID** and **AppSecret**.
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    WECHAT_APP_ID=wx1234567890abcdef
    WECHAT_APP_SECRET=your-app-secret
    WECHAT_TOKEN=your-verify-token
    WECHAT_ENCODING_AES_KEY=your-encoding-aes-key
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  WeChat Official Account AppID.
</ParamField>

<ParamField type="string">
  WeChat Official Account AppSecret.
</ParamField>

<ParamField type="string">
  Server token for webhook verification.
</ParamField>

<ParamField type="string">
  43-character AES key for encrypted message mode.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    WECHAT_APP_ID=wx1234567890abcdef
    WECHAT_APP_SECRET=abc123...
    WECHAT_TOKEN=my-verify-token
    WECHAT_ENCODING_AES_KEY=yourRandomAESKey43Chars...
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      wechat:
        app_id: "${WECHAT_APP_ID}"
        app_secret: "${WECHAT_APP_SECRET}"
        token: "${WECHAT_TOKEN}"
        encoding_aes_key: "${WECHAT_ENCODING_AES_KEY}"
    ```
  </Tab>
</Tabs>

## Notes

* Status: Beta
* WeChat's API operates in a passive response model - it sends you a message and you must reply within 5 seconds.
* For asynchronous (slow) responses, use customer service messages (requires Service Account).
* WeChat server IPs must be whitelisted in the developer settings.
* Template messages for proactive outreach require prior user consent and WeChat approval.
* Server must be accessible from WeChat's IP ranges (China-based).

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Zalo](/chat-providers/zalo) - Leading messaging platform in Vietnam
* [LINE](/chat-providers/line) - Dominant messaging platform in Japan and Taiwan
* [profclaw channels](/cli/channels) - Enable and test the WeChat connection from the CLI


# WhatsApp
Source: https://docs.profclaw.ai/chat-providers/whatsapp

Connect profClaw to WhatsApp via the WhatsApp Business API (Meta Cloud API). Requires a Meta Business account and phone number.

profClaw integrates with WhatsApp through the official Meta WhatsApp Business Cloud API. This is the production-grade approach using a dedicated business phone number.

## Capabilities

| Feature             | Supported           |
| ------------------- | ------------------- |
| 1:1 messaging       | Yes                 |
| Group messaging     | No (API limitation) |
| Media messages      | Yes                 |
| Interactive buttons | Yes (limited)       |
| Templates           | Yes                 |
| Webhooks            | Yes                 |
| Read receipts       | Yes                 |

## Requirements

* Meta Business account
* WhatsApp Business app verified
* A phone number (not already on WhatsApp personal)
* Business verification for scaling

## Setup

<Steps>
  <Step title="Create a Meta App">
    Go to [developers.facebook.com](https://developers.facebook.com) and create a new app. Select **Business** type.
  </Step>

  <Step title="Add WhatsApp Product">
    Under your app, add the **WhatsApp** product. Go to **WhatsApp > Getting Started**.
  </Step>

  <Step title="Get your credentials">
    Copy:

    * **Phone Number ID** (not the phone number itself)
    * **WhatsApp Business Account ID**
    * **Access Token** (temporary or permanent)
  </Step>

  <Step title="Configure webhook">
    Under **WhatsApp > Configuration**, set:

    * Webhook URL: `https://your-domain.com/webhooks/whatsapp`
    * Verify token: your custom string

    Subscribe to `messages` and `messaging_handoffs` events.
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    WHATSAPP_PHONE_NUMBER_ID=1234567890
    WHATSAPP_BUSINESS_ACCOUNT_ID=0987654321
    WHATSAPP_ACCESS_TOKEN=EAABwzLixnjYBO...
    WHATSAPP_WEBHOOK_VERIFY_TOKEN=my-verify-token
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Phone Number ID from Meta Developer portal (not the phone number itself).
</ParamField>

<ParamField type="string">
  WhatsApp Business Account ID.
</ParamField>

<ParamField type="string">
  Meta access token (system user or user token).
</ParamField>

<ParamField type="string">
  Your custom verify token for webhook setup.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    WHATSAPP_PHONE_NUMBER_ID=1234567890
    WHATSAPP_BUSINESS_ACCOUNT_ID=0987654321
    WHATSAPP_ACCESS_TOKEN=EAABwzLixnjYBO...
    WHATSAPP_WEBHOOK_VERIFY_TOKEN=my-custom-verify-token
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      whatsapp:
        phone_number_id: "${WHATSAPP_PHONE_NUMBER_ID}"
        business_account_id: "${WHATSAPP_BUSINESS_ACCOUNT_ID}"
        access_token: "${WHATSAPP_ACCESS_TOKEN}"
        webhook_verify_token: "${WHATSAPP_WEBHOOK_VERIFY_TOKEN}"
    ```
  </Tab>
</Tabs>

## Message Format

profClaw sends responses as plain text messages. For interactive messages:

```json theme={null}
{
  "messaging_product": "whatsapp",
  "to": "+1234567890",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": { "text": "Please confirm:" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "yes", "title": "Confirm" } }
      ]
    }
  }
}
```

## Notes

* WhatsApp API requires a public webhook URL with HTTPS.
* Messages to users require them to initiate contact first (24-hour messaging window).
* Outside the 24-hour window, you must use pre-approved message templates.
* Business verification required to message more than 250 unique users per day.
* A permanent access token from a system user is recommended for production.

## Related

* [WhatsApp Bot Guide](/guides/whatsapp-bot) - Step-by-step setup with Meta developer portal
* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [Telegram](/chat-providers/telegram) - Simpler bot setup without business verification
* [profclaw channels](/cli/channels) - Enable and test the WhatsApp connection from the CLI


# Zalo
Source: https://docs.profclaw.ai/chat-providers/zalo

Connect profClaw to Zalo via the Zalo Official Account API. The leading messaging platform in Vietnam.

Zalo is Vietnam's most popular messaging app with over 70 million monthly users. profClaw supports the Zalo Official Account (OA) API for business bot interactions.

## Capabilities

| Feature          | Supported |
| ---------------- | --------- |
| 1:1 messages     | Yes       |
| Group messages   | Limited   |
| Rich text        | Yes       |
| Image messages   | Yes       |
| Button templates | Yes       |
| Webhook          | Yes       |

## Setup

<Steps>
  <Step title="Create a Zalo Developer account">
    Register at [developers.zalo.me](https://developers.zalo.me).
  </Step>

  <Step title="Create an Official Account App">
    Create a new app and link it to a Zalo Official Account (OA). You need a verified business OA.
  </Step>

  <Step title="Get credentials">
    * **App ID**
    * **App Secret**
    * **OA Access Token** (from OA Management)
  </Step>

  <Step title="Configure webhook">
    In Zalo Developer Portal, set webhook URL:
    `https://your-domain.com/webhooks/zalo`
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    ZALO_APP_ID=your-app-id
    ZALO_APP_SECRET=your-app-secret
    ZALO_OA_ACCESS_TOKEN=your-oa-access-token
    ```
  </Step>
</Steps>

## Environment Variables

<ParamField type="string">
  Zalo Developer App ID.
</ParamField>

<ParamField type="string">
  Zalo Developer App Secret.
</ParamField>

<ParamField type="string">
  Zalo Official Account access token.
</ParamField>

## Configuration Example

<Tabs>
  <Tab title=".env">
    ```bash theme={null}
    ZALO_APP_ID=1234567890
    ZALO_APP_SECRET=abcdef...
    ZALO_OA_ACCESS_TOKEN=your-oa-token
    ```
  </Tab>

  <Tab title="settings.yml">
    ```yaml theme={null}
    chat:
      zalo:
        app_id: "${ZALO_APP_ID}"
        app_secret: "${ZALO_APP_SECRET}"
        oa_access_token: "${ZALO_OA_ACCESS_TOKEN}"
    ```
  </Tab>
</Tabs>

## Zalo Personal (Beta)

profClaw also includes experimental support for Zalo personal accounts via the `zalo-personal` provider. This uses unofficial APIs and may break with Zalo updates.

```bash theme={null}
ZALO_PERSONAL_COOKIE=...
```

<Warning>
  The `zalo-personal` provider uses unofficial APIs. Use the official OA API (`zalo`) for production.
</Warning>

## Notes

* Status: Beta
* Zalo requires a Vietnamese business entity for full OA verification.
* OA access tokens expire and need periodic refresh.
* Zalo messages support Vietnamese text natively.
* The Zalo OA API has rate limits of 2000 messages/minute.

## Related

* [Chat Providers Overview](/chat-providers/overview) - Compare all 27 supported channels
* [LINE](/chat-providers/line) - Dominant messaging platform in Japan and Taiwan
* [Viber](/chat-providers/viber) - Popular messaging app in Southeast Asia and Eastern Europe
* [profclaw channels](/cli/channels) - Enable and test the Zalo connection from the CLI


# profclaw agent
Source: https://docs.profclaw.ai/cli/agent

List and inspect AI agents configured in profClaw.

## Synopsis

```bash theme={null}
profclaw agent <subcommand> [flags]
```

## Description

`agent` commands let you inspect the AI agents that are registered and running in profClaw. Agents are responsible for processing tasks and chat sessions. Each agent has a type (e.g., `claude`, `openai`, `ollama`), a name, and health/performance statistics.

## Subcommands

| Subcommand | Alias    | Description                                      |
| ---------- | -------- | ------------------------------------------------ |
| `list`     | `ls`     | List all configured agents with health and stats |
| `status`   | `health` | Show full health status of all agents            |
| `types`    | -        | List available agent type identifiers            |

## `agent list`

Lists all configured agents in a table showing type, name, health status, completed tasks, and failed tasks.

<ParamField type="boolean">
  Output as JSON array.
</ParamField>

## `agent status`

Fetches the `/health` endpoint and displays version, overall status, and per-agent health with last-check timestamps.

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `agent types`

Lists the agent type identifiers available in this profClaw installation (e.g., `claude`, `openai`, `gemini`, `ollama`).

<ParamField type="boolean">
  Output as JSON array of strings.
</ParamField>

## Examples

<CodeGroup>
  ```bash List all agents theme={null}
  profclaw agent list
  ```

  ```bash List agents as JSON theme={null}
  profclaw agent list --json
  ```

  ```bash Check agent health theme={null}
  profclaw agent status
  ```

  ```bash Show available agent types theme={null}
  profclaw agent types
  ```
</CodeGroup>

## Example Output

```
Type      Name             Status      Completed  Failed
claude    Claude Agent     ● Healthy   142        3
openai    GPT-4o Agent     ● Healthy   87         1
ollama    Llama3 Agent     ● Unhealthy 0          5
```

## Agent Configuration

Agents are configured in `config/agents.yml`. See the [configuration reference](/configuration) for available options.

```yaml theme={null}
# config/agents.yml
agents:
  - type: claude
    name: Claude Agent
    model: claude-sonnet-4-6
  - type: openai
    name: GPT-4o Agent
    model: gpt-4o
```

## Related

* [`profclaw task`](/cli/task) - Create and track tasks run by agents
* [`profclaw chat`](/cli/chat) - Chat directly with an agent
* [`profclaw status`](/cli/status) - System-wide health overview
* [AI Providers](/ai-providers) - Configure provider credentials


# profclaw security audit
Source: https://docs.profclaw.ai/cli/audit

View the security audit log - a record of every tool execution, approval, and denial.

## Synopsis

```bash theme={null}
profclaw security audit [flags]
```

## Description

The security audit log captures every security-relevant action in profClaw: tool executions, approval requests, approvals, denials, and authentication events. It provides a tamper-evident trail for compliance and debugging.

The `audit` subcommand is accessed via `profclaw security audit`. See the [`security`](/cli/security) command for the full security command group.

## Flags

<ParamField type="string">
  Maximum number of log entries to show.
</ParamField>

<ParamField type="boolean">
  Show only entries with `pending` result - items awaiting approval.
</ParamField>

<ParamField type="boolean">
  Output as JSON array with full entry details.
</ParamField>

## Audit Entry Fields

| Field       | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `id`        | Unique entry ID                                                 |
| `action`    | What was attempted (e.g., `exec`, `write_file`, `http_request`) |
| `actor`     | User or agent that initiated the action                         |
| `target`    | Resource targeted (file path, URL, command)                     |
| `result`    | `approved`, `denied`, or `pending`                              |
| `createdAt` | Timestamp                                                       |

## Examples

<CodeGroup>
  ```bash View recent audit log theme={null}
  profclaw security audit
  ```

  ```bash Show all pending approvals theme={null}
  profclaw security audit --pending
  ```

  ```bash Show last 100 entries theme={null}
  profclaw security audit --limit 100
  ```

  ```bash Export as JSON theme={null}
  profclaw security audit --json | jq '.[] | select(.result == "denied")'
  ```

  ```bash Approve a pending item from the audit log theme={null}
  profclaw security audit --pending
  profclaw security approve <id>
  ```

  ```bash Deny with a reason theme={null}
  profclaw security deny <id> --reason "Unauthorized external request"
  ```
</CodeGroup>

## Audit Results

| Result     | Description                                    |
| ---------- | ---------------------------------------------- |
| `approved` | Action was allowed (automatically or manually) |
| `denied`   | Action was blocked                             |
| `pending`  | Awaiting manual approval from an admin         |

## Related

* [`profclaw security`](/cli/security) - Full security command group
* [`profclaw logs`](/cli/logs) - Server application logs
* [Security Guide](/security) - Security architecture


# profclaw auth
Source: https://docs.profclaw.ai/cli/auth

Authentication and user management - invite codes, password reset, user listing, and registration mode.

## Synopsis

```bash theme={null}
profclaw auth <subcommand> [flags]
```

## Description

`auth` commands connect directly to the database (no server required) for administrative user management. Use them to manage accounts, generate invite codes for new users, and control registration mode.

<Warning>
  These commands write directly to the database. The profClaw server does not need to be running, but you must be in the same directory as the profClaw installation (or have the correct database path configured).
</Warning>

## Subcommands

| Subcommand               | Description                                             |
| ------------------------ | ------------------------------------------------------- |
| `invite`                 | Generate one or more invite codes                       |
| `reset-password <email>` | Reset a user's password and generate new recovery codes |
| `list-users`             | List all registered users                               |
| `list-invites`           | List all invite codes and their status                  |
| `set-mode <mode>`        | Set registration mode to `open` or `invite`             |

## `auth invite`

Generate invite codes for new users to use during registration.

<ParamField type="string">
  Number of codes to generate (max 50).
</ParamField>

<ParamField type="string">
  Expiration duration. Format: `7d`, `24h`, `30m`. Codes without an expiry never expire.
</ParamField>

<ParamField type="string">
  Human-readable label for tracking (e.g., `"For Alice"`, `"Team onboarding"`).
</ParamField>

## `auth reset-password <email>`

Generates a random temporary password, invalidates all existing sessions for the user, and prints new recovery codes. The user must change their password after the next login.

## `auth list-users`

<ParamField type="string">
  Filter by user status. One of `active` or `suspended`.
</ParamField>

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `auth list-invites`

<ParamField type="boolean">
  Show only codes that have not been used yet.
</ParamField>

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `auth set-mode <mode>`

<ParamField type="string">
  Registration mode. `open` allows anyone to register. `invite` requires a valid invite code.
</ParamField>

## Examples

<CodeGroup>
  ```bash Generate a single invite code theme={null}
  profclaw auth invite
  ```

  ```bash Generate 5 codes expiring in 7 days theme={null}
  profclaw auth invite -n 5 --expires 7d --label "Team onboarding"
  ```

  ```bash Reset a user's password theme={null}
  profclaw auth reset-password alice@example.com
  ```

  ```bash List all users theme={null}
  profclaw auth list-users
  ```

  ```bash List active users only theme={null}
  profclaw auth list-users --status active
  ```

  ```bash Show unused invite codes theme={null}
  profclaw auth list-invites --unused
  ```

  ```bash Require invite codes for registration theme={null}
  profclaw auth set-mode invite
  ```

  ```bash Allow open registration theme={null}
  profclaw auth set-mode open
  ```
</CodeGroup>

## Related

* [`profclaw config login`](/cli/config) - Configure API token authentication
* [`profclaw device`](/cli/device) - Manage paired devices
* [`profclaw security`](/cli/security) - Security policies and approvals


# profclaw backup
Source: https://docs.profclaw.ai/cli/backup

Back up and restore profClaw data - database, configuration, skills, and memory index.

## Synopsis

```bash theme={null}
profclaw backup <subcommand> [flags]
```

## Description

`backup` creates and restores snapshots of profClaw's persistent data. A backup includes the SQLite database, configuration files, skills directory, and optionally the memory index. Backups are stored as compressed archives and can be restored to the same or a different machine.

## Subcommands

| Subcommand       | Description                         |
| ---------------- | ----------------------------------- |
| `create`         | Create a new backup                 |
| `list`           | List available backups              |
| `restore <file>` | Restore from a backup file          |
| `delete <file>`  | Delete a backup file                |
| `schedule`       | Configure automatic backup schedule |

## `backup create`

<ParamField type="string">
  Directory or file path for the backup archive. Defaults to `~/.profclaw/backups/profclaw-YYYY-MM-DD.tar.gz`.
</ParamField>

<ParamField type="boolean">
  Exclude the memory index from the backup (reduces size significantly).
</ParamField>

<ParamField type="boolean">
  Exclude configuration files (back up data only).
</ParamField>

<ParamField type="boolean">
  Output backup result as JSON.
</ParamField>

## `backup restore <file>`

<ParamField type="string">
  Path to the backup archive to restore.
</ParamField>

<ParamField type="boolean">
  List what would be restored without making changes.
</ParamField>

<ParamField type="boolean">
  Skip the confirmation prompt.
</ParamField>

<Warning>
  Restore overwrites the current database and configuration. Stop the server before restoring to avoid data corruption.
</Warning>

## `backup schedule`

<ParamField type="string">
  Schedule interval: `daily`, `weekly`, or a cron expression.
</ParamField>

<ParamField type="string">
  Number of backups to retain. Older backups are automatically deleted.
</ParamField>

## Examples

<CodeGroup>
  ```bash Create a backup theme={null}
  profclaw backup create
  ```

  ```bash Backup to a specific location theme={null}
  profclaw backup create --output /mnt/backups/profclaw-$(date +%Y%m%d).tar.gz
  ```

  ```bash Backup without the memory index theme={null}
  profclaw backup create --no-memory
  ```

  ```bash List available backups theme={null}
  profclaw backup list
  ```

  ```bash Restore from a backup theme={null}
  profclaw serve stop         # Stop the server first
  profclaw backup restore ~/.profclaw/backups/profclaw-2026-03-01.tar.gz
  profclaw serve              # Restart
  ```

  ```bash Schedule daily automated backups theme={null}
  profclaw backup schedule --interval daily --keep 14
  ```
</CodeGroup>

## What is Backed Up

| Component                            | Included by default             |
| ------------------------------------ | ------------------------------- |
| SQLite database (`data/profclaw.db`) | Yes                             |
| Configuration (`config/`)            | Yes                             |
| Skills (`skills/`)                   | Yes                             |
| `.env` file                          | No (contains secrets)           |
| Memory index                         | Yes (use `--no-memory` to skip) |
| Log files                            | No                              |

## Related

* [`profclaw reset`](/cli/reset) - Reset configuration without backup
* [`profclaw status`](/cli/status) - Verify system health after restore
* [Docker Deployment](/guides/docker-deployment) - Persistent volume backup strategies


# profclaw channels
Source: https://docs.profclaw.ai/cli/channels

profclaw channels - enable, disable, configure, and test messaging channels. Manage Slack, Discord, Telegram, and other chat provider connections.

## Synopsis

```bash theme={null}
profclaw channels <subcommand> [flags]
```

## Description

Manage messaging channel providers. Enable, disable, configure, and test chat channel connections like Slack, Discord, Telegram, and others.

## Subcommands

| Subcommand           | Alias | Description                 |
| -------------------- | ----- | --------------------------- |
| `list`               | `ls`  | List all messaging channels |
| `enable <provider>`  |       | Enable a messaging channel  |
| `disable <provider>` |       | Disable a messaging channel |
| `config <provider>`  |       | Show channel configuration  |
| `test <provider>`    |       | Test a channel connection   |

## Flags

| Flag     | Type    | Description    |
| -------- | ------- | -------------- |
| `--json` | boolean | Output as JSON |

## Examples

<CodeGroup>
  ```bash List all channels theme={null}
  profclaw channels list
  ```

  ```bash Enable Slack theme={null}
  profclaw channels enable slack
  ```

  ```bash Test Discord connection theme={null}
  profclaw channels test discord
  ```

  ```bash View Telegram config theme={null}
  profclaw channels config telegram
  ```

  ```bash Disable a channel theme={null}
  profclaw channels disable irc
  ```
</CodeGroup>

## Related

* [Chat Providers Overview](/chat-providers/overview)
* [Slack Setup](/chat-providers/slack)
* [Discord Setup](/chat-providers/discord)


# profclaw chat
Source: https://docs.profclaw.ai/cli/chat

Start an interactive AI chat session or send a single message from the terminal.

## Synopsis

```bash theme={null}
profclaw chat [message] [flags]
profclaw chat <subcommand> [flags]
```

## Description

`chat` connects to the profClaw API and starts a conversation with the AI. When called without a message it enters an interactive REPL with session persistence. When called with a message it runs in single-shot mode and exits.

Two execution modes are available:

* **Chat mode** (default) - conversational, no tools
* **Agentic mode** (`--agentic`) - full tool access, multi-step execution

## Flags

<ParamField type="string">
  Message to send. When provided, runs in single-shot mode and exits after the response. Omit to start an interactive session.
</ParamField>

<ParamField type="string">
  AI model to use (e.g., `sonnet`, `opus`, `gpt-4o`, `gemini-2-flash`). Defaults to the server's configured default model.
</ParamField>

<ParamField type="boolean">
  Enable tool calling for this session. The AI can use configured tools but will ask for approval on sensitive operations.
</ParamField>

<ParamField type="boolean">
  Enable agentic mode with all tools and full execution permissions. Implies `--tools`.
</ParamField>

<ParamField type="string">
  Resume an existing conversation by session ID. Use `profclaw chat sessions` to list recent sessions.
</ParamField>

<ParamField type="boolean">
  Output the response as JSON (single-shot mode only).
</ParamField>

## Subcommands

| Subcommand        | Alias | Description                                            |
| ----------------- | ----- | ------------------------------------------------------ |
| `quick <message>` | -     | Quick single-shot chat without creating a conversation |
| `agent <message>` | `run` | Run in agentic mode with all tools                     |
| `sessions`        | `ls`  | List recent chat sessions                              |

## REPL Commands

When in interactive mode, type `/` commands to control the session:

| Command                | Description                             |
| ---------------------- | --------------------------------------- |
| `/exit`, `/quit`, `/q` | Exit the chat                           |
| `/clear`               | Clear the terminal screen               |
| `/help`, `/?`          | Show available commands                 |
| `/session`             | Show the current session ID             |
| `/model <name>`        | Switch to a different model mid-session |
| `/tools`               | Toggle tool calling on/off              |
| `/agentic`             | Toggle agentic mode on/off              |

## Examples

<CodeGroup>
  ```bash Interactive chat session theme={null}
  profclaw chat
  ```

  ```bash Single-shot message theme={null}
  profclaw chat "What is the capital of France?"
  ```

  ```bash Use a specific model theme={null}
  profclaw chat -m opus "Explain quantum entanglement"
  ```

  ```bash Agentic mode (tools enabled) theme={null}
  profclaw chat -a "List all running Docker containers and show their memory usage"
  ```

  ```bash Run a single agentic task theme={null}
  profclaw chat agent "Find all TODO comments in the src/ directory"
  # or
  profclaw chat run "Find all TODO comments in the src/ directory"
  ```

  ```bash Quick single-shot (no session created) theme={null}
  profclaw chat quick "Current time?"
  ```

  ```bash Resume a previous session theme={null}
  profclaw chat sessions                     # list sessions
  profclaw chat -s abc12345                  # resume by session ID
  ```

  ```bash JSON output for scripting theme={null}
  profclaw chat --json "List the top 5 planets by size"
  ```
</CodeGroup>

## Related

* [`profclaw agent`](/cli/agent) - Manage AI agents
* [`profclaw task`](/cli/task) - Create and track agentic tasks
* [`profclaw tui`](/cli/tui) - Terminal dashboard
* [`profclaw summary`](/cli/summary) - Browse completed work summaries


# profclaw completion
Source: https://docs.profclaw.ai/cli/completion

profclaw completion - generate shell tab-completion scripts for bash, zsh, and fish. Install once and autocomplete every profClaw command and flag.

## Synopsis

```bash theme={null}
profclaw completion <shell>
```

## Description

Generate shell completion scripts for tab-completion of profClaw commands, subcommands, and flags.

## Subcommands

| Subcommand | Description                     |
| ---------- | ------------------------------- |
| `bash`     | Generate bash completion script |
| `zsh`      | Generate zsh completion script  |
| `fish`     | Generate fish completion script |

## Setup

<Tabs>
  <Tab title="Bash">
    ```bash theme={null}
    # Add to ~/.bashrc
    eval "$(profclaw completion bash)"
    ```
  </Tab>

  <Tab title="Zsh">
    ```bash theme={null}
    # Add to ~/.zshrc
    eval "$(profclaw completion zsh)"
    ```
  </Tab>

  <Tab title="Fish">
    ```bash theme={null}
    profclaw completion fish | source

    # Or persist it
    profclaw completion fish > ~/.config/fish/completions/profclaw.fish
    ```
  </Tab>
</Tabs>

## Related

* [CLI Overview](/cli/overview)
* [Installation](/getting-started/installation)


# profclaw config
Source: https://docs.profclaw.ai/cli/config

Get, set, and reset CLI and server-side configuration values.

## Synopsis

```bash theme={null}
profclaw config <subcommand> [flags]
```

## Description

`config` manages two layers of configuration:

* **CLI config** - stored locally in `~/.profclaw/config.json`. Controls how the CLI connects to the server (API URL and token, default agent, output format).
* **Server settings** - stored in `config/settings.yml` and the database. Controls runtime behavior of the running server (use `--server` flag).

## Subcommands

| Subcommand          | Description                                  |
| ------------------- | -------------------------------------------- |
| `get [key]`         | Print one or all configuration values        |
| `set <key> <value>` | Set a configuration value                    |
| `reset`             | Reset configuration to defaults              |
| `path`              | Print the path to the CLI config file        |
| `login`             | Configure API authentication (URL and token) |

## `config get`

<ParamField type="string">
  Optional key to retrieve. Omit to print all values. For server settings, use dotted format: `system.telemetry`.
</ParamField>

<ParamField type="boolean">
  Output as JSON.
</ParamField>

<ParamField type="boolean">
  Fetch server-side settings from the running API instead of the local CLI config.
</ParamField>

## `config set`

<ParamField type="string">
  Configuration key to set. CLI keys: `apiUrl`, `apiToken`, `defaultAgent`, `outputFormat`. Server keys use `category.key` format (e.g., `system.telemetry`).
</ParamField>

<ParamField type="string">
  Value to set. For server settings, JSON values are parsed automatically (`true`, `false`, numbers, objects).
</ParamField>

<ParamField type="boolean">
  Apply change to server-side settings via API.
</ParamField>

## `config login`

<ParamField type="string">
  API bearer token. Saved to the CLI config file and used for all subsequent API calls.
</ParamField>

<ParamField type="string">
  API base URL (e.g., `https://my-server.example.com`).
</ParamField>

## CLI Config Keys

| Key            | Default                 | Description                          |
| -------------- | ----------------------- | ------------------------------------ |
| `apiUrl`       | `http://localhost:3000` | Base URL of the profClaw API         |
| `apiToken`     | -                       | Bearer token for authentication      |
| `defaultAgent` | -                       | Default agent type for task creation |
| `outputFormat` | `table`                 | Output format (`table` or `json`)    |

## Examples

<CodeGroup>
  ```bash Show all CLI config theme={null}
  profclaw config get
  ```

  ```bash Get a single value theme={null}
  profclaw config get apiUrl
  ```

  ```bash Set the API URL theme={null}
  profclaw config set apiUrl http://my-server:3000
  ```

  ```bash Configure authentication theme={null}
  profclaw config login --url https://my-server.com --token eyJ...
  ```

  ```bash View server-side settings theme={null}
  profclaw config get --server
  ```

  ```bash Update a server setting theme={null}
  profclaw config set --server system.telemetry false
  ```

  ```bash Reset CLI config to defaults theme={null}
  profclaw config reset
  ```

  ```bash Show config file location theme={null}
  profclaw config path
  ```
</CodeGroup>

## Related

* [`profclaw auth`](/cli/auth) - User and invite management
* [`profclaw onboard`](/cli/onboard) - First-run configuration wizard
* [Configuration Reference](/configuration) - Full settings documentation


# profclaw cost
Source: https://docs.profclaw.ai/cli/cost

View AI token usage, cost analytics, and budget status across models and agents.

## Synopsis

```bash theme={null}
profclaw cost <subcommand> [flags]
```

## Description

`cost` provides visibility into AI API spending. It reads usage data from the profClaw server, which tracks token consumption per task, model, and agent. Use it to monitor budgets, identify expensive operations, and spot cost anomalies.

## Subcommands

| Subcommand  | Alias   | Description                                                  |
| ----------- | ------- | ------------------------------------------------------------ |
| `summary`   | `sum`   | Aggregate cost and token totals with a 7-day daily breakdown |
| `budget`    | -       | Show budget utilization with a progress bar                  |
| `analytics` | `stats` | Detailed breakdown by model, agent, and day                  |

## `cost summary`

Shows total cost, total tokens, task count, and the last 7 days of daily usage.

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `cost budget`

Displays current daily spend against the configured daily budget limit. The progress bar changes color at 50% (yellow) and 80% (red). Shows a warning when the budget is exceeded.

<ParamField type="boolean">
  Output as JSON with raw budget config and usage data.
</ParamField>

## `cost analytics`

Provides breakdowns by model and by agent, plus a 7-day daily table. Use this to identify which models or agents are driving costs.

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## Examples

<CodeGroup>
  ```bash View cost summary theme={null}
  profclaw cost summary
  ```

  ```bash Check budget utilization theme={null}
  profclaw cost budget
  ```

  ```bash Detailed analytics by model and agent theme={null}
  profclaw cost analytics
  ```

  ```bash Export analytics as JSON theme={null}
  profclaw cost analytics --json | jq '.byModel'
  ```
</CodeGroup>

## Example Output

```
## Cost Summary

Total Cost:   $1.2340
Total Tokens: 1,234,567
Task Count:   89

### Daily Breakdown
Date         Cost     Tokens
2026-03-12   $0.18    145,200
2026-03-11   $0.24    198,400
2026-03-10   $0.09    72,100
...
```

## Budget Configuration

Set daily and monthly cost limits in `config/settings.yml` or via environment variables:

```yaml theme={null}
# config/settings.yml
costs:
  dailyLimit: 5.00      # USD
  monthlyLimit: 100.00  # USD
  alerts: [50, 80, 95]  # Alert at these percentages
```

## Related

* [`profclaw status`](/cli/status) - System overview including provider health
* [`profclaw summary`](/cli/summary) - Browse agent work summaries
* [`profclaw agent`](/cli/agent) - Agent stats including task counts


# profclaw cron
Source: https://docs.profclaw.ai/cli/cron

Manage scheduled jobs - list, create, enable, disable, and trigger cron jobs.

## Synopsis

```bash theme={null}
profclaw cron <subcommand> [flags]
```

## Description

`cron` manages scheduled tasks that run automatically on a schedule. Cron jobs can trigger agent tasks, send notifications, sync data, or run any configured workflow. They use standard cron expression syntax for scheduling and are defined in `config/cron.yml` or via the API.

## Subcommands

| Subcommand     | Description                                       |
| -------------- | ------------------------------------------------- |
| `list`         | List all configured cron jobs                     |
| `show <id>`    | Show details for a cron job                       |
| `trigger <id>` | Manually trigger a cron job immediately           |
| `enable <id>`  | Enable a disabled cron job                        |
| `disable <id>` | Disable a cron job without deleting it            |
| `create`       | Create a new cron job (interactive or with flags) |
| `delete <id>`  | Delete a cron job                                 |

## `cron list`

<ParamField type="boolean">
  Show only enabled cron jobs.
</ParamField>

<ParamField type="boolean">
  Output as JSON array.
</ParamField>

## `cron trigger <id>`

Executes the cron job immediately regardless of its schedule. Useful for testing before deployment or running jobs on demand.

<ParamField type="boolean">
  Output trigger result as JSON.
</ParamField>

## `cron create`

<ParamField type="string">
  Job name (unique identifier).
</ParamField>

<ParamField type="string">
  Cron schedule expression (e.g., `0 9 * * 1-5` for weekdays at 9am).
</ParamField>

<ParamField type="string">
  Agent prompt to execute on schedule.
</ParamField>

<ParamField type="string">
  Agent to assign the scheduled task to.
</ParamField>

## Examples

<CodeGroup>
  ```bash List all scheduled jobs theme={null}
  profclaw cron list
  ```

  ```bash List enabled jobs only theme={null}
  profclaw cron list --enabled-only
  ```

  ```bash Show job details theme={null}
  profclaw cron show daily-report
  ```

  ```bash Manually trigger a job theme={null}
  profclaw cron trigger daily-report
  ```

  ```bash Enable a disabled job theme={null}
  profclaw cron enable daily-report
  ```

  ```bash Disable a job (keep config) theme={null}
  profclaw cron disable daily-report
  ```

  ```bash Create a weekday morning job theme={null}
  profclaw cron create \
    --name standup-summary \
    --schedule "0 9 * * 1-5" \
    --prompt "Summarize yesterday's GitHub activity" \
    --agent claude
  ```

  ```bash Delete a job theme={null}
  profclaw cron delete standup-summary
  ```
</CodeGroup>

## Cron Expression Reference

| Expression     | Description         |
| -------------- | ------------------- |
| `0 9 * * 1-5`  | Weekdays at 9:00 AM |
| `0 */2 * * *`  | Every 2 hours       |
| `0 0 * * *`    | Daily at midnight   |
| `0 0 * * 0`    | Weekly on Sunday    |
| `0 0 1 * *`    | Monthly on the 1st  |
| `*/15 * * * *` | Every 15 minutes    |

## Related

* [`profclaw task`](/cli/task) - Tasks created by cron jobs appear here
* [`profclaw serve --no-cron`](/cli/serve) - Disable cron when starting the server
* [Cron Templates](/configuration) - Pre-built schedule configurations


# profclaw daemon
Source: https://docs.profclaw.ai/cli/daemon

Install and manage profClaw as a persistent system service using launchd (macOS) or systemd (Linux).

## Synopsis

```bash theme={null}
profclaw daemon <subcommand> [flags]
```

## Description

`daemon` registers profClaw as an OS-level service so it starts automatically on boot and restarts on failure. On macOS it creates a `launchd` plist at `~/Library/LaunchAgents/com.profclaw.agent.plist`. On Linux it creates a `systemd` user unit at `~/.config/systemd/user/profclaw.service`.

Logs are written to `~/.profclaw/daemon.log` and `~/.profclaw/daemon-error.log` on macOS, and to the system journal on Linux.

## Subcommands

| Subcommand  | Description                                     |
| ----------- | ----------------------------------------------- |
| `install`   | Register the service with launchd / systemd     |
| `uninstall` | Remove the service registration                 |
| `start`     | Start the service                               |
| `stop`      | Stop the service                                |
| `restart`   | Restart the service (also rotates logs)         |
| `status`    | Show current service status, PID, and log sizes |
| `logs`      | Tail service logs                               |
| `rotate`    | Rotate log files when > 10 MB (macOS only)      |

## Examples

<CodeGroup>
  ```bash Install and start (macOS) theme={null}
  profclaw daemon install
  profclaw daemon start
  ```

  ```bash Install and start (Linux) theme={null}
  profclaw daemon install
  profclaw daemon start
  # Optionally enable start-on-boot
  systemctl --user enable profclaw
  ```

  ```bash Check service status theme={null}
  profclaw daemon status
  ```

  ```bash Tail logs in real time theme={null}
  profclaw daemon logs --follow
  ```

  ```bash Show last 100 lines of error log theme={null}
  profclaw daemon logs --errors -n 100
  ```

  ```bash Restart and rotate logs theme={null}
  profclaw daemon restart
  ```

  ```bash Remove service theme={null}
  profclaw daemon stop
  profclaw daemon uninstall
  ```
</CodeGroup>

## `daemon logs` Flags

<ParamField type="boolean">
  Follow log output in real time. Press `Ctrl+C` to stop.
</ParamField>

<ParamField type="string">
  Number of lines to show. Maps to `tail -n` on macOS and `journalctl -n` on Linux.
</ParamField>

<ParamField type="boolean">
  Show the error log only (`daemon-error.log` on macOS, journal priority `err` on Linux).
</ParamField>

## Crash Loop Protection

The service is configured with restart limits to prevent runaway crash loops:

| Platform        | Behavior                                                |
| --------------- | ------------------------------------------------------- |
| macOS (launchd) | `ThrottleInterval=10s` between restart attempts         |
| Linux (systemd) | Max 5 restart attempts per 60 seconds (`RestartSec=5s`) |

If the limit is hit, use `profclaw doctor` to identify the root cause, then manually start the service again.

## Log Rotation

On macOS, log files rotate automatically when they exceed 10 MB (one `.1` backup kept). On Linux, `journald` handles rotation automatically.

```bash theme={null}
# Manually rotate macOS logs
profclaw daemon rotate
```

## Related

* [`profclaw serve`](/cli/serve) - Start the server in foreground mode
* [`profclaw status`](/cli/status) - Quick system status
* [`profclaw logs`](/cli/logs) - View server logs via the API
* [`profclaw doctor`](/cli/doctor) - Diagnose issues


# profclaw devices
Source: https://docs.profclaw.ai/cli/device

Manage paired devices - list, pair with a code, unpair, and inspect device details.

## Synopsis

```bash theme={null}
profclaw devices <subcommand> [flags]
```

## Description

`devices` manages the devices that are trusted to connect to your profClaw instance. Devices are paired using short pairing codes generated from the web UI or via QR code. Once paired, a device receives a session token and can authenticate with the API.

## Subcommands

| Subcommand    | Alias | Description                            |
| ------------- | ----- | -------------------------------------- |
| `list`        | `ls`  | List all paired devices                |
| `pair <code>` | -     | Pair a new device using a pairing code |
| `unpair <id>` | -     | Remove a paired device                 |
| `info <id>`   | -     | Show details for a specific device     |

## `devices list`

<ParamField type="boolean">
  Output as JSON array with id, name, platform, version, and last seen time.
</ParamField>

## `devices pair <code>`

<ParamField type="string">
  Pairing code shown in the profClaw web UI or QR code. Codes are short-lived and single-use.
</ParamField>

<ParamField type="boolean">
  Output the paired device details as JSON.
</ParamField>

## `devices unpair <id>`

<ParamField type="string">
  Device ID to remove. After unpairing, the device loses API access.
</ParamField>

<ParamField type="boolean">
  Skip the confirmation prompt.
</ParamField>

<ParamField type="boolean">
  Output `{"ok": true, "id": "..."}` on success.
</ParamField>

## `devices info <id>`

<ParamField type="string">
  Device ID to inspect.
</ParamField>

<ParamField type="boolean">
  Output device details as JSON.
</ParamField>

## Examples

<CodeGroup>
  ```bash List paired devices theme={null}
  profclaw devices list
  ```

  ```bash Pair a new device theme={null}
  profclaw devices pair ABC-123
  ```

  ```bash Show device details theme={null}
  profclaw devices info d3a4f5e6
  ```

  ```bash Unpair a device theme={null}
  profclaw devices unpair d3a4f5e6
  ```

  ```bash Unpair without confirmation theme={null}
  profclaw devices unpair d3a4f5e6 --yes
  ```

  ```bash List devices as JSON theme={null}
  profclaw devices list --json | jq '.[].name'
  ```
</CodeGroup>

## Generating Pairing Codes

Pairing codes are generated from:

* **Web UI**: Settings > Devices > Add Device
* **QR code**: Scan with the profClaw mobile app

Codes expire after a short window. Generate a fresh code if pairing fails.

## Related

* [`profclaw auth`](/cli/auth) - User and invite management
* [`profclaw security`](/cli/security) - Security policies
* [Security Guide](/security) - Authentication and device trust model


# profclaw doctor
Source: https://docs.profclaw.ai/cli/doctor

Run system diagnostics to detect configuration issues, missing dependencies, and environment problems.

## Synopsis

```bash theme={null}
profclaw doctor [flags]
```

## Description

`doctor` runs a series of health checks against the local environment and the running profClaw server. Each check reports `pass`, `warn`, or `fail` along with a suggested fix command.

Checks performed:

| Check           | What it tests                                     |
| --------------- | ------------------------------------------------- |
| **Node.js**     | Version is >= 22                                  |
| **Config**      | `config/settings.yml` exists                      |
| **Port**        | Configured port is available or in use            |
| **Redis**       | `REDIS_URL` is reachable (optional for pico/mini) |
| **Ollama**      | Ollama API is reachable at `localhost:11434`      |
| **Server**      | profClaw HTTP server responds at `/health`        |
| **Database**    | Database is configured and accessible             |
| **AI Provider** | At least one healthy provider is configured       |
| **Memory**      | Sufficient free system RAM                        |
| **Disk**        | Sufficient free disk space                        |
| **Cloudflared** | `cloudflared` binary is installed (optional)      |
| **Tailscale**   | `tailscale` binary is installed (optional)        |

## Flags

<ParamField type="boolean">
  Output all check results as a JSON array instead of the colored table. Each result includes `name`, `status`, `message`, and optional `fix`.
</ParamField>

## Examples

<CodeGroup>
  ```bash Run all checks theme={null}
  profclaw doctor
  ```

  ```bash Output as JSON (for scripting) theme={null}
  profclaw doctor --json
  ```

  ```bash Check and auto-fix common issues theme={null}
  profclaw doctor && echo "All checks passed"
  ```
</CodeGroup>

## Example Output

```
profClaw Doctor

  ✓ Node.js       v22.11.0
  ✓ Config        settings.yml found (+.env)
  ✓ Port          Port 3000 available
  ⚠ Redis         REDIS_URL not set (optional for pico/mini mode)
    Fix: docker compose up redis -d
  ⚠ Ollama        Not running (optional)
    Fix: https://ollama.com/download
  ✓ Server        Running and healthy
  ✓ Database      Configured and accessible
  ✓ AI Provider   2/2 healthy
  ✓ Memory        14.2 GB free
  ✓ Disk          120G free (42% used)
  ⚠ Cloudflared   Not installed (optional)
    Fix: brew install cloudflared
  ⚠ Tailscale     Not installed (optional)
    Fix: https://tailscale.com/download

  10/12 passed, 4 warnings
```

## Exit Codes

| Code | Meaning                                           |
| ---- | ------------------------------------------------- |
| `0`  | All checks passed (warnings do not cause failure) |
| `1`  | One or more checks failed                         |

## Related

* [`profclaw onboard`](/cli/onboard) - Run the full setup wizard
* [`profclaw status`](/cli/status) - Quick system status
* [`profclaw serve`](/cli/serve) - Start the server
* [`profclaw logs`](/cli/logs) - View server logs


# profclaw github
Source: https://docs.profclaw.ai/cli/github

Manage GitHub integration - connect repositories, sync issues, and configure webhook triggers.

## Synopsis

```bash theme={null}
profclaw github <subcommand> [flags]
```

## Description

`github` manages profClaw's GitHub integration. Once connected, profClaw can listen for GitHub webhooks (issues, pull requests, comments, pushes) and automatically dispatch agent tasks in response. It can also read repository context for agents working on code.

## Subcommands

| Subcommand    | Description                                               |
| ------------- | --------------------------------------------------------- |
| `status`      | Show GitHub connection status and configured repositories |
| `connect`     | Add a GitHub token and configure webhook                  |
| `disconnect`  | Remove the GitHub integration                             |
| `repos`       | List connected repositories                               |
| `sync <repo>` | Manually sync open issues from a repository               |
| `webhook`     | Show webhook configuration for a repository               |

## `github connect`

<ParamField type="string">
  GitHub personal access token or GitHub App token. Requires `repo` and `read:org` scopes for private repos.
</ParamField>

<ParamField type="string">
  Repository to connect in `owner/repo` format.
</ParamField>

## `github sync <repo>`

<ParamField type="string">
  Repository in `owner/repo` format.
</ParamField>

<ParamField type="string">
  Only sync issues with this label (e.g., `profclaw`, `ai-task`).
</ParamField>

<ParamField type="string">
  Maximum issues to sync.
</ParamField>

## Examples

<CodeGroup>
  ```bash Check GitHub integration status theme={null}
  profclaw github status
  ```

  ```bash Connect with a GitHub token theme={null}
  profclaw github connect --token ghp_... --repo myorg/myrepo
  ```

  ```bash List connected repositories theme={null}
  profclaw github repos
  ```

  ```bash Sync issues from a repository theme={null}
  profclaw github sync myorg/myrepo
  ```

  ```bash Sync issues with a specific label theme={null}
  profclaw github sync myorg/myrepo --label profclaw
  ```

  ```bash Show webhook URL for a repository theme={null}
  profclaw github webhook myorg/myrepo
  ```

  ```bash Disconnect GitHub integration theme={null}
  profclaw github disconnect
  ```
</CodeGroup>

## Webhook Events

When a webhook is configured, profClaw responds to:

| Event                   | Action                                   |
| ----------------------- | ---------------------------------------- |
| `issues.opened`         | Create an agent task for the new issue   |
| `issues.labeled`        | Trigger when a specific label is applied |
| `pull_request.opened`   | Trigger code review workflow             |
| `issue_comment.created` | Respond to `@profclaw` mentions          |
| `push`                  | Trigger on-push workflows                |

## Environment Variables

```bash theme={null}
GITHUB_TOKEN=ghp_...     # Personal access token
GITHUB_WEBHOOK_SECRET=   # Webhook HMAC secret for verification
```

## Related

* [`profclaw jira`](/cli/jira) - Jira integration
* [`profclaw linear`](/cli/linear) - Linear integration
* [`profclaw sync`](/cli/sync) - Cross-platform sync operations
* [GitHub Integration Guide](/integrations/github) - Full setup instructions


# profclaw init
Source: https://docs.profclaw.ai/cli/init

Initialize a new profClaw project directory with default configuration files.

## Synopsis

```bash theme={null}
profclaw init [directory] [flags]
```

## Description

`init` creates the directory structure and default configuration files needed to run profClaw. It is a lightweight alternative to `profclaw onboard` for cases where you want to manage configuration manually or integrate with an existing setup script.

For a guided first-time setup with environment detection, AI provider configuration, and admin account creation, use [`profclaw onboard`](/cli/onboard) instead.

## Arguments

<ParamField type="string">
  Directory to initialize. Defaults to the current directory. Created if it does not exist.
</ParamField>

## Flags

<ParamField type="string">
  Deployment mode to write into the generated config: `pico`, `mini`, or `pro`.
</ParamField>

<ParamField type="boolean">
  Overwrite existing configuration files. By default, `init` skips files that already exist.
</ParamField>

<ParamField type="boolean">
  Skip creating the `.env` template file.
</ParamField>

## Files Created

```
config/
  settings.yml    # Core server configuration
  agents.yml      # Agent configuration
  cron.yml        # Scheduled jobs (empty)
  pricing.yml     # Model pricing overrides
skills/           # Skills directory (empty)
data/             # Database directory (empty, created on first run)
.env.example      # Environment variable template
```

## Examples

<CodeGroup>
  ```bash Initialize current directory theme={null}
  profclaw init
  ```

  ```bash Initialize in pico mode theme={null}
  profclaw init --mode pico
  ```

  ```bash Initialize a new project directory theme={null}
  profclaw init ./my-profclaw
  ```

  ```bash Re-initialize and overwrite existing files theme={null}
  profclaw init --force
  ```

  ```bash Initialize without .env template theme={null}
  profclaw init --no-env
  ```
</CodeGroup>

## After Initializing

```bash theme={null}
# Copy and edit the env template
cp .env.example .env
# Add your API keys and configuration

# Run the interactive setup wizard
profclaw onboard

# Or start directly if already configured
profclaw serve
```

## Related

* [`profclaw onboard`](/cli/onboard) - Guided setup wizard (recommended for first-time setup)
* [`profclaw serve`](/cli/serve) - Start the server
* [`profclaw doctor`](/cli/doctor) - Verify environment after init
* [Configuration Reference](/configuration) - All settings documentation


# profclaw jira
Source: https://docs.profclaw.ai/cli/jira

Manage Jira integration - connect projects, sync tickets, and configure automation triggers.

## Synopsis

```bash theme={null}
profclaw jira <subcommand> [flags]
```

## Description

`jira` manages the profClaw Jira integration. Once configured, profClaw can watch for new tickets, respond to status changes, and assign agent tasks to work on Jira issues. The integration uses the Jira Cloud REST API with OAuth 2.0 or API token authentication.

## Subcommands

| Subcommand       | Description                             |
| ---------------- | --------------------------------------- |
| `status`         | Show Jira connection and project status |
| `connect`        | Configure Jira credentials and project  |
| `disconnect`     | Remove the Jira integration             |
| `projects`       | List connected Jira projects            |
| `sync <project>` | Manually sync issues from a project     |
| `issues`         | List synced Jira issues                 |

## `jira connect`

<ParamField type="string">
  Jira Cloud URL (e.g., `https://myorg.atlassian.net`).
</ParamField>

<ParamField type="string">
  Atlassian account email used for API token auth.
</ParamField>

<ParamField type="string">
  Jira API token. Generate at `id.atlassian.com/manage-profile/security/api-tokens`.
</ParamField>

<ParamField type="string">
  Jira project key to connect (e.g., `ENG`, `PLATFORM`).
</ParamField>

## `jira sync <project>`

<ParamField type="string">
  Jira project key to sync.
</ParamField>

<ParamField type="string">
  Filter by issue status (e.g., `"To Do"`, `"In Progress"`).
</ParamField>

<ParamField type="string">
  Filter by Jira label.
</ParamField>

<ParamField type="string">
  Maximum issues to sync.
</ParamField>

## Examples

<CodeGroup>
  ```bash Check Jira integration status theme={null}
  profclaw jira status
  ```

  ```bash Connect to Jira theme={null}
  profclaw jira connect \
    --url https://myorg.atlassian.net \
    --email admin@myorg.com \
    --token ATATT... \
    --project ENG
  ```

  ```bash List connected projects theme={null}
  profclaw jira projects
  ```

  ```bash Sync issues from a project theme={null}
  profclaw jira sync ENG
  ```

  ```bash Sync only "To Do" issues theme={null}
  profclaw jira sync ENG --status "To Do"
  ```

  ```bash List synced issues theme={null}
  profclaw jira issues
  ```

  ```bash Disconnect Jira theme={null}
  profclaw jira disconnect
  ```
</CodeGroup>

## Environment Variables

```bash theme={null}
JIRA_URL=https://myorg.atlassian.net
JIRA_EMAIL=admin@myorg.com
JIRA_API_TOKEN=ATATT...
```

## Related

* [`profclaw github`](/cli/github) - GitHub integration
* [`profclaw linear`](/cli/linear) - Linear integration
* [`profclaw sync`](/cli/sync) - Cross-platform sync
* [Jira Integration Guide](/integrations/jira) - OAuth setup and field mapping


# profclaw linear
Source: https://docs.profclaw.ai/cli/linear

Manage Linear integration - connect workspaces, sync issues, and automate ticket workflows.

## Synopsis

```bash theme={null}
profclaw linear <subcommand> [flags]
```

## Description

`linear` manages the profClaw Linear integration. Linear is a modern project management tool popular with engineering teams. Once connected, profClaw can watch for new issues, respond to status transitions, and assign agent tasks to work on Linear tickets.

## Subcommands

| Subcommand    | Description                            |
| ------------- | -------------------------------------- |
| `status`      | Show Linear connection and team status |
| `connect`     | Configure Linear API key and team      |
| `disconnect`  | Remove the Linear integration          |
| `teams`       | List connected Linear teams            |
| `sync <team>` | Manually sync issues from a team       |
| `issues`      | List synced Linear issues              |

## `linear connect`

<ParamField type="string">
  Linear API key. Generate at `linear.app/settings/api`.
</ParamField>

<ParamField type="string">
  Linear team ID or key to connect.
</ParamField>

## `linear sync <team>`

<ParamField type="string">
  Team ID or key to sync issues from.
</ParamField>

<ParamField type="string">
  Filter by issue state name (e.g., `Todo`, `In Progress`, `Backlog`).
</ParamField>

<ParamField type="string">
  Filter by issue label.
</ParamField>

<ParamField type="string">
  Maximum issues to sync.
</ParamField>

## Examples

<CodeGroup>
  ```bash Check Linear integration status theme={null}
  profclaw linear status
  ```

  ```bash Connect to Linear theme={null}
  profclaw linear connect --token lin_api_... --team ENG
  ```

  ```bash List teams theme={null}
  profclaw linear teams
  ```

  ```bash Sync issues from a team theme={null}
  profclaw linear sync ENG
  ```

  ```bash Sync only Todo issues theme={null}
  profclaw linear sync ENG --state Todo
  ```

  ```bash List synced issues theme={null}
  profclaw linear issues
  ```

  ```bash Disconnect Linear theme={null}
  profclaw linear disconnect
  ```
</CodeGroup>

## Automation Triggers

When connected, profClaw can respond to Linear webhooks:

| Event            | Action                                        |
| ---------------- | --------------------------------------------- |
| `Issue.create`   | Dispatch agent task for new issues            |
| `Issue.update`   | Trigger on state change (e.g., "In Progress") |
| `Comment.create` | Respond to `@profclaw` mentions               |

## Environment Variables

```bash theme={null}
LINEAR_API_KEY=lin_api_...
LINEAR_WEBHOOK_SECRET=...
```

## Related

* [`profclaw github`](/cli/github) - GitHub integration
* [`profclaw jira`](/cli/jira) - Jira integration
* [`profclaw sync`](/cli/sync) - Cross-platform sync
* [Linear Integration Guide](/integrations/linear) - Full setup instructions


# profclaw logs
Source: https://docs.profclaw.ai/cli/logs

View and stream server logs with filtering by level, component, and time range.

## Synopsis

```bash theme={null}
profclaw logs [flags]
```

## Description

`logs` fetches structured log entries from the running profClaw server. Logs can be filtered by level, component, and recency. In follow mode (`--follow`), it connects to the server's SSE log stream and prints new entries as they arrive.

## Flags

<ParamField type="string">
  Filter by log level. One of `debug`, `info`, `warn`, `error`. Shows only entries at or above the specified level.
</ParamField>

<ParamField type="string">
  Filter by component name (e.g., `queue`, `executor`, `chat`, `cron`).
</ParamField>

<ParamField type="string">
  Show logs from this time window. Format: `30m`, `2h`, `1d`. Defaults to the last hour.
</ParamField>

<ParamField type="string">
  Maximum number of log entries to return (non-follow mode).
</ParamField>

<ParamField type="boolean">
  Stream new log entries as they arrive via Server-Sent Events. Press `Ctrl+C` to stop.
</ParamField>

<ParamField type="boolean">
  Output as JSON. In follow mode each event is printed as a JSON line.
</ParamField>

## Examples

<CodeGroup>
  ```bash Show last hour of logs theme={null}
  profclaw logs
  ```

  ```bash Show only errors theme={null}
  profclaw logs --level error
  ```

  ```bash Show logs from a specific component theme={null}
  profclaw logs --component queue
  profclaw logs --component executor
  ```

  ```bash Show last 30 minutes of warnings and errors theme={null}
  profclaw logs --level warn --since 30m
  ```

  ```bash Show last 200 entries theme={null}
  profclaw logs --limit 200
  ```

  ```bash Follow live log stream theme={null}
  profclaw logs --follow
  ```

  ```bash Follow errors only theme={null}
  profclaw logs --follow --level error
  ```

  ```bash Stream logs as JSON (for log aggregators) theme={null}
  profclaw logs --follow --json
  ```
</CodeGroup>

## Log Levels

| Level   | Color  | Description                                  |
| ------- | ------ | -------------------------------------------- |
| `debug` | dim    | Verbose internal state, used for development |
| `info`  | blue   | Normal operational events                    |
| `warn`  | yellow | Non-fatal issues that need attention         |
| `error` | red    | Errors that affect functionality             |

## Daemon Logs

When running profClaw as a daemon, logs go to the system journal (Linux) or flat files (macOS). Use these commands to access them:

```bash theme={null}
# macOS daemon logs
profclaw daemon logs --follow
profclaw daemon logs --errors

# Linux daemon logs
journalctl --user -u profclaw -f
```

## Related

* [`profclaw daemon logs`](/cli/daemon) - Logs when running as a system service
* [`profclaw status`](/cli/status) - System health overview
* [`profclaw doctor`](/cli/doctor) - Diagnose issues


# profclaw mcp
Source: https://docs.profclaw.ai/cli/mcp

Manage MCP (Model Context Protocol) server connections and expose profClaw as an MCP server.

## Synopsis

```bash theme={null}
profclaw mcp <subcommand> [flags]
```

## Description

`mcp` manages connections to external MCP (Model Context Protocol) servers and can run profClaw itself as an MCP server. MCP servers expose tools that agents can call during execution. profClaw can connect to multiple MCP servers simultaneously, making all their tools available to agents.

## Subcommands

| Subcommand          | Alias   | Description                                            |
| ------------------- | ------- | ------------------------------------------------------ |
| `status`            | -       | Show connection status for all configured MCP servers  |
| `list-tools`        | `tools` | List all tools from connected MCP servers              |
| `connect <name>`    | -       | Connect to a configured MCP server                     |
| `disconnect <name>` | -       | Disconnect from an MCP server                          |
| `serve`             | -       | Start profClaw as a standalone MCP server (stdio mode) |

## `mcp status`

<ParamField type="boolean">
  Output as JSON with server name, transport, connection status, and tool count.
</ParamField>

## `mcp list-tools`

Lists all tools currently available from connected MCP servers, grouped by server.

<ParamField type="boolean">
  Output as JSON with tool name, server, and description.
</ParamField>

## `mcp connect <name>`

<ParamField type="string">
  Name of the MCP server as defined in your profClaw config.
</ParamField>

<ParamField type="boolean">
  Output connection result as JSON.
</ParamField>

## `mcp disconnect <name>`

<ParamField type="string">
  Name of the MCP server to disconnect.
</ParamField>

## `mcp serve`

Starts profClaw as a standalone MCP server over stdio. Use this to connect profClaw's tools to Claude Desktop, Cursor, or any other MCP-compatible client. Requires a production build (`pnpm build`).

## Examples

<CodeGroup>
  ```bash Show all MCP server connections theme={null}
  profclaw mcp status
  ```

  ```bash List tools from all connected servers theme={null}
  profclaw mcp list-tools
  ```

  ```bash Connect to a configured server theme={null}
  profclaw mcp connect filesystem
  profclaw mcp connect github
  ```

  ```bash Disconnect from a server theme={null}
  profclaw mcp disconnect filesystem
  ```

  ```bash Run profClaw as an MCP server (for Claude Desktop) theme={null}
  profclaw mcp serve
  ```

  ```bash Check status as JSON theme={null}
  profclaw mcp status --json | jq '.servers[] | select(.connected)'
  ```
</CodeGroup>

## MCP Server Configuration

Configure MCP servers in `config/settings.yml`:

```yaml theme={null}
mcp:
  servers:
    - name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    - name: github
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"
```

## Claude Desktop Integration

To use profClaw tools in Claude Desktop, add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "profclaw": {
      "command": "profclaw",
      "args": ["mcp", "serve"]
    }
  }
}
```

## Related

* [`profclaw tools`](/cli/tools) - Built-in tools (no MCP server needed)
* [`profclaw plugins`](/cli/plugins) - Plugins can also provide tools
* [MCP Integration Guide](/guides/mcp) - Setting up MCP connections


# profclaw memory
Source: https://docs.profclaw.ai/cli/memory

Manage the profClaw memory index - search, sync, list indexed files, and clear stored context.

## Synopsis

```bash theme={null}
profclaw memory <subcommand> [flags]
```

## Description

`memory` manages profClaw's context memory index. The memory system indexes files and conversation history into chunks that are retrieved during agent execution to provide relevant context. Commands let you search the index, trigger a sync from disk, inspect what is indexed, and clear everything.

## Subcommands

| Subcommand       | Alias | Description                            |
| ---------------- | ----- | -------------------------------------- |
| `search <query>` | -     | Search memory for relevant chunks      |
| `stats`          | -     | Show index statistics                  |
| `sync`           | -     | Sync memory index from disk files      |
| `files`          | `ls`  | List all indexed files                 |
| `clear`          | -     | Delete all memory chunks and the index |

## `memory search <query>`

Performs a semantic search over the memory index and returns the most relevant chunks.

<ParamField type="string">
  Search query string. Matched semantically against indexed content.
</ParamField>

<ParamField type="string">
  Maximum number of chunks to return.
</ParamField>

<ParamField type="boolean">
  Output as JSON with scores, file paths, and content.
</ParamField>

## `memory stats`

<ParamField type="boolean">
  Output statistics as JSON including chunk count, file count, token estimate, embedding model, and last sync time.
</ParamField>

## `memory sync`

Crawls the configured memory directories and updates the index - adding new files, updating changed files, and removing deleted files.

<ParamField type="boolean">
  Output sync result as JSON with counts for added, updated, and removed chunks.
</ParamField>

## `memory clear`

<ParamField type="boolean">
  Skip the confirmation prompt. Required for non-interactive use.
</ParamField>

<ParamField type="boolean">
  Output `{"ok": true}` on success.
</ParamField>

<Warning>
  `memory clear` permanently deletes all indexed content. The index must be rebuilt from disk with `memory sync`.
</Warning>

## Examples

<CodeGroup>
  ```bash Search memory theme={null}
  profclaw memory search "authentication flow"
  ```

  ```bash Search with more results theme={null}
  profclaw memory search "database schema" --limit 20
  ```

  ```bash Show index stats theme={null}
  profclaw memory stats
  ```

  ```bash Sync index from disk theme={null}
  profclaw memory sync
  ```

  ```bash List indexed files theme={null}
  profclaw memory files
  ```

  ```bash Clear all memory (with confirmation) theme={null}
  profclaw memory clear
  ```

  ```bash Clear without prompt (non-interactive) theme={null}
  profclaw memory clear --yes
  ```
</CodeGroup>

## Related

* [`profclaw summary`](/cli/summary) - Browse AI work summaries (separate from memory)
* [`profclaw status`](/cli/status) - Shows memory chunk count in the overview
* [Memory Configuration](/configuration) - Configure which directories to index


# profclaw models
Source: https://docs.profclaw.ai/cli/models

profclaw models - list available AI models across providers, view model details, manage aliases, test models, and set the default for chat sessions.

## Synopsis

```bash theme={null}
profclaw models <subcommand> [flags]
```

## Description

List available AI models across all configured providers, view model details, manage aliases, and set the default model for chat sessions.

## Subcommands

| Subcommand            | Alias | Description                      |
| --------------------- | ----- | -------------------------------- |
| `list`                | `ls`  | List available models            |
| `info <model>`        |       | Show detailed model information  |
| `set-default <model>` |       | Set the default model            |
| `aliases`             |       | List model aliases               |
| `test <model>`        |       | Test a model with a quick prompt |

## Flags

| Flag                | Type    | Description        |
| ------------------- | ------- | ------------------ |
| `--provider <name>` | string  | Filter by provider |
| `--json`            | boolean | Output as JSON     |

## Examples

<CodeGroup>
  ```bash List all models theme={null}
  profclaw models list
  ```

  ```bash List models from a specific provider theme={null}
  profclaw models list --provider ollama
  ```

  ```bash View model info theme={null}
  profclaw models info claude-sonnet-4-6
  ```

  ```bash Set default model theme={null}
  profclaw models set-default claude-sonnet-4-6
  ```

  ```bash View aliases theme={null}
  profclaw models aliases
  # sonnet -> claude-sonnet-4-6
  # opus -> claude-opus-4-6
  # gpt4 -> gpt-4o
  ```

  ```bash Test a model theme={null}
  profclaw models test llama3.2
  ```
</CodeGroup>

## Related

* [AI Providers Overview](/ai-providers/overview)
* [profclaw provider](/cli/provider)


# profclaw onboard
Source: https://docs.profclaw.ai/cli/onboard

Zero-to-running onboarding wizard - environment detection, mode selection, provider setup, and server start in one command.

## Synopsis

```bash theme={null}
profclaw onboard [flags]
```

## Description

`onboard` is the recommended first command to run after installing profClaw. It walks through a 6-step wizard:

1. **Environment Detection** - scans for Node.js, Redis, Ollama, Claude CLI, Git, Docker
2. **Deployment Mode** - recommends `pico`, `mini`, or `pro` based on available resources
3. **AI Provider** - configure Anthropic, OpenAI, or Ollama (or skip for later)
4. **Configuration** - generates `.env` and `config/settings.yml`
5. **Setup** - creates the admin account and database
6. **Validation** - verifies all required files were created

## Flags

<ParamField type="boolean">
  Run without prompts. Useful for Docker builds, CI pipelines, and automated deployments. Uses defaults or values from other flags.
</ParamField>

<ParamField type="string">
  Deployment mode to configure. One of `pico`, `mini`, or `pro`. If omitted in interactive mode, recommended based on detected resources.
</ParamField>

<ParamField type="string">
  AI provider to configure in non-interactive mode. One of `anthropic`, `openai`, `ollama`. API keys must already be set as environment variables.
</ParamField>

<ParamField type="string">
  Server port to write into the generated `.env` file.
</ParamField>

## Examples

<CodeGroup>
  ```bash Interactive (recommended for first-time setup) theme={null}
  profclaw onboard
  ```

  ```bash Non-interactive (CI / Docker) theme={null}
  profclaw onboard --non-interactive --mode mini
  ```

  ```bash Non-interactive with Anthropic theme={null}
  ANTHROPIC_API_KEY=sk-ant-... profclaw onboard --non-interactive --mode mini --provider anthropic
  ```

  ```bash Pro mode with Redis theme={null}
  REDIS_URL=redis://localhost:6379 profclaw onboard --non-interactive --mode pro
  ```
</CodeGroup>

## Deployment Modes

| Mode   | RAM      | Use case                                                     |
| ------ | -------- | ------------------------------------------------------------ |
| `pico` | \~50 MB  | Agent + tools only, IoT, edge devices, personal use          |
| `mini` | \~150 MB | Dashboard, cron, integrations - small teams and home servers |
| `pro`  | \~300 MB | Everything, requires Redis - production and enterprise       |

## What Gets Created

After onboarding succeeds:

```
.env                     # Environment configuration
config/settings.yml      # Server settings
data/profclaw.db         # SQLite database
```

## After Onboarding

```bash theme={null}
profclaw serve           # Start the server
profclaw doctor          # Verify everything is healthy
profclaw chat            # Start an interactive chat session
```

## Related

* [`profclaw init`](/cli/init) - Lightweight init without the wizard
* [`profclaw doctor`](/cli/doctor) - Diagnose environment issues
* [`profclaw serve`](/cli/serve) - Start the HTTP server
* [`profclaw config`](/cli/config) - Manage configuration


# CLI Overview
Source: https://docs.profclaw.ai/cli/overview

The profClaw command-line interface - manage every aspect of your AI agent engine from the terminal.

## Installation

<CodeGroup>
  ```bash npm (global) theme={null}
  npm install -g profclaw
  ```

  ```bash pnpm (global) theme={null}
  pnpm add -g profclaw
  ```

  ```bash From source theme={null}
  git clone https://github.com/profclaw/profclaw
  cd profclaw
  pnpm install && pnpm build
  npm link
  ```
</CodeGroup>

## Verify Installation

```bash theme={null}
profclaw --version
profclaw doctor
```

## Quick Setup

<Steps>
  <Step title="Initialize">
    ```bash theme={null}
    profclaw init
    ```

    Creates the default configuration files in the current directory.
  </Step>

  <Step title="Run the onboarding wizard">
    ```bash theme={null}
    profclaw onboard
    ```

    Detects your environment, selects the right deployment mode, and configures your first AI provider.
  </Step>

  <Step title="Start the server">
    ```bash theme={null}
    profclaw serve
    ```

    Starts the HTTP API server on port 3000 (configurable with `-p`).
  </Step>
</Steps>

## Global Flags

These flags are available on every command.

<ParamField type="boolean">
  Show help text for the command.
</ParamField>

<ParamField type="boolean">
  Print the installed profClaw version and exit.
</ParamField>

<ParamField type="boolean">
  Output raw JSON instead of formatted tables. Available on most subcommands. Useful for scripting and piping to `jq`.
</ParamField>

## Environment Variables

The CLI reads these variables for its own configuration (separate from the server).

| Variable             | Default                 | Description                                |
| -------------------- | ----------------------- | ------------------------------------------ |
| `PROFCLAW_API_URL`   | `http://localhost:3000` | URL of the profClaw server                 |
| `PROFCLAW_API_TOKEN` | -                       | Bearer token for API authentication        |
| `PROFCLAW_MODE`      | `mini`                  | Deployment mode (`pico`, `mini`, `pro`)    |
| `PORT`               | `3000`                  | Server port (used by `serve` and `daemon`) |

Set API credentials permanently:

```bash theme={null}
profclaw config set apiUrl http://my-server:3000
profclaw config login --token eyJ...
```

Or via environment:

```bash theme={null}
export PROFCLAW_API_URL=http://my-server:3000
export PROFCLAW_API_TOKEN=eyJ...
```

## Command Groups

| Group                                               | Description                |
| --------------------------------------------------- | -------------------------- |
| [`init`](/cli/init) / [`onboard`](/cli/onboard)     | First-run setup            |
| [`serve`](/cli/serve) / [`daemon`](/cli/daemon)     | Run the server             |
| [`chat`](/cli/chat)                                 | Interactive AI chat        |
| [`agent`](/cli/agent) / [`task`](/cli/task)         | Agent and task management  |
| [`config`](/cli/config)                             | Configuration management   |
| [`auth`](/cli/auth)                                 | User and invite management |
| [`skill`](/cli/skills) / [`plugin`](/cli/plugins)   | Extend functionality       |
| [`tools`](/cli/tools) / [`mcp`](/cli/mcp)           | Tool and MCP management    |
| [`memory`](/cli/memory) / [`summary`](/cli/summary) | Knowledge and history      |
| [`cost`](/cli/cost) / [`status`](/cli/status)       | Monitoring                 |
| [`security`](/cli/security) / [`audit`](/cli/audit) | Security management        |
| [`doctor`](/cli/doctor) / [`logs`](/cli/logs)       | Diagnostics                |
| [`device`](/cli/device)                             | Device pairing             |
| [`backup`](/cli/backup) / [`reset`](/cli/reset)     | Data management            |
| [`update`](/cli/update) / [`version`](/cli/version) | Lifecycle                  |

## Shell Completion

Generate shell completion scripts to enable tab completion.

<CodeGroup>
  ```bash bash theme={null}
  profclaw completion bash >> ~/.bashrc
  source ~/.bashrc
  ```

  ```bash zsh theme={null}
  profclaw completion zsh >> ~/.zshrc
  source ~/.zshrc
  ```

  ```bash fish theme={null}
  profclaw completion fish > ~/.config/fish/completions/profclaw.fish
  ```
</CodeGroup>

## Related

* [Getting Started](/getting-started/installation) - Full installation guide
* [Configuration](/configuration) - Configuration reference
* [`profclaw doctor`](/cli/doctor) - Diagnose environment issues
* [`profclaw onboard`](/cli/onboard) - Interactive setup wizard


# profclaw plugin
Source: https://docs.profclaw.ai/cli/plugins

Install, uninstall, list, create, and search profClaw plugins from npm and ClawHub.

## Synopsis

```bash theme={null}
profclaw plugin <subcommand> [flags]
```

## Description

`plugin` manages the profClaw plugin ecosystem. Plugins extend profClaw with new tools, chat channels, integrations, and skills. They can be installed from npm (packages named `profclaw-plugin-*`) or from ClawHub (the community skill registry). You can also scaffold new plugins from templates.

## Subcommands

| Subcommand            | Description                             |
| --------------------- | --------------------------------------- |
| `list`                | List installed plugins from all sources |
| `install <package>`   | Install a plugin from npm               |
| `uninstall <package>` | Uninstall a plugin                      |
| `search [query]`      | Search npm and ClawHub for plugins      |
| `create <name>`       | Scaffold a new plugin project           |

## `plugin list`

Shows plugins from three sources: loaded plugin directories, marketplace-tracked installs, and ClawHub skills.

<ParamField type="boolean">
  Also show ClawHub-installed skills in the output.
</ParamField>

## `plugin install <package>`

Installs a plugin from npm. The package name is resolved automatically: `github` becomes `profclaw-plugin-github`.

<ParamField type="string">
  Package name. Can be short form (`github`) or full form (`profclaw-plugin-github`).
</ParamField>

<ParamField type="string">
  Specific version to install (e.g., `1.2.3`). Defaults to latest.
</ParamField>

## `plugin uninstall <package>`

<ParamField type="string">
  Package name to uninstall (short or full form).
</ParamField>

## `plugin search [query]`

Searches both npm and ClawHub for plugins matching the query. Returns package names, descriptions, and categories.

<ParamField type="string">
  Search terms. Omit to browse all available plugins.
</ParamField>

<ParamField type="boolean">
  Search npm packages only.
</ParamField>

<ParamField type="boolean">
  Search ClawHub only.
</ParamField>

## `plugin create <name>`

Scaffolds a new plugin project with the correct structure, `package.json`, and example code.

<ParamField type="string">
  Plugin name (without the `profclaw-plugin-` prefix). Creates `profclaw-plugin-<name>/`.
</ParamField>

<ParamField type="string">
  Plugin type: `tool`, `channel`, `integration`, or `skill`.
</ParamField>

<ParamField type="string">
  Plugin description for `package.json`.
</ParamField>

<ParamField type="string">
  Author name for `package.json`.
</ParamField>

<ParamField type="string">
  Output directory. Defaults to `./profclaw-plugin-<name>/`.
</ParamField>

## Examples

<CodeGroup>
  ```bash Search for plugins theme={null}
  profclaw plugin search
  profclaw plugin search github
  profclaw plugin search --clawhub-only
  ```

  ```bash Install a plugin (short name) theme={null}
  profclaw plugin install github
  ```

  ```bash Install a specific version theme={null}
  profclaw plugin install github --version 1.2.0
  ```

  ```bash List installed plugins theme={null}
  profclaw plugin list
  profclaw plugin list --clawhub
  ```

  ```bash Uninstall a plugin theme={null}
  profclaw plugin uninstall github
  ```

  ```bash Scaffold a new tool plugin theme={null}
  profclaw plugin create my-tool --type tool --description "My custom tool"
  ```

  ```bash Scaffold a channel integration theme={null}
  profclaw plugin create slack-extended --type channel --author "myorg"
  ```
</CodeGroup>

## Plugin Types

| Type          | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| `tool`        | Adds new tools to the agent execution registry                |
| `channel`     | Adds a new chat channel provider (e.g., a messaging platform) |
| `integration` | Connects to an external service (ticketing, CI/CD, etc.)      |
| `skill`       | Adds pre-built AI skill definitions                           |

## Plugin Directories

Plugins are loaded from:

```
~/.profclaw/plugins/    # User-installed plugins
./plugins/              # Project-local plugins
node_modules/profclaw-plugin-*/  # npm-installed plugins
```

## Related

* [`profclaw skill`](/cli/skills) - Manage skills (some provided by plugins)
* [`profclaw tools`](/cli/tools) - Built-in tools
* [`profclaw mcp`](/cli/mcp) - MCP server integrations
* [Plugin Development Guide](/plugins) - Building and publishing plugins


# profclaw provider
Source: https://docs.profclaw.ai/cli/provider

profclaw provider - add, remove, test, and configure AI provider connections. Set the default provider and list available models from any provider.

## Synopsis

```bash theme={null}
profclaw provider <subcommand> [flags]
```

## Description

Add, remove, and test AI provider configurations. Manage which providers are active and set the default provider for chat sessions.

## Subcommands

| Subcommand       | Alias | Description                            |
| ---------------- | ----- | -------------------------------------- |
| `list`           | `ls`  | List configured AI providers           |
| `add <type>`     |       | Add and configure an AI provider       |
| `remove <type>`  |       | Remove a provider configuration        |
| `test [type]`    |       | Test provider health (all or specific) |
| `default [type]` |       | Get or set the default provider        |
| `models [type]`  |       | List available models                  |

## Flags

| Flag     | Type    | Description                |
| -------- | ------- | -------------------------- |
| `--yes`  | boolean | Skip confirmation (remove) |
| `--json` | boolean | Output as JSON             |

## Examples

<CodeGroup>
  ```bash List providers theme={null}
  profclaw provider list
  ```

  ```bash Add Ollama theme={null}
  profclaw provider add ollama
  ```

  ```bash Test all providers theme={null}
  profclaw provider test
  ```

  ```bash Set default theme={null}
  profclaw provider default anthropic
  ```

  ```bash List models for a provider theme={null}
  profclaw provider models openai
  ```
</CodeGroup>

## Related

* [AI Providers Overview](/ai-providers/overview)
* [Configuration](/configuration/overview)
* [profclaw models](/cli/models)


# profclaw queue
Source: https://docs.profclaw.ai/cli/queue

Inspect and manage the profClaw task queue - view pending jobs, drain the queue, and check queue health.

## Synopsis

```bash theme={null}
profclaw queue <subcommand> [flags]
```

## Description

`queue` provides visibility into profClaw's task execution queue. In `mini` mode, an in-memory queue is used. In `pro` mode, BullMQ with Redis is used for durability and distributed processing. Queue commands let you see what is waiting, pause processing, drain failed jobs, and check queue health metrics.

## Subcommands

| Subcommand     | Description                                                |
| -------------- | ---------------------------------------------------------- |
| `status`       | Show queue health, counts by state, and throughput metrics |
| `list [state]` | List jobs in a specific state                              |
| `drain`        | Remove all completed and failed jobs                       |
| `pause`        | Pause job processing                                       |
| `resume`       | Resume paused job processing                               |
| `retry-all`    | Requeue all failed jobs                                    |

## `queue status`

Shows queue state counts (waiting, active, completed, failed, delayed), current workers, and throughput.

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `queue list [state]`

<ParamField type="string">
  Job state to list: `waiting`, `active`, `completed`, `failed`, `delayed`.
</ParamField>

<ParamField type="string">
  Maximum jobs to show.
</ParamField>

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `queue drain`

Removes stale completed and failed jobs to free memory (in-memory mode) or Redis storage (pro mode).

<ParamField type="boolean">
  Only remove failed jobs.
</ParamField>

<ParamField type="boolean">
  Only remove completed jobs.
</ParamField>

## Examples

<CodeGroup>
  ```bash Check queue health theme={null}
  profclaw queue status
  ```

  ```bash List waiting jobs theme={null}
  profclaw queue list waiting
  ```

  ```bash List failed jobs theme={null}
  profclaw queue list failed
  ```

  ```bash Retry all failed jobs theme={null}
  profclaw queue retry-all
  ```

  ```bash Drain old completed jobs theme={null}
  profclaw queue drain --completed-only
  ```

  ```bash Pause the queue (maintenance) theme={null}
  profclaw queue pause
  ```

  ```bash Resume processing theme={null}
  profclaw queue resume
  ```

  ```bash Export queue status as JSON theme={null}
  profclaw queue status --json
  ```
</CodeGroup>

## Queue Modes

| Mode            | Backend        | Persistence            | Workers          |
| --------------- | -------------- | ---------------------- | ---------------- |
| `pico` / `mini` | In-memory      | None (lost on restart) | Single process   |
| `pro`           | BullMQ + Redis | Durable                | Multiple workers |

## Related

* [`profclaw task`](/cli/task) - View and manage individual tasks
* [`profclaw status`](/cli/status) - System overview
* [Deployment Modes](/getting-started/deployment-modes) - Queue configuration per mode


# profclaw reset
Source: https://docs.profclaw.ai/cli/reset

Reset profClaw configuration, database, or the complete installation to factory defaults.

## Synopsis

```bash theme={null}
profclaw reset [flags]
```

## Description

`reset` removes profClaw's persistent state. Use it to start fresh after a failed setup, before reinstalling, or to wipe data from a development environment. It can selectively reset CLI config, server settings, the database, the memory index, or everything at once.

<Warning>
  `reset` is destructive and cannot be undone. Run `profclaw backup create` before resetting if you need to preserve data.
</Warning>

## Flags

<ParamField type="boolean">
  Reset CLI config (`~/.profclaw/config.json`) to defaults. API URL reverts to `http://localhost:3000`.
</ParamField>

<ParamField type="boolean">
  Reset server settings (`config/settings.yml`) to defaults.
</ParamField>

<ParamField type="boolean">
  Delete the SQLite database (`data/profclaw.db`). All users, tasks, conversations, and sessions are lost.
</ParamField>

<ParamField type="boolean">
  Clear the memory index. Files on disk are not deleted, but the index must be rebuilt with `profclaw memory sync`.
</ParamField>

<ParamField type="boolean">
  Reset everything: config, settings, database, and memory index.
</ParamField>

<ParamField type="boolean">
  Skip all confirmation prompts. Required for non-interactive use.
</ParamField>

## Examples

<CodeGroup>
  ```bash Reset CLI config only theme={null}
  profclaw reset --config
  ```

  ```bash Reset server settings to defaults theme={null}
  profclaw reset --settings
  ```

  ```bash Delete the database (fresh start) theme={null}
  profclaw reset --db
  ```

  ```bash Full reset (wipe everything) theme={null}
  profclaw reset --all
  ```

  ```bash Full reset without prompts (CI / reinstall scripts) theme={null}
  profclaw reset --all --yes
  ```

  ```bash Recommended before a full reinstall theme={null}
  profclaw backup create
  profclaw reset --all --yes
  profclaw onboard
  ```
</CodeGroup>

## After Resetting

If you reset the database or all data, you must run `onboard` or `setup` again to create the admin account and configure providers:

```bash theme={null}
profclaw onboard
# or
profclaw serve &
profclaw setup   # web-based setup wizard
```

## Related

* [`profclaw backup`](/cli/backup) - Back up before resetting
* [`profclaw onboard`](/cli/onboard) - Re-run after a full reset
* [`profclaw config reset`](/cli/config) - Reset CLI config via the config command


# profclaw security
Source: https://docs.profclaw.ai/cli/security

Manage security policies, review audit logs, and approve or deny pending tool execution requests.

## Synopsis

```bash theme={null}
profclaw security <subcommand> [flags]
```

## Description

`security` manages profClaw's security enforcement layer. Three policy levels control how strictly tool execution is governed. In `standard` and `strict` modes, certain tool calls require explicit approval before they run. This command lets you view the current policy, change it, review the audit log, and approve or deny pending requests.

## Subcommands

| Subcommand           | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `status`             | Show current policy level and pending approval count             |
| `set-policy <level>` | Set the security policy to `permissive`, `standard`, or `strict` |
| `audit`              | View the security audit log                                      |
| `approve <id>`       | Approve a pending tool execution request                         |
| `deny <id>`          | Deny a pending tool execution request                            |

## Security Policy Levels

| Level        | Description                                   |
| ------------ | --------------------------------------------- |
| `permissive` | All tools run without approval                |
| `standard`   | Moderate and dangerous tools require approval |
| `strict`     | All non-safe tools require explicit approval  |

## `security status`

<ParamField type="boolean">
  Output as JSON with policy level, pending approval count, and last audit time.
</ParamField>

## `security set-policy <level>`

<ParamField type="string">
  One of `permissive`, `standard`, or `strict`.
</ParamField>

<ParamField type="boolean">
  Output the updated status as JSON.
</ParamField>

## `security audit`

<ParamField type="string">
  Maximum number of entries to show.
</ParamField>

<ParamField type="boolean">
  Show only entries with `pending` result status (awaiting approval).
</ParamField>

<ParamField type="boolean">
  Output as JSON array.
</ParamField>

## `security approve <id>` / `security deny <id>`

<ParamField type="string">
  Audit entry ID to approve or deny.
</ParamField>

<ParamField type="string">
  Reason for denial (only for `deny` subcommand).
</ParamField>

<ParamField type="boolean">
  Output result as JSON.
</ParamField>

## Examples

<CodeGroup>
  ```bash Check security status theme={null}
  profclaw security status
  ```

  ```bash Set to strict mode theme={null}
  profclaw security set-policy strict
  ```

  ```bash Set to permissive (development) theme={null}
  profclaw security set-policy permissive
  ```

  ```bash View audit log theme={null}
  profclaw security audit
  ```

  ```bash Show only pending approvals theme={null}
  profclaw security audit --pending
  ```

  ```bash Approve a pending request theme={null}
  profclaw security approve abc12345
  ```

  ```bash Deny a pending request with reason theme={null}
  profclaw security deny abc12345 --reason "File write outside allowed directories"
  ```
</CodeGroup>

## Related

* [`profclaw audit`](/cli/audit) - Detailed audit log viewer
* [`profclaw auth`](/cli/auth) - User and authentication management
* [`profclaw device`](/cli/device) - Device pairing and trust
* [Security Guide](/security) - Security architecture and configuration


# profclaw serve
Source: https://docs.profclaw.ai/cli/serve

Start the profClaw HTTP API server with auto-restart on crash.

## Synopsis

```bash theme={null}
profclaw serve [flags]
```

## Description

`serve` starts the profClaw HTTP API server. It displays an ASCII banner, checks that the configured port is available, then spawns the server process. In production mode it monitors the child process and automatically restarts it on crash using exponential backoff (up to 5 restart attempts).

The server exposes:

* REST API at `http://localhost:<port>/api`
* Health endpoint at `http://localhost:<port>/health`
* Web UI at `http://localhost:<port>/`

## Flags

<ParamField type="string">
  Port to listen on. Must be available. If already in use, the command exits with instructions to free the port or use an alternate.
</ParamField>

<ParamField type="boolean">
  Disable scheduled cron jobs. The server starts normally but no cron triggers will fire.
</ParamField>

<ParamField type="boolean">
  Run in development mode with file watching via `tsx watch`. Auto-restarts on source changes. Disables the crash-restart loop.
</ParamField>

<ParamField type="boolean">
  Disable automatic restart on crash. Used internally by the `daemon` subcommand - the OS service manager handles restarts.
</ParamField>

## Crash Recovery

In production mode (`serve` without `--dev`), the process manager applies exponential backoff:

| Attempt | Wait |
| ------- | ---- |
| 1       | 1s   |
| 2       | 2s   |
| 3       | 4s   |
| 4       | 8s   |
| 5       | 16s  |

After 5 consecutive crashes in quick succession the process exits. Fix the underlying issue and run `profclaw serve` again.

## Examples

<CodeGroup>
  ```bash Start on default port 3000 theme={null}
  profclaw serve
  ```

  ```bash Start on a custom port theme={null}
  profclaw serve -p 8080
  ```

  ```bash Development mode with watch theme={null}
  profclaw serve --dev
  ```

  ```bash Disable cron jobs theme={null}
  profclaw serve --no-cron
  ```

  ```bash Run as a managed daemon (systemd / launchd) theme={null}
  profclaw daemon install
  profclaw daemon start
  ```
</CodeGroup>

## Environment Variables

| Variable        | Description                                          |
| --------------- | ---------------------------------------------------- |
| `PORT`          | Overrides the `--port` flag                          |
| `ENABLE_CRON`   | Set to `false` to disable cron (same as `--no-cron`) |
| `PROFCLAW_MODE` | Deployment mode (`pico`, `mini`, `pro`)              |

## Related

* [`profclaw daemon`](/cli/daemon) - Run as a system service (launchd/systemd)
* [`profclaw status`](/cli/status) - Check server health
* [`profclaw logs`](/cli/logs) - View server logs
* [`profclaw doctor`](/cli/doctor) - Diagnose startup issues


# profclaw session
Source: https://docs.profclaw.ai/cli/session

profclaw session - list, inspect, and delete chat sessions. View conversation history and clean up old sessions stored by the profClaw server.

## Synopsis

```bash theme={null}
profclaw session <subcommand> [flags]
```

## Description

Manage chat sessions, view conversation history, and clean up old sessions. Each chat interaction creates a session that persists messages and tool call history.

## Subcommands

| Subcommand  | Alias | Description                              |
| ----------- | ----- | ---------------------------------------- |
| `list`      | `ls`  | List chat sessions                       |
| `show <id>` |       | Show session details and message preview |
| `kill <id>` |       | Delete a chat session                    |
| `clear`     |       | Delete all chat sessions                 |

## Flags

| Flag              | Type    | Default | Description          |
| ----------------- | ------- | ------- | -------------------- |
| `-l, --limit <n>` | number  | 20      | Max sessions to list |
| `--yes`           | boolean |         | Skip confirmation    |
| `--json`          | boolean |         | Output as JSON       |

## Examples

<CodeGroup>
  ```bash List recent sessions theme={null}
  profclaw session list
  ```

  ```bash Show session details theme={null}
  profclaw session show sess_abc123
  ```

  ```bash Delete a session theme={null}
  profclaw session kill sess_abc123
  ```

  ```bash Clear all sessions theme={null}
  profclaw session clear --yes
  ```
</CodeGroup>

## Related

* [profclaw chat](/cli/chat)
* [Agent Sessions API](/api-reference/agent-sessions)


# profclaw setup
Source: https://docs.profclaw.ai/cli/setup

profclaw setup - interactive first-time setup wizard for creating an admin account, configuring an AI provider, and setting registration mode.

## Synopsis

```bash theme={null}
profclaw setup [flags]
```

## Description

Interactive first-time setup wizard that creates an admin account, configures an AI provider, and sets the registration mode. Designed for initial deployment configuration.

<Note>
  For a more comprehensive onboarding experience that includes environment detection and deployment mode selection, use [`profclaw onboard`](/cli/onboard) instead.
</Note>

## Flags

| Flag                          | Type    | Default | Description                                  |
| ----------------------------- | ------- | ------- | -------------------------------------------- |
| `--non-interactive`           | boolean |         | Run without prompts (for CI/Docker)          |
| `--admin-email <email>`       | string  |         | Admin email                                  |
| `--admin-password <password>` | string  |         | Admin password                               |
| `--admin-name <name>`         | string  |         | Admin display name                           |
| `--ai-provider <provider>`    | string  |         | AI provider: anthropic, openai, ollama, skip |
| `--registration-mode <mode>`  | string  |         | Registration mode: invite, open              |

## Interactive Mode

```bash theme={null}
profclaw setup
```

Walks through:

1. Admin account creation (email, password, display name)
2. AI provider selection and API key configuration
3. Registration mode (invite-only or open)

## Non-Interactive Mode

For automated deployments (Docker, CI):

```bash theme={null}
profclaw setup \
  --non-interactive \
  --admin-email admin@example.com \
  --admin-password SecurePass123! \
  --admin-name "Admin" \
  --ai-provider anthropic \
  --registration-mode invite
```

## Related

* [profclaw onboard](/cli/onboard)
* [profclaw init](/cli/init)
* [Installation Guide](/getting-started/installation)


# profclaw skill
Source: https://docs.profclaw.ai/cli/skills

List, inspect, enable, disable, and reload profClaw skills.

## Synopsis

```bash theme={null}
profclaw skill <subcommand> [flags]
```

## Description

`skill` manages profClaw's skill system. Skills are pre-built, reusable AI agent capabilities defined in `SKILL.md` files. They extend what agents can do when invoked by name (e.g., `commit`, `review-pr`, `deploy`). Skills can be enabled or disabled at runtime without restarting the server.

## Subcommands

| Subcommand       | Alias | Description                                    |
| ---------------- | ----- | ---------------------------------------------- |
| `list`           | `ls`  | List all skills with enabled status and source |
| `info <name>`    | -     | Show detailed information for a skill          |
| `enable <name>`  | -     | Enable a disabled skill                        |
| `disable <name>` | -     | Disable an enabled skill                       |
| `reload`         | -     | Hot-reload all skills from disk                |

## `skill list`

<ParamField type="boolean">
  Output as JSON with the full skill list and summary stats.
</ParamField>

## `skill info <name>`

Displays name, description, enabled status, source path, eligibility, capabilities, dependencies, and usage statistics (invocation count, average duration, last used).

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `skill enable <name>` / `skill disable <name>`

Toggles a skill on or off. The change takes effect immediately - no server restart needed.

<ParamField type="boolean">
  Output result as JSON.
</ParamField>

## `skill reload`

Rescans the `skills/` directory and reloads all skill definitions from disk. Use this after adding, editing, or removing a `SKILL.md` file without restarting the server.

<ParamField type="boolean">
  Output reload stats (loaded, failed, total) as JSON.
</ParamField>

## Examples

<CodeGroup>
  ```bash List all skills theme={null}
  profclaw skill list
  ```

  ```bash Show skill details theme={null}
  profclaw skill info commit
  profclaw skill info review-pr
  ```

  ```bash Enable a skill theme={null}
  profclaw skill enable deploy
  ```

  ```bash Disable a skill theme={null}
  profclaw skill disable web-search
  ```

  ```bash Reload after adding a new SKILL.md theme={null}
  profclaw skill reload
  ```

  ```bash List skills as JSON for scripting theme={null}
  profclaw skill list --json | jq '[.skills[] | select(.enabled)]'
  ```
</CodeGroup>

## Skill Sources

| Source    | Location                      | Description                   |
| --------- | ----------------------------- | ----------------------------- |
| `builtin` | `skills/` in profClaw install | Shipped with profClaw         |
| `local`   | `~/.profclaw/skills/`         | User-defined skills           |
| `plugin`  | Plugin package                | Provided by installed plugins |

## Built-in Skills (examples)

| Skill          | Description                                               |
| -------------- | --------------------------------------------------------- |
| `commit`       | Generate and create a git commit with a good message      |
| `review-pr`    | Code review a GitHub pull request                         |
| `deploy`       | Deploy an application using configured deployment scripts |
| `analyze-code` | Static analysis and suggestions for a codebase            |
| `fix-tests`    | Diagnose and fix failing tests                            |
| `write-docs`   | Generate documentation for code                           |

## Related

* [`profclaw plugin`](/cli/plugins) - Install plugins that provide additional skills
* [`profclaw tools`](/cli/tools) - Built-in execution tools used by skills
* [`profclaw chat`](/cli/chat) - Invoke skills in a chat session
* [Skills Guide](/skills) - Writing custom skills


# profclaw status
Source: https://docs.profclaw.ai/cli/status

Compact one-line system status overview showing server health, providers, skills, memory, and tunnels.

## Synopsis

```bash theme={null}
profclaw status [flags]
```

## Description

`status` fetches key metrics from the running profClaw server in parallel and displays a compact summary. It checks:

* Server health, version, and uptime
* Configured AI providers and their health
* Loaded skills (total and enabled count)
* Memory index statistics (chunks and files)
* Tunnel status (Cloudflare Tunnel and Tailscale)

Unlike `profclaw tui`, `status` is non-interactive and designed for quick checks from the terminal or in shell scripts.

## Flags

<ParamField type="boolean">
  Output all data as structured JSON. Includes the full response from each subsystem.
</ParamField>

## Examples

<CodeGroup>
  ```bash Quick status check theme={null}
  profclaw status
  ```

  ```bash JSON output for scripting theme={null}
  profclaw status --json
  ```

  ```bash Use in a health-check script theme={null}
  profclaw status --json | jq '.health.healthy'
  ```
</CodeGroup>

## Example Output

```
profClaw v2.0.0 | Mode: mini | Status: healthy

Providers    3 configured (anthropic, openai, ollama)
Skills       12 loaded, 10 enabled
Memory       2,841 chunks across 47 files
Tunnels      Cloudflare: active | Tailscale: not running
```

## Related

* [`profclaw tui`](/cli/tui) - Full terminal dashboard with watch mode
* [`profclaw doctor`](/cli/doctor) - Detailed diagnostics with fix suggestions
* [`profclaw agent status`](/cli/agent) - Per-agent health details
* [`profclaw logs`](/cli/logs) - View server logs


# profclaw summary
Source: https://docs.profclaw.ai/cli/summary

Browse, search, and inspect AI work summaries generated after agentic task completion.

## Synopsis

```bash theme={null}
profclaw summary <subcommand> [flags]
```

## Description

`summary` provides access to the AI-generated work summaries that profClaw creates after completing agentic tasks. Each summary captures what changed, why it changed, and how it was accomplished, along with a list of affected files. Summaries are useful for reviewing what agents have done, understanding code changes, and building institutional knowledge.

## Subcommands

| Subcommand       | Alias | Description                           |
| ---------------- | ----- | ------------------------------------- |
| `list`           | `ls`  | List recent summaries                 |
| `show <id>`      | `get` | Show full details for a summary       |
| `search <query>` | -     | Full-text search across all summaries |
| `stats`          | -     | Show aggregate statistics             |

## `summary list`

<ParamField type="string">
  Filter by agent name.
</ParamField>

<ParamField type="string">
  Maximum number of summaries to return.
</ParamField>

<ParamField type="boolean">
  Output as JSON array.
</ParamField>

## `summary show <id>`

Displays the full summary including the "What Changed", "Why", "How", and list of files modified.

<ParamField type="string">
  Summary ID or prefix.
</ParamField>

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `summary search <query>`

<ParamField type="string">
  Search terms to match against summary titles and content.
</ParamField>

<ParamField type="string">
  Maximum results to return.
</ParamField>

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `summary stats`

Shows total summary count, total tokens consumed, total cost, files changed, and a breakdown by agent.

<ParamField type="boolean">
  Output stats as JSON.
</ParamField>

## Examples

<CodeGroup>
  ```bash List recent summaries theme={null}
  profclaw summary list
  ```

  ```bash List summaries from a specific agent theme={null}
  profclaw summary list --agent claude
  ```

  ```bash Show a summary's full details theme={null}
  profclaw summary show abc12345
  ```

  ```bash Search summaries theme={null}
  profclaw summary search "authentication refactor"
  ```

  ```bash View summary statistics theme={null}
  profclaw summary stats
  ```

  ```bash Export recent summaries as JSON theme={null}
  profclaw summary list --json | jq '.[].title'
  ```
</CodeGroup>

## Related

* [`profclaw task`](/cli/task) - View task status (summaries are generated on completion)
* [`profclaw agent`](/cli/agent) - Agent health and performance stats
* [`profclaw memory`](/cli/memory) - Search the memory index


# profclaw sync
Source: https://docs.profclaw.ai/cli/sync

Synchronize issues, tasks, and state across GitHub, Jira, and Linear integrations.

## Synopsis

```bash theme={null}
profclaw sync <subcommand> [flags]
```

## Description

`sync` orchestrates cross-platform synchronization between profClaw and connected integrations (GitHub, Jira, Linear). It pulls new tickets and issues into the profClaw task queue, pushes status updates back to the source, and keeps bi-directional state in sync.

## Subcommands

| Subcommand       | Description                                         |
| ---------------- | --------------------------------------------------- |
| `all`            | Sync all configured integrations                    |
| `github [repo]`  | Sync GitHub issues (all repos or a specific one)    |
| `jira [project]` | Sync Jira tickets (all projects or a specific one)  |
| `linear [team]`  | Sync Linear issues (all teams or a specific one)    |
| `status`         | Show last sync time and result for each integration |

## `sync all`

<ParamField type="boolean">
  Show what would be synced without making changes.
</ParamField>

<ParamField type="boolean">
  Output sync results as JSON.
</ParamField>

## `sync github [repo]` / `sync jira [project]` / `sync linear [team]`

<ParamField type="boolean">
  Preview changes without applying them.
</ParamField>

<ParamField type="boolean">
  Force a full resync even if items appear unchanged.
</ParamField>

<ParamField type="string">
  Maximum items to sync per integration.
</ParamField>

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## Examples

<CodeGroup>
  ```bash Sync all integrations theme={null}
  profclaw sync all
  ```

  ```bash Preview what would be synced theme={null}
  profclaw sync all --dry-run
  ```

  ```bash Sync GitHub only theme={null}
  profclaw sync github
  ```

  ```bash Sync a specific GitHub repo theme={null}
  profclaw sync github myorg/myrepo
  ```

  ```bash Sync Jira theme={null}
  profclaw sync jira
  ```

  ```bash Sync a specific Linear team theme={null}
  profclaw sync linear ENG
  ```

  ```bash Check last sync status theme={null}
  profclaw sync status
  ```

  ```bash Force a full resync theme={null}
  profclaw sync all --force
  ```
</CodeGroup>

## Sync Configuration

Configure sync behavior per integration in `config/settings.yml`:

```yaml theme={null}
sync:
  github:
    enabled: true
    label: "profclaw"        # Only sync issues with this label
    autoCreateTasks: true    # Auto-create agent tasks for new issues
  jira:
    enabled: true
    projects: ["ENG", "OPS"]
    stateMapping:
      "Todo": pending
      "In Progress": in_progress
  linear:
    enabled: true
    autoAssign: true
```

## Related

* [`profclaw github`](/cli/github) - GitHub integration commands
* [`profclaw jira`](/cli/jira) - Jira integration commands
* [`profclaw linear`](/cli/linear) - Linear integration commands
* [`profclaw task`](/cli/task) - View synced tasks


# profclaw task
Source: https://docs.profclaw.ai/cli/task

Create, list, inspect, cancel, and retry agentic tasks.

## Synopsis

```bash theme={null}
profclaw task <subcommand> [flags]
```

## Description

`task` manages the agentic work queue. Tasks are units of work assigned to agents - they can originate from GitHub issues, Jira tickets, Linear cards, Slack messages, cron schedules, or the CLI. Each task progresses through a lifecycle: `pending` -> `queued` -> `in_progress` -> `completed` (or `failed` / `cancelled`).

## Subcommands

| Subcommand       | Alias | Description                          |
| ---------------- | ----- | ------------------------------------ |
| `list`           | `ls`  | List all tasks with filtering        |
| `show <id>`      | `get` | Show detailed information for a task |
| `create <title>` | -     | Create a new task                    |
| `cancel <id>`    | -     | Cancel a running or pending task     |
| `retry <id>`     | -     | Requeue a failed task                |
| `status [id]`    | -     | Quick status check or summary counts |

## `task list`

<ParamField type="string">
  Filter by task status: `pending`, `queued`, `in_progress`, `completed`, `failed`, `cancelled`.
</ParamField>

<ParamField type="string">
  Maximum number of tasks to return.
</ParamField>

<ParamField type="boolean">
  Output as JSON array.
</ParamField>

## `task create <title>`

<ParamField type="string">
  Task title. The title is also used as the initial prompt if no description is provided.
</ParamField>

<ParamField type="string">
  Task description / detailed prompt for the agent.
</ParamField>

<ParamField type="string">
  Priority level from 1 (critical) to 5 (low). Affects queue ordering.
</ParamField>

<ParamField type="string">
  Agent name to assign the task to. Defaults to the system's configured default agent.
</ParamField>

<ParamField type="boolean">
  Output created task as JSON.
</ParamField>

## `task show <id>`

<ParamField type="string">
  Task ID or ID prefix (first 8 characters are sufficient).
</ParamField>

<ParamField type="boolean">
  Output as JSON.
</ParamField>

## `task status [id]`

Without an ID, prints a summary count by status. With an ID, prints just the status string for that task - useful in scripts.

## Examples

<CodeGroup>
  ```bash List all tasks theme={null}
  profclaw task list
  ```

  ```bash List only failed tasks theme={null}
  profclaw task list --status failed
  ```

  ```bash Create a simple task theme={null}
  profclaw task create "Review pull request #123"
  ```

  ```bash Create a detailed task with priority theme={null}
  profclaw task create "Analyze codebase dependencies" \
    --description "Check all npm packages for outdated versions and security issues" \
    --priority 2 \
    --agent claude
  ```

  ```bash Show task details theme={null}
  profclaw task show abc12345
  ```

  ```bash Cancel a task theme={null}
  profclaw task cancel abc12345
  ```

  ```bash Retry a failed task theme={null}
  profclaw task retry abc12345
  ```

  ```bash Count tasks by status theme={null}
  profclaw task status
  ```

  ```bash Quick status check in a script theme={null}
  STATUS=$(profclaw task status abc12345)
  echo "Task is: $STATUS"
  ```
</CodeGroup>

## Task Status Values

| Status        | Description                                  |
| ------------- | -------------------------------------------- |
| `pending`     | Waiting to be picked up by the queue         |
| `queued`      | In the queue, waiting for an available agent |
| `in_progress` | Currently being executed by an agent         |
| `completed`   | Finished successfully                        |
| `failed`      | Execution ended with an error                |
| `cancelled`   | Manually cancelled before completion         |

## Related

* [`profclaw agent`](/cli/agent) - View agent health and stats
* [`profclaw queue`](/cli/queue) - Inspect the task queue
* [`profclaw summary`](/cli/summary) - Browse completed work summaries
* [`profclaw chat`](/cli/chat) - Interactive agentic chat


# profclaw ticket
Source: https://docs.profclaw.ai/cli/ticket

profclaw ticket - create, update, assign, and transition AI-native tickets. Link tickets to GitHub, Jira, and Linear and assign them to AI agents.

## Synopsis

```bash theme={null}
profclaw ticket <subcommand> [flags]
# Alias: profclaw tkt
```

## Description

Manage AI-native tickets for tracking work, bugs, and features. Tickets can be linked to external platforms (GitHub, Jira, Linear) and assigned to AI agents for automated processing.

## Subcommands

| Subcommand                           | Alias  | Description                      |
| ------------------------------------ | ------ | -------------------------------- |
| `list`                               | `ls`   | List all tickets                 |
| `show <id>`                          | `get`  | Show ticket details              |
| `create <title>`                     |        | Create a new ticket              |
| `update <id>`                        |        | Update a ticket                  |
| `transition <id> <status>`           | `move` | Change ticket status             |
| `assign <id> <agent>`                |        | Assign ticket to an AI agent     |
| `comment <id> <content>`             |        | Add a comment to a ticket        |
| `link <id> <platform> <external-id>` |        | Link ticket to external platform |
| `delete <id>`                        | `rm`   | Delete a ticket                  |
| `status`                             |        | Show ticket status overview      |

## Flags

| Flag                        | Type    | Default  | Description                       |
| --------------------------- | ------- | -------- | --------------------------------- |
| `-s, --status <status>`     | string  |          | Filter by status                  |
| `-t, --type <type>`         | string  | `task`   | Ticket type                       |
| `-p, --priority <priority>` | string  | `medium` | Priority level                    |
| `-d, --description <desc>`  | string  |          | Ticket description                |
| `-a, --agent <agent>`       | string  |          | Assigned AI agent                 |
| `-l, --labels <labels>`     | string  |          | Comma-separated labels            |
| `--parent <id>`             | string  |          | Parent ticket ID                  |
| `-f, --force`               | boolean |          | Force delete without confirmation |
| `--json`                    | boolean |          | Output as JSON                    |

## Examples

<CodeGroup>
  ```bash Create a ticket theme={null}
  profclaw ticket create "Fix login timeout" \
    -d "Users report 5s timeout on login" \
    -p high -t bug
  ```

  ```bash Assign to an agent theme={null}
  profclaw ticket assign TKT-42 code-reviewer
  ```

  ```bash Link to GitHub issue theme={null}
  profclaw ticket link TKT-42 github 123 \
    -u "https://github.com/org/repo/issues/123"
  ```

  ```bash Transition status theme={null}
  profclaw ticket move TKT-42 in_progress
  ```

  ```bash List high-priority bugs theme={null}
  profclaw tkt ls -t bug -p high
  ```
</CodeGroup>

## Related

* [Task Management](/cli/task)
* [GitHub Integration](/integrations/github)
* [Jira Integration](/integrations/jira)
* [Linear Integration](/integrations/linear)


# profclaw tools
Source: https://docs.profclaw.ai/cli/tools

List, inspect, and directly execute the built-in execution tools available to agents.

## Synopsis

```bash theme={null}
profclaw tools <subcommand> [flags]
```

## Description

`tools` provides direct access to profClaw's built-in tool registry without going through an agent. Tools are grouped by category (file, system, git, web, memory, etc.) and each has a security level (`safe`, `moderate`, `dangerous`). Use `tools exec` to invoke any tool directly from the CLI for testing and automation.

## Subcommands

| Subcommand              | Description                                       |
| ----------------------- | ------------------------------------------------- |
| `list`                  | List all registered tools grouped by category     |
| `info <name>`           | Show detailed information and examples for a tool |
| `exec <name>`           | Execute a tool with JSON parameters               |
| `run <command...>`      | Shortcut: run a shell command via the `exec` tool |
| `git-status`            | Shortcut: show git status                         |
| `sysinfo`               | Shortcut: show system information                 |
| `env [name]`            | Shortcut: show environment variables              |
| `which <command>`       | Shortcut: find a command in PATH                  |
| `read <path>`           | Shortcut: read a file                             |
| `find <pattern>`        | Shortcut: search for files by name pattern        |
| `grep <pattern> [path]` | Shortcut: search file contents                    |

## `tools list`

<ParamField type="string">
  Filter by category (e.g., `file`, `system`, `git`, `web`, `memory`).
</ParamField>

<ParamField type="boolean">
  Output as JSON array with name, description, category, and security level.
</ParamField>

## `tools exec <name>`

<ParamField type="string">
  Tool name as shown in `tools list`.
</ParamField>

<ParamField type="string">
  Tool parameters as a JSON string. Must match the tool's input schema.
</ParamField>

<ParamField type="string">
  Working directory for the tool execution context.
</ParamField>

<ParamField type="boolean">
  Skip the approval prompt for moderate-security tools.
</ParamField>

<ParamField type="boolean">
  Output the raw tool result as JSON.
</ParamField>

## Tool Security Levels

| Level       | Description                        | Approval Required         |
| ----------- | ---------------------------------- | ------------------------- |
| `safe`      | Read-only operations               | Never                     |
| `moderate`  | Write operations, network requests | Prompted (skip with `-y`) |
| `dangerous` | System-level operations            | Always prompted           |

## Examples

<CodeGroup>
  ```bash List all tools theme={null}
  profclaw tools list
  ```

  ```bash List file tools only theme={null}
  profclaw tools list --category file
  ```

  ```bash Get tool details theme={null}
  profclaw tools info exec
  profclaw tools info read_file
  ```

  ```bash Execute a tool with parameters theme={null}
  profclaw tools exec read_file -p '{"path": "README.md", "maxLines": 50}'
  ```

  ```bash Run a shell command theme={null}
  profclaw tools run ls -la src/
  ```

  ```bash Run a shell command with working directory theme={null}
  profclaw tools run --workdir /tmp ls -la
  ```

  ```bash Search for files theme={null}
  profclaw tools find "*.ts" --path src/
  ```

  ```bash Search file contents theme={null}
  profclaw tools grep "TODO" src/ --context 2
  ```

  ```bash Case-insensitive grep theme={null}
  profclaw tools grep -i "error" src/ --ignore-case
  ```

  ```bash Show system info theme={null}
  profclaw tools sysinfo --type memory
  ```

  ```bash Check git status theme={null}
  profclaw tools git-status --short
  ```
</CodeGroup>

## Related

* [`profclaw mcp`](/cli/mcp) - Manage external MCP tool servers
* [`profclaw skills`](/cli/skills) - Manage skills that use tools
* [`profclaw chat -a`](/cli/chat) - Chat with all tools enabled


# profclaw tui
Source: https://docs.profclaw.ai/cli/tui

Display a live terminal dashboard showing system status, AI providers, recent sessions, and tasks.

## Synopsis

```bash theme={null}
profclaw tui [flags]
```

## Description

`tui` renders a static or auto-refreshing dashboard in the terminal. It fetches data from four API endpoints in parallel and displays them in a clean, color-coded layout:

* **System** - version, deployment mode, uptime, health status
* **AI Providers** - configured providers with health and latency
* **Recent Sessions** - last 5 chat conversations
* **Recent Tasks** - last 5 tasks with status indicators

Requires the profClaw server to be running. If the server is unreachable, the system panel shows a connection error while other panels display what data is available.

## Flags

<ParamField type="boolean">
  Refresh the dashboard automatically at the configured interval. Press `Ctrl+C` to stop.
</ParamField>

<ParamField type="string">
  Refresh interval in seconds when `--watch` is active.
</ParamField>

## Examples

<CodeGroup>
  ```bash Show dashboard once theme={null}
  profclaw tui
  ```

  ```bash Live dashboard (refreshes every 5 seconds) theme={null}
  profclaw tui --watch
  ```

  ```bash Live dashboard with custom refresh rate theme={null}
  profclaw tui --watch --interval 10
  ```
</CodeGroup>

## Example Output

```
  profClaw Dashboard
  --------------------------------------------------

  System
    Version:  2.0.0
    Mode:     mini
    Uptime:   2d 14h 30m
    Status:   ● healthy

  AI Providers
  Provider    Status   Latency
  anthropic   ● ok     142ms
  openai      ● ok     210ms

  Recent Sessions
  ID        Title                    Updated
  a1b2c3d4  Code review assistant    5 minutes ago
  e5f6g7h8  Docker setup             2 hours ago

  Recent Tasks
  ID        Title                    Status       Updated
  i9j0k1l2  Review PR #45            completed    1 hour ago
  m3n4o5p6  Analyze dependencies     in_progress  just now

  Run `profclaw --help` for all commands
```

## Related

* [`profclaw status`](/cli/status) - Compact one-line system status
* [`profclaw logs`](/cli/logs) - View server logs
* [`profclaw chat`](/cli/chat) - Start an interactive chat session
* [`profclaw task`](/cli/task) - Manage tasks


# profclaw tunnel
Source: https://docs.profclaw.ai/cli/tunnel

profclaw tunnel - start and stop Cloudflare and Tailscale tunnels to expose your local profClaw instance for remote access without port forwarding.

## Synopsis

```bash theme={null}
profclaw tunnel <subcommand> [flags]
```

## Description

Manage network tunnels for exposing your local profClaw instance to the internet. Supports Cloudflare Quick Tunnels and Tailscale mesh networking.

## Subcommands

| Subcommand  | Description                       |
| ----------- | --------------------------------- |
| `status`    | Show tunnel status (default)      |
| `start`     | Start a Cloudflare quick tunnel   |
| `stop`      | Stop the active Cloudflare tunnel |
| `tailscale` | Show detailed Tailscale status    |

## Flags

| Flag         | Type    | Default | Description          |
| ------------ | ------- | ------- | -------------------- |
| `--port <n>` | number  | 3000    | Local port to tunnel |
| `--json`     | boolean |         | Output as JSON       |

## Examples

<CodeGroup>
  ```bash Start a Cloudflare tunnel theme={null}
  profclaw tunnel start
  # Output: Tunnel active at https://random-name.trycloudflare.com
  ```

  ```bash Start on custom port theme={null}
  profclaw tunnel start --port 4000
  ```

  ```bash Check tunnel status theme={null}
  profclaw tunnel status
  ```

  ```bash Check Tailscale status theme={null}
  profclaw tunnel tailscale
  ```
</CodeGroup>

## Prerequisites

* **Cloudflare**: `cloudflared` must be installed (`brew install cloudflared`)
* **Tailscale**: `tailscale` must be installed and authenticated

## Related

* [Cloudflare Integration](/integrations/cloudflare)
* [Tailscale Integration](/integrations/tailscale)
* [Self-Hosted Guide](/guides/self-hosted)


# profclaw update
Source: https://docs.profclaw.ai/cli/update

Update profClaw to the latest version or a specific release.

## Synopsis

```bash theme={null}
profclaw update [version] [flags]
```

## Description

`update` checks for a newer version of profClaw and applies the update. It respects the original installation method (npm or binary) and runs the appropriate update command. After updating, it validates the new version with a health check.

## Arguments

<ParamField type="string">
  Specific version to install (e.g., `2.1.0`). Omit to install the latest stable release.
</ParamField>

## Flags

<ParamField type="boolean">
  Check for updates without installing. Prints the current version and the latest available version.
</ParamField>

<ParamField type="boolean">
  Include pre-release versions (alpha, beta, rc) when looking for updates.
</ParamField>

<ParamField type="boolean">
  Skip the confirmation prompt before updating.
</ParamField>

<ParamField type="boolean">
  Restart the daemon after a successful update (if running as a system service).
</ParamField>

## Examples

<CodeGroup>
  ```bash Check for updates (no install) theme={null}
  profclaw update --check
  ```

  ```bash Update to latest stable theme={null}
  profclaw update
  ```

  ```bash Update without confirmation theme={null}
  profclaw update --yes
  ```

  ```bash Update to a specific version theme={null}
  profclaw update 2.1.0
  ```

  ```bash Include pre-release versions theme={null}
  profclaw update --pre
  ```

  ```bash Update and restart daemon theme={null}
  profclaw update --yes --restart
  ```
</CodeGroup>

## Manual Update Methods

<CodeGroup>
  ```bash npm global install theme={null}
  npm install -g profclaw@latest
  ```

  ```bash pnpm global install theme={null}
  pnpm add -g profclaw@latest
  ```

  ```bash Docker theme={null}
  docker pull profclaw/profclaw:latest
  docker compose pull && docker compose up -d
  ```
</CodeGroup>

## Migration Notes

Before updating across major versions, run:

```bash theme={null}
profclaw backup create          # Back up data first
profclaw update                 # Apply update
profclaw doctor                 # Verify health
```

Check the [changelog](https://github.com/profclaw/profclaw/releases) for breaking changes between major versions.

## Related

* [`profclaw version`](/cli/version) - Print current version info
* [`profclaw backup`](/cli/backup) - Back up before major updates
* [`profclaw doctor`](/cli/doctor) - Verify health after update


# profclaw version
Source: https://docs.profclaw.ai/cli/version

Print version information for the installed profClaw CLI and connected server.

## Synopsis

```bash theme={null}
profclaw version [flags]
profclaw --version
```

## Description

`version` prints the installed version of the profClaw CLI. With `--server`, it also queries the running server for its version, deployment mode, and build metadata. Use this to confirm versions after an update or when filing a bug report.

## Flags

<ParamField type="boolean">
  Also fetch and display version information from the running profClaw server.
</ParamField>

<ParamField type="boolean">
  Output version data as JSON.
</ParamField>

## Examples

<CodeGroup>
  ```bash Print CLI version theme={null}
  profclaw version
  ```

  ```bash Short form theme={null}
  profclaw --version
  ```

  ```bash Show CLI and server versions theme={null}
  profclaw version --server
  ```

  ```bash JSON output for scripts theme={null}
  profclaw version --json
  profclaw version --server --json
  ```

  ```bash Use in scripts theme={null}
  VERSION=$(profclaw version --json | jq -r '.version')
  echo "Running profClaw $VERSION"
  ```
</CodeGroup>

## Example Output

```
profClaw v2.0.0
CLI:    2.0.0
Node:   v22.11.0
```

With `--server`:

```
profClaw v2.0.0
CLI:    2.0.0
Server: 2.0.0
Mode:   mini
Node:   v22.11.0
```

## Related

* [`profclaw update`](/cli/update) - Update to a newer version
* [`profclaw doctor`](/cli/doctor) - Full environment health check
* [`profclaw status`](/cli/status) - System status including version


# profclaw webhooks
Source: https://docs.profclaw.ai/cli/webhooks

profclaw webhooks - create, delete, test, and inspect outbound webhook endpoints. Monitor delivery history and configure signing secrets for event delivery.

## Synopsis

```bash theme={null}
profclaw webhooks <subcommand> [flags]
```

## Description

Manage webhook endpoints that receive event deliveries from profClaw. Create, test, and monitor webhooks for integrating with external services.

## Subcommands

| Subcommand     | Alias | Description                         |
| -------------- | ----- | ----------------------------------- |
| `list`         | `ls`  | List configured webhooks            |
| `create <url>` |       | Create a new webhook                |
| `delete <id>`  |       | Delete a webhook                    |
| `test <id>`    |       | Send a test delivery to a webhook   |
| `history <id>` |       | Show delivery history for a webhook |

## Flags

| Flag                | Type    | Default | Description                     |
| ------------------- | ------- | ------- | ------------------------------- |
| `--secret <secret>` | string  |         | Webhook signing secret (create) |
| `-l, --limit <n>`   | number  | 20      | Max entries for history         |
| `--yes`             | boolean |         | Skip confirmation (delete)      |
| `--json`            | boolean |         | Output as JSON                  |

## Examples

<CodeGroup>
  ```bash List webhooks theme={null}
  profclaw webhooks list
  ```

  ```bash Create a webhook theme={null}
  profclaw webhooks create https://example.com/hook --secret my-secret
  ```

  ```bash Test a webhook theme={null}
  profclaw webhooks test wh_abc123
  ```

  ```bash View delivery history theme={null}
  profclaw webhooks history wh_abc123 --limit 50
  ```
</CodeGroup>

## Related

* [Webhooks API](/api-reference/webhooks)
* [Integrations Overview](/integrations/overview)


# Environment Variables
Source: https://docs.profclaw.ai/configuration/environment-variables

Complete reference of all profClaw environment variables

## Core Settings

| Variable          | Default        | Description                                 |
| ----------------- | -------------- | ------------------------------------------- |
| `PROFCLAW_MODE`   | `mini`         | Deployment mode: `pico`, `mini`, or `pro`   |
| `PORT`            | `3000`         | HTTP server port                            |
| `HOST`            | `0.0.0.0`      | HTTP bind address                           |
| `NODE_ENV`        | `production`   | Node environment                            |
| `LOG_LEVEL`       | `info`         | Log level: `debug`, `info`, `warn`, `error` |
| `DATA_DIR`        | `.profclaw`    | Data directory path                         |
| `PROFCLAW_SECRET` | auto-generated | Secret key for signing tokens               |

## AI Provider Keys

| Variable                       | Provider           | Required                |
| ------------------------------ | ------------------ | ----------------------- |
| `ANTHROPIC_API_KEY`            | Anthropic (Claude) | For Anthropic provider  |
| `OPENAI_API_KEY`               | OpenAI (GPT)       | For OpenAI provider     |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Google (Gemini)    | For Google provider     |
| `GROQ_API_KEY`                 | Groq               | For Groq provider       |
| `MISTRAL_API_KEY`              | Mistral            | For Mistral provider    |
| `COHERE_API_KEY`               | Cohere             | For Cohere provider     |
| `PERPLEXITY_API_KEY`           | Perplexity         | For Perplexity provider |
| `TOGETHER_API_KEY`             | Together AI        | For Together provider   |
| `FIREWORKS_API_KEY`            | Fireworks AI       | For Fireworks provider  |
| `DEEPSEEK_API_KEY`             | DeepSeek           | For DeepSeek provider   |
| `XAI_API_KEY`                  | xAI (Grok)         | For xAI provider        |
| `OPENROUTER_API_KEY`           | OpenRouter         | For OpenRouter provider |
| `CEREBRAS_API_KEY`             | Cerebras           | For Cerebras provider   |
| `SAMBANOVA_API_KEY`            | SambaNova          | For SambaNova provider  |
| `AZURE_OPENAI_API_KEY`         | Azure OpenAI       | For Azure provider      |
| `AZURE_OPENAI_ENDPOINT`        | Azure OpenAI       | Azure endpoint URL      |
| `AWS_ACCESS_KEY_ID`            | Amazon Bedrock     | For Bedrock provider    |
| `AWS_SECRET_ACCESS_KEY`        | Amazon Bedrock     | For Bedrock provider    |
| `AWS_REGION`                   | Amazon Bedrock     | AWS region              |

## Local AI Providers

| Variable            | Default                  | Description             |
| ------------------- | ------------------------ | ----------------------- |
| `OLLAMA_BASE_URL`   | `http://localhost:11434` | Ollama server URL       |
| `OLLAMA_MODEL`      | `llama3.2`               | Default Ollama model    |
| `LMSTUDIO_BASE_URL` | `http://localhost:1234`  | LM Studio server URL    |
| `LMSTUDIO_MODEL`    | none                     | Default LM Studio model |

## Chat Provider Settings

| Variable                    | Default | Description                         |
| --------------------------- | ------- | ----------------------------------- |
| `SLACK_BOT_TOKEN`           | none    | Slack bot OAuth token               |
| `SLACK_APP_TOKEN`           | none    | Slack app-level token (Socket Mode) |
| `SLACK_SIGNING_SECRET`      | none    | Slack request signing secret        |
| `DISCORD_BOT_TOKEN`         | none    | Discord bot token                   |
| `DISCORD_APPLICATION_ID`    | none    | Discord application ID              |
| `TELEGRAM_BOT_TOKEN`        | none    | Telegram bot token                  |
| `WHATSAPP_ACCESS_TOKEN`     | none    | WhatsApp Business API token         |
| `WHATSAPP_PHONE_NUMBER_ID`  | none    | WhatsApp phone number ID            |
| `WHATSAPP_VERIFY_TOKEN`     | none    | Webhook verification token          |
| `MATRIX_HOMESERVER_URL`     | none    | Matrix homeserver URL               |
| `MATRIX_ACCESS_TOKEN`       | none    | Matrix access token                 |
| `MATRIX_USER_ID`            | none    | Matrix bot user ID                  |
| `TEAMS_APP_ID`              | none    | Microsoft Teams app ID              |
| `TEAMS_APP_PASSWORD`        | none    | Microsoft Teams app password        |
| `ROCKETCHAT_URL`            | none    | Rocket.Chat server URL              |
| `ROCKETCHAT_USER`           | none    | Rocket.Chat bot username            |
| `ROCKETCHAT_PASSWORD`       | none    | Rocket.Chat bot password            |
| `LINE_CHANNEL_ACCESS_TOKEN` | none    | LINE channel token                  |
| `LINE_CHANNEL_SECRET`       | none    | LINE channel secret                 |
| `SIGNAL_PHONE_NUMBER`       | none    | Signal phone number                 |
| `VIBER_AUTH_TOKEN`          | none    | Viber bot auth token                |

## Queue Settings

| Variable                 | Default  | Description                                  |
| ------------------------ | -------- | -------------------------------------------- |
| `REDIS_URL`              | none     | Redis connection URL (required for pro mode) |
| `POOL_MAX_CONCURRENT`    | `50`     | Max concurrent tool executions               |
| `POOL_TIMEOUT_MS`        | `300000` | Tool execution timeout (5 min)               |
| `QUEUE_RETRY_ATTEMPTS`   | `3`      | Failed job retry count                       |
| `QUEUE_RETRY_DELAY`      | `5000`   | Retry delay in ms                            |
| `QUEUE_STALLED_INTERVAL` | `30000`  | Stalled job check interval                   |

## Security Settings

| Variable                   | Default    | Description                                       |
| -------------------------- | ---------- | ------------------------------------------------- |
| `SECURITY_MODE`            | `standard` | Security mode: `permissive`, `standard`, `strict` |
| `AUDIT_LOG_ENABLED`        | `true`     | Enable audit logging                              |
| `AUDIT_LOG_RETENTION_DAYS` | `90`       | Audit log retention period                        |
| `DEVICE_PAIRING_ENABLED`   | `true`     | Enable QR code device pairing                     |
| `DEVICE_PAIRING_EXPIRY`    | `300`      | Pairing code expiry in seconds                    |
| `MAX_DEVICES`              | `10`       | Maximum paired devices                            |
| `PLUGIN_SANDBOX_ENABLED`   | `true`     | Enable plugin sandboxing                          |
| `CORS_ORIGINS`             | `*`        | Allowed CORS origins                              |
| `RATE_LIMIT_WINDOW`        | `60000`    | Rate limit window in ms                           |
| `RATE_LIMIT_MAX`           | `100`      | Max requests per window                           |

## Integration Settings

| Variable                | Default | Description                |
| ----------------------- | ------- | -------------------------- |
| `GITHUB_APP_ID`         | none    | GitHub App ID              |
| `GITHUB_PRIVATE_KEY`    | none    | GitHub App private key     |
| `GITHUB_CLIENT_ID`      | none    | GitHub OAuth client ID     |
| `GITHUB_CLIENT_SECRET`  | none    | GitHub OAuth client secret |
| `GITHUB_WEBHOOK_SECRET` | none    | GitHub webhook secret      |
| `JIRA_CLIENT_ID`        | none    | Jira OAuth client ID       |
| `JIRA_CLIENT_SECRET`    | none    | Jira OAuth client secret   |
| `JIRA_BASE_URL`         | none    | Jira instance URL          |
| `LINEAR_API_KEY`        | none    | Linear API key             |
| `LINEAR_WEBHOOK_SECRET` | none    | Linear webhook secret      |
| `CLOUDFLARE_API_TOKEN`  | none    | Cloudflare API token       |
| `CLOUDFLARE_ACCOUNT_ID` | none    | Cloudflare account ID      |
| `TAILSCALE_AUTH_KEY`    | none    | Tailscale auth key         |

## Memory and Storage

| Variable                | Default                 | Description                 |
| ----------------------- | ----------------------- | --------------------------- |
| `MEMORY_BACKEND`        | `sqlite`                | Memory storage backend      |
| `MEMORY_MAX_ENTRIES`    | `10000`                 | Maximum memory entries      |
| `MEMORY_WATCH_INTERVAL` | `5000`                  | File watch interval in ms   |
| `SQLITE_PATH`           | `.profclaw/profclaw.db` | SQLite database path        |
| `BACKUP_ENABLED`        | `false`                 | Enable automatic backups    |
| `BACKUP_INTERVAL`       | `86400000`              | Backup interval in ms (24h) |
| `BACKUP_RETENTION`      | `7`                     | Number of backups to retain |

## Advanced

| Variable                | Default             | Description                  |
| ----------------------- | ------------------- | ---------------------------- |
| `MCP_ENABLED`           | `true`              | Enable MCP server support    |
| `MCP_MAX_SERVERS`       | `5`                 | Max concurrent MCP servers   |
| `SYNC_ENABLED`          | `false`             | Enable multi-device sync     |
| `SYNC_INTERVAL`         | `30000`             | Sync interval in ms          |
| `CRON_ENABLED`          | `true`              | Enable cron scheduler        |
| `PLUGINS_DIR`           | `.profclaw/plugins` | Plugin directory             |
| `SKILLS_DIR`            | `skills`            | Skills directory             |
| `BROWSER_POOL_SIZE`     | `3`                 | Browser automation pool size |
| `WEB_SEARCH_PROVIDER`   | `auto`              | Web search provider          |
| `NOTIFICATIONS_ENABLED` | `true`              | Enable notifications         |


# Configuration Overview
Source: https://docs.profclaw.ai/configuration/overview

How to configure profClaw via environment variables, settings.yml, and CLI

## Configuration Sources

profClaw reads configuration from three sources, in order of priority (highest first):

1. **Environment variables** - Override everything, ideal for Docker/CI
2. **settings.yml** - File-based config in `.profclaw/settings.yml`
3. **Built-in defaults** - Sensible defaults for mini mode

## Quick Configuration

The fastest way to configure profClaw:

```bash theme={null}
# Set deployment mode
export PROFCLAW_MODE=mini

# Add an AI provider
export ANTHROPIC_API_KEY=sk-ant-your-key

# Start
profclaw serve
```

## Configuration File

Create `.profclaw/settings.yml` for persistent configuration:

```yaml theme={null}
mode: mini
port: 3000

providers:
  default: anthropic
  anthropic:
    apiKey: ${ANTHROPIC_API_KEY}
    model: claude-sonnet-4-6
  ollama:
    baseUrl: http://localhost:11434
    model: llama3.2

chat:
  defaultChannel: webchat
  maxHistoryLength: 100

security:
  mode: standard
  auditLog: true

queue:
  maxConcurrent: 25
  timeoutMs: 300000
```

## Configuration via CLI

Use the `profclaw config` command for interactive configuration:

```bash theme={null}
# View current config
profclaw config show

# Set a value
profclaw config set providers.default anthropic

# Add a provider
profclaw config providers add openai

# Reset to defaults
profclaw config reset
```

## Configuration Sections

<Columns>
  <Card title="Environment Variables" icon="list" href="/configuration/environment-variables">
    Complete reference of all 130+ environment variables with defaults and descriptions.
  </Card>

  <Card title="settings.yml" icon="file" href="/configuration/settings-yml">
    File-based configuration with YAML schema reference.
  </Card>

  <Card title="Security Config" icon="shield" href="/configuration/security-config">
    Security modes, guards, audit settings, and device trust policies.
  </Card>

  <Card title="Deployment Modes" icon="server" href="/getting-started/deployment-modes">
    Mode-specific feature availability and resource limits.
  </Card>
</Columns>


# Security Configuration
Source: https://docs.profclaw.ai/configuration/security-config

Configure security modes, guards, and audit policies

## Security Modes

Set the security mode to control how profClaw handles potentially dangerous operations:

```bash theme={null}
export SECURITY_MODE=standard
```

| Feature          | Permissive | Standard   | Strict |
| ---------------- | ---------- | ---------- | ------ |
| File read        | Auto-allow | Auto-allow | Prompt |
| File write       | Auto-allow | Prompt     | Prompt |
| File delete      | Auto-allow | Prompt     | Deny   |
| Shell commands   | Auto-allow | Prompt     | Deny   |
| Network requests | Auto-allow | Auto-allow | Prompt |
| Git operations   | Auto-allow | Auto-allow | Prompt |
| Package install  | Auto-allow | Prompt     | Deny   |

<Warning>
  **Permissive mode** is for development only. Never use it in production or with untrusted inputs.
</Warning>

## Command Guards

Guards are rules that restrict specific commands or patterns:

```yaml theme={null}
# .profclaw/settings.yml
security:
  guards:
    - pattern: "rm -rf /"
      action: deny
      reason: "Dangerous recursive delete"
    - pattern: "DROP TABLE"
      action: deny
      reason: "SQL table drop blocked"
    - pattern: "curl.*|.*sh"
      action: prompt
      reason: "Pipe to shell detected"
    - path: "/etc/*"
      action: deny
      reason: "System file access blocked"
    - path: "~/.ssh/*"
      action: deny
      reason: "SSH key access blocked"
```

## Path Restrictions

Limit which directories profClaw can access:

```yaml theme={null}
security:
  allowedPaths:
    - "./src"
    - "./tests"
    - "./docs"
  deniedPaths:
    - "./.env"
    - "./.env.local"
    - "./secrets"
    - "~/.ssh"
```

## Audit Logging

Every tool execution and security decision is logged:

```yaml theme={null}
security:
  auditLog:
    enabled: true
    retentionDays: 90
    includeToolResults: false  # Set true for full audit trail
    exportFormat: json         # json | csv
```

View audit logs:

```bash theme={null}
profclaw audit list
profclaw audit list --since 24h
profclaw audit export --format json --output audit.json
```

## Device Pairing

Control how devices authenticate with your profClaw instance:

```yaml theme={null}
security:
  devicePairing:
    enabled: true
    maxDevices: 10
    expirySeconds: 300
    requireApproval: true  # Manual approval for new devices
```

Generate a pairing code:

```bash theme={null}
profclaw device pair
```

## Network Policies

Control outbound network access:

```yaml theme={null}
security:
  network:
    allowedDomains:
      - "api.anthropic.com"
      - "api.openai.com"
      - "github.com"
      - "*.githubusercontent.com"
    blockedDomains:
      - "*.malware.com"
    maxRequestsPerMinute: 60
```

## Plugin Security

Plugins run in a sandboxed environment by default:

```yaml theme={null}
security:
  plugins:
    sandbox: true
    allowedPermissions:
      - "read_file"
      - "write_file"
    deniedPermissions:
      - "shell_exec"
      - "network_unrestricted"
    reviewRequired: true  # Require manual review before enabling
```

See [Plugin Security](/security/plugins) for details.


# settings.yml
Source: https://docs.profclaw.ai/configuration/settings-yml

File-based configuration reference for profClaw

## Overview

The `settings.yml` file provides persistent file-based configuration. It lives at `.profclaw/settings.yml` relative to your project root (or `$DATA_DIR/settings.yml`).

Create it during setup:

```bash theme={null}
profclaw init
```

Or manually create the file:

```bash theme={null}
mkdir -p .profclaw
touch .profclaw/settings.yml
```

## Full Schema Reference

```yaml theme={null}
# Deployment mode
mode: mini  # pico | mini | pro

# Server settings
server:
  port: 3000
  host: 0.0.0.0
  cors:
    origins:
      - "http://localhost:3000"
      - "https://your-domain.com"

# AI Provider configuration
providers:
  default: anthropic
  anthropic:
    apiKey: ${ANTHROPIC_API_KEY}
    model: claude-sonnet-4-6
    maxTokens: 8192
  openai:
    apiKey: ${OPENAI_API_KEY}
    model: gpt-4o
  ollama:
    baseUrl: http://localhost:11434
    model: llama3.2
  # Add more providers as needed

# Chat channel configuration
chat:
  defaultChannel: webchat
  maxHistoryLength: 100
  channels:
    webchat:
      enabled: true
    slack:
      enabled: true
      botToken: ${SLACK_BOT_TOKEN}
      appToken: ${SLACK_APP_TOKEN}
    discord:
      enabled: true
      botToken: ${DISCORD_BOT_TOKEN}
    telegram:
      enabled: true
      botToken: ${TELEGRAM_BOT_TOKEN}

# Security settings
security:
  mode: standard  # permissive | standard | strict
  auditLog:
    enabled: true
    retentionDays: 90
  devicePairing:
    enabled: true
    maxDevices: 10
    expirySeconds: 300
  rateLimiting:
    windowMs: 60000
    maxRequests: 100

# Queue settings
queue:
  maxConcurrent: 25
  timeoutMs: 300000
  retryAttempts: 3
  retryDelay: 5000
  # Redis config (pro mode only)
  redis:
    url: ${REDIS_URL}

# Memory settings
memory:
  backend: sqlite
  maxEntries: 10000
  watchInterval: 5000

# Cron jobs
cron:
  enabled: true
  jobs:
    - name: daily-summary
      schedule: "0 9 * * *"
      task: summary
    - name: cleanup
      schedule: "0 0 * * 0"
      task: cleanup

# Integration settings
integrations:
  github:
    enabled: true
    appId: ${GITHUB_APP_ID}
    webhookSecret: ${GITHUB_WEBHOOK_SECRET}
  jira:
    enabled: false
  linear:
    enabled: false

# Plugin settings
plugins:
  enabled: true
  directory: .profclaw/plugins
  sandbox: true

# MCP settings
mcp:
  enabled: true
  maxServers: 5
  servers: []

# Backup settings
backup:
  enabled: false
  interval: 86400000
  retention: 7
  path: .profclaw/backups
```

## Environment Variable Interpolation

Use `${VAR_NAME}` syntax to reference environment variables in settings.yml:

```yaml theme={null}
providers:
  anthropic:
    apiKey: ${ANTHROPIC_API_KEY}
```

This keeps secrets out of the configuration file.

## Validating Configuration

profClaw validates settings.yml against a Zod schema on startup. Check your config:

```bash theme={null}
profclaw config validate
```

## Precedence

When the same setting is defined in multiple places:

1. **Environment variable** wins over settings.yml
2. **settings.yml** wins over built-in defaults
3. **CLI flags** win over everything (for that invocation)

Example:

```bash theme={null}
# settings.yml says port: 3000
# This overrides it for this run:
PORT=4000 profclaw serve
```


# Deployment Modes
Source: https://docs.profclaw.ai/getting-started/deployment-modes

Compare pico, mini, and pro modes to choose the right setup

## Overview

profClaw runs in three deployment modes that control resource usage, available features, and scaling behavior. Set the mode via the `PROFCLAW_MODE` environment variable.

```bash theme={null}
export PROFCLAW_MODE=mini  # pico | mini | pro
```

```mermaid theme={null}
flowchart TD
  Env{"PROFCLAW_MODE"}
  Pico["pico\n512MB RAM / 1 core\n3 providers / 2 channels\nin-memory queue"]
  Mini["mini (default)\n2GB RAM / 2 cores\n15 providers / 10 channels\nin-memory queue"]
  Pro["pro\n8GB+ RAM / 4+ cores\n37 providers / 27 channels\nBullMQ + Redis\nclustering + sync"]

  Env -- "pico" --> Pico
  Env -- "mini" --> Mini
  Env -- "pro" --> Pro
```

## Mode Comparison

| Feature               | Pico      | Mini      | Pro            |
| --------------------- | --------- | --------- | -------------- |
| **RAM**               | 512MB     | 2GB       | 8GB+           |
| **CPU Cores**         | 1         | 2         | 4+             |
| **AI Providers**      | 3         | 15        | 37             |
| **Chat Channels**     | 2         | 10        | 27             |
| **Tools**             | 15        | 50        | 77+            |
| **Skills**            | 10        | 30        | 50             |
| **Queue**             | In-memory | In-memory | BullMQ + Redis |
| **Max Concurrent**    | 5         | 25        | 50+            |
| **Audit Logging**     | Basic     | Standard  | Full           |
| **Plugin Support**    | No        | Basic     | Full           |
| **MCP Servers**       | 1         | 5         | Unlimited      |
| **Backup/Restore**    | Manual    | Scheduled | Continuous     |
| **Multi-device Sync** | No        | No        | Yes            |
| **Clustering**        | No        | No        | Yes            |

## Pico Mode

Designed for resource-constrained environments like Raspberry Pi, IoT devices, or personal use on older hardware.

```bash theme={null}
export PROFCLAW_MODE=pico
```

**Included providers**: Ollama, OpenAI, Anthropic
**Included channels**: Webchat, Telegram
**Docker image**: `profclaw/profclaw:pico` (optimized, smaller image)

<Warning>
  Pico mode disables plugins, multi-device sync, and advanced security features to minimize resource usage.
</Warning>

## Mini Mode (Default)

The balanced option for small teams and home servers. Supports most features without requiring Redis.

```bash theme={null}
export PROFCLAW_MODE=mini
```

**Key features**:

* 15 AI providers including all major cloud providers
* 10 chat channels including Slack, Discord, Telegram
* Background task processing with in-memory queue
* Standard audit logging
* Basic plugin support

## Pro Mode

Full-featured production mode. Requires Redis for the BullMQ job queue.

```bash theme={null}
export PROFCLAW_MODE=pro
export REDIS_URL=redis://localhost:6379
```

**Key features**:

* All 37 AI providers
* All 27 chat channels
* Redis-backed job queue with persistence and retry
* Full audit logging with compliance support
* Plugin marketplace (ClawHub) access
* Multi-device sync
* Horizontal scaling with clustering
* Continuous backup

## Switching Modes

You can switch modes at any time by changing the environment variable and restarting:

```bash theme={null}
# Upgrade from mini to pro
export PROFCLAW_MODE=pro
export REDIS_URL=redis://localhost:6379
profclaw serve
```

<Note>
  Switching from a higher mode to a lower mode may disable features that are in use. Run `profclaw doctor` after switching to verify your configuration.
</Note>

## Environment Detection

During `profclaw onboard`, the wizard detects your environment and recommends a mode:

| Environment                | Recommended Mode |
| -------------------------- | ---------------- |
| Raspberry Pi / ARM SBC     | Pico             |
| Local development machine  | Mini             |
| Docker (limited resources) | Pico or Mini     |
| VPS (2-4GB RAM)            | Mini             |
| VPS (8GB+ RAM)             | Pro              |
| Kubernetes cluster         | Pro              |

```mermaid theme={null}
flowchart TD
  Onboard["profclaw onboard\nenvironment detection"]
  ARM{"ARM SBC /\nRaspberry Pi?"}
  RAM{"RAM available?"}
  Redis{"Redis\navailable?"}

  Onboard --> ARM
  ARM -- "yes" --> Pico["Recommend: pico"]
  ARM -- "no" --> RAM
  RAM -- "< 4GB" --> Mini["Recommend: mini"]
  RAM -- ">= 8GB" --> Redis
  Redis -- "yes" --> Pro["Recommend: pro"]
  Redis -- "no" --> Mini
```

<Card title="Next: Configuration" icon="arrow-right" href="/configuration/overview">
  Deep dive into environment variables and settings.
</Card>


# First Run
Source: https://docs.profclaw.ai/getting-started/first-run

Start profClaw, access the web UI, and send your first message. Covers the web interface, CLI chat, TUI, tools, skills, and API access.

## Start the Server

<Tabs>
  <Tab title="Standard">
    ```bash theme={null}
    profclaw serve
    ```

    Starts the HTTP server at `http://localhost:3000`. Output includes connected providers and chat channels.
  </Tab>

  <Tab title="Daemon">
    ```bash theme={null}
    profclaw daemon start
    ```

    Runs profClaw as a background service that persists after you close the terminal. Check status with `profclaw daemon status`.
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    docker start profclaw
    ```

    Or if using Docker Compose: `docker compose up -d`
  </Tab>
</Tabs>

## Access the Web UI

Open `http://localhost:3000` in your browser. You will see the profClaw web chat interface (WebChat provider).

<Tip>
  If the port is already in use, set a different one with `PORT=3001 profclaw serve` or via the `PORT` environment variable in your configuration.
</Tip>

## Send Your First Message

Type a message in the chat input:

```
What can you help me with?
```

profClaw responds with its capabilities based on your configured tools and providers. The response varies by [deployment mode](/getting-started/deployment-modes) - pro mode has access to all 77+ tools, while pico mode provides a focused essential set.

## Try the CLI Chat

Interact directly from your terminal without opening a browser:

```bash theme={null}
profclaw chat
```

This opens an interactive terminal session:

```
profClaw v2.x.x - Interactive Chat
Type /help for commands, /exit to quit
--------------------------------------

You: Summarize the README.md in this directory

Agent: I'll read the README.md file and summarize it for you.

[Tool: read_file] Reading README.md...

Here's a summary of the README:
...
```

Pass a one-shot message without entering the interactive session:

```bash theme={null}
profclaw chat "What is the current directory?"
```

## Try the TUI

For a richer terminal experience with panels and syntax highlighting:

```bash theme={null}
profclaw tui
```

The TUI provides a split-pane view with the conversation on one side and tool execution output on the other.

## Use Tools

profClaw agents have access to tools. Try asking:

```
List the files in the current directory
Search for TODO comments in my codebase
Create a new file called hello.txt with "Hello World"
Run my test suite
Fetch the content of https://example.com
```

<Note>
  Tools are subject to your [security policy](/security/overview). In `standard` mode, destructive operations like shell execution require explicit approval before they run. Use `profclaw config set security.mode permissive` for unrestricted local development only.
</Note>

See [Tools Overview](/tools/overview) for the full list of available tools and how model-aware tier routing works.

## Use Skills

Skills are pre-built expertise modules invoked with slash commands:

```
/commit
/review-pr 42
/summarize src/
/web-research "Hono middleware patterns"
```

See [Skills Overview](/skills/overview) for all 50 built-in skills and how to create your own.

## API Access

Send messages programmatically via the REST API:

```bash theme={null}
curl -X POST http://localhost:3000/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello profClaw", "provider": "anthropic"}'
```

The API returns a streaming JSON response with tool calls and the final message. See the [API Reference](/api-reference/overview) for full documentation.

## Next Steps

<CardGroup>
  <Card title="Deployment Modes" icon="server" href="/getting-started/deployment-modes">
    Understand pico, mini, and pro modes and what each enables.
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/tools/overview">
    Explore the 77+ built-in tools and how execution works.
  </Card>

  <Card title="AI Providers" icon="brain" href="/ai-providers/overview">
    Configure additional AI providers and model aliases.
  </Card>

  <Card title="Chat Providers" icon="messages" href="/chat-providers/overview">
    Connect Slack, Discord, Telegram, or other chat channels.
  </Card>
</CardGroup>


# Installation
Source: https://docs.profclaw.ai/getting-started/installation

Install profClaw on macOS, Linux, Windows, or via Docker. Covers system requirements, all install methods, and post-install setup.

## System Requirements

| Requirement | Minimum      | Recommended           |
| ----------- | ------------ | --------------------- |
| Node.js     | 22+          | 22 LTS                |
| RAM         | 512MB (pico) | 2GB+ (mini/pro)       |
| Disk        | 500MB        | 2GB+                  |
| Redis       | Optional     | Required for pro mode |

<Note>
  Node.js 22 or later is required. Check your version with `node --version`. Install or upgrade via [nodejs.org](https://nodejs.org) or a version manager like `nvm`.
</Note>

## Install Methods

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install -g profclaw
    ```

    Verify the installation:

    ```bash theme={null}
    profclaw version
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add -g profclaw
    ```

    Verify the installation:

    ```bash theme={null}
    profclaw version
    ```
  </Tab>

  <Tab title="Docker">
    Pull the latest image:

    ```bash theme={null}
    docker pull profclaw/profclaw:latest
    ```

    Run with default settings:

    ```bash theme={null}
    docker run -d \
      --name profclaw \
      -p 3000:3000 \
      -v profclaw-data:/data \
      profclaw/profclaw:latest
    ```

    Or use Docker Compose for a full stack with Redis:

    ```yaml theme={null}
    services:
      profclaw:
        image: profclaw/profclaw:latest
        ports:
          - "3000:3000"
        volumes:
          - profclaw-data:/data
        environment:
          - PROFCLAW_MODE=mini
          - PORT=3000
    volumes:
      profclaw-data:
    ```

    See the [Docker Deployment guide](/guides/docker-deployment) for a production-ready setup with Redis, Nginx, and health checks.
  </Tab>

  <Tab title="Docker (Pico)">
    Optimized image for resource-constrained environments (Raspberry Pi, edge devices):

    ```bash theme={null}
    docker pull profclaw/profclaw:pico
    ```

    ```bash theme={null}
    docker run -d \
      --name profclaw \
      -p 3000:3000 \
      --memory=512m \
      profclaw/profclaw:pico
    ```
  </Tab>

  <Tab title="From Source">
    Clone and build from source for development or contributions:

    ```bash theme={null}
    git clone https://github.com/profclaw/profclaw.git
    cd profclaw
    pnpm install
    pnpm build
    pnpm dev
    ```

    The dev server starts with hot reload at `http://localhost:3000`.
  </Tab>
</Tabs>

## Post-Install Setup

After installation, run the interactive setup wizard:

```bash theme={null}
profclaw init
profclaw onboard
```

This will:

1. Create a `.profclaw/` configuration directory
2. Detect your environment (Docker, VPS, local machine)
3. Recommend a [deployment mode](/getting-started/deployment-modes) (pico/mini/pro)
4. Set up your first AI provider
5. Configure optional chat channels

See [Onboarding](/getting-started/onboard) for a step-by-step walkthrough of the wizard.

## Verify the Installation

Run the health check to confirm everything is configured correctly:

```bash theme={null}
profclaw doctor
```

Expected output:

```
profClaw Doctor v2.x.x
--------------------------
✓ Node.js 22.x detected
✓ Configuration valid
✓ AI Provider: Anthropic connected
✓ Chat: Webchat ready on :3000
✓ Security: Standard mode active
✓ Storage: SQLite initialized
--------------------------
All checks passed!
```

<Tip>
  If any checks fail, the `doctor` command prints the specific issue and a remediation hint. Common issues: missing API keys, port conflicts, or an outdated Node.js version.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Onboarding Wizard" icon="wand-magic-sparkles" href="/getting-started/onboard">
    Step-by-step walkthrough of the interactive setup wizard.
  </Card>

  <Card title="First Run" icon="play" href="/getting-started/first-run">
    Start the server and send your first message to the agent.
  </Card>

  <Card title="Deployment Modes" icon="server" href="/getting-started/deployment-modes">
    Compare pico, mini, and pro modes to pick the right one for your hardware.
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/guides/docker-deployment">
    Production-ready Docker setup with Redis and persistent storage.
  </Card>
</CardGroup>


# Onboarding Wizard
Source: https://docs.profclaw.ai/getting-started/onboard

Walk through the interactive profclaw onboard wizard. Covers environment detection, deployment mode selection, AI provider setup, chat channels, and security policy.

## The Onboarding Wizard

The `profclaw onboard` command launches an interactive wizard that configures your instance in 5 steps. Run it after `profclaw init`:

```bash theme={null}
profclaw init
profclaw onboard
```

<Note>
  You can re-run `profclaw onboard` at any time to change your configuration. Existing settings are preserved - the wizard only overwrites what you explicitly change.
</Note>

## Step 1: Environment Detection

profClaw automatically detects your runtime environment and applies appropriate defaults:

| Environment        | Detection Method                     | Applied Defaults                                 |
| ------------------ | ------------------------------------ | ------------------------------------------------ |
| Docker             | `/.dockerenv` present                | Persistent volume paths, no hot reload           |
| VPS / Cloud        | Non-interactive TTY, public IP       | Systemd service hints, `WEBHOOK_BASE_URL` prompt |
| Local Machine      | Interactive TTY, macOS/Linux desktop | Hot reload, `localhost` defaults                 |
| Raspberry Pi / ARM | CPU architecture check               | Pico mode defaults, memory limits                |

## Step 2: Deployment Mode

Choose your deployment mode based on available hardware resources:

<Tabs>
  <Tab title="Pico">
    **Best for**: IoT, edge devices, Raspberry Pi, personal use on constrained hardware.

    * 512MB RAM, 1 CPU core
    * Up to 3 AI providers
    * 2 chat channels
    * 15 essential tools
    * In-memory queue only (no Redis required)
  </Tab>

  <Tab title="Mini (Default)">
    **Best for**: Small teams, home servers, development environments.

    * 2GB RAM, 2 CPU cores
    * Up to 15 AI providers
    * 10 chat channels
    * 50 tools
    * In-memory queue with optional Redis
    * Background job support
  </Tab>

  <Tab title="Pro">
    **Best for**: Production deployments, enterprise, multi-team environments.

    * 8GB+ RAM, 4+ CPU cores
    * All 37 AI providers
    * All 27 chat channels
    * All 77+ tools
    * Redis-backed BullMQ (required)
    * Full audit logging and clustering support
  </Tab>
</Tabs>

Set via environment variable to skip the wizard prompt:

```bash theme={null}
export PROFCLAW_MODE=mini
```

See [Deployment Modes](/getting-started/deployment-modes) for a detailed feature comparison.

## Step 3: AI Provider Setup

Configure at least one AI provider. The wizard prompts for API keys:

```
? Select your primary AI provider:
  > Anthropic (Claude)
    OpenAI (GPT-4o)
    Google (Gemini)
    Ollama (Local)
    Other...

? Enter your Anthropic API key: sk-ant-***
? Test connection? Yes
  ✓ Connected to Anthropic - Claude Sonnet 4.6 available
```

<Tip>
  If you want to run fully offline without cloud API costs, choose **Ollama (Local)**. Make sure Ollama is installed and running first: `brew install ollama && ollama serve`. See the [Local LLM guide](/guides/local-llm).
</Tip>

You can add more providers later:

```bash theme={null}
profclaw config providers add openai --key sk-...
```

See [AI Providers Overview](/ai-providers/overview) for the full list of supported providers and configuration options.

## Step 4: Chat Channel (Optional)

Connect a chat channel for conversational access from outside the web UI:

```
? Set up a chat channel now?
  > Webchat (built-in, no setup needed)
    Slack
    Discord
    Telegram
    Skip for now
```

WebChat is enabled by default at `http://localhost:3000` and requires no additional configuration.

For Slack, Discord, or other platforms, the wizard walks you through credential collection. You can also skip this step and configure channels later. See [Chat Providers Overview](/chat-providers/overview) for setup guides per platform.

## Step 5: Security Policy

Choose the security posture that fits your deployment:

```
? Select security mode:
  > Standard (recommended)
    Permissive (development only)
    Strict (production/enterprise)
```

| Mode         | Description                                                | Best For                              |
| ------------ | ---------------------------------------------------------- | ------------------------------------- |
| `permissive` | Tools execute without approval prompts                     | Local development, trusted users only |
| `standard`   | Destructive operations require approval                    | Most deployments                      |
| `strict`     | All write operations require approval, extra guards active | Production, shared environments       |

<Warning>
  Do not use `permissive` mode in any deployment accessible by untrusted users. Anyone who can message the agent can execute file operations and shell commands.
</Warning>

See [Security Overview](/security/overview) for a full description of all five security modes and the defense-in-depth architecture.

## Verify Setup

After onboarding, confirm everything works:

```bash theme={null}
profclaw doctor
```

Expected output:

```
profClaw Doctor v2.x.x
--------------------------
✓ Node.js 22.x detected
✓ Configuration valid
✓ AI Provider: Anthropic connected
✓ Chat: Webchat ready on :3000
✓ Security: Standard mode active
✓ Storage: SQLite initialized
--------------------------
All checks passed!
```

If any checks fail, the `doctor` command prints the specific issue and remediation steps.

<Card title="Next: First Run" icon="arrow-right" href="/getting-started/first-run">
  Start profClaw and send your first message to the agent.
</Card>


# Backup and Restore
Source: https://docs.profclaw.ai/guides/backup-restore

Protect your profClaw data with backups and disaster recovery

## Overview

profClaw stores configuration, memory, audit logs, and task history locally. Regular backups ensure you can recover from hardware failures, corruption, or accidental deletion.

## What Gets Backed Up

| Data             | Location                 | Included             |
| ---------------- | ------------------------ | -------------------- |
| Configuration    | `.profclaw/settings.yml` | Yes                  |
| SQLite database  | `.profclaw/profclaw.db`  | Yes                  |
| Memory entries   | `.profclaw/memory/`      | Yes                  |
| Audit logs       | `.profclaw/audit/`       | Yes                  |
| Plugin data      | `.profclaw/plugins/`     | Yes                  |
| Encryption keys  | `.profclaw/keys/`        | Yes                  |
| Skills           | `skills/`                | Yes                  |
| Environment vars | `.env`                   | No (manual)          |
| Redis data       | External                 | No (separate backup) |

## Manual Backup

```bash theme={null}
# Create a backup
profclaw backup create

# Create with custom output path
profclaw backup create --output ./backups/

# Create with timestamp
profclaw backup create --output ./backups/profclaw-$(date +%Y%m%d).tar.gz
```

## Automatic Backups

Enable scheduled backups:

```yaml theme={null}
backup:
  enabled: true
  interval: 86400000   # Every 24 hours (ms)
  retention: 7         # Keep last 7 backups
  path: .profclaw/backups
```

Or via environment variables:

```bash theme={null}
export BACKUP_ENABLED=true
export BACKUP_INTERVAL=86400000
export BACKUP_RETENTION=7
```

## Restore

```bash theme={null}
# List available backups
profclaw backup list

# Restore from latest
profclaw backup restore --latest

# Restore from specific file
profclaw backup restore --file ./backups/profclaw-20260312.tar.gz
```

<Warning>
  Restoring a backup replaces your current data. The current state is automatically saved as a pre-restore backup before the restore operation begins.
</Warning>

## Docker Backup

For Docker deployments, back up the data volume:

```bash theme={null}
# Backup
docker run --rm \
  -v profclaw-data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/profclaw-$(date +%Y%m%d).tar.gz /data

# Restore
docker run --rm \
  -v profclaw-data:/data \
  -v $(pwd)/backups:/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/profclaw-20260312.tar.gz -C /"
```

## Redis Backup (Pro Mode)

If using Redis for the job queue:

```bash theme={null}
# Trigger Redis RDB snapshot
redis-cli BGSAVE

# Copy the dump file
cp /var/lib/redis/dump.rdb ./backups/redis-$(date +%Y%m%d).rdb
```

## Disaster Recovery Checklist

1. Stop profClaw: `profclaw daemon stop` or `systemctl stop profclaw`
2. Restore backup: `profclaw backup restore --file backup.tar.gz`
3. Verify config: `profclaw doctor`
4. Restore Redis (if pro mode): Copy RDB file to Redis data directory
5. Start profClaw: `profclaw serve`
6. Verify: `profclaw status`


# Docker Deployment
Source: https://docs.profclaw.ai/guides/docker-deployment

Production-ready Docker setup for profClaw with Redis, persistent storage, Nginx reverse proxy, health checks, and backup procedures.

## Overview

Deploy profClaw in Docker for production use with persistent storage, Redis for job queues, and optional Nginx for TLS termination.

## Quick Start

For a minimal single-container setup without Redis:

```bash theme={null}
docker run -d \
  --name profclaw \
  -p 3000:3000 \
  -v profclaw-data:/data \
  -e PROFCLAW_MODE=mini \
  -e ANTHROPIC_API_KEY=sk-ant-your-key \
  profclaw/profclaw:latest
```

<Note>
  This runs in `mini` mode without Redis. Background jobs use an in-memory queue, which does not persist across restarts. For production, use the Docker Compose setup below with Redis.
</Note>

## Docker Compose (Recommended)

Create a `docker-compose.yml` file:

```yaml theme={null}
services:
  profclaw:
    image: profclaw/profclaw:latest
    container_name: profclaw
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - profclaw-data:/data
      - ./settings.yml:/app/.profclaw/settings.yml:ro
    environment:
      - PROFCLAW_MODE=pro
      - REDIS_URL=redis://redis:6379
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - SECURITY_MODE=standard
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    container_name: profclaw-redis
    restart: unless-stopped
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  profclaw-data:
  redis-data:
```

Start the stack:

```bash theme={null}
docker compose up -d
```

Verify it is running:

```bash theme={null}
docker compose ps
curl http://localhost:3000/api/health
```

## Pico Mode (Resource-Constrained)

For Raspberry Pi or other devices with limited resources, use the pico image with explicit memory limits:

```yaml theme={null}
services:
  profclaw:
    image: profclaw/profclaw:pico
    container_name: profclaw
    restart: unless-stopped
    ports:
      - "3000:3000"
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
    environment:
      - PROFCLAW_MODE=pico
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
```

This configuration uses Ollama running on the host for AI inference, keeping all model compute off the constrained container. See the [Local LLM guide](/guides/local-llm) for Ollama setup.

## With Nginx Reverse Proxy

Add Nginx for TLS termination and a clean public URL:

```yaml theme={null}
services:
  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - profclaw

  profclaw:
    image: profclaw/profclaw:latest
    expose:
      - "3000"
    environment:
      - PROFCLAW_MODE=pro
      - REDIS_URL=redis://redis:6379
      - WEBHOOK_BASE_URL=https://profclaw.example.com
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  profclaw-data:
  redis-data:
```

Example `nginx.conf`:

```nginx theme={null}
server {
    listen 80;
    server_name profclaw.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name profclaw.example.com;

    ssl_certificate     /etc/nginx/certs/cert.pem;
    ssl_certificate_key /etc/nginx/certs/key.pem;

    location / {
        proxy_pass http://profclaw:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

<Tip>
  For automatic certificate renewal, replace the `nginx` service with Caddy, which handles TLS automatically: `caddy:2-alpine`. The Caddyfile is simpler than the nginx config above.
</Tip>

## Environment Variables

Pass secrets via environment variables rather than mounting them into the settings.yml file. Use a `.env` file with `docker compose --env-file`:

```bash theme={null}
# .env (do not commit to git)
ANTHROPIC_API_KEY=sk-ant-...
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...
```

```bash theme={null}
docker compose --env-file .env up -d
```

## Health Checks

```bash theme={null}
# profClaw API health
curl http://localhost:3000/api/health

# Docker container health status
docker inspect --format='{{.State.Health.Status}}' profclaw

# View logs
docker logs profclaw --follow --tail 100
```

Add a health check to the profclaw service in your Compose file for automatic restart on failure:

```yaml theme={null}
profclaw:
  # ...
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 15s
```

## Backup

Backup the profclaw data volume before upgrades or regularly via cron:

```bash theme={null}
# Create a dated backup archive
docker run --rm \
  -v profclaw-data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/profclaw-$(date +%Y%m%d).tar.gz /data
```

Restore from backup:

```bash theme={null}
docker run --rm \
  -v profclaw-data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar xzf /backup/profclaw-20240101.tar.gz -C /
```

See the [Backup and Restore guide](/guides/backup-restore) for scheduled backup configuration.

## Updating

Pull the latest image and recreate the containers:

```bash theme={null}
docker compose pull
docker compose up -d
```

Docker Compose only recreates containers whose image has changed, so Redis is not disrupted if only the profclaw image updated.

## Related Guides

<CardGroup>
  <Card title="Self-Hosted Deployment" icon="server" href="/guides/self-hosted">
    Configure public webhooks and systemd for VPS deployments.
  </Card>

  <Card title="Backup and Restore" icon="database" href="/guides/backup-restore">
    Automated backups, retention policies, and restore procedures.
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/guides/monitoring">
    Health endpoints, metrics, and alerting for production deployments.
  </Card>

  <Card title="Security Overview" icon="shield" href="/security/overview">
    Configure security modes and guards for production.
  </Card>
</CardGroup>


# GitHub Workflow Automation
Source: https://docs.profclaw.ai/guides/github-workflow

Automate issues, PRs, and code reviews with profClaw agents

## Overview

Connect profClaw to GitHub to automatically triage issues, review pull requests, sync tasks, and run agentic workflows triggered by repository events.

## Prerequisites

* profClaw running in mini or pro mode
* A GitHub account with repo access
* GitHub App or Personal Access Token

## Step 1: Create a GitHub App

<Steps>
  <Step title="Create the App">
    Go to **Settings > Developer Settings > GitHub Apps > New GitHub App**.

    Set the following:

    * **Name**: profClaw Bot
    * **Homepage URL**: Your profClaw instance URL
    * **Webhook URL**: `https://your-profclaw.com/api/integrations/github/webhook`
  </Step>

  <Step title="Set Permissions">
    | Permission    | Access       | Purpose                   |
    | ------------- | ------------ | ------------------------- |
    | Issues        | Read & Write | Create/update issues      |
    | Pull Requests | Read & Write | Review PRs, post comments |
    | Contents      | Read         | Read repository files     |
    | Metadata      | Read         | Repository info           |
    | Webhooks      | Read & Write | Receive events            |
  </Step>

  <Step title="Subscribe to Events">
    * `issues` - Issue opened, edited, closed
    * `pull_request` - PR opened, updated, merged
    * `issue_comment` - Comments on issues/PRs
    * `push` - Code pushed to branches
  </Step>

  <Step title="Generate Private Key">
    After creating the app, generate a private key and save the `.pem` file.
  </Step>
</Steps>

## Step 2: Configure profClaw

```bash theme={null}
export GITHUB_APP_ID=123456
export GITHUB_PRIVATE_KEY="$(cat path/to/private-key.pem)"
export GITHUB_WEBHOOK_SECRET=your-webhook-secret
```

Or use OAuth for personal use:

```bash theme={null}
profclaw auth github
```

## Step 3: Enable GitHub Integration

```yaml theme={null}
integrations:
  github:
    enabled: true
    features:
      issueSync: true
      prReview: true
      codeSearch: true
      ticketSync: true
```

## Automated PR Reviews

profClaw can automatically review pull requests when they're opened:

```yaml theme={null}
integrations:
  github:
    prReview:
      enabled: true
      autoReview: true
      reviewPrompt: |
        Review this PR for:
        - Code quality and best practices
        - Security vulnerabilities
        - Test coverage
        - Documentation
      labels:
        approved: "profclaw-approved"
        needsWork: "needs-changes"
```

## Issue Triage

Automatically label and assign incoming issues:

```yaml theme={null}
integrations:
  github:
    issueTriage:
      enabled: true
      autoLabel: true
      autoAssign: true
      rules:
        - match: "bug"
          labels: ["bug", "triage"]
        - match: "feature request"
          labels: ["enhancement"]
        - match: "security"
          labels: ["security", "priority-high"]
```

## Cron-Based Workflows

Run periodic GitHub workflows:

```yaml theme={null}
cron:
  jobs:
    - name: stale-issues
      schedule: "0 9 * * 1"  # Monday at 9 AM
      task: |
        Find issues with no activity for 30 days
        and add a "stale" label

    - name: weekly-summary
      schedule: "0 17 * * 5"  # Friday at 5 PM
      task: |
        Generate a summary of this week's PRs,
        issues opened/closed, and contributors
```

## CLI Usage

```bash theme={null}
# Sync GitHub issues to profClaw tasks
profclaw github sync

# Review a specific PR
profclaw github review 42

# Search code across repos
profclaw github search "TODO security"
```


# Run Local LLMs
Source: https://docs.profclaw.ai/guides/local-llm

Use Ollama or LM Studio for fully offline AI capabilities

## Overview

profClaw supports local LLM inference through Ollama and LM Studio. Run AI agents entirely on your own hardware with no API keys or cloud dependencies.

## Ollama Setup

<Steps>
  <Step title="Install Ollama">
    ```bash theme={null}
    # macOS
    brew install ollama

    # Linux
    curl -fsSL https://ollama.com/install.sh | sh
    ```
  </Step>

  <Step title="Pull a Model">
    ```bash theme={null}
    # General purpose
    ollama pull llama3.2

    # Coding focused
    ollama pull codellama:13b

    # Small and fast
    ollama pull phi3:mini
    ```
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    export OLLAMA_BASE_URL=http://localhost:11434
    export OLLAMA_MODEL=llama3.2
    ```

    Or in `settings.yml`:

    ```yaml theme={null}
    providers:
      default: ollama
      ollama:
        baseUrl: http://localhost:11434
        model: llama3.2
    ```
  </Step>

  <Step title="Start and Test">
    ```bash theme={null}
    ollama serve &
    profclaw serve
    ```

    ```bash theme={null}
    profclaw chat
    > Hello, are you running locally?
    ```
  </Step>
</Steps>

## LM Studio Setup

<Steps>
  <Step title="Install LM Studio">
    Download from [lmstudio.ai](https://lmstudio.ai). Available for macOS, Windows, and Linux.
  </Step>

  <Step title="Download a Model">
    Open LM Studio, browse the model catalog, and download a model (e.g., Llama 3.2, Mistral, Phi-3).
  </Step>

  <Step title="Start the Server">
    In LM Studio, go to the **Local Server** tab and click **Start Server**. Default port is 1234.
  </Step>

  <Step title="Configure profClaw">
    ```bash theme={null}
    export LMSTUDIO_BASE_URL=http://localhost:1234
    export LMSTUDIO_MODEL=your-model-name
    ```
  </Step>
</Steps>

## Recommended Models

| Model             | Size  | Best For             | VRAM Needed |
| ----------------- | ----- | -------------------- | ----------- |
| Llama 3.2 3B      | 2GB   | Quick tasks, chat    | 4GB         |
| Llama 3.2 8B      | 4.7GB | General purpose      | 8GB         |
| CodeLlama 13B     | 7.4GB | Code generation      | 16GB        |
| Mistral 7B        | 4.1GB | Balanced performance | 8GB         |
| Phi-3 Mini        | 2.2GB | Edge devices         | 4GB         |
| DeepSeek Coder V2 | 8.9GB | Code tasks           | 16GB        |

## Hybrid Setup

Use local models for simple tasks and cloud providers for complex ones:

```yaml theme={null}
providers:
  default: ollama
  ollama:
    baseUrl: http://localhost:11434
    model: llama3.2
  anthropic:
    apiKey: ${ANTHROPIC_API_KEY}
    model: claude-sonnet-4-6
```

Switch providers per conversation:

```bash theme={null}
profclaw chat --provider anthropic
profclaw chat --provider ollama
```

## Docker with Ollama

Run both profClaw and Ollama in Docker:

```yaml theme={null}
services:
  profclaw:
    image: profclaw/profclaw:latest
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - OLLAMA_MODEL=llama3.2
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    volumes:
      - ollama-models:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]  # GPU passthrough

volumes:
  ollama-models:
```

## Performance Tips

<AccordionGroup>
  <Accordion title="GPU Acceleration">
    Ollama automatically uses GPU if available. Check with `ollama list` - GPU-accelerated models show higher tokens/sec.
  </Accordion>

  <Accordion title="Context Length">
    Local models have smaller context windows than cloud models. Set `POOL_TIMEOUT_MS` higher for larger contexts.
  </Accordion>

  <Accordion title="Quantization">
    Use quantized models (Q4\_K\_M, Q5\_K\_M) for better speed with minimal quality loss:

    ```bash theme={null}
    ollama pull llama3.2:q4_k_m
    ```
  </Accordion>
</AccordionGroup>


# Running profClaw on Low-Memory Devices
Source: https://docs.profclaw.ai/guides/low-memory-devices

Install and run profClaw on Raspberry Pi Zero, $5 VPS, and other 512MB RAM devices

<Note>
  See [INSTALLATION.md](/docs/INSTALLATION.md) for the standard setup guide and [README](/docs/README.md) for a full feature overview.
</Note>

## The Problem

`npm install -g profclaw` on a 512MB device will get OOM-killed. Node's package installer is memory-hungry — it can spike past 400MB during dependency resolution alone.

You have three options depending on what you have available.

## Hardware Requirements

| Mode     | Minimum RAM | Swap Needed | Typical Device             |
| -------- | ----------- | ----------- | -------------------------- |
| **pico** | 256MB       | 256MB+      | Raspberry Pi Zero, \$5 VPS |
| **mini** | 512MB       | optional    | Raspberry Pi 3, \$10 VPS   |
| **pro**  | 2GB         | none        | Raspberry Pi 4+, \$20+ VPS |

***

## Option 1: Docker Pico Image (Recommended)

No npm install. Pull a pre-built image that runs in under 200MB of RAM.

```bash theme={null}
docker run -d \
  --name profclaw \
  --restart unless-stopped \
  -p 3000:3000 \
  -v profclaw-data:/data \
  -e PROFCLAW_MODE=pico \
  ghcr.io/profclaw/profclaw:pico
```

Point to a remote Ollama instance on a beefier machine:

```bash theme={null}
docker run -d \
  --name profclaw \
  --restart unless-stopped \
  -p 3000:3000 \
  -v profclaw-data:/data \
  -e PROFCLAW_MODE=pico \
  -e OLLAMA_BASE_URL=http://192.168.1.50:11434 \
  ghcr.io/profclaw/profclaw:pico
```

### Verify it works

```bash theme={null}
curl http://localhost:3000/health
```

A `200 OK` with `{"status":"ok"}` means the container is up and accepting requests.

### Connect an AI provider

Pass API keys as environment variables. Add whichever provider you use:

```bash theme={null}
docker run -d \
  --name profclaw \
  --restart unless-stopped \
  -p 3000:3000 \
  -v profclaw-data:/data \
  -e PROFCLAW_MODE=pico \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e GOOGLE_GENERATIVE_AI_API_KEY=AIza... \
  -e CEREBRAS_API_KEY=csk-... \
  -e OLLAMA_BASE_URL=http://192.168.1.50:11434 \
  ghcr.io/profclaw/profclaw:pico
```

You only need one provider. Set the one you have and skip the rest.

<Note>
  Pico mode skips authentication. There is no login screen and no user session required. Whoever can reach port 3000 can use the API. Do not expose the port publicly without a reverse proxy or firewall rule.
</Note>

***

## Option 2: Add Swap Before npm Install

Works on Raspberry Pi OS and most Debian-based systems. Gives the installer the memory headroom it needs.

```bash theme={null}
# Create a 1GB swap file
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Verify swap is active
free -h

# Now install
npm install -g profclaw

# Initialize and start
profclaw init
profclaw serve --mode pico
```

Make swap permanent across reboots:

```bash theme={null}
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
```

<Note>
  On SD card devices (Pi Zero, Pi 3), heavy swap use will wear out your card faster. Use a USB SSD or a ramdisk-backed swap if running long-term.
</Note>

***

## Option 3: Cross-Install from Another Machine

Install profClaw on a machine with enough RAM, then copy the installed binary to your low-memory device.

On the build machine:

```bash theme={null}
# Install into a local directory (not global)
mkdir profclaw-bundle && cd profclaw-bundle
npm pack profclaw
npm install --prefix ./install profclaw

# Copy to target device
scp -r ./install pi@raspberrypi.local:/opt/profclaw
```

On the target device:

```bash theme={null}
# Run directly from the copied install
/opt/profclaw/node_modules/.bin/profclaw init
/opt/profclaw/node_modules/.bin/profclaw serve --mode pico
```

Optionally symlink it:

```bash theme={null}
sudo ln -s /opt/profclaw/node_modules/.bin/profclaw /usr/local/bin/profclaw
```

***

## Pico Mode: What Works, What Doesn't

### Works in pico

* Agent engine (full reasoning loop)
* 72 core tools (file, git, shell, HTTP, memory, cron)
* CLI chat (`profclaw chat`)
* REST API on port 3000
* Cron jobs and scheduled tasks
* One chat channel (your choice: Slack, Telegram, Discord, etc.)

### Not available in pico

| Feature                        | Why                               |
| ------------------------------ | --------------------------------- |
| Web UI dashboard               | Removed to save \~80MB at idle    |
| Redis queue                    | Replaced with SQLite-backed queue |
| Browser/Playwright tools       | Chromium won't fit in memory      |
| Multiple simultaneous channels | Single channel limit              |
| Real-time multi-user sessions  | No WebSocket broadcast layer      |

Switch to mini mode when you have 512MB+:

```bash theme={null}
profclaw serve --mode mini
```

Mini adds the web UI and multi-channel support. Pro adds Redis, browser tools, and full concurrency.

***

## Using a Separate Ollama Instance

Running inference on a Pi Zero is impractical. Point profClaw at an Ollama instance running on another machine on your network.

```bash theme={null}
# In .env or environment
OLLAMA_BASE_URL=http://192.168.1.50:11434
```

Or in `settings.yml`:

```yaml theme={null}
ai:
  provider: ollama
  baseUrl: http://192.168.1.50:11434
  model: llama3.2:3b
```

The Pi Zero acts as the agent runtime — tool execution, memory, scheduling, API surface — while a beefier machine handles inference. Works well with a Pi 5 or an old laptop as the Ollama host.

Verify the connection:

```bash theme={null}
profclaw doctor
```

The doctor check will confirm the Ollama endpoint is reachable and the model is loaded.

***

## Troubleshooting

### Container won't start

Check the logs before anything else:

```bash theme={null}
docker logs profclaw
```

Common causes: port 3000 already in use, missing `PROFCLAW_MODE`, or a bad volume mount path. The logs will point to the specific error.

### OOM during npm install (Options 2 and 3)

If the install gets killed mid-way, you do not have enough memory headroom. Use the swap method from Option 2 first, then retry:

```bash theme={null}
sudo swapon /swapfile
npm install -g profclaw
```

If you already added swap and it still fails, the swap file may be too small. Extend it:

```bash theme={null}
sudo swapoff /swapfile
sudo fallocate -l 2G /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```

### "No AI provider configured"

profClaw requires at least one AI provider key at startup. Set the env var for the provider you want to use:

```bash theme={null}
# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini
export GOOGLE_GENERATIVE_AI_API_KEY=AIza...

# Cerebras
export CEREBRAS_API_KEY=csk-...

# Local Ollama
export OLLAMA_BASE_URL=http://192.168.1.50:11434
```

For Docker, pass it with `-e` as shown in the install command above. For the npm install path, add it to your `.env` file in the profClaw data directory.

### Can't reach the API

1. Check the container or process is actually running:

```bash theme={null}
docker ps | grep profclaw
```

2. Confirm the port binding:

```bash theme={null}
docker port profclaw
```

3. Try curl from inside the container to rule out a network issue:

```bash theme={null}
docker exec profclaw curl -s http://localhost:3000/health
```

If that works but `curl http://localhost:3000/health` from your host does not, the problem is the port binding or a local firewall rule, not profClaw itself.

***

For the standard installation path on a full-spec machine, see the [main installation guide](/docs/INSTALLATION.md).


# Monitoring
Source: https://docs.profclaw.ai/guides/monitoring

Monitor profClaw health, performance, and costs

## Overview

Monitor your profClaw instance with built-in health endpoints, cost tracking, and log management. Integrate with external monitoring tools for production alerting.

## Health Endpoints

profClaw exposes health and readiness endpoints:

```bash theme={null}
# Basic health check
curl http://localhost:3000/api/health
# Returns: { "status": "ok", "version": "2.x.x", "mode": "mini", "uptime": 3600 }

# Readiness check (includes dependency checks)
curl http://localhost:3000/api/ready
# Returns: { "status": "ready", "checks": { "database": "ok", "redis": "ok", "providers": "ok" } }
```

## CLI Monitoring

```bash theme={null}
# System status overview
profclaw status

# Run diagnostic checks
profclaw doctor

# View active sessions
profclaw agent sessions

# Queue status
profclaw queue status
```

## Cost Tracking

Track AI provider token usage and costs:

```bash theme={null}
# Today's costs
profclaw cost

# Cost breakdown by provider
profclaw cost --breakdown

# Cost for a date range
profclaw cost --since 2026-03-01 --until 2026-03-12

# Export as JSON
profclaw cost --json
```

Sample output:

```
profClaw Cost Report - Today
──────────────────────────────
Provider        Tokens (in/out)    Cost
Anthropic       125,430 / 42,100   $0.89
OpenAI          45,200 / 15,600    $0.23
Ollama          89,000 / 31,200    $0.00 (local)
──────────────────────────────
Total                              $1.12
```

## Log Management

```bash theme={null}
# View live logs
profclaw logs --follow

# Filter by level
profclaw logs --level error

# Filter by time
profclaw logs --since 1h

# Filter by component
profclaw logs --component chat
profclaw logs --component security
profclaw logs --component queue
```

## Audit Log

For security and compliance monitoring:

```bash theme={null}
# View recent audit events
profclaw audit list

# Filter by event type
profclaw audit list --type tool_execution
profclaw audit list --type security_decision

# Export for compliance
profclaw audit export --format json --since 2026-03-01
```

## External Monitoring Integration

### Uptime Monitoring

Point any uptime monitor (UptimeRobot, Pingdom, etc.) at:

```
https://your-profclaw.com/api/health
```

Expected response: HTTP 200 with `{"status":"ok"}`

### Prometheus (Advanced)

profClaw can expose Prometheus-compatible metrics:

```yaml theme={null}
monitoring:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics
```

Available metrics:

* `profclaw_requests_total` - Total HTTP requests
* `profclaw_tool_executions_total` - Tool executions by tool name
* `profclaw_active_sessions` - Current active agent sessions
* `profclaw_queue_depth` - Current queue depth
* `profclaw_provider_tokens_total` - Token usage by provider
* `profclaw_provider_cost_total` - Cost by provider

### Alerting Rules

Example Prometheus alert rules:

```yaml theme={null}
groups:
  - name: profclaw
    rules:
      - alert: ProfClawDown
        expr: up{job="profclaw"} == 0
        for: 1m
      - alert: HighErrorRate
        expr: rate(profclaw_requests_total{status="5xx"}[5m]) > 0.1
        for: 5m
      - alert: QueueBacklog
        expr: profclaw_queue_depth > 100
        for: 10m
```


# Multi-Agent Workflows
Source: https://docs.profclaw.ai/guides/multi-agent

Orchestrate multiple AI agents working in parallel

## Overview

profClaw supports spawning multiple agent sessions that work in parallel, each with their own context, tools, and objectives. This enables complex workflows like researching multiple topics simultaneously, running parallel code reviews, or coordinating development tasks.

## Spawning Sessions

Use the `sessions-spawn` tool to create parallel agent sessions:

```bash theme={null}
profclaw agent spawn \
  --count 3 \
  --task "Review the authentication module for security issues" \
  --task "Check test coverage for the API routes" \
  --task "Audit environment variable usage"
```

## Session Architecture

Each spawned session:

* Gets its own execution context and tool access
* Runs independently and in parallel
* Can use all available tools (subject to security policy)
* Reports results back to the parent session
* Has configurable timeout via `POOL_TIMEOUT_MS`

```
Parent Session
├── Child Session 1 (security review)
├── Child Session 2 (test coverage)
└── Child Session 3 (env var audit)
```

## API Usage

Spawn sessions via the REST API:

```bash theme={null}
curl -X POST http://localhost:3000/api/agents/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "sessions": [
      {
        "task": "Review auth module for vulnerabilities",
        "provider": "anthropic",
        "model": "claude-sonnet-4-6",
        "tools": ["read_file", "grep", "glob"]
      },
      {
        "task": "Check test coverage",
        "provider": "anthropic",
        "tools": ["read_file", "test_run", "glob"]
      }
    ],
    "timeout": 300000
  }'
```

## Concurrency Limits

| Mode | Max Concurrent Sessions |
| ---- | ----------------------- |
| Pico | 2                       |
| Mini | 10                      |
| Pro  | 50+                     |

Configure via:

```bash theme={null}
export POOL_MAX_CONCURRENT=25
```

## Patterns

### Fan-Out / Fan-In

Distribute work across multiple agents, then aggregate results:

```
1. Parent receives complex task
2. Decomposes into subtasks
3. Spawns N child sessions (fan-out)
4. Children work in parallel
5. Parent collects all results (fan-in)
6. Parent synthesizes final answer
```

### Pipeline

Chain agents where each builds on the previous result:

```
Agent 1: Research → Agent 2: Plan → Agent 3: Implement → Agent 4: Review
```

### Specialist Teams

Different agents with different provider/model configurations:

```yaml theme={null}
# Fast agent for search and exploration
- provider: groq
  model: llama-3.3-70b
  task: "Find all API endpoints"

# Powerful agent for analysis
- provider: anthropic
  model: claude-sonnet-4-6
  task: "Analyze the codebase architecture"
```

## Resource Management

<Warning>
  Each session consumes API tokens from the configured provider. Monitor costs with `profclaw cost` when running many parallel sessions.
</Warning>

```bash theme={null}
# Check active sessions
profclaw agent sessions

# View cost breakdown
profclaw cost --today
```


# Quickstart
Source: https://docs.profclaw.ai/guides/quickstart

Get profClaw running in 5 minutes

## Pick your install method

### npm (easiest)

1. Run `npx profclaw onboard`
2. Follow the wizard. It detects your environment, asks for an AI key, starts the server.
3. Verify: `curl http://localhost:3000/health`

### Docker

1. `docker run -d -p 3000:3000 -e ANTHROPIC_API_KEY=sk-ant-xxx ghcr.io/profclaw/profclaw:latest`
2. Verify: `curl http://localhost:3000/health`

### Raspberry Pi / edge device

1. `docker run -d -p 3000:3000 -e PROFCLAW_MODE=pico ghcr.io/profclaw/profclaw:pico`
2. No auth needed in pico mode
3. See [low-memory guide](/guides/low-memory-devices) for details

## Send your first message

```bash theme={null}
curl -X POST http://localhost:3000/api/chat/send \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'
```

## Try the CLI

```bash theme={null}
profclaw chat "What can you do?"
profclaw chat --tui
```

## Open the dashboard

[http://localhost:3000](http://localhost:3000) (mini and pro modes only, not pico)

## Next steps

* [Full installation guide](/installation) for advanced config
* [AI providers](/providers) to add more models
* [Low-memory devices](/guides/low-memory-devices) for Pi and edge
* [Report a bug](https://github.com/profclaw/profclaw/issues/new?template=bug_report.md)


# Self-Hosted Production
Source: https://docs.profclaw.ai/guides/self-hosted

Deploy profClaw on your own server with systemd, TLS, and monitoring

## Overview

Run profClaw on a VPS or bare-metal server with production-grade configuration: systemd service management, TLS via Caddy or Nginx, and basic monitoring.

## Server Requirements

| Component | Minimum                    | Recommended      |
| --------- | -------------------------- | ---------------- |
| OS        | Ubuntu 22.04+ / Debian 12+ | Ubuntu 24.04 LTS |
| RAM       | 2GB (mini)                 | 4GB+             |
| CPU       | 2 cores                    | 4 cores          |
| Disk      | 10GB                       | 50GB SSD         |
| Node.js   | 22+                        | 22 LTS           |

## Installation

```bash theme={null}
# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt-get install -y nodejs

# Install profClaw
npm install -g profclaw

# Initialize
profclaw init
profclaw onboard
```

## Systemd Service

Create `/etc/systemd/system/profclaw.service`:

```ini theme={null}
[Unit]
Description=profClaw AI Agent Engine
After=network.target redis-server.service

[Service]
Type=simple
User=profclaw
Group=profclaw
WorkingDirectory=/opt/profclaw
ExecStart=/usr/bin/profclaw serve
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=PROFCLAW_MODE=pro
Environment=PORT=3000
EnvironmentFile=/opt/profclaw/.env

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable profclaw
sudo systemctl start profclaw
```

## TLS with Caddy

Install Caddy for automatic HTTPS:

```bash theme={null}
sudo apt install -y caddy
```

Edit `/etc/caddy/Caddyfile`:

```
profclaw.example.com {
    reverse_proxy localhost:3000
}
```

```bash theme={null}
sudo systemctl restart caddy
```

Caddy automatically provisions and renews Let's Encrypt certificates.

## Firewall

```bash theme={null}
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP (redirect)
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable
```

## Redis (Pro Mode)

```bash theme={null}
sudo apt install redis-server
sudo systemctl enable redis-server
```

Add to your `.env`:

```bash theme={null}
REDIS_URL=redis://localhost:6379
```

## Backup Cron

Add to crontab:

```bash theme={null}
0 2 * * * profclaw backup create --output /opt/profclaw/backups/
0 3 * * 0 find /opt/profclaw/backups/ -mtime +30 -delete
```

## Monitoring

Check status:

```bash theme={null}
sudo systemctl status profclaw
profclaw status
profclaw doctor
```

Health endpoint for uptime monitors:

```bash theme={null}
curl -f https://profclaw.example.com/api/health
```

## Log Management

```bash theme={null}
# View live logs
sudo journalctl -u profclaw -f

# View recent logs
profclaw logs --since 1h
```

Configure log rotation in settings.yml:

```yaml theme={null}
logging:
  level: info
  maxFiles: 10
  maxSize: 10m
```


# Build a Slack Bot
Source: https://docs.profclaw.ai/guides/slack-bot

Connect profClaw to your Slack workspace as an AI assistant. Step-by-step guide to creating a Slack app, configuring Socket Mode, and enabling tools.

## Overview

This guide walks you through setting up profClaw as a Slack bot that can respond to messages, execute tools, and run agentic workflows directly in your Slack channels.

## Prerequisites

* profClaw installed and running (mini or pro mode) - see [Installation](/getting-started/installation)
* A Slack workspace where you have admin access
* An AI provider configured (e.g., Anthropic or OpenAI) - see [AI Providers](/ai-providers/overview)

## Step 1: Create a Slack App

<Steps>
  <Step title="Create the app">
    Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**.

    Select **From scratch**, name it "profClaw", and choose your workspace.
  </Step>

  <Step title="Configure Bot Token Scopes">
    Navigate to **OAuth and Permissions** and add these Bot Token Scopes:

    | Scope               | Purpose               |
    | ------------------- | --------------------- |
    | `chat:write`        | Send messages         |
    | `app_mentions:read` | Respond to @mentions  |
    | `channels:history`  | Read channel messages |
    | `channels:read`     | List channels         |
    | `files:read`        | Access shared files   |
    | `files:write`       | Upload files          |
    | `im:history`        | Read direct messages  |
    | `im:read`           | Access DM channels    |
    | `im:write`          | Send direct messages  |
  </Step>

  <Step title="Enable Socket Mode">
    Go to **Socket Mode** and enable it. Create an app-level token with `connections:write` scope.

    Save the token - it starts with `xapp-`.

    Socket Mode connects to Slack over a persistent WebSocket, so you do not need a public webhook URL for development.
  </Step>

  <Step title="Enable Events">
    Go to **Event Subscriptions** and enable events. Subscribe to:

    * `message.channels`
    * `message.im`
    * `app_mention`
  </Step>

  <Step title="Install to workspace">
    Go to **Install App** and click **Install to Workspace**. Authorize the permissions.

    Save the **Bot User OAuth Token** - it starts with `xoxb-`.
  </Step>

  <Step title="Copy the Signing Secret">
    Go to **Basic Information** and copy the **Signing Secret** from the App Credentials section.
  </Step>
</Steps>

## Step 2: Configure profClaw

Set the required environment variables:

```bash theme={null}
export SLACK_BOT_TOKEN=xoxb-your-bot-token
export SLACK_APP_TOKEN=xapp-your-app-token
export SLACK_SIGNING_SECRET=your-signing-secret
```

Or add to `.profclaw/settings.yml`:

```yaml theme={null}
chat:
  channels:
    slack:
      enabled: true
      botToken: ${SLACK_BOT_TOKEN}
      appToken: ${SLACK_APP_TOKEN}
      signingSecret: ${SLACK_SIGNING_SECRET}
```

## Step 3: Start profClaw

```bash theme={null}
profclaw serve
```

You should see:

```
✓ Slack bot connected via Socket Mode
✓ Listening for events in workspace: Your Workspace
```

<Tip>
  Run `profclaw doctor --chat` to verify Slack connectivity without starting the full server.
</Tip>

## Step 4: Test It

Invite the bot to a channel first:

```
/invite @profClaw
```

Then mention it or send a direct message:

```
@profClaw What files are in the src/ directory?
@profClaw Summarize the open issues in our repo
```

The bot replies in a thread by default, showing tool execution progress as it runs.

## Configuration Options

| Variable                   | Default | Description                               |
| -------------------------- | ------- | ----------------------------------------- |
| `SLACK_RESPONSE_THREAD`    | `true`  | Reply in threads instead of inline        |
| `SLACK_TYPING_INDICATOR`   | `true`  | Show typing indicator while processing    |
| `SLACK_MAX_MESSAGE_LENGTH` | `4000`  | Max message length (Slack API limit)      |
| `SLACK_ALLOWED_CHANNELS`   | `*`     | Comma-separated channel IDs to respond in |

## Security Considerations

<Warning>
  The Slack bot inherits your profClaw security mode. In `permissive` mode, anyone who can message the bot can execute file operations and shell commands. Use `standard` or `ask` mode for any shared workspace.
</Warning>

Restrict which channels the bot responds in using allowlists:

```yaml theme={null}
chat:
  channels:
    slack:
      allowedChannels:
        - C0123456789  # #engineering
        - C9876543210  # #devops
      allowedUsers:
        - U012345678   # restrict to specific users
```

See [Security Overview](/security/overview) for how security modes affect tool execution.

## Multi-Workspace Setup

To run the bot across multiple Slack workspaces, configure multiple accounts:

```yaml theme={null}
chat:
  slack:
    accounts:
      - id: work
        botToken: xoxb-work-...
        appToken: xapp-work-...
        signingSecret: ...
        isDefault: true
      - id: community
        botToken: xoxb-community-...
        appToken: xapp-community-...
        signingSecret: ...
```

## Related Guides

<CardGroup>
  <Card title="Chat Providers Overview" icon="messages" href="/chat-providers/overview">
    Connect profClaw to Discord, Telegram, WhatsApp, and more.
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/guides/docker-deployment">
    Run profClaw and your Slack bot in production with Docker.
  </Card>
</CardGroup>


# WhatsApp Bot
Source: https://docs.profclaw.ai/guides/whatsapp-bot

Connect profClaw to WhatsApp Business for mobile AI access

## Overview

Connect profClaw to WhatsApp Business API to interact with your AI agent from your phone. Send text messages, images, and documents for AI processing.

## Prerequisites

* profClaw running (mini or pro mode)
* Meta Business account
* WhatsApp Business API access

## Step 1: Meta Business Setup

<Steps>
  <Step title="Create Meta App">
    Go to [developers.facebook.com](https://developers.facebook.com), create a new app, and select **Business** type.
  </Step>

  <Step title="Add WhatsApp Product">
    In your app dashboard, add the **WhatsApp** product and complete the setup wizard.
  </Step>

  <Step title="Get Credentials">
    From the WhatsApp settings, note:

    * **Phone Number ID**
    * **Access Token** (permanent token recommended)
    * **Verify Token** (you create this)
  </Step>

  <Step title="Configure Webhook">
    Set the webhook URL to:

    ```
    https://your-profclaw.com/api/chat/whatsapp/webhook
    ```

    Subscribe to `messages` events.
  </Step>
</Steps>

## Step 2: Configure profClaw

```bash theme={null}
export WHATSAPP_ACCESS_TOKEN=your-access-token
export WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
export WHATSAPP_VERIFY_TOKEN=your-verify-token
```

```yaml theme={null}
chat:
  channels:
    whatsapp:
      enabled: true
      accessToken: ${WHATSAPP_ACCESS_TOKEN}
      phoneNumberId: ${WHATSAPP_PHONE_NUMBER_ID}
      verifyToken: ${WHATSAPP_VERIFY_TOKEN}
```

## Step 3: Test

Send a message to your WhatsApp Business number:

```
You: What's the weather like?
profClaw: I can help with that! Let me search for current weather information...
```

## Features

| Feature             | Supported                       |
| ------------------- | ------------------------------- |
| Text messages       | Yes                             |
| Image analysis      | Yes (with vision-capable model) |
| Document processing | Yes                             |
| Voice messages      | Planned                         |
| Location sharing    | Planned                         |
| Group chats         | Yes (pro mode)                  |

## Message Format

profClaw formats responses for WhatsApp's constraints:

* Messages longer than 4096 characters are split
* Code blocks use monospace formatting
* Tables are converted to readable lists
* Links are preserved as clickable URLs

## Security

<Warning>
  WhatsApp messages are processed through Meta's servers. Do not send sensitive credentials or secrets via WhatsApp chat. Use the web UI or CLI for sensitive operations.
</Warning>

Restrict which phone numbers can interact:

```yaml theme={null}
chat:
  channels:
    whatsapp:
      allowedNumbers:
        - "+1234567890"
        - "+0987654321"
```


# Introduction
Source: https://docs.profclaw.ai/index

profClaw is a local-first AI agent engine. Connect 37 AI providers, 27 chat channels, and 77+ tools in a single self-hosted install.

## Welcome to profClaw

profClaw is a lightweight, self-hosted AI agent engine that runs anywhere - Docker, VPS, home server, or Mac. Wire together AI providers, chat channels, and tools through a single install and configuration file.

<CardGroup>
  <Card title="37 AI Providers" icon="brain">
    Anthropic, OpenAI, Google, Ollama, Groq, Mistral, and 31 more. Mix cloud and local models.
  </Card>

  <Card title="27 Chat Channels" icon="messages">
    Slack, Discord, Telegram, WhatsApp, Teams, and more. One agent, every platform.
  </Card>

  <Card title="77+ Tools" icon="wrench">
    File ops, git, browser, web search, cron, memory, sessions, and custom tools.
  </Card>
</CardGroup>

## Quick Start

Get profClaw running in under 5 minutes.

<Steps>
  <Step title="Install">
    ```bash theme={null}
    npm install -g profclaw
    ```

    For Docker, see the [full installation guide](/getting-started/installation).
  </Step>

  <Step title="Initialize and configure">
    ```bash theme={null}
    profclaw init
    profclaw onboard
    ```

    The wizard detects your environment, sets the deployment mode, and configures your first AI provider.
  </Step>

  <Step title="Start the server">
    ```bash theme={null}
    profclaw serve
    ```

    Open `http://localhost:3000` to access the web UI. See [First Run](/getting-started/first-run) for a walkthrough.
  </Step>
</Steps>

<Card title="Full Installation Guide" icon="arrow-right" href="/getting-started/installation">
  Detailed setup instructions for all platforms, install methods, and post-install verification.
</Card>

## Choose Your Path

<CardGroup>
  <Card title="Set up a Slack Bot" icon="slack" href="/guides/slack-bot">
    Connect profClaw to your Slack workspace as an AI assistant with tool access.
  </Card>

  <Card title="Run Local LLMs" icon="microchip" href="/guides/local-llm">
    Use Ollama or LM Studio for fully offline AI capabilities.
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/guides/docker-deployment">
    Production-ready Docker setup with Redis and persistent storage.
  </Card>

  <Card title="GitHub Workflow" icon="github" href="/guides/github-workflow">
    Automate issues, PRs, and code reviews with profClaw agents.
  </Card>
</CardGroup>

## Deployment Modes

profClaw scales from a Raspberry Pi to a full production cluster. Choose the mode that fits your hardware.

| Mode     | RAM / CPU      | AI Providers | Chat Channels | Tools | Best For                        |
| -------- | -------------- | ------------ | ------------- | ----- | ------------------------------- |
| **Pico** | 512MB, 1 core  | 3            | 2             | 15    | IoT, edge devices, personal use |
| **Mini** | 2GB, 2 cores   | 15           | 10            | 50    | Small teams, home servers       |
| **Pro**  | 8GB+, 4+ cores | 37           | 27            | 77+   | Production, enterprise          |

<Card title="Deployment Modes" icon="server" href="/getting-started/deployment-modes">
  Compare features in detail and choose the right mode for your setup.
</Card>

## Key Features

<AccordionGroup>
  <Accordion title="Agentic Execution Engine">
    Multi-step tool execution with self-correction, smart prompts, and sandboxed environments. Supports parallel tool calls and streaming responses. Model-aware tool routing ensures small local models only receive tools they can handle reliably.
  </Accordion>

  <Accordion title="50 Built-in Skills">
    Pre-built expertise modules like `commit`, `review-pr`, `deploy`, `analyze-code`, and more. Invoked with slash commands (`/commit`, `/review-pr 42`). Create custom skills with a plain Markdown `SKILL.md` file - no code required. See [Skills](/skills/overview).
  </Accordion>

  <Accordion title="Plugin System">
    Extend profClaw with custom plugins using the TypeScript SDK. Add new tools, search providers, integrations, or model adapters. Browse and install community plugins via ClawHub. See [Plugins](/plugins/overview).
  </Accordion>

  <Accordion title="Security First">
    Five security modes (deny, sandbox, standard, ask, full), per-tool approval gates, filesystem path guards, SSRF protection, prompt injection detection, audit logging, and QR-based device pairing. See [Security Overview](/security/overview).
  </Accordion>

  <Accordion title="Configuration">
    130+ environment variables for fine-grained control. All settings configurable via env vars or `settings.yml`. See [Configuration Overview](/configuration/overview) and [Environment Variables](/configuration/environment-variables).
  </Accordion>
</AccordionGroup>

## Reference

<CardGroup>
  <Card title="CLI Reference" icon="terminal" href="/cli/chat">
    All CLI commands: chat, serve, agent, doctor, config, and more.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    REST API for chat, agents, tasks, memory, and webhooks.
  </Card>

  <Card title="Configuration" icon="sliders" href="/configuration/overview">
    settings.yml schema, environment variables, and security config.
  </Card>
</CardGroup>


# Cloudflare Integration
Source: https://docs.profclaw.ai/integrations/cloudflare

Deploy profClaw to Cloudflare Workers and use D1, R2, and KV for storage

profClaw can run on Cloudflare's edge infrastructure. Workers host the Hono API, D1 provides SQLite-compatible database storage, R2 handles file storage, and KV stores session and configuration data.

## Supported Services

| Service             | profClaw Use Case                                     |
| ------------------- | ----------------------------------------------------- |
| Workers             | Host the Hono API server                              |
| D1 (SQLite)         | Task, conversation, and memory storage                |
| R2 (Object Storage) | File attachments, backup exports                      |
| KV                  | Session tokens, rate limit counters, feature flags    |
| Tunnels             | Expose local profClaw to webhooks (via `cloudflared`) |

## Setup

### 1. Install Wrangler

```bash theme={null}
pnpm add -g wrangler
wrangler login
```

### 2. Configure environment variables

```bash theme={null}
CLOUDFLARE_API_TOKEN=your-api-token
CLOUDFLARE_ACCOUNT_ID=your-account-id
```

The API token needs permissions: `Workers Scripts:Edit`, `D1:Edit`, `R2:Edit`, `KV:Edit`.

### 3. Create resources

```bash theme={null}
# Create D1 database
wrangler d1 create profclaw-db

# Create R2 bucket
wrangler r2 bucket create profclaw-files

# Create KV namespace
wrangler kv:namespace create profclaw-sessions
```

### 4. Configure wrangler.toml

```toml theme={null}
name = "profclaw"
main = "dist/server.js"
compatibility_date = "2024-01-01"

[[d1_databases]]
binding = "DB"
database_name = "profclaw-db"
database_id = "your-database-id"

[[r2_buckets]]
binding = "FILES"
bucket_name = "profclaw-files"

[[kv_namespaces]]
binding = "SESSIONS"
id = "your-kv-namespace-id"
```

## Cloudflare Tunnels

Use `cloudflared` to expose your local profClaw instance for webhook development:

```bash theme={null}
# Install cloudflared
brew install cloudflare/cloudflare/cloudflared

# Authenticate
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create profclaw

# Route traffic
cloudflared tunnel route dns profclaw profclaw.yourdomain.com

# Run tunnel
cloudflared tunnel run profclaw
```

The `cloudflare-tunnel.ts` module (`src/integrations/cloudflare-tunnel.ts`) provides a programmatic interface for managing tunnel status and health checks.

## D1 Storage Adapter

profClaw's storage layer abstracts over D1 and LibSQL. When `CLOUDFLARE_D1_DATABASE_ID` is set, the D1 adapter is used automatically. The schema is compatible between local SQLite (via libsql) and Cloudflare D1.

## R2 File Storage

Files uploaded via the chat or backup routes are stored in R2 when the `R2_BUCKET` binding is configured. The bucket serves as the target for:

* Conversation attachments
* Backup exports (`.json` archives)
* Skill packages

## KV Rate Limiting

When Redis is not available (pico/mini mode), KV namespaces can be used for rate limit counters and session token storage. This allows profClaw to run fully serverless on Cloudflare without a Redis dependency.


# GitHub Integration
Source: https://docs.profclaw.ai/integrations/github

Connect profClaw to GitHub for issue automation, PR reviews, and code task dispatch

The GitHub integration lets profClaw receive webhook events, create tasks from issues and pull requests, post AI-generated comments, and perform OAuth-authenticated repo operations.

## How It Works

profClaw listens at `/api/webhooks/github`. On each inbound event it verifies the `X-Hub-Signature-256` HMAC signature, then routes based on the event type.

### Supported Events

| Event                           | Action              | Trigger                      |
| ------------------------------- | ------------------- | ---------------------------- |
| `issues.opened`                 | Creates a task      | Always (if label matches)    |
| `issues.labeled`                | Creates a task      | Label = `ai-task`            |
| `issue_comment.created`         | Creates a task      | Contains `@profclaw` mention |
| `pull_request.opened`           | Creates review task | Always                       |
| `pull_request.review_requested` | Creates review task | Always                       |
| `ping`                          | Handshake reply     | Webhook setup                |

The label that triggers task creation defaults to `ai-task` and can be overridden with `GITHUB_AI_TASK_LABEL`. Review tasks use `ai-review` (`GITHUB_AI_REVIEW_LABEL`).

## Setup

### 1. Configure environment variables

```bash theme={null}
GITHUB_WEBHOOK_SECRET=your-32-char-secret
GITHUB_AI_TASK_LABEL=ai-task
GITHUB_AI_REVIEW_LABEL=ai-review

# For OAuth (repo read/write, PR comments)
GITHUB_CLIENT_ID=your-oauth-app-client-id
GITHUB_CLIENT_SECRET=your-oauth-app-client-secret
GITHUB_REDIRECT_URI=https://your-host/api/auth/github/callback
```

### 2. Create the GitHub webhook

In your repo settings: **Settings > Webhooks > Add webhook**

* **Payload URL**: `https://your-host/api/webhooks/github`
* **Content type**: `application/json`
* **Secret**: same as `GITHUB_WEBHOOK_SECRET`
* **Events**: Issues, Issue comments, Pull requests, Pull request reviews

### 3. OAuth connection (optional)

OAuth lets the agent comment on issues and create PRs. Redirect users to:

```
GET /api/auth/github
```

The callback at `/api/auth/github/callback` exchanges the code for a session. For SPA flows use `GET /api/auth/github/url` to retrieve the authorization URL without a redirect.

## Signature Verification

```typescript theme={null}
// src/integrations/github.ts
export function verifyGitHubSignature(
  payload: string,
  signature: string | undefined
): boolean
```

All incoming webhooks are verified with `createHmac('sha256', WEBHOOK_SECRET)`. Requests that fail verification return `403`. Set `GITHUB_WEBHOOK_SECRET` to a strong random value.

## Task Creation from Issues

When profClaw receives `issues.labeled` with the `ai-task` label, it creates a task with:

```json theme={null}
{
  "title": "GitHub Issue #42: Fix the login bug",
  "source": "github",
  "sourceId": "42",
  "sourceUrl": "https://github.com/org/repo/issues/42",
  "repository": "org/repo",
  "labels": ["ai-task", "bug"],
  "priority": 2
}
```

Priority is inferred from GitHub labels: `critical` > `high` > `medium` > `low`.

## PR Review Automation

On `pull_request.opened`, profClaw creates a review task. The agent reads the diff, checks for common issues, and posts a review comment. The result is posted back via the GitHub API using the authenticated user's token.

## Ticket Sync

The `GitHubTicketSync` class (`src/integrations/github-ticket-sync.ts`) provides bidirectional sync for projects using GitHub Issues as a ticket tracker. It maps GitHub issue states to profClaw `TicketStatus` values and keeps labels in sync.


# Jira Integration
Source: https://docs.profclaw.ai/integrations/jira

Connect profClaw to Jira Cloud via OAuth 2.0 for bidirectional ticket sync

The Jira integration uses OAuth 2.0 (3-legged) to authenticate with Jira Cloud. Once connected, profClaw can create issues, update status, sync comments, and receive webhook notifications.

## Setup

### 1. Create an OAuth 2.0 app in Atlassian

1. Go to [developer.atlassian.com](https://developer.atlassian.com/console/myapps/)
2. Create a new app, select **OAuth 2.0 (3LO)**
3. Add the callback URL: `https://your-host/api/auth/jira/callback`
4. Enable scopes: `read:jira-work`, `write:jira-work`, `offline_access`

### 2. Configure environment variables

```bash theme={null}
JIRA_CLIENT_ID=your-client-id
JIRA_CLIENT_SECRET=your-client-secret
JIRA_REDIRECT_URI=https://your-host/api/auth/jira/callback
```

### 3. Connect via OAuth

Redirect the user to start the OAuth flow:

```
GET /api/auth/jira
```

After authorization, the callback at `/api/auth/jira/callback` exchanges the code for tokens and stores them. Refresh tokens are used automatically when the access token expires.

## Webhook Events

Register a Jira webhook to receive real-time events:

* **URL**: `https://your-host/api/webhooks/jira`
* **Events**: `jira:issue_created`, `jira:issue_updated`, `comment_created`

Incoming events are verified and routed to create or update local tasks.

## Status Mapping

Jira statuses map to profClaw `TicketStatus` values via the sync adapter:

| Jira Status | profClaw Status |
| ----------- | --------------- |
| To Do       | `open`          |
| In Progress | `in_progress`   |
| In Review   | `in_review`     |
| Done        | `closed`        |
| Cancelled   | `cancelled`     |

Mapping is bidirectional. When a profClaw ticket changes status, the corresponding Jira issue updates via the Jira REST API.

## Priority Mapping

| Jira Priority | profClaw Priority |
| ------------- | ----------------- |
| Highest       | `critical` (1)    |
| High          | `high` (2)        |
| Medium        | `medium` (3)      |
| Low           | `low` (4)         |
| Lowest        | `low` (4)         |

## Bidirectional Sync

The sync engine polls Jira for updates every 60 seconds (configurable via `syncIntervalMs`). Conflicts use the `latest_wins` strategy by default.

```typescript theme={null}
// src/sync/types.ts
export type ConflictStrategy = 'local_wins' | 'remote_wins' | 'latest_wins' | 'manual';
```

To enable Jira sync, configure the platform in your settings:

```yaml theme={null}
# config/settings.yml
sync:
  platforms:
    jira:
      accessToken: "${JIRA_ACCESS_TOKEN}"
      workspaceId: "your-site-id.atlassian.net"
      projectId: "PROJ"
```

## Jira Client

The `JiraClient` class (`src/integrations/jira-client.ts`) wraps the Jira REST API v3:

* `createIssue(fields)` - Create a new Jira issue
* `updateIssue(issueKey, fields)` - Update fields on an existing issue
* `transitionIssue(issueKey, transitionId)` - Change issue status
* `addComment(issueKey, body)` - Add a comment
* `getIssue(issueKey)` - Fetch a single issue
* `searchIssues(jql, options)` - JQL search with pagination


# Linear Integration
Source: https://docs.profclaw.ai/integrations/linear

Connect profClaw to Linear for issue sync, label-driven automation, and OAuth-based operations

The Linear integration uses OAuth 2.0 to connect to your Linear workspace. profClaw can create issues, update their state, sync labels, and receive webhook events from Linear teams.

## Setup

### 1. Create a Linear OAuth app

1. Go to [linear.app/settings/api](https://linear.app/settings/api)
2. Create a new application
3. Set the callback URL: `https://your-host/api/auth/linear/callback`
4. Note the **Client ID** and **Client Secret**

### 2. Configure environment variables

```bash theme={null}
LINEAR_CLIENT_ID=your-client-id
LINEAR_CLIENT_SECRET=your-client-secret
LINEAR_REDIRECT_URI=https://your-host/api/auth/linear/callback
```

### 3. Connect via OAuth

```
GET /api/auth/linear
```

The callback at `/api/auth/linear/callback` stores the access token and associates it with the current user session.

## Webhook Events

Linear webhooks arrive at `/api/webhooks/linear`. Supported event types:

| Event                | Action                     |
| -------------------- | -------------------------- |
| `Issue.created`      | Creates a profClaw task    |
| `Issue.updated`      | Updates local ticket state |
| `Comment.created`    | Syncs comment to profClaw  |
| `IssueLabel.created` | Updates label mapping      |

## State Mapping

Linear uses workflow states per team. The Linear adapter maps these to profClaw statuses:

| Linear State Type | profClaw Status |
| ----------------- | --------------- |
| `triage`          | `open`          |
| `backlog`         | `open`          |
| `unstarted`       | `open`          |
| `started`         | `in_progress`   |
| `completed`       | `closed`        |
| `cancelled`       | `cancelled`     |

## Priority Mapping

| Linear Priority | profClaw Priority |
| --------------- | ----------------- |
| Urgent (1)      | `critical`        |
| High (2)        | `high`            |
| Medium (3)      | `medium`          |
| Low (4)         | `low`             |
| No priority (0) | `low`             |

## Label Mapping

Linear labels are synced as profClaw ticket labels. The `LabelMapper` (`src/integrations/linear.ts`) maintains a cache of the label ID-to-name mapping per team.

## Bidirectional Sync

Configure the Linear sync adapter in `settings.yml`:

```yaml theme={null}
sync:
  platforms:
    linear:
      apiKey: "${LINEAR_API_KEY}"
      teamId: "your-team-id"
      projectId: "your-project-id"  # optional
```

The sync engine pulls changes every 60 seconds using the Linear `updatedAt` cursor. Pushes happen immediately on local ticket mutations.

## Linear Client

The `LinearClient` class (`src/integrations/linear-client.ts`) wraps the Linear GraphQL API:

* `createIssue(input)` - Create a new issue
* `updateIssue(id, input)` - Update title, description, state, priority, or labels
* `deleteIssue(id)` - Archive an issue
* `getIssue(id)` - Fetch a single issue with state and labels
* `listIssues(options)` - Paginated list with cursor support
* `addComment(issueId, body)` - Add a comment
* `getTeamStates(teamId)` - Fetch workflow states for mapping
* `getTeamLabels(teamId)` - Fetch label definitions

All GraphQL operations are authenticated with the `Authorization: Bearer <token>` header.


# Integrations Overview
Source: https://docs.profclaw.ai/integrations/overview

Connect profClaw to GitHub, Jira, Linear, Cloudflare, and Tailscale

profClaw integrates with the tools your team already uses. Webhooks create tasks automatically, OAuth connections let the agent act on your behalf, and the sync engine keeps ticket state consistent across platforms.

## Available Integrations

<CardGroup>
  <Card title="GitHub" icon="github" href="/integrations/github">
    Issue and PR webhooks, OAuth for repo access, automated code reviews, and AI task labels.
  </Card>

  <Card title="Jira" icon="atlassian" href="/integrations/jira">
    OAuth 2.0 connection, bidirectional ticket sync, status field mapping, and sprint support.
  </Card>

  <Card title="Linear" icon="linear" href="/integrations/linear">
    OAuth 2.0, issue sync, label and state mapping, and team-based project routing.
  </Card>

  <Card title="Cloudflare" icon="cloudflare" href="/integrations/cloudflare">
    Workers deployment, D1 database, R2 storage, KV namespaces, and edge routing.
  </Card>

  <Card title="Tailscale" icon="network-wired" href="/integrations/tailscale">
    Mesh VPN tunnels, secure device-to-device access, and zero-config private networking.
  </Card>
</CardGroup>

## Comparison Table

| Feature            | GitHub              | Jira            | Linear          |
| ------------------ | ------------------- | --------------- | --------------- |
| OAuth              | Yes                 | Yes (OAuth 2.0) | Yes (OAuth 2.0) |
| Webhooks           | Yes                 | Yes             | Yes             |
| Bidirectional sync | Yes                 | Yes             | Yes             |
| Auto task creation | Yes (label trigger) | Via webhook     | Via webhook     |
| PR reviews         | Yes                 | -               | -               |
| Comment sync       | Yes                 | Yes             | Yes             |
| Priority mapping   | Yes                 | Yes             | Yes             |
| Status mapping     | Yes                 | Yes             | Yes             |

## How Integrations Work

### Webhook-to-Task Pipeline

When a webhook arrives at `/api/webhooks/github` (or Jira/Linear), profClaw:

1. Verifies the signature (`X-Hub-Signature-256` for GitHub)
2. Parses the event type (`issues.opened`, `pull_request.opened`, etc.)
3. Checks configured label triggers (`ai-task`, `ai-review`)
4. Creates a `Task` via `addTask()` and queues it for agent processing
5. Posts a result comment back to the source issue or PR

### Sync Engine

The sync engine (`src/sync/`) handles bidirectional state updates:

* **Push**: Local ticket changes propagate to the external platform
* **Pull**: External changes update local tickets on a polling interval
* **Bidirectional**: Both directions, with conflict resolution

Conflict strategies: `local_wins`, `remote_wins`, `latest_wins`, `manual`

### Environment Variables

```bash theme={null}
# GitHub
GITHUB_WEBHOOK_SECRET=your-secret
GITHUB_AI_TASK_LABEL=ai-task
GITHUB_AI_REVIEW_LABEL=ai-review

# Jira
JIRA_CLIENT_ID=your-client-id
JIRA_CLIENT_SECRET=your-client-secret
JIRA_REDIRECT_URI=https://your-host/api/auth/jira/callback

# Linear
LINEAR_CLIENT_ID=your-client-id
LINEAR_CLIENT_SECRET=your-client-secret
LINEAR_REDIRECT_URI=https://your-host/api/auth/linear/callback

# Cloudflare
CLOUDFLARE_API_TOKEN=your-token
CLOUDFLARE_ACCOUNT_ID=your-account-id

# Tailscale
TAILSCALE_AUTH_KEY=your-auth-key
TAILSCALE_TAILNET=your-tailnet
```


# Tailscale Integration
Source: https://docs.profclaw.ai/integrations/tailscale

Use Tailscale to securely connect profClaw devices without port forwarding

Tailscale creates a mesh VPN between your profClaw instances, agents, and devices. No firewall rules or open ports are needed. Every node authenticates with a Tailscale auth key and gets a stable private IP on your tailnet.

## Use Cases

* **Multi-device sync**: Two profClaw instances sync their state over Tailscale without exposing ports to the internet
* **Private webhook delivery**: Receive GitHub/Jira webhooks to a home server via a Tailscale Funnel or a cloudflared alternative
* **Agent-to-agent calls**: Sub-agents spawned on different machines communicate over the tailnet
* **Remote CLI access**: Run `profclaw` CLI commands against a remote server over `ssh`

## Setup

### 1. Install Tailscale

```bash theme={null}
# macOS
brew install tailscale

# Linux
curl -fsSL https://tailscale.com/install.sh | sh

# Docker
docker pull tailscale/tailscale
```

### 2. Configure environment variables

```bash theme={null}
TAILSCALE_AUTH_KEY=tskey-auth-...
TAILSCALE_TAILNET=your-tailnet-name.ts.net
TAILSCALE_HOSTNAME=profclaw-server   # optional, defaults to hostname
```

Generate an auth key at [login.tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys). Use **reusable, ephemeral** keys for containerized deployments.

### 3. Start Tailscale

```bash theme={null}
tailscale up --authkey="${TAILSCALE_AUTH_KEY}" --hostname=profclaw-server
```

### 4. Verify connectivity

```bash theme={null}
tailscale status
tailscale ping profclaw-server
```

## profClaw Tailscale Module

The `tailscale.ts` integration (`src/integrations/tailscale.ts`) wraps the Tailscale local API for:

* Querying device status and assigned IP addresses
* Checking peer connectivity before sync operations
* Registering the current node on startup

## Tunnel Configuration

For receiving webhooks from GitHub or Jira on a private instance, use **Tailscale Funnel**:

```bash theme={null}
# Expose profClaw port 3000 via Tailscale Funnel
tailscale funnel 3000
```

This gives you a public HTTPS URL (`https://profclaw-server.tailnet-xyz.ts.net`) without opening any inbound firewall rules.

## Security Model

* All traffic between tailnet nodes is encrypted with WireGuard
* Device authentication uses the Tailscale identity provider (Google, GitHub, OIDC, or SAML)
* ACLs on the Tailscale admin panel control which nodes can reach the profClaw API port
* The profClaw device identity system (`src/auth/device-identity.ts`) uses Ed25519 key pairs that complement Tailscale's node identity

## Multi-Device Sync over Tailscale

When two profClaw instances are on the same tailnet, configure the sync engine to use Tailscale private IPs:

```yaml theme={null}
# config/settings.yml
sync:
  peers:
    - name: profclaw-home
      url: http://100.64.0.2:3000  # Tailscale IP
      authToken: "${PEER_AUTH_TOKEN}"
```

Sync traffic stays within the encrypted tailnet mesh - no TLS certificates required for intra-tailnet communication.


# Plugin Examples
Source: https://docs.profclaw.ai/plugins/examples

Complete example plugins: a search provider and a custom tool

## Example 1: Brave Search Provider

A full search plugin using the Brave Search API.

```typescript theme={null}
// src/index.ts
import { definePlugin } from 'profclaw/plugins/sdk';
import type { SearchOptions, SearchResponse, PluginConfig, PluginHealth } from 'profclaw/plugins/sdk';

export default definePlugin({
  metadata: {
    id: 'brave-search',
    name: 'Brave Search',
    description: 'Privacy-focused web search via Brave API',
    category: 'search',
    icon: 'search',
    version: '1.0.0',
    author: 'your-name',
    pricing: { type: 'freemium', freeQuota: 2000 },
    rateLimit: { requestsPerSecond: 1, requestsPerDay: 2000 },
  },
  settingsSchema: {
    credentials: [
      {
        key: 'apiKey',
        type: 'password',
        label: 'Brave API Key',
        description: 'Get your key at api.search.brave.com',
        required: true,
        placeholder: 'BSA...',
      },
    ],
    settings: [
      {
        key: 'maxResults',
        type: 'number',
        label: 'Max Results',
        default: 10,
        validation: { min: 1, max: 20 },
      },
      {
        key: 'safeSearch',
        type: 'select',
        label: 'Safe Search',
        default: 'moderate',
        options: [
          { value: 'off', label: 'Off' },
          { value: 'moderate', label: 'Moderate' },
          { value: 'strict', label: 'Strict' },
        ],
      },
    ],
  },

  searchProvider: (config: PluginConfig) => ({
    metadata: {
      id: 'brave-search',
      name: 'Brave Search',
      description: 'Privacy-focused web search',
      category: 'search' as const,
      version: '1.0.0',
    },

    async search(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
      const apiKey = config.credentials?.apiKey;
      if (!apiKey) throw new Error('Brave API key not configured');

      const params = new URLSearchParams({
        q: query,
        count: String(options.limit ?? config.settings.maxResults ?? 10),
        safesearch: config.settings.safeSearch as string ?? 'moderate',
      });

      const start = Date.now();
      const res = await fetch(`https://api.search.brave.com/res/v1/web/search?${params}`, {
        headers: { 'X-Subscription-Token': apiKey, 'Accept': 'application/json' },
      });

      if (!res.ok) throw new Error(`Brave API error: ${res.status}`);
      const data = await res.json() as {
        web?: { results?: Array<{ title: string; url: string; description?: string }> };
        query?: { original: string };
      };

      return {
        provider: 'brave',
        query,
        searchTime: Date.now() - start,
        results: (data.web?.results ?? []).map((r) => ({
          title: r.title,
          url: r.url,
          snippet: r.description ?? '',
        })),
      };
    },

    async isAvailable(): Promise<boolean> {
      return Boolean(config.credentials?.apiKey);
    },

    async healthCheck(): Promise<PluginHealth> {
      try {
        await this.search('test', { limit: 1 });
        return { healthy: true, lastCheck: new Date() };
      } catch (err) {
        return {
          healthy: false,
          lastCheck: new Date(),
          errorMessage: err instanceof Error ? err.message : 'Unknown error',
        };
      }
    },
  }),
});
```

***

## Example 2: Custom Tool Plugin

A tool plugin that fetches data from an internal API.

```typescript theme={null}
// src/index.ts
import { definePlugin } from 'profclaw/plugins/sdk';

export default definePlugin({
  metadata: {
    id: 'internal-api',
    name: 'Internal API Tools',
    description: 'Tools for querying the internal company API',
    category: 'tool',
    version: '1.0.0',
    author: 'your-team',
    pricing: { type: 'free' },
  },
  settingsSchema: {
    credentials: [
      { key: 'apiKey', type: 'password', label: 'API Key', required: true },
    ],
    settings: [
      { key: 'baseUrl', type: 'url', label: 'API Base URL', required: true,
        placeholder: 'https://api.internal.example.com' },
    ],
  },

  tools: [
    {
      name: 'get_customer',
      description: 'Fetch customer details by ID or email',
      parameters: {
        identifier: {
          type: 'string',
          description: 'Customer ID or email address',
          required: true,
        },
      },
      async execute({ identifier }) {
        // Note: access config via closure in a real plugin
        const res = await fetch(`https://api.internal.example.com/customers/${identifier}`, {
          headers: { 'Authorization': 'Bearer YOUR_KEY' },
        });
        if (!res.ok) {
          return { success: false, error: `API error ${res.status}` };
        }
        return { success: true, data: await res.json(), metadata: { executionTime: 100 } };
      },
    },
    {
      name: 'list_open_tickets',
      description: 'List open support tickets for a customer',
      parameters: {
        customerId: { type: 'string', description: 'Customer ID', required: true },
        limit: { type: 'number', description: 'Max results', default: 10 },
      },
      async execute({ customerId, limit }) {
        const res = await fetch(
          `https://api.internal.example.com/tickets?customerId=${customerId}&limit=${limit}`
        );
        if (!res.ok) return { success: false, error: `API error ${res.status}` };
        return { success: true, data: await res.json() };
      },
    },
  ],

  async onLoad(config) {
    // Validate connectivity on load
    const res = await fetch(`${config.settings.baseUrl}/health`, {
      headers: { 'Authorization': `Bearer ${config.credentials?.apiKey}` },
    });
    if (!res.ok) throw new Error('Internal API unreachable on load');
  },

  async healthCheck() {
    return { healthy: true, lastCheck: new Date() };
  },
});
```

***

## Example 3: Skill Plugin

Add a custom skill that the AI can invoke:

```typescript theme={null}
export default definePlugin({
  metadata: {
    id: 'code-standards',
    name: 'Code Standards',
    description: 'Company-specific coding standards as a skill',
    category: 'tool',
    version: '1.0.0',
    pricing: { type: 'free' },
  },
  settingsSchema: { credentials: [], settings: [] },

  skills: [
    {
      name: 'apply-code-standards',
      description: 'Apply company TypeScript and formatting standards',
      content: `# apply-code-standards

When reviewing or writing TypeScript code, enforce:
- No \`any\` types - use \`unknown\` with type guards
- All exported functions must have explicit return types
- Use \`import type\` for type-only imports
- Max file length: 500 lines
- Tailwind v4 only for styles - no inline style props
`,
    },
  ],
});
```


# Plugin System Overview
Source: https://docs.profclaw.ai/plugins/overview

Extend profClaw with custom tools, search providers, integrations, and model adapters. Covers the plugin lifecycle, settings schema, sandbox, and ClawHub marketplace.

profClaw's plugin system lets you add new capabilities without forking the core. Plugins can provide AI tools (for function calling), search providers, skills, and chat channel integrations.

## Plugin Categories

| Category      | What it adds                                       |
| ------------- | -------------------------------------------------- |
| `tool`        | New tools available to the AI during execution     |
| `search`      | A new web or knowledge search backend              |
| `integration` | External service connection (ticket systems, APIs) |
| `model`       | A custom AI model provider                         |

## Architecture

```
Plugin Package (npm)
    |
    v
pluginRegistry.register(id, factory)
    |
    v
pluginRegistry.create(config)  --> PluginInstance
    |
    v
Tool Router / Search Router use the plugin at runtime
```

The registry (`src/plugins/registry.ts`) holds factories keyed by plugin ID. Configuration is stored in the database and loaded on startup. Plugins run in an optional sandbox (`src/plugins/sandbox.ts`) for untrusted code.

## Plugin Metadata

Every plugin declares metadata that drives the settings UI and ClawHub listing:

```typescript theme={null}
export interface PluginMetadata {
  id: string;
  name: string;
  description: string;
  category: PluginCategory;
  icon?: string;           // Lucide icon name
  version: string;
  author?: string;
  homepage?: string;
  pricing?: {
    type: 'free' | 'paid' | 'freemium' | 'credit-based';
    costPer1k?: number;
    freeQuota?: number;
  };
  rateLimit?: {
    requestsPerSecond?: number;
    requestsPerMinute?: number;
    requestsPerDay?: number;
  };
}
```

## Plugin Lifecycle

<Steps>
  <Step title="Install">
    Install the plugin package via npm/pnpm or download from ClawHub:

    ```bash theme={null}
    profclaw plugins install @profclaw/plugin-jira-search
    ```
  </Step>

  <Step title="Register">
    The plugin factory is registered with `pluginRegistry.register(id, factory)` on server startup.
  </Step>

  <Step title="Configure">
    The user provides credentials and settings via the settings UI. The UI is auto-generated from the plugin's `PluginSettingsSchema`.
  </Step>

  <Step title="Load">
    The `onLoad(config)` lifecycle hook is called with the saved configuration. Use this to validate credentials and initialize connections.
  </Step>

  <Step title="Execute">
    Tools or search functions are called at runtime by the execution engine. Results are returned to the AI model.
  </Step>

  <Step title="Health check">
    `healthCheck()` is polled periodically and surfaced in the settings dashboard.
  </Step>

  <Step title="Unload">
    `onUnload()` is called on server shutdown or when the plugin is disabled. Use this to close connections and clean up resources.
  </Step>
</Steps>

## Settings Schema

Plugins declare their settings schema for automatic UI generation. The schema drives both the settings form and validation:

```typescript theme={null}
export interface PluginSettingsSchema {
  credentials: SettingsField[];  // Stored encrypted
  settings: SettingsField[];     // Stored in plaintext
}

export interface SettingsField {
  key: string;
  type: 'text' | 'password' | 'number' | 'boolean' | 'select' | 'url';
  label: string;
  description?: string;
  required?: boolean;
  default?: unknown;
  options?: Array<{ value: string; label: string }>;
}
```

Fields with `type: 'password'` are encrypted at rest and never exposed in logs.

## Plugin Sandbox

By default, plugins from ClawHub run in a Node.js sandbox with restricted access:

* No direct filesystem access outside the plugin's data directory
* Network requests go through the SsrfGuard
* CPU and memory limits enforced
* Static code analysis on install

<Warning>
  Plugins you install from ClawHub or third parties run code on your machine. Review the source and check the ClawHub trust score before installing plugins from unknown authors.
</Warning>

Trust a plugin to run outside the sandbox (for performance-sensitive use cases):

```bash theme={null}
profclaw plugins trust @profclaw/plugin-jira-search
```

## ClawHub

ClawHub is profClaw's plugin and skill marketplace. Browse and install from the settings UI at **Settings > Plugins > Browse ClawHub**, or via CLI:

```bash theme={null}
# Browse and install
profclaw plugins search jira
profclaw plugins install @profclaw/plugin-jira-search

# Manage installed plugins
profclaw plugins list
profclaw plugins update @profclaw/plugin-jira-search
profclaw plugins disable my-plugin
profclaw plugins remove my-plugin
```

See [Publishing to ClawHub](/plugins/publishing) for details on submitting your own plugin.

## Writing a Plugin

A minimal tool plugin:

```typescript theme={null}
import type { PluginFactory, ToolPlugin } from 'profclaw/sdk';

const factory: PluginFactory<ToolPlugin> = {
  metadata: {
    id: 'my-lookup',
    name: 'My Lookup',
    description: 'Look up data from My API',
    category: 'tool',
    version: '1.0.0',
  },
  settingsSchema: {
    credentials: [
      { key: 'apiKey', type: 'password', label: 'API Key', required: true },
    ],
    settings: [],
  },
  create(config) {
    return {
      tools: [
        {
          name: 'my_lookup',
          description: 'Look up an item by ID',
          schema: z.object({ id: z.string() }),
          securityLevel: 'safe',
          async execute({ id }) {
            const data = await fetchFromApi(config.apiKey, id);
            return { result: data };
          },
        },
      ],
      async healthCheck() {
        return { ok: true };
      },
    };
  },
};

export default factory;
```

See [Plugin SDK Reference](/plugins/sdk) for the complete API.

## Related

<CardGroup>
  <Card title="Skills Overview" icon="book-open" href="/skills/overview">
    Add AI behavior with plain Markdown - no code required.
  </Card>

  <Card title="Custom Tools" icon="wrench" href="/tools/custom-tools">
    Add tools directly without packaging a full plugin.
  </Card>

  <Card title="Publishing to ClawHub" icon="upload" href="/plugins/publishing">
    Publish your plugin for the community.
  </Card>

  <Card title="Plugin SDK" icon="code" href="/plugins/sdk">
    Full TypeScript SDK reference for plugin development.
  </Card>
</CardGroup>


# Plugin Packaging
Source: https://docs.profclaw.ai/plugins/packaging

Package structure, manifest fields, and plugin build configuration

A profClaw plugin is a standard npm package with a `profclaw` field in `package.json` and a default export using `definePlugin`.

## Package Structure

```
my-profclaw-plugin/
  src/
    index.ts       # Default export: definePlugin(...)
    types.ts       # Internal types
  dist/
    index.js       # Compiled output
    index.d.ts     # TypeScript declarations
  package.json
  tsconfig.json
  README.md
```

## package.json Manifest

```json theme={null}
{
  "name": "@yourname/profclaw-plugin-myplugin",
  "version": "1.0.0",
  "description": "Short description of your plugin",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "keywords": ["profclaw-plugin"],
  "profclaw": {
    "pluginId": "myplugin",
    "category": "search",
    "minVersion": "2.0.0",
    "maxVersion": "3.x"
  },
  "peerDependencies": {
    "profclaw": ">=2.0.0"
  }
}
```

The `profclaw.pluginId` must be unique on ClawHub. The `keywords` array must include `"profclaw-plugin"` for the plugin to appear in search results.

## Plugin Manifest Fields

```typescript theme={null}
// src/plugins/sdk.ts
export interface PluginManifest {
  name: string;              // npm package name
  version: string;
  description: string;
  main: string;              // Entry point (dist/index.js)
  profclaw: {
    pluginId: string;        // Unique ID
    category: PluginCategory;
    minVersion?: string;     // Min profClaw version
    maxVersion?: string;     // Max profClaw version
  };
}
```

## Build Configuration

```json theme={null}
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "declaration": true,
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}
```

## Build Script

```json theme={null}
// package.json scripts
{
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "test": "vitest",
    "prepublishOnly": "pnpm build"
  }
}
```

## Dependencies

Keep dependencies minimal. Avoid bundling:

* `profclaw` (declare as `peerDependency`)
* `zod` (available from profClaw peer)
* Large AI SDKs (prefer HTTP calls)

Bundled dependencies increase install size and can conflict with the host's versions.

## Entry Point

`src/index.ts` must have a default export:

```typescript theme={null}
import { definePlugin } from 'profclaw/plugins/sdk';

const plugin = definePlugin({ ... });

export default plugin;
```

profClaw imports your plugin with `import(packageName)` and accesses `default`.

## Testing Your Plugin Locally

```bash theme={null}
# In profClaw's profclaw-docs repo or your development setup
pnpm add --workspace ./path/to/my-profclaw-plugin

# Or link globally
cd my-profclaw-plugin && pnpm link --global
cd profclaw && pnpm link --global my-profclaw-plugin
```

Then register in settings: **Settings > Plugins > Install from local path**.

## Scaffolding

Use the built-in scaffolder to bootstrap a new plugin:

```bash theme={null}
profclaw plugins scaffold --id my-plugin --category search
```

This generates the package structure with TypeScript config, a sample `definePlugin` call, and a test file.


# Publishing to ClawHub
Source: https://docs.profclaw.ai/plugins/publishing

Submit your plugin to the ClawHub marketplace for the profClaw community

ClawHub is the profClaw plugin marketplace. Published plugins appear in **Settings > Plugins > Browse ClawHub** and are installable with one click.

## Publishing Checklist

Before submitting, verify:

* [ ] `keywords` includes `"profclaw-plugin"` in `package.json`
* [ ] `profclaw.pluginId` is unique (check [clawhub.dev](https://clawhub.dev))
* [ ] Default export uses `definePlugin()`
* [ ] `settingsSchema` declared for all credentials and settings
* [ ] `healthCheck()` implemented and tested
* [ ] README includes setup instructions and screenshots
* [ ] Tests pass (`pnpm test`)
* [ ] Build succeeds (`pnpm build`)
* [ ] No hardcoded secrets or credentials in source

## Step 1: Publish to npm

```bash theme={null}
npm login
npm publish --access public
```

Your package name should follow the convention: `@yourname/profclaw-plugin-<name>`

## Step 2: Submit to ClawHub

### Via CLI

```bash theme={null}
profclaw plugins publish --npm-package @yourname/profclaw-plugin-myplugin
```

This submits to the ClawHub API for review.

### Via Web

1. Sign in at [clawhub.dev](https://clawhub.dev)
2. Click **Submit Plugin**
3. Enter your npm package name
4. Fill in the listing details (category, icon, screenshots)
5. Submit for review

## Review Process

ClawHub review checks:

* Plugin loads without errors in a sandboxed profClaw instance
* `healthCheck()` returns `{ healthy: boolean }`
* No malicious code (automated + manual scan)
* README quality and accuracy
* No duplicate functionality without meaningful differentiation

Review typically takes 1-3 business days. You will receive an email on approval or rejection with feedback.

## Versioning

Follow semantic versioning:

| Change                            | Version bump |
| --------------------------------- | ------------ |
| New feature, backwards compatible | `minor`      |
| Bug fix                           | `patch`      |
| Breaking API change               | `major`      |

When you publish a new npm version, ClawHub picks it up automatically within 1 hour. Users on auto-update receive the new version on their next profClaw restart.

## Listing Metadata

After approval, update your listing at [clawhub.dev/my-plugins](https://clawhub.dev/my-plugins):

* **Icon**: PNG or SVG, 128x128px minimum
* **Screenshots**: Show the plugin working in the settings UI
* **Category**: `search`, `tool`, `integration`, or `model`
* **Pricing**: Mark as free, paid, or freemium
* **Support URL**: Link to your issue tracker

## Unpublishing

To remove a plugin from ClawHub:

```bash theme={null}
profclaw plugins unpublish @yourname/profclaw-plugin-myplugin
```

This hides the listing. Users who already installed the plugin can continue using it. The npm package remains published.

## ClawHub API

For automated publishing in CI/CD:

```bash theme={null}
curl -X POST https://api.clawhub.dev/v1/plugins \
  -H "Authorization: Bearer ${CLAWHUB_TOKEN}" \
  -d '{"npmPackage": "@yourname/profclaw-plugin-myplugin"}'
```

Get a ClawHub API token at [clawhub.dev/settings/tokens](https://clawhub.dev/settings/tokens).


# Plugin SDK
Source: https://docs.profclaw.ai/plugins/sdk

Full API reference for the profClaw plugin SDK

Import the SDK from `profclaw/plugins/sdk`:

```typescript theme={null}
import { definePlugin } from 'profclaw/plugins/sdk';
```

## `definePlugin(plugin: ProfClawPlugin)`

The main entry point. Returns the plugin definition validated and ready for registration.

```typescript theme={null}
export default definePlugin({
  metadata: {
    id: 'my-search',
    name: 'My Search',
    description: 'Custom search provider',
    category: 'search',
    version: '1.0.0',
    author: 'your-name',
    pricing: { type: 'free' },
  },
  settingsSchema: {
    credentials: [
      {
        key: 'apiKey',
        type: 'password',
        label: 'API Key',
        required: true,
      }
    ],
    settings: [
      {
        key: 'maxResults',
        type: 'number',
        label: 'Max Results',
        default: 10,
      }
    ],
  },
  tools: [...],
  searchProvider: (config) => ({ ... }),
  async onLoad(config) {
    // validate config, establish connections
  },
  async onUnload() {
    // cleanup
  },
  async healthCheck() {
    return { healthy: true, lastCheck: new Date() };
  },
});
```

## `ProfClawPlugin` Interface

```typescript theme={null}
export interface ProfClawPlugin {
  metadata: PluginMetadata;
  settingsSchema?: PluginSettingsSchema;
  tools?: PluginToolDefinition[];
  searchProvider?: (config: PluginConfig) => SearchProvider;
  skills?: PluginSkillDefinition[];
  onLoad?(config: PluginConfig): Promise<void>;
  onUnload?(): Promise<void>;
  healthCheck?(): Promise<PluginHealth>;
}
```

## `PluginToolDefinition`

Define AI tools that the agent can call:

```typescript theme={null}
export interface PluginToolDefinition {
  name: string;
  description: string;
  category?: string;
  parameters: Record<string, {
    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
    description: string;
    required?: boolean;
    enum?: string[];
    default?: unknown;
  }>;
  execute(params: Record<string, unknown>): Promise<ToolResult>;
}
```

**Example tool**:

```typescript theme={null}
{
  name: 'search_docs',
  description: 'Search internal documentation',
  parameters: {
    query: { type: 'string', description: 'Search query', required: true },
    limit: { type: 'number', description: 'Max results', default: 5 },
  },
  async execute({ query, limit }) {
    const results = await mySearchApi.search(query as string, limit as number);
    return {
      success: true,
      data: results,
      metadata: { executionTime: 120 },
    };
  },
}
```

## `SearchProvider` Interface

```typescript theme={null}
export interface SearchProvider {
  metadata: PluginMetadata;
  search(query: string, options?: SearchOptions): Promise<SearchResponse>;
  isAvailable(): Promise<boolean>;
  healthCheck(): Promise<PluginHealth>;
}
```

**`SearchOptions`**:

```typescript theme={null}
export interface SearchOptions {
  limit?: number;
  offset?: number;
  language?: string;
  region?: string;
  freshness?: 'day' | 'week' | 'month' | 'year';
  safeSearch?: boolean | 'moderate' | 'strict';
  includeImages?: boolean;
  includeNews?: boolean;
  includeDomains?: string[];
  excludeDomains?: string[];
}
```

**`SearchResponse`**:

```typescript theme={null}
export interface SearchResponse {
  results: SearchResult[];
  query: string;
  totalResults?: number;
  searchTime?: number;
  provider: string;
  cached?: boolean;
}
```

## `PluginConfig`

The config passed to your factory and `onLoad`:

```typescript theme={null}
export interface PluginConfig {
  id: string;
  pluginId: string;
  enabled: boolean;
  priority: number;        // Higher = preferred when multiple providers exist
  settings: Record<string, unknown>;
  credentials?: {
    apiKey?: string;
    baseUrl?: string;
    [key: string]: string | undefined;
  };
}
```

## `ToolResult`

```typescript theme={null}
export interface ToolResult {
  success: boolean;
  data?: unknown;
  error?: string;
  metadata?: {
    executionTime: number;
    tokensUsed?: number;
    cost?: number;
  };
}
```

## `PluginHealth`

```typescript theme={null}
export interface PluginHealth {
  healthy: boolean;
  lastCheck: Date;
  latency?: number;
  errorMessage?: string;
  usageStats?: {
    requestsToday: number;
    requestsThisMonth: number;
    tokensUsed?: number;
    costEstimate?: number;
  };
}
```

## Skills

Plugins can bundle skill definitions (SKILL.md content as strings):

```typescript theme={null}
skills: [
  {
    name: 'my-skill',
    description: 'Does something useful',
    content: `# my-skill\nUse this skill to...`,
  }
]
```


# Audit Logging
Source: https://docs.profclaw.ai/security/audit

Immutable audit trail of all tool calls, approvals, security events, and compliance reporting.

## Overview

The audit log records every security-relevant event in profClaw: tool calls, approval decisions, security guard blocks, authentication events, and configuration changes. Logs are append-only and cannot be modified after writing.

## What Gets Logged

| Event Type       | Logged Fields                                                  |
| ---------------- | -------------------------------------------------------------- |
| Tool call        | Tool name, params (sanitized), user, channel, result, duration |
| Tool blocked     | Tool name, reason, security mode, risk level                   |
| Approval request | Tool name, approver, decision (allow-once/allow-always/deny)   |
| Prompt guard hit | Risk level, score, pattern matched, input length               |
| SSRF guard block | URL (host only), reason, resolved IP                           |
| FsGuard block    | Path (normalized), operation, reason                           |
| Auth event       | Login, logout, token refresh, failed auth                      |
| Config change    | Field changed, old/new value (sensitive values masked)         |
| Plugin load      | Plugin name, version, permissions requested                    |
| Skill scan       | Skill name, findings, risk level                               |

## Log Format

Each audit entry is a structured JSON line:

```json theme={null}
{
  "timestamp": "2026-03-12T09:15:32.445Z",
  "eventType": "tool_call",
  "level": "INFO",
  "risk": "LOW",
  "conversationId": "conv_abc123",
  "userId": "user_xyz",
  "channelProvider": "slack",
  "channelId": "C01234567",
  "tool": {
    "name": "read_file",
    "params": { "path": "src/index.ts" },
    "result": "success",
    "durationMs": 12
  }
}
```

Sensitive values in params (tokens, passwords, keys) are automatically masked: `"apiKey": "***"`.

## Viewing Audit Logs

### CLI

```bash theme={null}
# View recent events
profclaw audit log --last 100

# Filter by event type
profclaw audit log --type tool_call --last 50

# Filter by risk level
profclaw audit log --risk HIGH,CRITICAL

# Filter by user
profclaw audit log --user user_xyz

# Search for specific tool
profclaw audit log --tool exec
```

### Via API

```http theme={null}
GET /api/audit/events?limit=50&type=tool_call&risk=HIGH
Authorization: Bearer <token>
```

### Log Files

Audit logs are written to:

* **SQLite** (default): stored in profClaw's database
* **File**: `~/.profclaw/audit.jsonl` (enable with `auditLog.file: true`)
* **Syslog**: Forward to external syslog server (enterprise)

## Configuration

```yaml theme={null}
security:
  auditLog:
    enabled: true
    retention: 90           # Days to retain events
    file: false             # Also write to JSONL file
    filePath: "~/.profclaw/audit.jsonl"
    maskFields:
      - "apiKey"
      - "token"
      - "password"
      - "secret"
    syslog:
      enabled: false
      host: "logs.company.com"
      port: 514
      protocol: "udp"
```

## Compliance Reports

Generate compliance reports from the audit log:

```bash theme={null}
# Summary report (last 30 days)
profclaw audit report --days 30

# Tool usage breakdown
profclaw audit report --type tool-usage

# Security events only
profclaw audit report --type security

# Export as CSV
profclaw audit report --format csv --output audit-report.csv
```

Sample report output:

```
Audit Report: 2026-02-10 to 2026-03-12
Period: 30 days

Tool Calls: 2,847 total
  - read_file:     1,203 (42%)
  - web_fetch:       412 (14%)
  - exec:            298 (10%)
  - edit_file:       201  (7%)

Security Events: 23 total
  - Prompt guard warnings:  8
  - FsGuard blocks:         6
  - Approval denials:       5
  - SSRF blocks:            4

Risk Distribution:
  LOW:      2,831 (99.4%)
  MEDIUM:       9  (0.3%)
  HIGH:         4  (0.1%)
  CRITICAL:     0  (0.0%)
```

## Alerting

Configure alerts for high-risk events:

```yaml theme={null}
security:
  auditLog:
    alerts:
      - event: tool_blocked
        risk: HIGH
        notify: slack          # Send to Slack channel
        channel: "#security"

      - event: prompt_guard
        risk: CRITICAL
        notify: email
        to: "admin@example.com"
```

## Log Retention

Audit logs are retained for 90 days by default. After retention expires, entries are permanently deleted. Adjust retention for compliance requirements:

```yaml theme={null}
security:
  auditLog:
    retention: 365    # 1 year for compliance
```

## Related Docs

<CardGroup>
  <Card title="Guards" icon="lock" href="/security/guards">
    Guard decisions that generate audit events.
  </Card>

  <Card title="Security Modes" icon="shield" href="/security/modes">
    Mode decisions are audit-logged.
  </Card>
</CardGroup>


# Device Pairing
Source: https://docs.profclaw.ai/security/device-pairing

QR code pairing, DM verification codes, device identity, and trusted sender management.

## Overview

Device pairing controls who can interact with profClaw through chat channels. When someone messages profClaw for the first time from an unknown account, device pairing can require them to verify their identity with a code before any tools run.

This prevents unauthorized users from discovering a profClaw instance and using it to execute commands.

## Pairing Methods

<Tabs>
  <Tab title="QR Code Pairing">
    Generate a QR code that the user scans with their phone to prove they are a trusted device.

    ### Setup

    ```bash theme={null}
    # Generate a pairing QR code
    profclaw auth pair --output qr

    # Or show as terminal text
    profclaw auth pair --output text
    ```

    ### How It Works

    1. profClaw generates a unique pairing token (TOTP-based)
    2. The user scans the QR code in the profClaw mobile app or web UI
    3. The app verifies the token against the profClaw server
    4. The device receives a trust certificate stored locally
    5. Future messages from this device bypass DM verification

    The QR code expires after 5 minutes. Generate a new one if it expires.
  </Tab>

  <Tab title="DM Verification Code">
    When an unknown user messages profClaw directly (not in a channel), they receive a verification code request before any tools run.

    ### How It Works

    1. Unknown user sends a message to profClaw
    2. profClaw sends back: "Please verify with code: **A7X-29K**"
    3. User replies with the code within the expiry window
    4. On success, profClaw processes the original message
    5. The user is added to trusted senders automatically

    ### Configuration

    ```yaml theme={null}
    security:
      dmPairing:
        enabled: true
        codeLength: 6           # Characters in the code
        codeExpiryMs: 300000    # 5 minutes
        maxAttempts: 3          # Attempts before lockout
        trustedSenders:
          - "U01234567"         # Pre-approved Slack user ID
          - "123456789"         # Pre-approved Telegram user ID
    ```

    ### Pre-approving Users

    Add user IDs to `trustedSenders` to skip verification for known users:

    ```yaml theme={null}
    security:
      dmPairing:
        trustedSenders:
          - "U01234ALICE"    # Alice's Slack ID
          - "U01234BOB"      # Bob's Slack ID
    ```
  </Tab>
</Tabs>

## Device Identity

Each device that pairs with profClaw receives a unique device identity:

```typescript theme={null}
interface DeviceIdentity {
  deviceId: string;       // Unique device ID
  deviceName: string;     // Human-readable name
  platform: string;       // "ios", "android", "web", "desktop"
  publicKey: string;      // Ed25519 public key for request signing
  createdAt: string;      // ISO timestamp
  lastSeenAt: string;
  trusted: boolean;
  trustLevel: 'full' | 'limited' | 'read-only';
}
```

## Trust Levels

| Level       | Permissions                                           |
| ----------- | ----------------------------------------------------- |
| `full`      | All tools, all channels                               |
| `limited`   | Standard tier tools only, no dangerous operations     |
| `read-only` | Safe tools only (read\_file, grep, git\_status, etc.) |

Assign trust levels per device:

```bash theme={null}
profclaw device trust <device-id> --level limited
```

## Managing Paired Devices

```bash theme={null}
# List all paired devices
profclaw device list

# Show device details
profclaw device info <device-id>

# Revoke a device
profclaw device revoke <device-id>

# Update trust level
profclaw device trust <device-id> --level read-only
```

## Channel Allowlisting

Restrict which channels profClaw responds to:

```yaml theme={null}
security:
  channelAllowlist:
    - channelId: "C01TEAM"
      provider: slack
      name: "#engineering"
      enabled: true

    - channelId: "-100123456789"
      provider: telegram
      name: "Engineering Group"
      enabled: true
```

With channel allowlisting enabled, messages from non-listed channels are silently ignored.

## Session-Level Security

When a chat session is active, security context travels with it:

* The authenticated `userId` from the original request
* The `channelProvider` and `channelId`
* The applicable security mode and exec policies
* The device's trust level

Tool calls inherit the session's security context. A read-only device cannot execute write tools even if the global security mode is `full`.

## Audit Trail

All pairing events are recorded in the audit log:

* Device paired: device ID, platform, time
* Verification code issued: channel, code expiry
* Verification success/failure: user ID, attempts
* Device revoked: admin user, reason

```bash theme={null}
profclaw audit log --type auth_event --last 20
```

## Related Docs

<CardGroup>
  <Card title="Security Modes" icon="shield" href="/security/modes">
    Per-user and per-channel security policies.
  </Card>

  <Card title="Audit Logging" icon="scroll" href="/security/audit">
    Full audit trail of pairing events.
  </Card>
</CardGroup>


# Security Guards
Source: https://docs.profclaw.ai/security/guards

FsGuard (path traversal), SsrfGuard (SSRF), PromptGuard (injection), and AuditScanner.

## Overview

Security guards are input-level validation layers that run independently of the security mode. Even in `full` mode, the FsGuard and SsrfGuard still block access to dangerous paths and private networks.

Each guard returns a `GuardResult`:

```typescript theme={null}
interface GuardResult {
  allowed: boolean;
  reason?: string;      // Why it was blocked
  risk: RiskLevel;      // LOW | MEDIUM | HIGH | CRITICAL
  score?: number;       // 0-100 severity score
}
```

## FsGuard - Filesystem Guard

Prevents path traversal attacks and blocks access to sensitive files.

### How It Works

1. **Path normalization** - Resolves `../` sequences to eliminate traversal
2. **Symlink resolution** - Resolves symlinks to their real paths to detect symlink-based escapes
3. **Allowlist check** - Verified resolved path is within an allowed directory
4. **Blocklist check** - Verified path is not in the blocked paths list
5. **Pattern check** - Verified filename does not match blocked patterns

### Default Blocked Paths

```
/etc/passwd
/etc/shadow
/etc/sudoers
~/.ssh/
~/.gnupg/
~/.aws/credentials
~/.config/gcloud/
/proc/
/sys/
/dev/
```

### Default Blocked Filename Patterns

```
.env
.env.local
.env.production
.env.staging
id_rsa, id_ed25519, id_ecdsa
*.pem, *.key
credentials.json
service-account.json
```

### Configuration

```yaml theme={null}
security:
  fsGuard:
    enabled: true
    allowedPaths:
      - "{{ workdir }}"       # Project directory (required)
      - "/tmp"                # System temp
      - "/home/user/projects" # Additional allowed directory
    blockedPaths:
      - "/etc/passwd"         # Extra blocked paths (merged with defaults)
    blockedPatterns:
      - ".secret"             # Extra patterns
    followSymlinks: true      # Resolve symlinks before checking
```

### Disabling FsGuard

You can disable FsGuard for specific operations if you need to access files outside the default paths:

```yaml theme={null}
security:
  fsGuard:
    enabled: false  # NOT recommended for production
```

Instead, prefer adding specific paths to `allowedPaths`.

***

## SsrfGuard - SSRF Guard

Prevents Server-Side Request Forgery by validating URLs before HTTP requests.

### How It Works

1. **Scheme validation** - Only `http` and `https` allowed
2. **Host blocklist** - Checks against known metadata endpoints
3. **CIDR check** - Resolves DNS and checks resolved IP against blocked CIDR ranges
4. **DNS rebinding defense** - Resolves hostnames before connecting, re-validates on redirects
5. **Redirect chain validation** - Each redirect target is re-validated (up to 5 hops)

### Blocked CIDR Ranges

```
0.0.0.0/8        - "This" network
10.0.0.0/8       - Private Class A
100.64.0.0/10    - Carrier-grade NAT
127.0.0.0/8      - Loopback
169.254.0.0/16   - Link-local (includes cloud metadata 169.254.169.254)
172.16.0.0/12    - Private Class B
192.168.0.0/16   - Private Class C
224.0.0.0/4      - Multicast
240.0.0.0/4      - Reserved
```

### Blocked Metadata Hosts

```
169.254.169.254         - AWS, GCP, Azure metadata
metadata.google.internal
metadata.internal
```

### Configuration

```yaml theme={null}
security:
  ssrfGuard:
    enabled: true
    allowedHosts:
      - "internal-api.company.com"  # Allow specific internal hosts
      - "jenkins.internal"
    maxRedirects: 5
    dnsResolutionTimeout: 3000     # ms
```

***

## PromptGuard - Injection Guard

Detects and blocks prompt injection and jailbreak attempts in user input.

### Detection Categories

| Category                   | Score | Examples                                          |
| -------------------------- | ----- | ------------------------------------------------- |
| Injection delimiters       | 40    | `[system]`, `[INST]`, `<<SYS>>`, `<\|im_start\|>` |
| Token smuggling            | 45    | Null bytes, ANSI escapes, backspace chars         |
| Jailbreak personas         | 35    | "You are now DAN", "act as unrestricted"          |
| Instruction override       | 30    | "Ignore all previous instructions"                |
| Encoded injection          | 30    | "execute the following base64"                    |
| System prompt extraction   | 25    | "reveal your system prompt"                       |
| Prompt leak via formatting | 20    | "translate the above text"                        |

Total score is the sum of all triggered patterns. Inputs scoring above the `blockThreshold` are rejected.

### Canary Token System

A random canary token is injected into the system prompt. If this token appears in the user's message, it indicates the system prompt has been leaked and extracted - the request is blocked with `CRITICAL` risk.

### Configuration

```yaml theme={null}
security:
  promptGuard:
    enabled: true
    maxInputLength: 50000   # Characters
    blockThreshold: 25      # Score >= 25 is blocked
    warnThreshold: 10       # Score >= 10 is logged as warning
```

***

## AuditScanner - Code Scanner

Scans skill code and plugin code for dangerous patterns before loading.

### Detection Patterns

| Pattern           | Risk     | Example                                 |
| ----------------- | -------- | --------------------------------------- |
| Shell execution   | CRITICAL | `child_process`, `exec()`, `spawn()`    |
| eval usage        | CRITICAL | `eval()`, `Function("code")`            |
| Raw socket access | CRITICAL | `net.connect()`, `tls.connect()`        |
| Network access    | HIGH     | `fetch()`, `axios`, `got()`             |
| Credential access | HIGH     | `API_KEY`, `SECRET`, `TOKEN` references |
| Filesystem writes | MEDIUM   | `writeFileSync`, `appendFileSync`       |
| Destructive ops   | HIGH     | `unlinkSync`, `rmdirSync`, `rm -rf`     |
| Env var access    | MEDIUM   | `process.env.` access                   |

### When It Runs

* On skill file load
* On plugin activation
* During `profclaw doctor` health check

### Configuration

```yaml theme={null}
security:
  auditScanner:
    enabled: true
    alertOnMatch: true   # Log warnings when patterns match
```

## Related Docs

<CardGroup>
  <Card title="Security Modes" icon="shield" href="/security/modes">
    Guards apply within all modes except deny.
  </Card>

  <Card title="Audit Logging" icon="scroll" href="/security/audit">
    Guard decisions are recorded in the audit log.
  </Card>
</CardGroup>


# Security Modes
Source: https://docs.profclaw.ai/security/modes

Five security modes from complete lockdown to unrestricted execution. Configure globally or per channel.

## The Five Modes

profClaw's security mode determines how tool calls are validated before execution. The mode can be set globally, per channel, per user, or per conversation.

<Tabs>
  <Tab title="deny">
    **No tool execution allowed.**

    All tool calls are blocked regardless of which tool or who is calling. The AI can still respond conversationally but cannot execute any actions.

    Use for: Read-only channels, demo environments, untrusted public chats.

    ```yaml theme={null}
    security:
      mode: deny
    ```
  </Tab>

  <Tab title="sandbox">
    **All execution runs in an isolated Docker container.**

    Tools run inside a Docker container with limited filesystem mounts, no network access by default, and resource limits. The container is destroyed after each tool call.

    Use for: Code execution environments, untrusted user inputs, CI/CD pipelines.

    ```yaml theme={null}
    security:
      mode: sandbox
      sandboxConfig:
        image: "node:22-alpine"
        networkMode: "none"
        memoryLimit: "512m"
        cpuLimit: "0.5"
        mounts:
          - hostPath: "{{ workdir }}"
            containerPath: "/workspace"
            readonly: false
    ```
  </Tab>

  <Tab title="allowlist">
    **Only explicitly listed commands and paths are permitted.**

    All tool calls are checked against a pre-approved allowlist. Anything not on the list is blocked.

    Use for: Production deployments where only known operations should run.

    ```yaml theme={null}
    security:
      mode: allowlist
      allowlist:
        - pattern: "read_file"
          type: command
          description: "Allow reading files"
        - pattern: "src/**"
          type: path
          description: "Allow access to src directory"
        - pattern: "https://api.github.com/**"
          type: url
          description: "Allow GitHub API calls"
    ```
  </Tab>

  <Tab title="ask">
    **Moderate and dangerous operations require user approval.**

    `safe` tools run immediately. `moderate` and `dangerous` tools send an approval request to the user and wait for confirmation before executing.

    Use for: Personal deployments, sensitive environments where you want oversight.

    ```yaml theme={null}
    security:
      mode: ask
      askTimeout: 60000   # 60 seconds to approve, then auto-deny
    ```

    Approval decisions:

    * **Allow once** - Run this specific call
    * **Allow always** - Add to allowlist for future calls
    * **Deny** - Block this call
  </Tab>

  <Tab title="full">
    **No restrictions. All tools run immediately.**

    No approval prompts, no allowlist checks. The AI can execute any tool without confirmation.

    Use for: Local development only. Do not use in production or with untrusted models.

    ```yaml theme={null}
    security:
      mode: full
    ```

    <Warning>
      `full` mode is dangerous. Only use on trusted local machines with trusted AI models. Never use with public-facing deployments.
    </Warning>
  </Tab>
</Tabs>

## Mode Comparison

| Feature           | deny   | sandbox        | allowlist         | ask                    | full         |
| ----------------- | ------ | -------------- | ----------------- | ---------------------- | ------------ |
| Tool execution    | Never  | In container   | Pre-approved only | With approval          | Always       |
| Approval prompts  | -      | -              | -                 | For moderate/dangerous | Never        |
| Filesystem access | None   | Container only | Listed paths      | Guarded                | Guarded      |
| Network access    | None   | Container only | Listed URLs       | SSRF-guarded           | SSRF-guarded |
| Best for          | Public | Execution      | Production        | Personal               | Dev only     |

## Per-Channel Mode Override

Set different modes for different channels:

```yaml theme={null}
security:
  mode: ask                 # global default

channels:
  slack:
    security:
      mode: allowlist       # stricter for Slack

  webchat:
    security:
      mode: full            # permissive for local webchat

  telegram:
    security:
      mode: deny            # block all tools on Telegram
```

## Per-User Policies

Apply different modes based on the authenticated user:

```yaml theme={null}
security:
  execPolicies:
    - id: admin-policy
      name: "Admin users"
      match:
        users: ["user-id-123", "user-id-456"]
      action: allow
      priority: 100
      enabled: true

    - id: guest-policy
      name: "Guest users"
      match:
        users: ["*"]
      action: ask
      priority: 1
      enabled: true
```

## Granular Exec Policies

Policies can match on tools, commands, paths, users, and channels with priority ordering:

```yaml theme={null}
security:
  execPolicies:
    - id: no-write-from-slack
      match:
        tools: ["write_file", "edit_file"]
        channels: ["C01234"]         # Slack channel ID
      action: deny
      priority: 90
      enabled: true

    - id: git-requires-approval
      match:
        tools: ["git_commit", "git_remote"]
      action: ask
      priority: 80
      enabled: true
```

Higher `priority` values are evaluated first.

## Related Docs

<CardGroup>
  <Card title="Guards" icon="lock" href="/security/guards">
    FsGuard and SsrfGuard apply within all modes except deny.
  </Card>

  <Card title="Audit" icon="scroll" href="/security/audit">
    All mode decisions are recorded in the audit log.
  </Card>
</CardGroup>


# Security Overview
Source: https://docs.profclaw.ai/security/overview

profClaw's defense-in-depth security model. Covers security modes, prompt guards, filesystem guards, SSRF protection, sandboxing, audit logging, and device pairing.

## Security Architecture

profClaw is designed with a defense-in-depth model. Security is enforced at multiple independent layers - a failure in one layer does not compromise the system.

```mermaid theme={null}
flowchart TD
  Input["User Input / Tool Call"]
  PG["Prompt Guard\ninjection / jailbreak / smuggling detection"]
  SM["Security Mode\ndeny / sandbox / allowlist / ask / full"]
  TR["Tool Registry\ntier filtering + availability"]
  ZV["Schema Validation\nZod parse + type enforcement"]
  FS["FsGuard\npath traversal prevention"]
  SS["SsrfGuard\nprivate IP / internal host blocking"]
  EX["Execution\nDocker sandbox or local with policy"]
  AL["Audit Logger\nimmutable event log"]

  Input --> PG
  PG -- "score < threshold" --> SM
  PG -- "score >= threshold" --> Blocked["BLOCKED"]
  SM --> TR
  TR --> ZV
  ZV --> FS
  FS --> SS
  SS --> EX
  EX --> AL
```

## Security Components

<CardGroup>
  <Card title="Security Modes" icon="shield" href="/security/modes">
    Five modes from `deny` (no tools) to `full` (unrestricted). Configured per channel, user, or globally.
  </Card>

  <Card title="Guards" icon="lock" href="/security/guards">
    FsGuard (path traversal), SsrfGuard (SSRF/network), PromptGuard (injection), AuditScanner.
  </Card>

  <Card title="Audit Logging" icon="scroll" href="/security/audit">
    Immutable audit trail of all tool calls, approvals, and security events.
  </Card>

  <Card title="Device Pairing" icon="qrcode" href="/security/device-pairing">
    QR code pairing and DM verification for unknown senders.
  </Card>

  <Card title="Plugin Sandbox" icon="cube" href="/security/plugins">
    Permission model for plugins, static code scanning, and trust tiers.
  </Card>
</CardGroup>

## Security Modes

profClaw supports five security modes. The active mode applies globally but can be overridden per user or per chat channel.

| Mode       | Tools Available | Write/Exec Behavior                        | Best For                            |
| ---------- | --------------- | ------------------------------------------ | ----------------------------------- |
| `deny`     | None            | All tool calls blocked                     | Read-only chat, unknown users       |
| `sandbox`  | Limited         | Docker-isolated execution only             | Untrusted input, shared deployments |
| `standard` | Standard tier   | Reads auto-approved; writes shown to user  | Most deployments (default)          |
| `ask`      | Full tier       | All write/exec operations require approval | Production, sensitive codebases     |
| `full`     | Full tier       | All tools execute without prompts          | Trusted local development only      |

<Warning>
  `full` mode disables all approval gates. Only use it in environments where every user with access is fully trusted. Never expose `full` mode to public-facing endpoints.
</Warning>

Configure globally or per-channel:

```yaml theme={null}
# settings.yml
security:
  mode: standard           # global default
  channels:
    slack:
      mode: ask            # stricter for Slack
    webchat:
      mode: standard
```

## Risk Levels

All security events are classified by a numeric risk score. Scores are computed by the PromptGuard and AuditScanner based on detected patterns.

| Level      | Score  | Default Behavior                           |
| ---------- | ------ | ------------------------------------------ |
| `LOW`      | 0-24   | Logged only                                |
| `MEDIUM`   | 25-49  | Logged, surfaced in audit dashboard        |
| `HIGH`     | 50-74  | Logged, may block depending on active mode |
| `CRITICAL` | 75-100 | Blocked and alerts sent                    |

```mermaid theme={null}
flowchart LR
  Event["Security Event"]
  Score{"Risk Score"}
  Low["LOW 0-24\nnormal operation\nlog only"]
  Med["MEDIUM 25-49\nlog + warn"]
  High["HIGH 50-74\nreview + may block"]
  Crit["CRITICAL 75-100\nblock + alert"]

  Event --> Score
  Score -- "0-24" --> Low
  Score -- "25-49" --> Med
  Score -- "50-74" --> High
  Score -- "75-100" --> Crit
```

## Default Security Configuration

Out of the box, profClaw runs in `standard` mode. These are the defaults applied when no `security:` block is present in `settings.yml`:

```yaml theme={null}
security:
  mode: standard          # standard is safe for most deployments
  fsGuard:
    enabled: true
    allowedPaths:
      - "{{ workdir }}"   # project directory
      - "{{ tmpdir }}"    # system temp
  ssrfGuard:
    enabled: true
    allowedHosts: []      # no private/internal hosts by default
  promptGuard:
    enabled: true
    blockThreshold: 25    # block inputs scoring >= 25
    warnThreshold: 10
  auditLog:
    enabled: true
    retention: 90         # days
```

## Security Responsibilities

| Layer          | Your Responsibility                          | profClaw's Default                         |
| -------------- | -------------------------------------------- | ------------------------------------------ |
| Network        | Set `allowedHosts` for external services     | Block all private IPs via SsrfGuard        |
| Filesystem     | Extend `allowedPaths` for needed directories | Block secrets, system files, parent paths  |
| Authentication | Configure your auth provider                 | Verify tokens per request                  |
| Secrets        | Store in env vars, not settings.yml          | Never log or expose key values             |
| Models         | Choose trusted AI providers                  | Validate all tool call parameters with Zod |

## Hardening Checklist

<AccordionGroup>
  <Accordion title="For production deployments">
    * Set `security.mode` to `ask` or `strict`
    * Set `WEBHOOK_BASE_URL` to your actual domain (not localhost)
    * Restrict chat channels with `allowedChannels` and `allowedUsers`
    * Set `ssrfGuard.allowedHosts` explicitly if the agent needs to call internal APIs
    * Enable device pairing for unknown sender verification
    * Review audit logs regularly with `profclaw logs --audit`
  </Accordion>

  <Accordion title="For shared or multi-tenant deployments">
    * Use `sandbox` mode to isolate tool execution in Docker containers
    * Set per-user rate limits via `RATE_LIMIT_*` env vars
    * Enable plugin sandboxing for any untrusted plugins
    * Use separate API keys per tenant where possible
  </Accordion>

  <Accordion title="For local development">
    * `standard` mode is safe and is the recommended default even locally
    * `full` mode is only appropriate for solo developer machines with no external access
    * Run `profclaw doctor --security` to verify your configuration
  </Accordion>
</AccordionGroup>

## Reporting Security Issues

Found a vulnerability? Email: [security@profclaw.ai](mailto:security@profclaw.ai)

Please do not open public GitHub issues for security vulnerabilities. We aim to respond to security reports within 48 hours.


# Plugin Sandboxing
Source: https://docs.profclaw.ai/security/plugins

Plugin permission model, code scanning, trust levels, and security review process.

## Overview

Plugins extend profClaw with new tools, providers, and integrations. Because plugins run as JavaScript in the same process, they have significant power. The plugin security system enforces a permission model, scans code for dangerous patterns, and requires explicit trust grants before plugins can run.

## Permission Model

Every plugin declares the permissions it needs in its manifest. profClaw only grants the minimum permissions required.

```typescript theme={null}
type PluginPermission =
  | 'exec'        // Shell command execution
  | 'filesystem'  // File read/write access
  | 'network'     // Outbound HTTP requests
  | 'system'      // System information access
  | 'browser'     // Browser automation
  | 'memory'      // Memory read/write access
  | 'tools'       // Register new tools
```

A plugin requesting only `network` and `tools` cannot access the filesystem or run shell commands.

## Plugin Manifest

```json theme={null}
{
  "name": "my-weather-plugin",
  "version": "1.0.0",
  "description": "Real-time weather data",
  "main": "dist/index.js",
  "profclaw": {
    "permissions": ["network", "tools"],
    "minVersion": "2.0.0"
  }
}
```

## Code Scanning

Before a plugin is loaded, the AuditScanner analyzes its code for dangerous patterns:

| Pattern                              | Risk     | Action                                        |
| ------------------------------------ | -------- | --------------------------------------------- |
| `child_process`, `exec()`, `spawn()` | CRITICAL | Block unless `exec` permission declared       |
| `eval()`, `new Function("code")`     | CRITICAL | Always blocked                                |
| `net.connect()`, raw sockets         | CRITICAL | Always blocked                                |
| `fetch()`, `axios`                   | HIGH     | Block unless `network` permission declared    |
| `process.env.API_KEY`                | HIGH     | Warn - may be leaking credentials             |
| `writeFileSync`                      | MEDIUM   | Block unless `filesystem` permission declared |
| `process.exit()`                     | HIGH     | Always blocked                                |

If the scanner finds `CRITICAL` patterns that do not match declared permissions, the plugin is rejected at load time.

## Trust Levels

Plugins are assigned one of three trust levels:

<Tabs>
  <Tab title="Trusted">
    Plugin has been explicitly reviewed and approved. All declared permissions are granted immediately.

    ```bash theme={null}
    profclaw plugins trust my-weather-plugin --level trusted
    ```

    Only grant `trusted` to plugins you have reviewed yourself or that come from verified ClawHub publishers.
  </Tab>

  <Tab title="Sandboxed">
    Plugin runs with its declared permissions but additional constraints:

    * Network calls go through SSRF guard
    * Filesystem access goes through FsGuard
    * No access to internal profClaw state beyond the plugin SDK
    * Resource limits applied (memory, CPU)

    This is the **default for newly installed plugins**.
  </Tab>

  <Tab title="Blocked">
    Plugin is installed but will not load. Use this to temporarily disable a plugin without uninstalling it.

    ```bash theme={null}
    profclaw plugins block suspicious-plugin
    ```
  </Tab>
</Tabs>

## Installing Plugins

```bash theme={null}
# Install from npm
profclaw plugins install profclaw-plugin-weather

# Install from a local directory
profclaw plugins install ./my-local-plugin/

# Install and trust immediately (after manual review)
profclaw plugins install profclaw-plugin-weather --trust
```

When installing, the scanner runs immediately:

```
Installing profclaw-plugin-weather@1.2.0...
Scanning plugin code...
  No dangerous patterns found.
  Declared permissions: network, tools
  Permission analysis: OK

Plugin installed in sandboxed mode.
To trust this plugin: profclaw plugins trust profclaw-plugin-weather
```

## Plugin Allowlist

In `allowlist` security mode, plugins must also be on the plugin allowlist:

```yaml theme={null}
security:
  pluginAllowlist:
    - pluginId: "profclaw-plugin-weather"
      name: "Weather Plugin"
      version: "^1.0.0"
      permissions:
        - network
        - tools
      trusted: true
      addedAt: "2026-03-12"
      addedBy: "admin"
```

## Managing Plugins

```bash theme={null}
# List all installed plugins with trust status
profclaw plugins list

# Show plugin details and scan results
profclaw plugins info my-plugin

# Re-scan a plugin after update
profclaw plugins scan my-plugin

# Update a plugin
profclaw plugins update my-plugin

# Uninstall
profclaw plugins uninstall my-plugin
```

## Writing Secure Plugins

When developing plugins, follow these rules:

<Steps>
  <Step title="Declare minimum permissions">
    Only request the permissions your plugin actually needs. Users will see and approve each permission.
  </Step>

  <Step title="Use the plugin SDK">
    Always use profClaw's SDK for tool execution rather than calling shell commands directly. The SDK applies security policies.
  </Step>

  <Step title="Never hardcode credentials">
    Use `context.env` to access configuration values. Never embed API keys in code.

    ```typescript theme={null}
    const apiKey = context.env.WEATHER_API_KEY;
    if (!apiKey) return { available: false, reason: 'WEATHER_API_KEY not set' };
    ```
  </Step>

  <Step title="Handle errors safely">
    Catch all errors and return structured error responses. Never let unhandled exceptions crash the server.
  </Step>
</Steps>

## Related Docs

<CardGroup>
  <Card title="Plugin SDK" icon="code" href="/plugins/sdk">
    Full plugin development API reference.
  </Card>

  <Card title="Audit Logging" icon="scroll" href="/security/audit">
    Plugin load and scan events are audit-logged.
  </Card>
</CardGroup>


# Built-in Skills
Source: https://docs.profclaw.ai/skills/built-in

Complete list of 50 pre-installed skills organized by category.

## Overview

profClaw ships with 50 built-in skills ready to use immediately. They cover software development, productivity tools, media, system administration, and smart home/personal integrations.

All built-in skills can be invoked with `/skill-name` or auto-activate on matching phrases.

## Development

<AccordionGroup>
  <Accordion title="code-review - Analyze and review code">
    Reviews code diffs, pull requests, and functions with structured, actionable feedback.

    **Triggers**: "review this", "review my code", "check this code", "review PR"

    **Output**: Structured feedback with Critical/Suggestion/Nitpick severity levels and file:line citations.
  </Accordion>

  <Accordion title="code-generation - Generate TypeScript, Python, and more">
    Generates production-quality code with proper types, error handling, and tests.

    **Triggers**: "generate", "write code for", "implement", "create a function"

    **Best for**: Boilerplate, utilities, data transformation functions.
  </Accordion>

  <Accordion title="debug-helper - Diagnose and fix bugs">
    Structured debugging methodology: hypothesis, investigation, fix, verification.

    **Triggers**: "debug this", "why is this failing", "help me fix", "error in"
  </Accordion>

  <Accordion title="git-workflow - Branching, commits, PRs">
    Branching conventions, commit message formatting, PR creation, merge strategies.

    **Triggers**: "commit", "branch", "pull request", "merge", "push", "git"

    **Enforces**: Conventional commit format, no force push to main, no .env commits.
  </Accordion>

  <Accordion title="api-tester - Test HTTP APIs">
    Makes HTTP requests, validates responses, and helps debug API issues.

    **Triggers**: "test this API", "call this endpoint", "check this curl"
  </Accordion>

  <Accordion title="docker-ops - Docker container operations">
    Build, run, inspect, and manage Docker containers and images.

    **Triggers**: "docker", "container", "build image", "dockerfile"
  </Accordion>

  <Accordion title="github-issues - GitHub issue management">
    Create, update, and triage GitHub issues directly from chat.

    **Triggers**: "create GitHub issue", "open an issue", "close issue"
  </Accordion>

  <Accordion title="coding-agent - Autonomous coding tasks">
    Long-running autonomous agent for multi-step coding tasks. Plans, implements, tests.

    **Best for**: Feature implementation, refactoring sessions, multi-file changes.
  </Accordion>
</AccordionGroup>

## profClaw Management

<AccordionGroup>
  <Accordion title="profclaw-assistant - General profClaw assistance">
    The default assistant skill. Helps with all profClaw features and configuration.
  </Accordion>

  <Accordion title="profclaw-tickets - Ticket creation and management">
    Create tickets, update status, assign work, and manage sprints through chat.

    **Triggers**: "create a ticket", "new task", "open a bug for", "update ticket"
  </Accordion>

  <Accordion title="profclaw-projects - Project setup and management">
    Create projects, configure settings, manage team members.

    **Triggers**: "create a project", "set up a project", "new project"
  </Accordion>

  <Accordion title="cron-manager - Schedule management">
    Create, modify, and monitor scheduled jobs through natural language.

    **Triggers**: "schedule", "run every", "set up a cron", "every morning"
  </Accordion>

  <Accordion title="memory-manager - Memory file management">
    Search, read, and update MEMORY.md and memory/\*.md files.

    **Triggers**: "remember this", "update memory", "recall when", "what was decided"
  </Accordion>

  <Accordion title="model-usage - Cost and token tracking">
    View token usage, costs, and model selection recommendations.

    **Triggers**: "how much have I spent", "token usage", "cost report"
  </Accordion>

  <Accordion title="session-logs - View session history">
    Browse and search past conversation logs.

    **Triggers**: "show my history", "find past conversation about"
  </Accordion>
</AccordionGroup>

## Research & Information

<AccordionGroup>
  <Accordion title="web-research - Structured web research">
    Multi-source research with citations, summaries, and fact-checking.

    **Triggers**: "research", "find information about", "look up", "search for"
  </Accordion>

  <Accordion title="summarize - Summarize documents and content">
    Summarizes long text, documents, URLs, and conversations.

    **Triggers**: "summarize", "tl;dr", "give me a summary of"
  </Accordion>

  <Accordion title="blogwatcher - Monitor blogs and feeds">
    Track and summarize updates from configured blog URLs and RSS feeds.
  </Accordion>

  <Accordion title="xurl - URL analysis and expansion">
    Expand shortened URLs, analyze link destinations, extract metadata.

    **Triggers**: "what is this URL", "expand this link", "analyze this link"
  </Accordion>

  <Accordion title="link-understand - Deep link analysis">
    Fetches and deeply analyzes a URL: extracts key information, purpose, and structure.
  </Accordion>
</AccordionGroup>

## Productivity & Notes

<AccordionGroup>
  <Accordion title="notion - Notion workspace operations">
    Create pages, update databases, search content in Notion.

    **Requires**: Notion API key configured.
  </Accordion>

  <Accordion title="obsidian - Obsidian vault management">
    Create notes, search the vault, manage backlinks in Obsidian.

    **Requires**: Obsidian vault path configured.
  </Accordion>

  <Accordion title="apple-notes - Apple Notes integration">
    Create and search Apple Notes. macOS only.
  </Accordion>

  <Accordion title="bear-notes - Bear app integration">
    Create notes, add tags, and search Bear. macOS only.
  </Accordion>

  <Accordion title="apple-reminders - Apple Reminders">
    Create, complete, and search reminders. macOS only.
  </Accordion>

  <Accordion title="things-mac - Things 3 task manager">
    Add tasks and projects to Things 3. macOS only.
  </Accordion>

  <Accordion title="trello - Trello board management">
    Create cards, move tasks, manage boards in Trello.

    **Requires**: Trello API key configured.
  </Accordion>
</AccordionGroup>

## Media & Creative

<AccordionGroup>
  <Accordion title="openai-image-gen - DALL-E image generation">
    Generate images via OpenAI DALL-E 3.

    **Requires**: OpenAI API key with image generation access.
    **Triggers**: "generate an image", "create an image of", "draw"
  </Accordion>

  <Accordion title="openai-whisper - Local audio transcription">
    Transcribe audio files using the local Whisper model.

    **Requires**: whisper.cpp or similar installed locally.
  </Accordion>

  <Accordion title="openai-whisper-api - Cloud audio transcription">
    Transcribe audio via OpenAI Whisper API.

    **Requires**: OpenAI API key.
  </Accordion>

  <Accordion title="sherpa-onnx-tts - Local text-to-speech">
    Convert text to speech using local Sherpa-ONNX models.

    **Requires**: sherpa-onnx installed locally.
  </Accordion>

  <Accordion title="video-frames - Extract video frames">
    Extract frames from video files for analysis.

    **Requires**: ffmpeg installed.
  </Accordion>

  <Accordion title="camsnap - Webcam snapshot">
    Capture a photo from the webcam for analysis.

    **Requires**: Camera access permission.
  </Accordion>

  <Accordion title="nano-pdf - PDF reading and analysis">
    Read, search, and summarize PDF documents.
  </Accordion>
</AccordionGroup>

## System & Developer Tools

<AccordionGroup>
  <Accordion title="system-admin - System administration">
    System status, process management, disk usage, service control.

    **Triggers**: "check system status", "how much disk space", "what processes"
  </Accordion>

  <Accordion title="file-manager - File organization">
    Move, rename, organize, and find files using natural language.

    **Triggers**: "organize my files", "find files matching", "rename all"
  </Accordion>

  <Accordion title="tmux - Terminal multiplexer control">
    Create panes, sessions, and send commands via tmux.

    **Requires**: tmux installed.
  </Accordion>

  <Accordion title="healthcheck - Service health monitoring">
    Check health endpoints and service status across your stack.
  </Accordion>

  <Accordion title="mcp-discovery - MCP server discovery">
    Discover and connect to Model Context Protocol servers.
  </Accordion>

  <Accordion title="skill-creator - Create new skills">
    Helps you write a new SKILL.md file with proper frontmatter.

    **Triggers**: "create a skill for", "help me write a skill"
  </Accordion>
</AccordionGroup>

## Personal & Smart Home

<AccordionGroup>
  <Accordion title="weather - Current weather">
    Get current weather and forecasts for any location.

    **Requires**: Weather API key configured.
    **Triggers**: "what's the weather", "will it rain"
  </Accordion>

  <Accordion title="openhue - Philips Hue control">
    Control Hue lights: on/off, color, brightness, scenes.

    **Requires**: Hue Bridge on local network.
  </Accordion>

  <Accordion title="spotify-player - Spotify playback control">
    Play, pause, skip, search tracks and control Spotify.

    **Requires**: Spotify Premium and API credentials.
  </Accordion>

  <Accordion title="songsee - Song identification">
    Identify songs from audio snippets or descriptions.
  </Accordion>

  <Accordion title="1password - Password manager">
    Look up and manage items in 1Password CLI.

    **Requires**: 1Password CLI installed and authenticated.
  </Accordion>

  <Accordion title="himalaya - Email client">
    Read, send, and manage email via the himalaya CLI email client.

    **Requires**: himalaya installed and configured.
  </Accordion>

  <Accordion title="goplaces - Location and maps">
    Search places, get directions, and explore locations.
  </Accordion>

  <Accordion title="phone-control - Mobile device control">
    Send SMS, trigger actions on paired mobile devices.
  </Accordion>

  <Accordion title="oracle - AI predictions and decisions">
    Decision-making helper using structured reasoning frameworks.
  </Accordion>

  <Accordion title="gog - Game of Games tracking">
    Track gaming sessions, achievements, and backlog.
  </Accordion>

  <Accordion title="nano-banana-pro - Custom automation">
    Connect to Banana Pro / Orange Pi boards for IoT automation.
  </Accordion>
</AccordionGroup>

## Related Docs

<CardGroup>
  <Card title="Using Skills" icon="play" href="/skills/using-skills">
    How to invoke, configure, and manage skills.
  </Card>

  <Card title="ClawHub" icon="store" href="/skills/clawhub">
    Find more community skills.
  </Card>
</CardGroup>


# ClawHub
Source: https://docs.profclaw.ai/skills/clawhub

Community skill marketplace. Browse, install, and publish profClaw skills.

## What is ClawHub?

ClawHub is the community marketplace for profClaw skills. Find pre-built skills for tools and workflows you use, or publish your own skills for others to use.

<Note>
  ClawHub is planned for the profClaw v2.1 release. The `profclaw skills install` command is available now and will connect to ClawHub when it launches.
</Note>

## Installing Skills

### From ClawHub

```bash theme={null}
# Install a skill by name
profclaw skills install trello
profclaw skills install github-issues
profclaw skills install linear-tasks

# Install from a specific publisher
profclaw skills install @community/weather
profclaw skills install @yourname/my-custom-skill
```

Skills are installed to `~/.profclaw/skills/` and available immediately.

### From a URL

```bash theme={null}
profclaw skills install https://github.com/user/profclaw-skills/tree/main/my-skill
```

### From a Local Path

```bash theme={null}
profclaw skills install ./path/to/my-skill/
```

## Browsing ClawHub

```bash theme={null}
# Search for skills
profclaw skills search "jira"
profclaw skills search "productivity"

# Browse by category
profclaw skills browse --category development
profclaw skills browse --category media
```

## Skill Categories

<CardGroup>
  <Card title="Development" icon="code">
    Code review, git workflow, debugging, testing, Docker, CI/CD
  </Card>

  <Card title="Productivity" icon="check">
    Task management, notes, calendar, email, reminders
  </Card>

  <Card title="Integrations" icon="plug">
    Jira, Linear, Trello, GitHub, Notion, Obsidian
  </Card>

  <Card title="Media" icon="image">
    Image generation, TTS, video, transcription
  </Card>

  <Card title="System" icon="server">
    System admin, Docker, monitoring, shell helpers
  </Card>

  <Card title="Personal" icon="user">
    Smart home, music, weather, travel
  </Card>
</CardGroup>

## Publishing a Skill

### Step 1: Prepare your skill

Ensure your `SKILL.md` has complete frontmatter:

```markdown theme={null}
---
name: my-skill
description: What this skill does in one sentence
version: 1.0.0
user-invocable: true
metadata: >
  {"profclaw": {
    "emoji": "star",
    "category": "productivity",
    "priority": 70,
    "triggerPatterns": ["help me with X"]
  }}
---
```

### Step 2: Create a repository

Structure your skill repository:

```
my-profclaw-skill/
  SKILL.md          # Main skill file
  README.md         # Documentation
  examples/         # Example conversations (optional)
  tests/            # Test cases (optional)
```

### Step 3: Publish

```bash theme={null}
profclaw skills publish ./my-skill/
```

You will be prompted to log in to ClawHub and confirm publishing.

### Step 4: Share

Your skill becomes available at:

```
profclaw skills install @yourusername/my-skill
```

## Skill Quality Guidelines

ClawHub skills are reviewed for:

* **Clarity** - Instructions must be clear and specific
* **Safety** - No instructions that encourage dangerous tool usage
* **Focus** - Each skill should do one thing well
* **Examples** - At least 2-3 example interactions

## Verified Skills

Skills marked with a verified badge have been reviewed by the profClaw team for quality and safety. Prioritize verified skills for production use.

## Offline Use

Installed skills work fully offline - they are cached locally at `~/.profclaw/skills/`. No internet connection is required to use installed skills.

## Related Docs

<CardGroup>
  <Card title="Creating Skills" icon="pen" href="/skills/creating-skills">
    Write your own skills before publishing.
  </Card>

  <Card title="Built-in Skills" icon="box" href="/skills/built-in">
    50 skills included with every profClaw installation.
  </Card>
</CardGroup>


# Creating Skills
Source: https://docs.profclaw.ai/skills/creating-skills

Write SKILL.md files to give the AI specialized instructions for any task domain.

## Skill File Format

A skill is a single `SKILL.md` file with YAML frontmatter and Markdown instructions:

```
your-project/
  skills/
    my-skill/
      SKILL.md
```

## Complete SKILL.md Example

```markdown theme={null}
---
name: api-reviewer
description: Review REST API designs for consistency and best practices
version: 1.0.0
user-invocable: true
metadata: >
  {"profclaw": {
    "emoji": "api",
    "category": "development",
    "priority": 75,
    "triggerPatterns": [
      "review this API",
      "is this REST API good",
      "check my endpoint design"
    ]
  }}
---

# API Reviewer

You are an API design expert. When asked to review a REST API, analyze it for
consistency, adherence to REST conventions, and potential usability issues.

## What This Skill Does

- Reviews REST endpoint designs for naming consistency
- Checks HTTP method usage (GET/POST/PUT/PATCH/DELETE)
- Validates status code choices
- Identifies missing error responses
- Suggests versioning improvements

## How to Review

### Step 1: Read the API Definition

If given an OpenAPI spec file, read it:
```

read\_file(path: "openapi.yml")

```

If pasted inline, work with the provided content.

### Step 2: Evaluate Across These Dimensions

**Naming Conventions**
- Resources should be nouns, not verbs: `/users` not `/getUsers`
- Use plural for collections: `/tickets` not `/ticket`
- Consistent casing: kebab-case for multi-word paths

**HTTP Methods**
- GET: Read only, idempotent, no body
- POST: Create, non-idempotent
- PUT: Replace entire resource
- PATCH: Partial update
- DELETE: Remove resource

**Status Codes**
- 200 OK, 201 Created, 204 No Content
- 400 Bad Request (client error), 401 Unauthorized, 403 Forbidden, 404 Not Found
- 500 Internal Server Error (never expose stack traces)

### Step 3: Output Format

```

## API Review: \[endpoint or spec name]

**Overall**: \[Looks good / Needs minor fixes / Needs redesign]

### Issues

* \[METHOD /path] **\[category]**: Issue description. Suggestion: ...

### Positives

* What is well-designed

```
```

## Frontmatter Reference

<ParamField type="string">
  Unique skill identifier in kebab-case. Must be unique across all loaded skills.
</ParamField>

<ParamField type="string">
  One-sentence description shown in skill lists and the UI.
</ParamField>

<ParamField type="string">
  Semver version string (e.g., `"1.0.0"`).
</ParamField>

<ParamField type="boolean">
  Whether this skill appears as a slash command. Set to `false` for background/system skills.
</ParamField>

<ParamField type="boolean">
  Prevent the AI from auto-activating this skill based on trigger patterns.
</ParamField>

<ParamField type="string">
  Set to `"tool"` to route slash command invocation directly to a tool instead of injecting as instructions.
</ParamField>

<ParamField type="string">
  Tool name to dispatch to when `command-dispatch: tool`.
</ParamField>

<ParamField type="string">
  How to pass slash command args to the tool: `"raw"` (as a string) or `"parsed"` (as structured params).
</ParamField>

## Metadata JSON Schema

The `metadata` field is a JSON string (or YAML block scalar) with this structure:

```json theme={null}
{
  "profclaw": {
    "emoji": "magnifying-glass",
    "category": "development",
    "priority": 85,
    "triggerPatterns": [
      "review my code",
      "check this PR"
    ]
  }
}
```

| Field             | Description                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `emoji`           | Lucide icon name for UI display                                                          |
| `category`        | Group in skill browser: `development`, `productivity`, `media`, `integrations`, `system` |
| `priority`        | Sort order in lists (0-100, higher = first)                                              |
| `triggerPatterns` | Phrases that cause auto-activation                                                       |

## Writing Good Instructions

### Be Specific About Tool Usage

Instead of "look at the code", tell the AI exactly which tools to use:

```markdown theme={null}
## How to Execute

1. Read the file:
   read_file(path: provided_path)

2. Search for patterns:
   grep(pattern: "TODO:", glob: "**/*.ts")
```

### Provide Output Format Templates

Give the AI a concrete output structure to follow:

```markdown theme={null}
## Output Format

Always respond in this format:

## Summary
[1-2 sentences]

## Issues Found
- [severity] [file:line]: description

## Recommendations
1. First recommendation
```

### Include Example Interactions

```markdown theme={null}
## Examples

**User**: Review this function: `[pastes code]`
**You**: *(reads code, analyzes it)* Structured feedback with file:line references.

**User**: Is this secure?
**You**: Focuses analysis on security: injection, auth, input validation.
```

## Command Dispatch Skill

For simple slash commands that just run a tool, use command dispatch instead of instructions:

```markdown theme={null}
---
name: run-tests
description: Run the test suite
user-invocable: true
command-dispatch: tool
command-tool: test_run
command-arg-mode: raw
---

Runs all tests using the configured test framework.
```

Now `/run-tests src/auth.test.ts` calls `test_run` with the file argument.

## Testing Your Skill

```bash theme={null}
# Load and test your skill
profclaw skills load ./skills/my-skill/SKILL.md

# Verify it appears in the list
profclaw skills list

# Test invocation
profclaw chat --skill my-skill "test message"
```

## Related Docs

<CardGroup>
  <Card title="Using Skills" icon="play" href="/skills/using-skills">
    How to invoke and manage skills.
  </Card>

  <Card title="ClawHub" icon="store" href="/skills/clawhub">
    Publish your skills to the community marketplace.
  </Card>
</CardGroup>


# Skills Overview
Source: https://docs.profclaw.ai/skills/overview

Skills are plain Markdown instruction sets that specialize the AI for specific tasks. 50 built-in skills, community ClawHub skills, and custom SKILL.md files.

## What Are Skills?

A skill is a `SKILL.md` file that gives the AI a focused set of instructions, context, and behaviors for a particular task domain. When a skill is active, the AI's system prompt is extended with that skill's instructions - making it an expert in that specific area.

Examples:

* The `code-review` skill makes the AI a thorough code reviewer with a specific feedback format
* The `git-workflow` skill teaches branching conventions and safe commit practices
* The `web-research` skill instructs structured information gathering with citations

Skills are **plain Markdown** with a YAML frontmatter header. No code required - anyone can write one.

## Skill Architecture

Skills are loaded from multiple sources in priority order. Later sources override earlier ones by skill name:

```
Loading Priority (lowest to highest):
1. Extra directories    (config.load.extraDirs)
2. Built-in skills      (50 bundled with profClaw)
3. Managed skills       (~/.profclaw/skills/)
4. Workspace skills     (<project>/skills/)
```

Your workspace `skills/` directory always wins, allowing you to override any built-in skill for a specific project.

## Skill File Format

```markdown theme={null}
---
name: code-review
description: Analyze diffs, suggest improvements, and review PRs
version: 1.0.0
metadata: {"profclaw": {"emoji": "magnifying-glass", "category": "development", "priority": 85}}
---

# Code Review

You are a thorough code reviewer...

## What This Skill Does
...
```

The YAML frontmatter defines the skill's identity and behavior flags. The Markdown body is injected as system instructions when the skill is active.

## Frontmatter Fields

| Field                      | Type                  | Description                                          |
| -------------------------- | --------------------- | ---------------------------------------------------- |
| `name`                     | string                | Unique skill identifier (kebab-case)                 |
| `description`              | string                | Short description shown in the UI                    |
| `version`                  | string                | Semver version                                       |
| `user-invocable`           | boolean               | Show as a slash command users can invoke             |
| `disable-model-invocation` | boolean               | Prevent the AI from auto-activating this skill       |
| `command-dispatch`         | `"tool"`              | Route slash command directly to a specific tool      |
| `command-tool`             | string                | Tool name for `command-dispatch` mode                |
| `command-arg-mode`         | `"raw"` or `"parsed"` | How arguments are passed to the tool                 |
| `metadata`                 | JSON string           | Extended metadata: category, emoji, trigger patterns |

## How Skills Are Activated

<Tabs>
  <Tab title="Slash Commands">
    User-invocable skills respond to `/skill-name` commands. Arguments after the command name are passed through:

    ```
    /code-review
    /git-workflow commit my changes
    /web-research latest Hono middleware docs
    /summarize src/chat/
    ```
  </Tab>

  <Tab title="AI Auto-Activation">
    Skills with `triggerPatterns` in their metadata are auto-activated when the AI detects a matching intent in the user's message:

    * "review my code" activates `code-review`
    * "commit my changes" activates `git-workflow`
    * "search for..." activates `web-research`

    Disable auto-activation for a specific skill with `disable-model-invocation: true` in frontmatter.
  </Tab>

  <Tab title="Preset Assignment">
    Skills can be assigned to a preset (persona) so they are always active for a specific channel or use case:

    ```yaml theme={null}
    # settings.yml
    presets:
      code-assistant:
        skills:
          - code-review
          - git-workflow
          - debug-helper
    ```
  </Tab>
</Tabs>

## Skill Sources

<CardGroup>
  <Card title="Built-in Skills" icon="box" href="/skills/built-in">
    50 pre-installed skills covering development, productivity, and media workflows.
  </Card>

  <Card title="ClawHub" icon="store" href="/skills/clawhub">
    Community skill marketplace. Browse and install with `profclaw skills install`.
  </Card>

  <Card title="Creating Skills" icon="pen" href="/skills/creating-skills">
    Write your own SKILL.md files for custom behavior. No code required.
  </Card>

  <Card title="Using Skills" icon="play" href="/skills/using-skills">
    How to invoke, list, manage, and configure skills.
  </Card>
</CardGroup>

## Managing Skills via CLI

```bash theme={null}
# List all available skills
profclaw skills list

# Search for skills on ClawHub
profclaw skills search code-review

# Install a skill from ClawHub
profclaw skills install @profclaw/skill-debug-helper

# Show skill details
profclaw skills show git-workflow

# Disable a built-in skill
profclaw skills disable web-research
```

## Skills vs Tools vs Plugins

Understanding when to use each extension mechanism:

|                    | Skills                       | Tools                    | Plugins            |
| ------------------ | ---------------------------- | ------------------------ | ------------------ |
| **Format**         | SKILL.md (Markdown)          | TypeScript code          | npm package        |
| **Purpose**        | AI instructions and behavior | Executable functions     | System extensions  |
| **Complexity**     | Simple - text only           | Medium - typed functions | Full - npm package |
| **Requires code**  | No                           | Yes                      | Yes                |
| **Can call tools** | Yes (by instruction)         | N/A                      | Yes                |
| **Can add tools**  | No                           | Yes (via plugin)         | Yes                |

Skills are the easiest and fastest way to extend profClaw behavior. Use [Plugins](/plugins/overview) when you need to add executable tools or system-level integrations.


# Using Skills
Source: https://docs.profclaw.ai/skills/using-skills

How to invoke skills via slash commands, auto-activation, and preset assignment.

## Invoking Skills

### Slash Commands

Type a `/` followed by the skill name in any chat:

```
/code-review
/git-workflow
/web-research BullMQ job retry patterns
/debug-helper
```

Arguments after the skill name are passed as the initial message to that skill's context.

### Natural Language

Skills with trigger patterns auto-activate when the AI detects matching intent. You do not need to use a slash command:

| You say                  | Activates          |
| ------------------------ | ------------------ |
| "review this code"       | `code-review`      |
| "commit my changes"      | `git-workflow`     |
| "search for..."          | `web-research`     |
| "help me debug this"     | `debug-helper`     |
| "create a ticket for..." | `profclaw-tickets` |

### From the CLI

```bash theme={null}
# Start a session with a specific skill
profclaw chat --skill code-review

# Run a one-shot skill command
profclaw run --skill git-workflow "commit all staged changes with message: fix queue null check"
```

## Managing Skills

### List Installed Skills

```bash theme={null}
profclaw skills list
```

Shows all loaded skills with their source (built-in, managed, workspace), version, and category.

### Install from ClawHub

```bash theme={null}
profclaw skills install trello
profclaw skills install github-issues
profclaw skills install @community/weather
```

### Update Skills

```bash theme={null}
profclaw skills update           # Update all managed skills
profclaw skills update trello    # Update specific skill
```

### Disable a Skill

```bash theme={null}
profclaw skills disable code-review
```

Or in `settings.yml`:

```yaml theme={null}
skills:
  disabled:
    - code-review
    - web-research
```

## Skill Configuration

Some skills accept configuration in `settings.yml`:

```yaml theme={null}
skills:
  config:
    git-workflow:
      defaultBranch: main
      requireTicketId: true
    web-research:
      maxResults: 5
      preferredProvider: brave
```

## Skill Precedence

When multiple sources define a skill with the same name, the higher-priority source wins:

```
workspace/skills/ > ~/.profclaw/skills/ > built-in > extra dirs
```

To override a built-in skill, create a file at `skills/code-review/SKILL.md` in your project root.

## Checking Active Skills

In a chat conversation, you can ask:

> "What skills are currently active?"

Or check from the CLI:

```bash theme={null}
profclaw skills status
```

## Preset-Based Skill Loading

Assign a bundle of skills to a persona (preset):

```yaml theme={null}
# settings.yml
presets:
  backend-dev:
    name: "Backend Developer"
    model: claude-sonnet-4-6
    skills:
      - code-review
      - git-workflow
      - debug-helper
      - api-tester
      - docker-ops

  content-creator:
    name: "Content Creator"
    model: claude-sonnet-4-6
    skills:
      - web-research
      - summarize
      - blogwatcher
```

Switch presets with `/preset backend-dev`.

## Skill Metadata

View detailed skill metadata:

```bash theme={null}
profclaw skills info code-review
```

Output:

```
code-review v1.0.0
  Category: development
  Source:   built-in
  Triggers: "review this", "review my code", "check this code"
  Command:  /code-review
```

## Related Docs

<CardGroup>
  <Card title="Built-in Skills" icon="box" href="/skills/built-in">
    Browse all 50 pre-installed skills.
  </Card>

  <Card title="Creating Skills" icon="pen" href="/skills/creating-skills">
    Write your own skills.
  </Card>
</CardGroup>


# 2026 04 02 engine hardening design
Source: https://docs.profclaw.ai/superpowers/specs/2026-04-02-engine-hardening-design



# profClaw Engine Hardening & Enhancement Spec

> Make profClaw launch-ready: reliable first-install, robust engine, Claude Code-inspired patterns.

**Date:** 2026-04-02
**Status:** Draft
**Priority focus:** CLI experience + Agent execution reliability

***

## Problem Statement

profClaw has a powerful engine (882-line executor, 72 tools, 35 providers, 22 chat channels) but isn't launch-ready because:

1. **First install breaks silently** — no auto-migrations, no setup redirect, no provider validation
2. **Engine lacks resilience patterns** — no circuit breakers, no context compaction, no deferred tool loading
3. **No hook system** — users can't customize behavior without modifying core code
4. **Tool results can blow up context** — no size limits, no disk spillover
5. **Streaming is rigid** — `generateText()` return value, not consumable async generator

Users who `npm i -g profclaw && profclaw serve` must get a working experience in 60 seconds or they uninstall.

***

## Workstreams

### WS-1: First-Install Reliability (CRITICAL — blocks launch)

These are the "user runs profclaw for the first time" fixes. All are independent and can be parallelized.

#### 1.1 Auto-Migration on Startup

* **File:** `src/storage/index.ts`
* **Change:** After `initStorage()` connects, call `await storage.runMigrations()`
* **Fallback:** If migration fails, log error with exact SQL that failed, suggest `profclaw db:migrate --verbose`
* **Test:** `src/storage/tests/auto-migrate.test.ts` — test fresh DB gets schema, test already-migrated DB is no-op

#### 1.2 Provider Validation on Startup

* **File:** `src/server.ts` (after agent init block \~line 768)
* **Change:** After agent registry populates, check `registry.getActiveAdapters().length > 0`. If zero:
  * Log: "No AI providers configured. Run `profclaw setup` or set ANTHROPIC\_API\_KEY / OPENAI\_API\_KEY"
  * If `PROFCLAW_STRICT_MODE=true`, exit(1)
  * Otherwise, continue but set `server.degradedMode = true`
* **Test:** `src/server/tests/startup-validation.test.ts`

#### 1.3 First-Run Setup Redirect

* **File:** `src/server.ts` (GET `/` route)
* **Change:** If admin user count === 0, redirect to `/setup` instead of serving blank dashboard
* **File:** `src/cli/commands/serve.ts`
* **Change:** On first boot, print banner: "First run detected. Visit [http://localhost:9100/setup](http://localhost:9100/setup) to configure profClaw"
* **Test:** `src/e2e/first-run.test.ts`

#### 1.4 In-Memory Storage Warning

* **File:** `src/server.ts`
* **Change:** When storage falls back to in-memory:
  * Log warning banner every 60s (not 30s — less noisy)
  * Add `X-ProfClaw-Storage: ephemeral` header via Hono middleware
  * Show yellow banner in UI dashboard
* **Test:** Extend existing storage tests

#### 1.5 Port Conflict Handling

* **File:** `src/cli/commands/serve.ts`
* **Change:** Replace check-then-bind with bind-or-retry:
  * Try configured port
  * If EADDRINUSE, try port+1, port+2 (max 3 attempts)
  * Log which port was actually used
* **Test:** `src/cli/tests/port-conflict.test.ts`

***

### WS-2: Engine Resilience (HIGH — prevents runtime failures)

#### 2.1 Circuit Breaker for Tools

* **File:** `src/agents/executor.ts`
* **New file:** `src/agents/circuit-breaker.ts`
* **Design:**
  ```typescript theme={null}
  interface CircuitBreaker {
    state: 'closed' | 'open' | 'half-open'
    failureCount: number
    lastFailureAt: number
    cooldownMs: number  // starts at 5s, doubles each trip, max 60s
  }

  class ToolCircuitBreaker {
    private breakers: Map<string, CircuitBreaker>

    canExecute(toolName: string): boolean
    recordSuccess(toolName: string): void
    recordFailure(toolName: string): void
    getStatus(): Map<string, CircuitBreaker>
  }
  ```
* **Integration:** In executor's tool execution block (\~line 494), check `circuitBreaker.canExecute(toolName)` before calling tool. On failure, `recordFailure()`. On success, `recordSuccess()`.
* **Thresholds:** 3 failures in 2 minutes → open. Half-open after cooldown. 1 success in half-open → close.
* **Test:** `src/agents/tests/circuit-breaker.test.ts`

#### 2.2 Per-Step Timeout Enforcement

* **File:** `src/agents/executor.ts`
* **Change:** The config already has `stepTimeoutMs: 60000` but it's not used. Wrap each step's tool execution in `Promise.race([toolExec, timeout(config.stepTimeoutMs)])`.
* **Test:** Extend `executor.test.ts`

#### 2.3 Tool Result Size Management

* **File:** `src/agents/executor.ts`
* **New file:** `src/agents/result-store.ts`
* **Design:**
  ```typescript theme={null}
  const MAX_INLINE_RESULT_SIZE = 50_000  // 50KB inline in context
  const MAX_RESULT_SIZE = 5_000_000       // 5MB total before truncation

  class ResultStore {
    store(toolCallId: string, result: unknown): StoredResult
    // If result > MAX_INLINE_RESULT_SIZE:
    //   1. Save full result to temp file
    //   2. Return summary + file path as inline result
    //   3. Provide retrieve() for tools that need the full data
    retrieve(toolCallId: string): unknown
    cleanup(): void  // called on session end
  }
  ```
* **Integration:** After tool returns result, pass through `resultStore.store()`. Agent sees summary; tools can access full data.
* **Test:** `src/agents/tests/result-store.test.ts`

***

### WS-3: Async Generator Streaming (HIGH — architectural upgrade)

This is the biggest change. Refactors the executor to yield events as they happen instead of returning a final result.

#### 3.1 Event Types

* **New file:** `src/agents/events.ts`
  ```typescript theme={null}
  type AgentEvent =
    | { type: 'session:start'; sessionId: string; config: AgentConfig }
    | { type: 'step:start'; stepIndex: number }
    | { type: 'tool:call'; toolName: string; args: unknown; toolCallId: string }
    | { type: 'tool:result'; toolCallId: string; result: unknown; duration: number }
    | { type: 'tool:error'; toolCallId: string; error: string }
    | { type: 'content'; text: string; delta: string }
    | { type: 'thinking'; text: string }
    | { type: 'cost:update'; tokens: TokenUsage; estimatedCost: number }
    | { type: 'circuit:open'; toolName: string; cooldownMs: number }
    | { type: 'step:complete'; stepIndex: number; summary: StepSummary }
    | { type: 'session:complete'; result: AgentResult }
    | { type: 'session:error'; error: AgentError }
    | { type: 'session:abort'; reason: string }
  ```

#### 3.2 Generator Executor

* **File:** `src/agents/executor.ts`
* **Change:** Add `async *stream()` method alongside existing `run()`:
  ```typescript theme={null}
  class AgentExecutor extends EventEmitter {
    // Existing — kept for backward compat
    async run(...): Promise<AgentState> {
      let lastResult: AgentResult | undefined
      for await (const event of this.stream(...)) {
        if (event.type === 'session:complete') lastResult = event.result
      }
      return this.buildState(lastResult)
    }

    // New — the real engine
    async *stream(
      model: LanguageModel,
      messages: ModelMessage[],
      tools: ToolSet,
      options?: StreamOptions
    ): AsyncGenerator<AgentEvent> {
      yield { type: 'session:start', ... }
      // ... existing logic refactored to yield events
    }
  }
  ```
* **Key:** `run()` wraps `stream()`, so all existing callers work unchanged. New callers (CLI TUI, SSE, SDK) consume the generator directly.
* **Test:** `src/agents/tests/streaming.test.ts`

#### 3.3 SSE Integration

* **File:** `src/server.ts` (SSE endpoint)
* **Change:** Replace manual event broadcasting with direct generator consumption:
  ```typescript theme={null}
  // On new task/chat request:
  const stream = executor.stream(model, messages, tools)
  for await (const event of stream) {
    broadcastSSE(event)
  }
  ```

***

### WS-4: Hook System (MEDIUM-HIGH — extensibility)

#### 4.1 Hook Registry

* **New file:** `src/hooks/registry.ts`
  ```typescript theme={null}
  type HookPoint =
    | 'beforeToolCall'
    | 'afterToolCall'
    | 'beforeApiCall'
    | 'afterResponse'
    | 'onSessionStart'
    | 'onSessionEnd'
    | 'onError'
    | 'onBudgetWarning'

  interface Hook {
    name: string
    point: HookPoint
    priority: number  // lower runs first
    handler: (context: HookContext) => Promise<HookResult>
  }

  interface HookResult {
    proceed: boolean      // false = abort the operation
    modified?: unknown    // override args/result if provided
    metadata?: Record<string, unknown>
  }

  class HookRegistry {
    register(hook: Hook): void
    unregister(name: string): void
    run(point: HookPoint, context: HookContext): Promise<HookResult>
  }
  ```

#### 4.2 Built-in Hooks

* **Cost warning hook:** Fires at 50%, 80%, 100% budget usage
* **Dangerous tool hook:** Prompts for confirmation on file writes, bash commands
* **Logging hook:** Records all tool calls to audit log

#### 4.3 Integration Points

* `src/agents/executor.ts` — wrap tool calls with `hooks.run('beforeToolCall')` / `hooks.run('afterToolCall')`
* `src/server.ts` — load hooks from `profclaw.hooks.yml` or `hooks/` directory on startup
* **Test:** `src/hooks/tests/registry.test.ts`

***

### WS-5: Deferred Tool Loading (MEDIUM — performance + context savings)

#### 5.1 Tool Categories

* **File:** `src/chat/execution/tools/` (existing tool definitions)
* **New file:** `src/agents/tool-loader.ts`
* **Design:** Categorize 72 tools into groups:
  ```
  always_loaded (10-15 core tools):
    - read_file, write_file, search_files
    - bash, git_status, git_commit
    - complete_task, create_ticket

  deferred (remaining 55+ tools):
    - browser_* (7 tools) — loaded when task mentions URLs/web
    - integration_* (12 tools) — loaded when task mentions Slack/GitHub/etc
    - canvas_* (5 tools) — loaded when task mentions diagrams/visuals
    - voice_* (3 tools) — loaded when task mentions audio/voice
    - ...
  ```

#### 5.2 Tool Search Tool

* **New file:** `src/chat/execution/tools/tool-search.ts`
  ```typescript theme={null}
  // Added to always_loaded set
  const toolSearchTool = {
    name: 'search_available_tools',
    description: 'Search for additional tools by capability. Returns matching tools that can be used.',
    parameters: { query: z.string().describe('What capability you need') },
    execute: async ({ query }) => {
      const matches = toolLoader.search(query)
      // Dynamically add matched tools to current session
      return { tools: matches.map(t => ({ name: t.name, description: t.description })) }
    }
  }
  ```
* **Test:** `src/agents/tests/tool-loader.test.ts`

***

### WS-6: Context Compaction (MEDIUM — prevents context overflow)

#### 6.1 History Compactor

* **New file:** `src/agents/context-compactor.ts`
  ```typescript theme={null}
  interface CompactionConfig {
    maxContextTokens: number        // default: model's context - 20% headroom
    compactionThreshold: number     // trigger at 70% of max
    preserveRecentTurns: number     // always keep last 5 turns verbatim
    summaryModel: string            // use cheap model for summarization
  }

  class ContextCompactor {
    async compact(messages: Message[], config: CompactionConfig): Promise<Message[]> {
      const tokenCount = estimateTokens(messages)
      if (tokenCount < config.compactionThreshold) return messages

      // Split: [older messages] | [recent N turns]
      // Summarize older messages into single system-context message
      // Return: [summary] + [recent turns]
    }
  }
  ```

#### 6.2 Integration

* **File:** `src/agents/executor.ts` — before each API call, run `compactor.compact(messages)`
* **File:** `src/chat/agentic-executor.ts` — same integration for chat executor
* **Test:** `src/agents/tests/context-compactor.test.ts`

***

## Parallelization Strategy

These workstreams have minimal dependencies:

```
Independent (can run in parallel):
├── WS-1.1  Auto-migration         (storage layer)
├── WS-1.2  Provider validation    (server startup)
├── WS-1.3  First-run redirect     (server routes)
├── WS-1.4  In-memory warning      (server middleware)
├── WS-1.5  Port conflict          (CLI serve command)
├── WS-2.1  Circuit breaker        (new file + executor integration)
├── WS-2.2  Step timeout           (executor only)
├── WS-4.1  Hook registry          (new file, standalone)
├── WS-5.1  Tool categorization    (new file, standalone)
├── WS-6.1  Context compactor      (new file, standalone)
└── WS-4.2  Built-in hooks         (depends on WS-4.1)

Sequential (depends on prior work):
WS-2.3  Result store        → needs to exist before WS-3
WS-3.1  Event types         → first
WS-3.2  Generator executor  → depends on 3.1, 2.1, 2.2, 2.3
WS-3.3  SSE integration     → depends on 3.2
WS-4.3  Hook integration    → depends on 4.1 + 3.2
WS-5.2  Tool search tool    → depends on 5.1
WS-6.2  Compactor integration → depends on 6.1 + 3.2
```

## Agent Dispatch Plan

**Batch 1 — All parallel (no dependencies):**

| Agent   | Workstream                                                          | Files touched                                |
| ------- | ------------------------------------------------------------------- | -------------------------------------------- |
| Agent A | WS-1.1 Auto-migration                                               | `src/storage/index.ts` + test                |
| Agent B | WS-1.2 + 1.3 + 1.4 Provider validation + first-run + memory warning | `src/server.ts` + tests                      |
| Agent C | WS-1.5 Port conflict                                                | `src/cli/commands/serve.ts` + test           |
| Agent D | WS-2.1 Circuit breaker                                              | New `src/agents/circuit-breaker.ts` + test   |
| Agent E | WS-2.2 Step timeout                                                 | `src/agents/executor.ts` (small change)      |
| Agent F | WS-2.3 Result store                                                 | New `src/agents/result-store.ts` + test      |
| Agent G | WS-4.1 + 4.2 Hook registry + built-ins                              | New `src/hooks/` + tests                     |
| Agent H | WS-5.1 Tool categorization + 5.2 search tool                        | New `src/agents/tool-loader.ts` + tool       |
| Agent I | WS-6.1 Context compactor                                            | New `src/agents/context-compactor.ts` + test |

**Batch 2 — Sequential (after batch 1):**

| Agent   | Workstream                                    | Depends on        |
| ------- | --------------------------------------------- | ----------------- |
| Agent J | WS-3.1 + 3.2 Event types + Generator refactor | Batch 1 (D, E, F) |
| Agent K | WS-3.3 SSE integration                        | Agent J           |
| Agent L | WS-4.3 Hook integration into executor         | Agent J + G       |
| Agent M | WS-6.2 Compactor integration                  | Agent J + I       |

**Batch 3 — Final verification:**

| Agent   | Task                                                              |
| ------- | ----------------------------------------------------------------- |
| Agent N | Run full test suite, fix any integration issues                   |
| Agent O | First-install smoke test (fresh DB, no config, verify setup flow) |

***

## Testing Requirements

Every workstream produces tests. Minimum coverage:

| Workstream | Test type          | Min test count                                                               |
| ---------- | ------------------ | ---------------------------------------------------------------------------- |
| WS-1.x     | Integration        | 8 tests (2 per sub-item)                                                     |
| WS-2.1     | Unit               | 6 tests (closed/open/half-open states, reset, concurrent)                    |
| WS-2.2     | Unit               | 3 tests (timeout fires, timeout doesn't fire, cleanup)                       |
| WS-2.3     | Unit               | 5 tests (inline, spillover, retrieve, cleanup, size edge cases)              |
| WS-3.x     | Unit + Integration | 8 tests (event ordering, backpressure, error propagation, SSE)               |
| WS-4.x     | Unit               | 6 tests (register, priority, abort, modify, lifecycle)                       |
| WS-5.x     | Unit               | 4 tests (categorize, search, dynamic add, always-loaded)                     |
| WS-6.x     | Unit               | 4 tests (below threshold no-op, compaction, preserve recent, token estimate) |

**Total: \~44 new tests minimum**

***

## Success Criteria

After all workstreams complete:

1. `npm i -g profclaw && profclaw serve` on a fresh machine → setup wizard appears (not blank screen)
2. No AI keys configured → clear error message with instructions (not silent failure)
3. Tool fails 3 times → circuit breaker opens, agent tries alternative approach
4. 200KB tool result → stored on disk, summary in context
5. 50+ turn conversation → context auto-compacts, no token overflow crash
6. Agent executor yields typed events → CLI/SSE/SDK can all consume same stream
7. Users can add hooks via `profclaw.hooks.yml` without modifying core code
8. Agent only sees \~15 tools initially, discovers more via search tool
9. All 95 existing tests still pass
10. 44+ new tests added and passing

***

## Non-Goals

* UI redesign (separate effort)
* New chat channel integrations
* New tool implementations
* Provider SDK upgrades
* Performance benchmarking (do after launch)


# Browser Tools
Source: https://docs.profclaw.ai/tools/browser-tools

Puppeteer-based browser automation: navigate, click, type, screenshot, and more.

## Overview

Browser tools give the agent a full Chromium browser it can control programmatically. This is useful for pages that require JavaScript to render, login flows, form submission, and visual verification via screenshots.

Browser tools are in the **Full tier** - they are only sent to frontier models (Claude, GPT-4o, Gemini) that can reliably reason about page state and UI interactions.

<Note>
  Browser tools require Puppeteer to be installed. Run `pnpm install` to install all optional dependencies, including Puppeteer.
</Note>

## Available Tools

| Tool                 | Description                             | Security   |
| -------------------- | --------------------------------------- | ---------- |
| `browser_navigate`   | Navigate to a URL                       | `moderate` |
| `browser_snapshot`   | Get the current page accessibility tree | `safe`     |
| `browser_click`      | Click an element by CSS selector        | `moderate` |
| `browser_type`       | Type text into an input field           | `moderate` |
| `browser_search`     | Search the web using browser navigation | `moderate` |
| `browser_screenshot` | Take a screenshot of the current page   | `safe`     |
| `browser_pages`      | List all open browser tabs/pages        | `safe`     |
| `browser_close`      | Close a page or the entire browser      | `moderate` |

## Tool Details

### `browser_navigate`

Navigate to a URL. Opens a new browser page if none is active.

<ParamField type="string">
  Full URL to navigate to. Must be `http://` or `https://`.
</ParamField>

<ParamField type="string">
  Wait condition: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`.
</ParamField>

<ParamField type="number">
  Navigation timeout in milliseconds.
</ParamField>

***

### `browser_snapshot`

Get the current page's accessibility tree as structured text. More token-efficient than a screenshot for text-heavy pages.

<ParamField type="boolean">
  Include hidden elements in the snapshot.
</ParamField>

***

### `browser_click`

Click an element on the page.

<ParamField type="string">
  CSS selector for the element to click. Use `aria/Button Name` for accessible selectors.
</ParamField>

<ParamField type="string">
  Mouse button: `left`, `right`, `middle`.
</ParamField>

<ParamField type="number">
  Number of clicks (use 2 for double-click).
</ParamField>

***

### `browser_type`

Type text into an input or textarea.

<ParamField type="string">
  CSS selector for the input element.
</ParamField>

<ParamField type="string">
  Text to type.
</ParamField>

<ParamField type="boolean">
  Clear existing content before typing.
</ParamField>

<ParamField type="number">
  Delay between keystrokes in milliseconds (simulates human typing).
</ParamField>

***

### `browser_screenshot`

Capture the current page as a PNG image.

<ParamField type="boolean">
  Capture the full scrollable page, not just the viewport.
</ParamField>

<ParamField type="string">
  Capture only a specific element instead of the whole page.
</ParamField>

<ParamField type="number">
  JPEG quality (1-100). Only applies when format is `jpeg`.
</ParamField>

***

### `browser_pages`

List all currently open browser pages/tabs.

Returns page IDs, URLs, and titles. Use page IDs to target operations at specific tabs.

***

### `browser_close`

Close a specific page or all browser pages.

<ParamField type="string">
  ID of the specific page to close. Omit to close all pages.
</ParamField>

## Typical Workflow

<Steps>
  <Step title="Navigate to the page">
    ```json theme={null}
    { "url": "https://app.example.com/login" }
    ```
  </Step>

  <Step title="Take a snapshot to see the page structure">
    ```json theme={null}
    { "includeHidden": false }
    ```
  </Step>

  <Step title="Fill in the login form">
    ```json theme={null}
    { "selector": "#email", "text": "user@example.com", "clear": true }
    ```

    ```json theme={null}
    { "selector": "#password", "text": "mypassword", "clear": true }
    ```
  </Step>

  <Step title="Click the submit button">
    ```json theme={null}
    { "selector": "button[type='submit']" }
    ```
  </Step>

  <Step title="Screenshot to verify the result">
    ```json theme={null}
    { "fullPage": false }
    ```
  </Step>
</Steps>

## Safe vs Full Browser Tools

By default, only "safe" browser tools (`browser_snapshot`, `browser_screenshot`, `browser_pages`) are included for non-frontier models. The full automation set requires a frontier model to reason about page state accurately.

```yaml theme={null}
# settings.yml - override for specific presets
presets:
  browser-agent:
    tools:
      promote:
        - browser_navigate
        - browser_click
        - browser_type
```

## Related Tools

<CardGroup>
  <Card title="Web Fetch" icon="globe" href="/tools/web-fetch">
    Faster for APIs and static pages that do not need JavaScript.
  </Card>

  <Card title="Web Search" icon="magnifying-glass" href="/tools/web-search">
    Search without opening a full browser session.
  </Card>
</CardGroup>


# Code Analysis
Source: https://docs.profclaw.ai/tools/code-analysis

Static analysis, linting, type checking, and image analysis tools.

## Overview

Code analysis tools help the agent verify code quality after making changes. Rather than relying solely on reading code, the agent can run the actual type checker or linter and get machine-precise feedback.

## Tools

### `exec` (for Analysis Tasks)

The `exec` tool is used for running analysis commands. It is in the Essential tier and works with any model.

**Security level**: `dangerous` | **Tier**: Essential

<ParamField type="string">
  Shell command to run (e.g., `"pnpm tsc --noEmit"`, `"pnpm lint"`).
</ParamField>

<ParamField type="string">
  Working directory. Defaults to the conversation workdir.
</ParamField>

<ParamField type="number">
  Timeout in milliseconds (default 5 minutes).
</ParamField>

<ParamField type="boolean">
  Run in the background and return immediately. Check with `session_status`.
</ParamField>

<CodeGroup>
  ```json TypeScript type check theme={null}
  {
    "command": "pnpm tsc --noEmit"
  }
  ```

  ```json ESLint check theme={null}
  {
    "command": "pnpm eslint src/ --max-warnings 0"
  }
  ```

  ```json Run both in sequence theme={null}
  {
    "command": "pnpm tsc --noEmit && pnpm lint"
  }
  ```
</CodeGroup>

***

### `image_analyze`

Analyze an image file and describe its contents. Useful for screenshots, diagrams, or design files.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Path to the image file (PNG, JPG, GIF, WebP).
</ParamField>

<ParamField type="string">
  Specific question to ask about the image (e.g., "What errors are visible?", "Describe the UI layout").
</ParamField>

```json theme={null}
{
  "path": "screenshots/error-state.png",
  "prompt": "What error messages are visible and what might cause them?"
}
```

***

### `link_understand`

Analyze a URL and extract structured understanding of its content without fetching the full HTML.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  URL to analyze.
</ParamField>

<ParamField type="string">
  Aspect to focus on: `"summary"`, `"code"`, `"api"`, `"docs"`.
</ParamField>

***

### `which`

Find the path to a binary (equivalent to `which` command).

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Command name to look up.
</ParamField>

Returns the full path to the binary, or an error if not found.

***

### `env`

Read environment variable values.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Specific environment variable to read. Omit to list all (filtered for safety).
</ParamField>

<Note>
  Secret-looking variables (containing `KEY`, `SECRET`, `TOKEN`, `PASSWORD`) are automatically masked in the output.
</Note>

***

### `system_info`

Get system information: OS, CPU, memory, Node version, disk space.

**Security level**: `safe` | **Tier**: Standard

***

### `process_list`

List running processes.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Filter processes by name.
</ParamField>

## Recommended Analysis Workflow

<Steps>
  <Step title="Make your changes">
    Use `edit_file` or `write_file` to apply code changes.
  </Step>

  <Step title="Type check">
    ```json theme={null}
    { "command": "pnpm tsc --noEmit 2>&1 | head -50" }
    ```

    Pipe through `head` to limit output for large projects.
  </Step>

  <Step title="Lint">
    ```json theme={null}
    { "command": "pnpm lint --quiet" }
    ```
  </Step>

  <Step title="Run affected tests">
    Use `test_run` with the `file` parameter to run tests for the changed module.
  </Step>
</Steps>

## Related Tools

<CardGroup>
  <Card title="Test Runner" icon="flask" href="/tools/test-runner">
    Run automated tests after type checking passes.
  </Card>

  <Card title="File Operations" icon="folder" href="/tools/file-operations">
    Read source files to understand the code before analyzing.
  </Card>
</CardGroup>


# Cron Tools
Source: https://docs.profclaw.ai/tools/cron-tools

Schedule HTTP webhooks, tool calls, and shell scripts to run automatically on a cron schedule.

## Overview

Cron tools let the agent create and manage scheduled jobs. You can schedule HTTP calls (webhooks), execute any profClaw tool automatically, or run shell commands on a cron expression or interval.

All cron tools are in the **Full tier** - they require capable models to correctly reason about cron expressions and job lifecycles.

## Available Tools

| Tool           | Description                 |
| -------------- | --------------------------- |
| `cron_create`  | Create a new scheduled job  |
| `cron_list`    | List all scheduled jobs     |
| `cron_trigger` | Manually trigger a job now  |
| `cron_pause`   | Pause or resume a job       |
| `cron_archive` | Archive (soft-delete) a job |
| `cron_delete`  | Permanently delete a job    |
| `cron_history` | View run history for a job  |

## Tool: `cron_create`

Create a new scheduled job.

**Security level**: `moderate` | **Tier**: Full

<ParamField type="string">
  Human-readable name for the job (max 100 characters).
</ParamField>

<ParamField type="string">
  Optional description of what the job does.
</ParamField>

<ParamField type="string">
  Cron expression (e.g., `"*/5 * * * *"` for every 5 minutes). Either `cron` or `interval` is required.
</ParamField>

<ParamField type="number">
  Interval in milliseconds (minimum 1000ms = 1 second). Alternative to `cron`.
</ParamField>

<ParamField type="string">
  Job type: `http`, `tool`, or `script`.
</ParamField>

### HTTP Job Parameters

<ParamField type="string">
  Webhook URL to call.
</ParamField>

<ParamField type="string">
  HTTP method: `GET`, `POST`, `PUT`, `DELETE`.
</ParamField>

<ParamField type="object">
  Request headers.
</ParamField>

<ParamField type="any">
  Request body (JSON-encoded automatically).
</ParamField>

### Tool Job Parameters

<ParamField type="string">
  Name of the profClaw tool to execute.
</ParamField>

<ParamField type="object">
  Parameters to pass to the tool.
</ParamField>

### Script Job Parameters

<ParamField type="string">
  Shell command to run.
</ParamField>

<ParamField type="array">
  Command arguments array.
</ParamField>

<ParamField type="string">
  Working directory for the script.
</ParamField>

### Limits

<ParamField type="number">
  Stop the job after this many successful runs.
</ParamField>

<ParamField type="number">
  Pause the job after this many consecutive failures.
</ParamField>

## Examples

<CodeGroup>
  ```json Daily health check webhook theme={null}
  {
    "name": "Daily health check",
    "description": "POST to our monitoring endpoint every day at 9am",
    "cron": "0 9 * * *",
    "type": "http",
    "url": "https://monitoring.example.com/ping",
    "method": "POST",
    "body": { "service": "profclaw", "check": "daily" }
  }
  ```

  ```json Run memory search every hour theme={null}
  {
    "name": "Hourly memory index",
    "cron": "0 * * * *",
    "type": "tool",
    "tool": "memory_stats"
  }
  ```

  ```json Run a script every 5 minutes theme={null}
  {
    "name": "Database cleanup",
    "interval": 300000,
    "type": "script",
    "command": "node",
    "args": ["scripts/cleanup.js"],
    "workdir": "/app"
  }
  ```
</CodeGroup>

## Common Cron Expressions

| Expression    | Meaning                   |
| ------------- | ------------------------- |
| `*/5 * * * *` | Every 5 minutes           |
| `0 * * * *`   | Every hour                |
| `0 9 * * *`   | Daily at 9:00 AM          |
| `0 9 * * 1-5` | Weekdays at 9:00 AM       |
| `0 0 * * 0`   | Weekly on Sunday midnight |
| `0 0 1 * *`   | Monthly on the 1st        |

## Tool: `cron_list`

List all scheduled jobs with status.

Returns job IDs, names, schedules, current status (active/paused/archived), last run time, and next scheduled run.

## Tool: `cron_trigger`

Manually trigger a job outside its schedule.

<ParamField type="string">
  Job ID to trigger.
</ParamField>

## Tool: `cron_pause`

Pause or resume a job.

<ParamField type="string">
  Job ID.
</ParamField>

<ParamField type="boolean">
  `true` to pause, `false` to resume.
</ParamField>

## Tool: `cron_history`

View the run history for a job.

<ParamField type="string">
  Job ID.
</ParamField>

<ParamField type="number">
  Maximum history entries.
</ParamField>

Returns: run timestamps, duration, status (success/failure), and any error messages.

## Related Tools

<CardGroup>
  <Card title="profClaw Ops" icon="ticket" href="/tools/profclaw-ops">
    Schedule recurring ticket creation or status updates.
  </Card>

  <Card title="Web Fetch" icon="globe" href="/tools/web-fetch">
    HTTP jobs use the same SSRF protections as web\_fetch.
  </Card>
</CardGroup>


# Custom Tools
Source: https://docs.profclaw.ai/tools/custom-tools

Register your own tools via the plugin SDK or settings configuration.

## Overview

profClaw's tool system is fully extensible. You can register custom tools that the AI can call just like built-in tools. Custom tools go through the same schema validation, security checks, and tier routing as built-in tools.

There are two ways to add custom tools:

1. **Plugin tools** - Packaged in a plugin with a `package.json` and full `ToolDefinition`
2. **Skill-based tools** - Lightweight command dispatch defined in a `SKILL.md` file

## Plugin Tool (Full SDK)

Create a plugin with a tool definition:

```typescript theme={null}
// my-plugin/src/tools/weather.ts
import { z } from 'zod';
import type { ToolDefinition, ToolResult, ToolExecutionContext } from 'profclaw/sdk';

const WeatherParamsSchema = z.object({
  city: z.string().describe('City name'),
  units: z.enum(['celsius', 'fahrenheit']).optional().default('celsius'),
});

export const weatherTool: ToolDefinition = {
  name: 'get_weather',
  description: 'Get current weather for a city.',
  category: 'custom',
  securityLevel: 'safe',
  parameters: WeatherParamsSchema,

  async execute(
    context: ToolExecutionContext,
    params: z.infer<typeof WeatherParamsSchema>
  ): Promise<ToolResult> {
    const response = await fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${params.city}`
    );
    const data = await response.json();
    return {
      success: true,
      output: `${params.city}: ${data.main.temp}°, ${data.weather[0].description}`,
    };
  },
};
```

Register it in your plugin's `index.ts`:

```typescript theme={null}
import type { PluginContext } from 'profclaw/sdk';
import { weatherTool } from './tools/weather.js';

export function activate(ctx: PluginContext): void {
  ctx.tools.register(weatherTool);
}
```

## Tool Definition Structure

<ParamField type="string">
  Unique tool name. Use `snake_case`. Must not conflict with built-in tool names.
</ParamField>

<ParamField type="string">
  Description shown to the AI model. Be specific about when to use this tool and what it returns.
</ParamField>

<ParamField type="string">
  Category: `execution`, `filesystem`, `web`, `data`, `system`, `profclaw`, `memory`, `browser`, `custom`.
</ParamField>

<ParamField type="string">
  Security level: `safe`, `moderate`, `dangerous`. Affects approval requirements.
</ParamField>

<ParamField type="ZodSchema">
  Zod schema for parameter validation. Fields with `.describe()` become parameter descriptions for the AI.
</ParamField>

<ParamField type="function">
  Async function `(context, params) => Promise<ToolResult>`. Receives a `ToolExecutionContext` with workdir, security policy, and session manager.
</ParamField>

<ParamField type="string">
  Which model tier receives this tool: `essential`, `standard`, `full`.
</ParamField>

<ParamField type="function">
  Optional availability check. Return `{ available: false, reason: "..." }` to hide the tool when its dependencies aren't configured.
</ParamField>

<ParamField type="boolean">
  Force approval requests regardless of security mode.
</ParamField>

<ParamField type="object">
  Rate limit config: `{ maxCalls: 10, windowMs: 60000 }`.
</ParamField>

## ToolResult Format

Your `execute` function must return a `ToolResult`:

```typescript theme={null}
// Success
return {
  success: true,
  data: { /* structured data for the model */ },
  output: "Human-readable summary shown to the model",
};

// Error
return {
  success: false,
  error: {
    code: 'FETCH_ERROR',
    message: 'Could not connect to weather API',
    retryable: true,
  },
};
```

## ToolExecutionContext

The `context` parameter gives you access to:

```typescript theme={null}
interface ToolExecutionContext {
  toolCallId: string;      // Unique ID for this call
  conversationId: string;  // Current conversation
  userId?: string;         // Authenticated user if any
  workdir: string;         // Working directory
  env: Record<string, string>; // Allowed environment vars
  securityPolicy: SecurityPolicy; // Active security policy
  signal?: AbortSignal;    // Cancellation signal
  sessionManager: SessionManager; // Session CRUD
}
```

## Skill-Based Command Dispatch

For simpler cases, you can define a command in a `SKILL.md` file that dispatches to an existing tool:

```yaml theme={null}
---
name: my-command
description: My custom slash command
command-dispatch: tool
command-tool: exec
command-arg-mode: raw
---

Run my custom script with the provided arguments.
```

When a user types `/my-command arg1 arg2`, it calls `exec` with the raw args as the command.

## Tool Tier Assignment

Custom tools default to the `full` tier. To make your tool available to smaller models, set a lower tier:

```typescript theme={null}
export const myTool: ToolDefinition = {
  name: 'my_simple_tool',
  tier: 'standard', // Available to 14B+ models
  // ...
};
```

## Testing Custom Tools

```typescript theme={null}
import { describe, it, expect } from 'vitest';
import { weatherTool } from './tools/weather.js';

describe('get_weather', () => {
  it('returns weather for a valid city', async () => {
    const ctx = createMockContext({ workdir: '/tmp' });
    const result = await weatherTool.execute(ctx, { city: 'London' });
    expect(result.success).toBe(true);
    expect(result.output).toContain('London');
  });
});
```

## Related Docs

<CardGroup>
  <Card title="Plugin SDK" icon="code" href="/plugins/sdk">
    Full plugin development guide.
  </Card>

  <Card title="Creating Skills" icon="book" href="/skills/creating-skills">
    Lighter-weight skill-based commands.
  </Card>
</CardGroup>


# File Operations
Source: https://docs.profclaw.ai/tools/file-operations

Read, write, edit, search, and navigate files and directories. All operations validated by FsGuard.

## Overview

File operation tools give the agent read and write access to your filesystem within the configured allowed paths. Every operation passes through `FsGuard` - a path normalization and allowlist guard that prevents path traversal attacks and blocks access to sensitive files like `.env`, SSH keys, and system credentials.

## Tools

### `read_file`

Read content from a file. Supports text and binary (base64) output and partial reads by line range.

**Security level**: `safe` | **Tier**: Essential

<ParamField type="string">
  File path to read. Can be relative (resolved against workdir) or absolute.
</ParamField>

<ParamField type="string">
  Output encoding. Options: `utf-8`, `base64`.
</ParamField>

<ParamField type="number">
  Maximum lines to read from the start (or from `offset`).
</ParamField>

<ParamField type="number">
  Start reading from this line number (0-indexed).
</ParamField>

<CodeGroup>
  ```json Read entire file theme={null}
  {
    "path": "src/server.ts"
  }
  ```

  ```json Read first 100 lines of a log theme={null}
  {
    "path": "app.log",
    "lines": 100
  }
  ```

  ```json Read lines 50-80 theme={null}
  {
    "path": "src/queue.ts",
    "offset": 50,
    "lines": 30
  }
  ```
</CodeGroup>

**Limits**: Files over 10MB are rejected. Blocked paths include `/etc/passwd`, `/etc/shadow`, `~/.ssh`, `~/.gnupg`, `.env*`.

***

### `write_file`

Write content to a file. Creates new files or overwrites existing ones.

**Security level**: `moderate` | **Tier**: Essential

<ParamField type="string">
  File path to write.
</ParamField>

<ParamField type="string">
  Content to write.
</ParamField>

<ParamField type="boolean">
  Append to end of file instead of overwriting.
</ParamField>

<ParamField type="boolean">
  Create parent directories if they do not exist.
</ParamField>

<CodeGroup>
  ```json Write a new file theme={null}
  {
    "path": "src/utils/helpers.ts",
    "content": "export function clamp(n: number, min: number, max: number) {\n  return Math.max(min, Math.min(max, n));\n}\n"
  }
  ```

  ```json Append to a log file theme={null}
  {
    "path": "debug.log",
    "content": "[2026-03-12] Server restarted\n",
    "append": true
  }
  ```
</CodeGroup>

***

### `edit_file`

Surgical find-and-replace in a file. Far more efficient than rewriting entire files - only changes what's needed.

**Security level**: `moderate` | **Tier**: Essential

<ParamField type="string">
  File path to edit.
</ParamField>

<ParamField type="string">
  Exact string to find. Must be unique in the file unless `replace_all` is true.
</ParamField>

<ParamField type="string">
  Replacement string.
</ParamField>

<ParamField type="boolean">
  Replace all occurrences instead of just the first.
</ParamField>

<CodeGroup>
  ```json Fix a typo theme={null}
  {
    "path": "src/index.ts",
    "old_string": "cosnt handler",
    "new_string": "const handler"
  }
  ```

  ```json Replace all occurrences theme={null}
  {
    "path": "src/config.ts",
    "old_string": "localhost",
    "new_string": "0.0.0.0",
    "replace_all": true
  }
  ```
</CodeGroup>

Returns a diff snippet showing the change. Fails with `AMBIGUOUS_MATCH` if `old_string` appears multiple times without `replace_all`.

***

### `search_files`

Find files using glob patterns.

**Security level**: `safe` | **Tier**: Essential

<ParamField type="string">
  Glob pattern (e.g., `**/*.ts`, `src/**/*.test.ts`).
</ParamField>

<ParamField type="string">
  Base directory to search from. Defaults to workdir.
</ParamField>

<ParamField type="number">
  Maximum files to return.
</ParamField>

Automatically ignores `node_modules/`, `.git/`, `dist/`, `build/`.

***

### `grep`

Search file contents using regex patterns.

**Security level**: `safe` | **Tier**: Essential

<ParamField type="string">
  Regex pattern to search for (case-insensitive by default).
</ParamField>

<ParamField type="string">
  File or directory to search. Defaults to workdir.
</ParamField>

<ParamField type="string">
  Glob filter for files (e.g., `**/*.ts`).
</ParamField>

<ParamField type="number">
  Maximum matches to return.
</ParamField>

<ParamField type="number">
  Lines of context to include around each match.
</ParamField>

Returns matches as `file:line: content` format.

***

### `directory_tree`

Show the directory structure as a tree.

**Security level**: `safe` | **Tier**: Essential

<ParamField type="string">
  Root directory.
</ParamField>

<ParamField type="number">
  Maximum depth to traverse (1-10).
</ParamField>

<ParamField type="boolean">
  Include files, not just directories.
</ParamField>

<ParamField type="string">
  Show only entries matching this glob (e.g., `*.ts`).
</ParamField>

Auto-skips: `node_modules`, `.git`, `dist`, `build`, `coverage`, `.next`, `__pycache__`, `.venv`.

***

### `patch_apply`

Apply a unified diff patch to a file.

**Security level**: `moderate` | **Tier**: Standard

<ParamField type="string">
  File to patch.
</ParamField>

<ParamField type="string">
  Unified diff content (standard `git diff` or `diff -u` format).
</ParamField>

<ParamField type="boolean">
  Apply patch in reverse (undo a patch).
</ParamField>

## Related Tools

<CardGroup>
  <Card title="Git Operations" icon="code-branch" href="/tools/git-operations">
    Stage and commit file changes with git tools.
  </Card>

  <Card title="Code Analysis" icon="magnifying-glass" href="/tools/code-analysis">
    Lint and type-check after editing files.
  </Card>
</CardGroup>


# Git Operations
Source: https://docs.profclaw.ai/tools/git-operations

Status, diff, log, commit, branch, stash, and remote operations. Requires git to be installed.

## Overview

Git tools let the agent inspect and modify version control state. All tools check for git availability at startup and report a helpful error if git is not installed. Operations run in the conversation's `workdir`, or a custom path you specify.

<Note>
  Git tools are config-gated: they check for `git` binary availability at startup and mark themselves unavailable if git is not found. This prevents confusing errors when profClaw runs in containers without git.
</Note>

## Tools

### `git_status`

Show working tree status.

**Security level**: `safe` | **Tier**: Essential

<ParamField type="string">
  Repository path. Defaults to workdir.
</ParamField>

<ParamField type="boolean">
  Show short format output.
</ParamField>

```json theme={null}
{ "path": "/home/user/my-project" }
```

***

### `git_diff`

Show changes between commits, working tree, and staging area.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Repository path.
</ParamField>

<ParamField type="string">
  Diff a specific file only.
</ParamField>

<ParamField type="boolean">
  Show staged (cached) changes.
</ParamField>

<ParamField type="string">
  Compare against a specific commit hash or ref.
</ParamField>

<CodeGroup>
  ```json Show unstaged changes theme={null}
  { "staged": false }
  ```

  ```json Show staged changes for one file theme={null}
  {
    "file": "src/server.ts",
    "staged": true
  }
  ```

  ```json Diff against a commit theme={null}
  {
    "commit": "HEAD~3"
  }
  ```
</CodeGroup>

***

### `git_log`

Show commit history.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Repository path.
</ParamField>

<ParamField type="number">
  Number of commits to show.
</ParamField>

<ParamField type="boolean">
  Show one-line format (hash + subject).
</ParamField>

<ParamField type="string">
  Filter commits by author name or email.
</ParamField>

<ParamField type="string">
  Show commits since a date (e.g., `"2 weeks ago"`, `"2026-01-01"`).
</ParamField>

***

### `git_commit`

Stage and commit changes.

**Security level**: `moderate` | **Tier**: Standard

<ParamField type="string">
  Commit message.
</ParamField>

<ParamField type="string">
  Repository path.
</ParamField>

<ParamField type="boolean">
  Stage all modified tracked files (`git commit -a`).
</ParamField>

<ParamField type="boolean">
  Amend the previous commit.
</ParamField>

<CodeGroup>
  ```json Commit staged files theme={null}
  {
    "message": "feat: add exponential backoff to retry logic"
  }
  ```

  ```json Stage all and commit theme={null}
  {
    "message": "fix: correct null check in queue handler",
    "all": true
  }
  ```
</CodeGroup>

<Warning>
  Amending commits that have already been pushed to a shared branch will require a force push, which is dangerous. Use with caution.
</Warning>

***

### `git_branch`

List, create, delete, or checkout branches.

**Security level**: `moderate` | **Tier**: Standard

<ParamField type="string">
  Repository path.
</ParamField>

<ParamField type="boolean">
  List all local branches.
</ParamField>

<ParamField type="string">
  Create a new branch with this name.
</ParamField>

<ParamField type="string">
  Delete a branch by name.
</ParamField>

<ParamField type="string">
  Switch to a branch by name.
</ParamField>

<CodeGroup>
  ```json List branches theme={null}
  { "list": true }
  ```

  ```json Create and checkout a feature branch theme={null}
  {
    "create": "feat/webhook-retry",
    "checkout": "feat/webhook-retry"
  }
  ```
</CodeGroup>

***

### `git_stash`

Manage the git stash.

**Security level**: `moderate` | **Tier**: Full

<ParamField type="string">
  Action to perform: `push`, `pop`, `list`, `show`, `drop`, `clear`.
</ParamField>

<ParamField type="string">
  Stash description (for `push` action).
</ParamField>

<ParamField type="number">
  Stash index for `pop`, `show`, or `drop`.
</ParamField>

<ParamField type="string">
  Repository path.
</ParamField>

***

### `git_remote`

Fetch, pull, or push to a remote.

**Security level**: `moderate` | **Tier**: Full

<ParamField type="string">
  Remote action: `fetch`, `pull`, `push`.
</ParamField>

<ParamField type="string">
  Remote name.
</ParamField>

<ParamField type="string">
  Branch name.
</ParamField>

<ParamField type="boolean">
  Force push. Use with extreme caution - never against protected branches.
</ParamField>

## Safety Rules

The git tools follow these safety rules automatically:

* `git_remote` with `force: true` will warn before executing
* The `git_commit` tool never commits `.env`, `*.key`, or `*.pem` files
* Branch deletions require an explicit `delete` parameter - no accidental deletes

## Related Tools

<CardGroup>
  <Card title="File Operations" icon="folder" href="/tools/file-operations">
    Edit files before staging and committing.
  </Card>

  <Card title="Test Runner" icon="flask" href="/tools/test-runner">
    Run tests before committing changes.
  </Card>
</CardGroup>


# Memory Tools
Source: https://docs.profclaw.ai/tools/memory

Semantic search and retrieval over MEMORY.md, memory files, and chat history using hybrid vector + full-text search.

## Overview

Memory tools let the agent recall past conversations, decisions, and preferences stored in memory files. The memory system indexes `MEMORY.md`, all files under `memory/*.md`, and recent chat history. Searches use a **hybrid approach** combining vector similarity (semantic) and full-text search (BM25) for best results.

<Tip>
  The `memory_search` tool description tells the AI it is a "mandatory recall step" - the model is instructed to search memory before answering questions about prior work, dates, people, or preferences.
</Tip>

## Tools

### `memory_search`

Semantically search memory files and chat history.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Natural language search query. Describe what you are looking for, not just keywords.
</ParamField>

<ParamField type="number">
  Maximum results to return (1-20).
</ParamField>

<ParamField type="number">
  Minimum relevance score threshold (0.0-1.0). Lower values return more results but may include irrelevant matches.
</ParamField>

<ParamField type="string">
  Filter by source: `all`, `memory` (files only), `chat` (conversations only), `custom`.
</ParamField>

<CodeGroup>
  ```json Search for prior decisions theme={null}
  {
    "query": "API authentication decisions",
    "maxResults": 5
  }
  ```

  ```json Find user preferences theme={null}
  {
    "query": "user preferences for notifications and alerts"
  }
  ```

  ```json Recall recent work theme={null}
  {
    "query": "changes made to login flow last week",
    "source": "chat"
  }
  ```
</CodeGroup>

**Response format:**

```json theme={null}
{
  "query": "API authentication decisions",
  "results": [
    {
      "path": "memory/architecture.md",
      "lines": "42-56",
      "text": "Decided to use JWT with 15-minute expiry...",
      "score": 0.87,
      "source": "memory"
    }
  ],
  "totalFound": 3,
  "method": "hybrid",
  "stats": {
    "totalFiles": 12,
    "totalChunks": 847
  }
}
```

***

### `memory_get`

Read a specific section from a memory file by path and line range.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Path to the memory file (e.g., `memory/decisions.md`).
</ParamField>

<ParamField type="string">
  Line range to read, in the format returned by `memory_search` (e.g., `"42-56"`).
</ParamField>

Use this after `memory_search` returns a match - read the full context around the matched snippet.

***

### `memory_stats`

Show memory system statistics.

**Security level**: `safe` | **Tier**: Standard

Returns: total indexed files, total chunks, last indexed timestamp, and available memory sources.

## Memory File Locations

| Source     | Path          | Description                               |
| ---------- | ------------- | ----------------------------------------- |
| Primary    | `MEMORY.md`   | Main memory file in project root          |
| Memory dir | `memory/*.md` | Additional memory files                   |
| Chat       | Internal DB   | Indexed conversation history              |
| Custom     | Configurable  | Extra directories via `memory.extraPaths` |

## Writing to Memory

Memory tools only read - they do not write. To save information to memory, use `write_file` or `edit_file` to update `MEMORY.md` directly:

```
write_file(
  path: "MEMORY.md",
  content: "\n## Decision: Auth Strategy\nDecided on JWT with refresh tokens...",
  append: true
)
```

The memory watcher picks up file changes and re-indexes automatically (debounced at 2 seconds).

## Memory Isolation

Each conversation operates within an `IsolationContext` that restricts which memory paths are accessible. In multi-user setups, different users see different memory namespaces. Shared project memory is accessible to all sessions that share a `projectId`.

## Related Tools

<CardGroup>
  <Card title="File Operations" icon="folder" href="/tools/file-operations">
    Read and write memory files directly.
  </Card>

  <Card title="Sessions" icon="window" href="/tools/sessions">
    Share memory context across spawned sessions.
  </Card>
</CardGroup>


# Notifications
Source: https://docs.profclaw.ai/tools/notifications

profClaw notification tools - send native OS notifications, read and write the clipboard, capture screenshots, and trigger Slack, Discord, and Telegram actions from agents.

## Overview

Integration tools let the agent interact with the host system beyond the filesystem: send native OS notifications, read/write the clipboard, and capture screenshots. These tools are in the **Full tier** and primarily useful for desktop deployments.

## Tools

### `notify`

Send a native operating system notification.

**Security level**: `moderate` | **Tier**: Standard

<ParamField type="string">
  Notification title.
</ParamField>

<ParamField type="string">
  Notification body text.
</ParamField>

<ParamField type="boolean">
  Play the system notification sound.
</ParamField>

<ParamField type="string">
  Urgency level: `low`, `normal`, `critical`. Affects display priority on Linux.
</ParamField>

<CodeGroup>
  ```json Simple notification theme={null}
  {
    "title": "Build Complete",
    "body": "Your TypeScript build finished successfully.",
    "sound": true
  }
  ```

  ```json Critical alert theme={null}
  {
    "title": "Test Failures",
    "body": "3 tests failed in src/queue/. Review required.",
    "urgency": "critical"
  }
  ```
</CodeGroup>

Platform support: macOS (via `osascript`), Linux (via `notify-send`), Windows (via PowerShell toast).

***

### `screen_capture`

Capture a screenshot of the entire screen or a specific region.

**Security level**: `moderate` | **Tier**: Full

<ParamField type="object">
  Capture region: `{ x, y, width, height }`. Omit for full screen.
</ParamField>

<ParamField type="number">
  Display index for multi-monitor setups.
</ParamField>

Returns the screenshot as a base64-encoded PNG.

<Note>
  On macOS, screen capture requires Screen Recording permission in System Settings > Privacy & Security.
</Note>

***

### `clipboard_read`

Read the current clipboard contents.

**Security level**: `moderate` | **Tier**: Full

<ParamField type="string">
  Content format: `text`, `image`.
</ParamField>

Returns the clipboard text or a base64 PNG for image content.

***

### `clipboard_write`

Write text to the clipboard.

**Security level**: `moderate` | **Tier**: Full

<ParamField type="string">
  Text to write to the clipboard.
</ParamField>

***

### Channel-Specific Notification Tools

For sending messages through chat channels rather than system notifications, profClaw provides channel-specific action tools:

#### `slack_actions`

Send messages, react to messages, or create channels in Slack.

**Tier**: Full | Requires: Slack provider configured

<ParamField type="string">
  Action type: `send_message`, `react`, `create_channel`.
</ParamField>

<ParamField type="string">
  Channel ID or name.
</ParamField>

<ParamField type="string">
  Message text.
</ParamField>

#### `discord_actions`

Send messages or create threads in Discord.

**Tier**: Full | Requires: Discord provider configured

#### `telegram_actions`

Send messages, photos, or documents via Telegram.

**Tier**: Full | Requires: Telegram provider configured

## Async Notification Pattern

Notifications from background jobs should be dispatched asynchronously to avoid blocking:

```typescript theme={null}
// In a tool or plugin
// Do NOT block waiting for notification delivery
void notify({ title: "Job complete", body: result.summary });
```

## Related Tools

<CardGroup>
  <Card title="Browser Tools" icon="browser" href="/tools/browser-tools">
    Take browser screenshots instead of system screenshots.
  </Card>

  <Card title="Sessions" icon="window" href="/tools/sessions">
    Send results back to parent sessions rather than system notifications.
  </Card>
</CardGroup>


# Tools Overview
Source: https://docs.profclaw.ai/tools/overview

77+ built-in tools across filesystem, git, web, browser, memory, sessions, cron, and more. Covers tool tiers, execution pipeline, security levels, and model-aware routing.

## What Are Tools?

Tools are functions the AI agent can call during a conversation. When you ask profClaw to read a file, run tests, or search the web, the AI emits a structured tool call. The execution engine validates it against the security policy, runs it, and returns the result back to the model.

profClaw ships 77+ built-in tools organized into **tiers** - essential tools work reliably with any model including small local models, while advanced tools require frontier models to use effectively.

## Tool Tiers

<Tabs>
  <Tab title="Essential (10 tools)">
    Core tools that work reliably with any model, including small local models like Qwen 7B.

    | Tool             | Category   | Description                                  |
    | ---------------- | ---------- | -------------------------------------------- |
    | `read_file`      | filesystem | Read file contents with optional line ranges |
    | `write_file`     | filesystem | Write or append to files                     |
    | `edit_file`      | filesystem | Surgical find-and-replace in files           |
    | `exec`           | execution  | Run shell commands                           |
    | `grep`           | filesystem | Regex search across file contents            |
    | `search_files`   | filesystem | Find files by glob pattern                   |
    | `directory_tree` | filesystem | Show project structure                       |
    | `git_status`     | git        | Show working tree status                     |
    | `web_fetch`      | web        | Fetch URL content as text                    |
    | `complete_task`  | profclaw   | Mark a task as complete                      |
  </Tab>

  <Tab title="Standard (25 tools)">
    Tools that need moderate reasoning ability - suitable for 14B+ local models or any cloud model.

    Includes all Essential tools plus: `git_diff`, `git_log`, `git_commit`, `git_branch`, `patch_apply`, `web_search`, `memory_search`, `memory_get`, `memory_stats`, `env`, `system_info`, `path_info`, `which`, `create_ticket`, `list_tickets`, `update_ticket`, `get_ticket`, `create_project`, `list_projects`, `test_run`, `image_analyze`, `link_understand`, `github_pr`, `notify`
  </Tab>

  <Tab title="Full (77+ tools)">
    All tools. Sent only to large frontier models (Claude, GPT-4o, Gemini 1.5+) that can reliably select the right tool from a large set.

    Includes Standard plus: browser automation (8 tools), cron management (7 tools), session spawning (4+ tools), integrations (4 tools), media generation (3 tools), channel-specific actions, subagent orchestration, canvas rendering, and maintenance utilities.
  </Tab>
</Tabs>

## Tool Categories

<CardGroup>
  <Card title="Filesystem" icon="folder" href="/tools/file-operations">
    Read, write, edit, search files and directories. Path-traversal safe with FsGuard.
  </Card>

  <Card title="Git" icon="code-branch" href="/tools/git-operations">
    Status, diff, commit, branch, stash, push, and pull operations.
  </Card>

  <Card title="Web Fetch" icon="globe" href="/tools/web-fetch">
    Fetch URLs, call APIs, convert HTML to text. SSRF-protected.
  </Card>

  <Card title="Web Search" icon="magnifying-glass" href="/tools/web-search">
    Search via Brave, Serper, SearXNG, or Tavily. Config-gated.
  </Card>

  <Card title="Browser" icon="browser" href="/tools/browser-tools">
    Puppeteer-based automation: navigate, click, type, screenshot, extract.
  </Card>

  <Card title="Memory" icon="brain" href="/tools/memory">
    Hybrid vector + full-text search over MEMORY.md and conversation history.
  </Card>

  <Card title="profClaw Ops" icon="ticket" href="/tools/profclaw-ops">
    Create and manage tickets and projects directly from chat.
  </Card>

  <Card title="Sessions" icon="window" href="/tools/sessions">
    Spawn, send messages to, and coordinate multi-agent sessions.
  </Card>

  <Card title="Test Runner" icon="flask" href="/tools/test-runner">
    Auto-detect and run vitest, jest, pytest, go test, and more.
  </Card>

  <Card title="Cron" icon="clock" href="/tools/cron-tools">
    Schedule HTTP webhooks, tool calls, or shell scripts on a cron expression.
  </Card>

  <Card title="Notifications" icon="bell" href="/tools/notifications">
    System notifications, clipboard access, and screen capture.
  </Card>

  <Card title="Custom Tools" icon="wrench" href="/tools/custom-tools">
    Register your own tools via plugins or the TypeScript SDK.
  </Card>
</CardGroup>

## How Tool Execution Works

<Steps>
  <Step title="Model emits a tool call">
    The AI model outputs a structured JSON tool call containing the tool name and parameter values.
  </Step>

  <Step title="Schema validation">
    Parameters are parsed through the tool's Zod schema. Invalid parameters return an error immediately without execution - the model receives the validation error and can retry with corrected values.
  </Step>

  <Step title="Security check">
    The active [security mode](/security/overview) is evaluated: mode level, allowlist, and approval requirements. Dangerous tools require explicit user approval in `ask` mode.
  </Step>

  <Step title="Execution">
    The tool executor runs. Long-running tools can stream progress updates back to the conversation. Tools that exceed `POOL_TIMEOUT_MS` (default: 5 minutes) are cancelled.
  </Step>

  <Step title="Result returned">
    The tool result (success or structured error) is appended to the conversation context. The model continues reasoning with the new information and may call additional tools.
  </Step>
</Steps>

## Security Levels

Each tool declares a security level that determines behavior across different security modes:

| Level       | Description                             | Behavior in `standard` mode     |
| ----------- | --------------------------------------- | ------------------------------- |
| `safe`      | Read-only, no side effects              | Always allowed                  |
| `moderate`  | Write operations, network requests      | Allowed without prompt          |
| `dangerous` | Shell exec, destructive file operations | Requires approval in `ask` mode |

See [Security Overview](/security/overview) for how security modes interact with tool execution.

## Model-Aware Tool Routing

profClaw automatically selects the right tool tier based on which model is active. Small local models receive only Essential tools to avoid context overload and unreliable tool selection. Frontier models receive the full set.

```
Local model (Qwen 7B)       → Essential tier  (10 tools)
Medium model (Mistral 14B)  → Standard tier   (25 tools)
Frontier (Claude, GPT-4o)   → Full tier       (77+ tools)
```

<Tip>
  Override model-aware routing for a specific tool by adding it to the `promote` list in your settings. This forces the tool into smaller model contexts regardless of tier:

  ```yaml theme={null}
  # settings.yml
  tools:
    promote:
      - browser_navigate
      - web_search
  ```
</Tip>

## Custom Tools

Add your own tools via the plugin system. A custom tool requires:

1. A Zod schema defining input parameters
2. An async `execute` function returning a result
3. A security level declaration

See [Custom Tools](/tools/custom-tools) and [Plugins Overview](/plugins/overview) for implementation details.

## Related

* [Security Overview](/security/overview) - How security modes control tool execution and approval
* [profclaw tools](/cli/tools) - List and directly execute tools from the CLI
* [AI Providers Overview](/ai-providers/overview) - Model-aware tier routing depends on the active provider
* [Plugins Overview](/plugins/overview) - Extend profClaw with custom tools via plugins


# profClaw Ops Tools
Source: https://docs.profclaw.ai/tools/profclaw-ops

profClaw Ops tools - let agents create and manage tickets and projects from within a chat session. Built-in task board operations without leaving the conversation.

## Overview

profClaw Ops tools let the agent read and write profClaw's own data: tickets, projects. This means you can ask the agent "create a ticket for this bug" or "what tickets are open in the backend project?" and it will interact with your task board directly.

These tools are **config-gated** - they check for an initialized database at startup and mark themselves unavailable if the storage layer is not initialized.

## Tools

### `create_ticket`

Create a new ticket in a project.

**Security level**: `moderate` | **Tier**: Standard

<ParamField type="string">
  Project key prefix (e.g., `"PC"` for profClaw, `"BE"` for backend).
</ParamField>

<ParamField type="string">
  Ticket title - a concise description of the work.
</ParamField>

<ParamField type="string">
  Detailed description with context, acceptance criteria, or steps to reproduce.
</ParamField>

<ParamField type="string">
  Ticket type: `task`, `bug`, `story`, `epic`, `subtask`, `feature`, `improvement`.
</ParamField>

<ParamField type="string">
  Priority: `critical`, `high`, `medium`, `low`, `none`.
</ParamField>

<ParamField type="array">
  String array of labels/tags to apply.
</ParamField>

<ParamField type="number">
  Story points estimate for sprint planning.
</ParamField>

<CodeGroup>
  ```json Create a bug ticket theme={null}
  {
    "projectKey": "PC",
    "title": "Memory search returns stale results after file edit",
    "description": "After editing MEMORY.md, search results still show old content for ~30s",
    "type": "bug",
    "priority": "high",
    "labels": ["memory", "performance"]
  }
  ```

  ```json Create a feature ticket theme={null}
  {
    "projectKey": "PC",
    "title": "Add Matrix channel provider",
    "type": "feature",
    "priority": "medium",
    "storyPoints": 8
  }
  ```
</CodeGroup>

***

### `list_tickets`

List tickets with optional filtering.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Filter by project key.
</ParamField>

<ParamField type="string">
  Filter by status: `open`, `in_progress`, `review`, `done`, `cancelled`.
</ParamField>

<ParamField type="string">
  Filter by priority.
</ParamField>

<ParamField type="string">
  Filter by assignee ID.
</ParamField>

<ParamField type="string">
  Filter by label.
</ParamField>

<ParamField type="number">
  Maximum tickets to return.
</ParamField>

***

### `get_ticket`

Get full details for a single ticket.

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  Ticket ID (e.g., `"PC-42"`).
</ParamField>

***

### `update_ticket`

Update fields on an existing ticket.

**Security level**: `moderate` | **Tier**: Standard

<ParamField type="string">
  Ticket ID to update.
</ParamField>

<ParamField type="string">
  New status value.
</ParamField>

<ParamField type="string">
  New priority.
</ParamField>

<ParamField type="string">
  Updated title.
</ParamField>

<ParamField type="string">
  Updated description.
</ParamField>

<ParamField type="string">
  Assign to a user by ID.
</ParamField>

<ParamField type="array">
  Replace all labels with this new array.
</ParamField>

***

### `create_project`

Create a new project.

**Security level**: `moderate` | **Tier**: Standard

<ParamField type="string">
  Project name.
</ParamField>

<ParamField type="string">
  2-10 character key prefix used in ticket IDs (e.g., `"PC"`). Must be unique.
</ParamField>

<ParamField type="string">
  Project description.
</ParamField>

<ParamField type="string">
  Emoji icon for the project (e.g., `"rocket"`).
</ParamField>

<ParamField type="string">
  Hex color code (e.g., `"#6366f1"`).
</ParamField>

***

### `list_projects`

List all projects.

**Security level**: `safe` | **Tier**: Standard

Returns all projects with their key, name, description, and ticket counts.

## Example Workflow

Ask profClaw in chat:

> "We found a bug in the auth flow - tokens aren't being refreshed. Create a critical bug ticket in the PC project."

The agent will call `create_ticket` with the details extracted from your message and return the ticket ID.

> "What bugs are currently open in PC with high or critical priority?"

The agent will call `list_tickets` with the appropriate filters.

## Related Tools

<CardGroup>
  <Card title="Sessions" icon="window" href="/tools/sessions">
    Spawn sessions linked to specific tickets for focused work.
  </Card>

  <Card title="Cron Tools" icon="clock" href="/tools/cron-tools">
    Schedule recurring ticket creation or status checks.
  </Card>
</CardGroup>


# Sessions
Source: https://docs.profclaw.ai/tools/sessions

Spawn, coordinate, and communicate between multi-agent sessions.

## Overview

Session tools enable multi-agent orchestration. One agent can spawn a child session, send it a task, and check back on its progress - enabling parallel workstreams and specialized sub-agents.

profClaw has two sets of session tools:

* **Sessions tools** (`sessions_*`) - manage conversation sessions as persistent chat threads
* **Session spawn tools** (`spawn_session`, `send_message`, etc.) - hierarchical agent-to-agent communication

## Sessions Tools

### `sessions_spawn`

Spawn a new chat session with an optional initial task.

**Security level**: `moderate` | **Tier**: Full

<ParamField type="string">
  Title for the new session. Auto-generated from the task if not provided.
</ParamField>

<ParamField type="string">
  Initial task or message to send to the new session.
</ParamField>

<ParamField type="string">
  Skill preset for the session: `profclaw-assistant`, `code-assistant`, `git-workflow`, etc.
</ParamField>

<ParamField type="string">
  Link this session to a project.
</ParamField>

<ParamField type="string">
  Link this session to a specific ticket for focused work.
</ParamField>

<ParamField type="string">
  Session mode: `chat` (conversational) or `agentic` (autonomous execution).
</ParamField>

<ParamField type="object">
  Additional key-value metadata to attach to the session.
</ParamField>

```json theme={null}
{
  "title": "Refactor auth module",
  "task": "Analyze src/auth/ and suggest a refactoring plan to split it into smaller modules",
  "presetId": "code-assistant",
  "mode": "agentic",
  "ticketId": "PC-88"
}
```

***

### `sessions_list`

List active or recent sessions.

**Security level**: `safe` | **Tier**: Full

<ParamField type="string">
  Filter by status: `active`, `idle`, `completed`.
</ParamField>

<ParamField type="string">
  Filter by project.
</ParamField>

<ParamField type="number">
  Maximum sessions to return.
</ParamField>

***

### `sessions_send`

Send a message to an existing session.

**Security level**: `moderate` | **Tier**: Full

<ParamField type="string">
  Target session ID.
</ParamField>

<ParamField type="string">
  Message to send.
</ParamField>

***

### `session_status`

Get the current status and model of an active session.

**Security level**: `safe` | **Tier**: Full

<ParamField type="string">
  Session ID. Defaults to the current session.
</ParamField>

## Hierarchical Agent Tools

These tools are used by an orchestrator agent to spawn and coordinate worker agents.

### `spawn_session`

Spawn a dedicated worker agent session.

<ParamField type="string">
  Name for the worker session.
</ParamField>

<ParamField type="string">
  System-level instructions for the worker.
</ParamField>

<ParamField type="string">
  Override the AI model for this worker (useful for routing cheap tasks to smaller models).
</ParamField>

***

### `send_message`

Send a message to a spawned worker and await a response.

<ParamField type="string">
  Worker session ID returned by `spawn_session`.
</ParamField>

<ParamField type="string">
  Task or message to send.
</ParamField>

<ParamField type="number">
  Maximum time to wait for a response in milliseconds.
</ParamField>

***

### `receive_messages`

Poll for new messages from a worker session without blocking.

***

### `list_sessions`

List all spawned worker sessions from the current conversation.

## Multi-Agent Patterns

<Tabs>
  <Tab title="Parallel Research">
    Spawn multiple agents to research different topics simultaneously, then synthesize:

    ```
    1. spawn_session("researcher-1") - "Research Hono middleware patterns"
    2. spawn_session("researcher-2") - "Research BullMQ queue patterns"
    3. send_message("researcher-1", "find best practices")
    4. send_message("researcher-2", "find best practices")
    5. receive_messages from both
    6. Synthesize results
    ```
  </Tab>

  <Tab title="Code + Review Pipeline">
    Separate code generation from review:

    ```
    1. spawn_session("coder") - "You write TypeScript"
    2. spawn_session("reviewer") - "You review TypeScript code"
    3. send_message("coder", "implement auth middleware")
    4. send_message("reviewer", result from coder)
    5. Apply reviewer feedback
    ```
  </Tab>
</Tabs>

## Related Tools

<CardGroup>
  <Card title="profClaw Ops" icon="ticket" href="/tools/profclaw-ops">
    Link sessions to tickets for focused work.
  </Card>

  <Card title="Memory" icon="brain" href="/tools/memory">
    Share knowledge across sessions via memory files.
  </Card>
</CardGroup>


# Test Runner
Source: https://docs.profclaw.ai/tools/test-runner

Auto-detect and run tests with structured output showing pass/fail counts and failure locations.

## Overview

`test_run` auto-detects the test framework from your project configuration and runs tests with structured output. Instead of raw terminal output, it returns parsed results: pass/fail/skip counts, failure details with `file:line` locations, and optionally coverage data.

Supported frameworks: **vitest**, **jest**, **pytest**, **go test**, **cargo test**, **mocha**, **jasmine**, and more.

## Tool: `test_run`

**Security level**: `moderate` | **Tier**: Standard

<ParamField type="string">
  Override the auto-detected test command. Leave blank to use auto-detection.
</ParamField>

<ParamField type="string">
  Run tests only in a specific file.
</ParamField>

<ParamField type="string">
  Filter by test name pattern. Passes `--grep` to vitest/jest or `-k` to pytest.
</ParamField>

<ParamField type="boolean">
  Enable code coverage reporting.
</ParamField>

## Examples

<CodeGroup>
  ```json Run all tests theme={null}
  {}
  ```

  ```json Run tests in one file theme={null}
  {
    "file": "src/queue/task-queue.test.ts"
  }
  ```

  ```json Run tests matching a pattern theme={null}
  {
    "grep": "auth"
  }
  ```

  ```json Run with coverage theme={null}
  {
    "coverage": true
  }
  ```

  ```json Override the command theme={null}
  {
    "command": "pnpm test --reporter=verbose"
  }
  ```
</CodeGroup>

## Response Format

```json theme={null}
{
  "success": true,
  "data": {
    "framework": "vitest",
    "passed": 42,
    "failed": 2,
    "skipped": 3,
    "total": 47,
    "durationMs": 3241,
    "failures": [
      {
        "name": "queue > retries exhausted > should emit failed event",
        "file": "src/queue/task-queue.test.ts",
        "line": 88,
        "message": "Expected 'failed' to equal 'error'"
      }
    ],
    "coverage": null
  }
}
```

## Framework Auto-Detection

The tool checks for the following config files in order:

| Config File                             | Framework  |
| --------------------------------------- | ---------- |
| `vitest.config.ts` / `vitest.config.js` | vitest     |
| `jest.config.ts` / `jest.config.js`     | jest       |
| `pytest.ini` / `pyproject.toml`         | pytest     |
| `go.mod`                                | go test    |
| `Cargo.toml`                            | cargo test |
| `package.json` with `"jest"` key        | jest       |
| `package.json` with `"vitest"` key      | vitest     |

## Timeouts

Tests are limited to **2 minutes** (120,000ms) by default. Long-running integration test suites should use the `command` override to set a higher timeout:

```json theme={null}
{
  "command": "pnpm vitest run --testTimeout=300000"
}
```

## Output Truncation

Raw test output is capped at **200,000 characters**. For very large test suites, use the `file` or `grep` parameters to narrow down which tests to run.

## Related Tools

<CardGroup>
  <Card title="File Operations" icon="folder" href="/tools/file-operations">
    Read test files to understand what they test before running.
  </Card>

  <Card title="Code Analysis" icon="magnifying-glass" href="/tools/code-analysis">
    Lint and type-check in addition to running tests.
  </Card>
</CardGroup>


# Web Fetch
Source: https://docs.profclaw.ai/tools/web-fetch

Fetch URLs, call REST APIs, and retrieve web content. Protected by SSRF Guard.

## Overview

`web_fetch` lets the agent make outbound HTTP requests. It supports all common HTTP methods, custom headers, request bodies, and can optionally extract readable text from HTML pages.

Every request passes through `SsrfGuard` before execution - a defense layer that blocks private IP ranges, cloud metadata endpoints, and DNS rebinding attacks.

## Tool: `web_fetch`

**Security level**: `moderate` | **Tier**: Essential

<ParamField type="string">
  Full URL to fetch. Must be a valid `http://` or `https://` URL.
</ParamField>

<ParamField type="string">
  HTTP method: `GET`, `POST`, `PUT`, `DELETE`.
</ParamField>

<ParamField type="object">
  Custom request headers as key-value pairs.
</ParamField>

<ParamField type="string">
  Request body for `POST` or `PUT`. Typically JSON-encoded.
</ParamField>

<ParamField type="number">
  Request timeout in seconds. Maximum enforced by server policy.
</ParamField>

<ParamField type="boolean">
  Extract readable text content from HTML pages (strips tags, navigation, scripts).
</ParamField>

## Examples

<CodeGroup>
  ```json Fetch a documentation page as text theme={null}
  {
    "url": "https://docs.example.com/api",
    "extractText": true
  }
  ```

  ```json Call a JSON API theme={null}
  {
    "url": "https://api.github.com/repos/profclaw/profclaw",
    "headers": {
      "Accept": "application/vnd.github.v3+json"
    }
  }
  ```

  ```json POST to a webhook theme={null}
  {
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "method": "POST",
    "headers": { "Content-Type": "application/json" },
    "body": "{\"text\": \"Build completed successfully\"}"
  }
  ```

  ```json Fetch with authentication theme={null}
  {
    "url": "https://api.example.com/v1/status",
    "headers": {
      "Authorization": "Bearer eyJhbGci..."
    }
  }
  ```
</CodeGroup>

## Response

A successful fetch returns:

```json theme={null}
{
  "success": true,
  "data": {
    "url": "https://api.example.com/status",
    "status": 200,
    "contentType": "application/json",
    "body": "{ \"status\": \"ok\" }",
    "bodyLength": 16
  }
}
```

## Content Limits

Responses are capped at **500KB**. Larger responses are truncated. For large downloads, consider fetching a specific resource path rather than a whole page.

## SSRF Protection

The `SsrfGuard` blocks requests to:

| Category         | Examples                                                     |
| ---------------- | ------------------------------------------------------------ |
| Loopback         | `127.0.0.1`, `::1`, `localhost`                              |
| Private networks | `10.x.x.x`, `172.16-31.x.x`, `192.168.x.x`                   |
| Link-local       | `169.254.x.x` (includes cloud metadata at `169.254.169.254`) |
| Cloud metadata   | `metadata.google.internal`, `metadata.internal`              |
| Reserved ranges  | RFC 1918 + all IANA special-use ranges                       |

The guard resolves DNS before connecting to defend against DNS rebinding attacks. Redirect chains are re-validated at each hop, up to 5 redirects.

<Tip>
  To allow specific internal hosts (e.g., for self-hosted integrations), add them to `security.ssrfGuard.allowedHosts` in your `settings.yml`.
</Tip>

## Allowed Hosts Setting

```yaml theme={null}
security:
  ssrfGuard:
    enabled: true
    allowedHosts:
      - "internal-api.company.local"
      - "jenkins.internal"
```

## Related Tools

<CardGroup>
  <Card title="Web Search" icon="magnifying-glass" href="/tools/web-search">
    Search the web instead of fetching a specific URL.
  </Card>

  <Card title="Browser Tools" icon="browser" href="/tools/browser-tools">
    Interact with JavaScript-rendered pages using a real browser.
  </Card>
</CardGroup>


# Web Search
Source: https://docs.profclaw.ai/tools/web-search

Search the web using Brave, Serper, SearXNG, or Tavily. Requires API key configuration.

## Overview

`web_search` lets the agent query a search engine and get back a ranked list of results with titles, URLs, and snippets. This is useful for current events, recent documentation, or researching topics the model may not know about.

The tool is **config-gated** - it checks for a configured search provider at startup and marks itself unavailable if none is found. This prevents the model from attempting searches that will always fail.

## Supported Providers

<Tabs>
  <Tab title="Brave Search">
    Privacy-focused search engine with a dedicated API.

    ```yaml theme={null}
    # settings.yml
    integrations:
      webSearch:
        provider: brave
        apiKey: "BSA-xxxxxxxxxxxx"
    ```

    Get your key at [brave.com/search/api](https://brave.com/search/api/).
  </Tab>

  <Tab title="Serper">
    Google search results via the Serper API.

    ```yaml theme={null}
    integrations:
      webSearch:
        provider: serper
        apiKey: "your-serper-key"
    ```

    Get your key at [serper.dev](https://serper.dev/).
  </Tab>

  <Tab title="SearXNG">
    Self-hosted meta-search engine. No API key required.

    ```yaml theme={null}
    integrations:
      webSearch:
        provider: searxng
        baseUrl: "https://your-searxng-instance.com"
    ```
  </Tab>

  <Tab title="Tavily">
    AI-optimized search API with clean result extraction.

    ```yaml theme={null}
    integrations:
      webSearch:
        provider: tavily
        apiKey: "tvly-xxxxxxxxxxxx"
    ```

    Get your key at [tavily.com](https://tavily.com/).
  </Tab>
</Tabs>

## Tool: `web_search`

**Security level**: `safe` | **Tier**: Standard

<ParamField type="string">
  The search query. Be specific - use terms like "site:docs.example.com" to scope searches.
</ParamField>

<ParamField type="number">
  Number of results to return. Range: 1-20.
</ParamField>

## Examples

<CodeGroup>
  ```json General search theme={null}
  {
    "query": "Hono middleware error handling TypeScript 2026",
    "count": 5
  }
  ```

  ```json Search documentation theme={null}
  {
    "query": "site:docs.anthropic.com tool use streaming",
    "count": 10
  }
  ```

  ```json Research a topic theme={null}
  {
    "query": "BullMQ job progress tracking patterns",
    "count": 8
  }
  ```
</CodeGroup>

## Response Format

```json theme={null}
{
  "success": true,
  "data": {
    "query": "Hono middleware error handling",
    "provider": "brave",
    "results": [
      {
        "title": "Error Handling - Hono",
        "url": "https://hono.dev/guides/error-handling",
        "snippet": "Hono has built-in error handling middleware..."
      }
    ],
    "totalResults": 5
  }
}
```

## Checking Availability

You can check the current search configuration from the CLI:

```bash theme={null}
profclaw config show --section integrations.webSearch
```

Or from within a conversation, the model can check availability programmatically before attempting a search.

## Related Tools

<CardGroup>
  <Card title="Web Fetch" icon="globe" href="/tools/web-fetch">
    Fetch a specific URL once you have found it via search.
  </Card>

  <Card title="Browser Tools" icon="browser" href="/tools/browser-tools">
    Browse pages that require JavaScript execution.
  </Card>
</CardGroup>