### Run FastClaw for First Time

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Starts FastClaw in foreground mode, initiating a setup wizard to configure LLM providers and create a default agent. Use `fastclaw daemon start` for background operation or `fastclaw daemon install` to set up a system service.

```bash
fastclaw
```

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

### Run Multi-pod Setup with Docker Compose

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/deploy/multi-pod/README.md

Use this command to build and start the multi-pod environment, including Postgres, MinIO, and two gateway pods. The initial build may take a few minutes.

```bash
docker compose -f deploy/multi-pod/docker-compose.yaml up --build
```

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

### Setup Camoufox Browser with CLI

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/commands.md

Install the Camoufox browser and its dependencies. Use '--with-deps' on Linux to include system libraries.

```bash
camoufox-cli install                 # Download Camoufox browser
```

```bash
camoufox-cli install --with-deps     # Download browser + system libs (Linux)
```

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

### Run FastClaw Gateway

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Starts the FastClaw gateway in the foreground on http://localhost:18953. A setup wizard will automatically open on a fresh install if no users exist.

```bash
fastclaw
# or explicitly:
fastclaw gateway --port 18953
```

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

### Configure Multi-pod Postgres + S3 Deployment

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Example environment variables for setting up a multi-pod deployment using PostgreSQL for storage and S3 for object storage. The gateway is then started with these configurations.

```bash
# Multi-pod Postgres + S3 deployment
export FASTCLAW_BIND=all
export FASTCLAW_STORAGE_TYPE=postgres
export FASTCLAW_STORAGE_DSN="postgres://user:pass@host:5432/fastclaw?sslmode=disable"
export FASTCLAW_OBJECT_STORE_ENDPOINT=s3.amazonaws.com
export FASTCLAW_OBJECT_STORE_BUCKET=fastclaw-skills
fastclaw
```

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

### Build the Proxy

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/tools/openclaw-plugin-bridge/README.md

Navigate to the proxy directory and install dependencies, then build the project.

```bash
cd tools/openclaw-proxy
pnpm install && pnpm build
```

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

### Install and Run Node.js

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/skills/code-runner/SKILL.md

Install Node.js and npm if they are not available using package managers like `apt-get` or `apk`. Then, execute JavaScript code using `node -e` for one-liners.

```bash
# Install node if not available
apt-get update && apt-get install -y nodejs npm 2>/dev/null || apk add nodejs npm 2>/dev/null
node -e "console.log('hello')"
```

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

### List Installed Skills

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Displays a list of all skills currently installed, including their source and a brief description.

```bash
fastclaw skill list
```

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

### Snapshot Output Example

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/snapshot-refs.md

Example of the structured output from the snapshot command, showing elements and their assigned refs.

```text
- heading "Example Domain" [ref=e1]
- navigation
  - link "Home" [ref=e2]
  - link "Products" [ref=e3]
  - link "About" [ref=e4]
- button "Sign In" [ref=e5]
- main
  - heading "Welcome" [ref=e6]
  - textbox "Email" [ref=e7]
  - textbox "Password" [ref=e8]
  - button "Log In" [ref=e9]
- contentinfo
  - link "Privacy Policy" [ref=e10]
```

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

### Skill Installation

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Endpoint for installing skills from ClawHub or GitHub.

```APIDOC
## POST /api/skills/install

### Description
Installs a skill from a specified source, such as ClawHub or GitHub.

### Method
POST

### Endpoint
/api/skills/install

### Parameters
#### Request Body
- **source** (string) - Required - The source of the skill (e.g., 'clawhub', 'github').
- **name** (string) - Required - The name of the skill.
- **url** (string) - Optional - The URL of the skill repository if the source is GitHub.
```

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

### Start Fastclaw Docker Deployment

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Navigate to the Docker deployment directory and execute the start script to launch Fastclaw services.

```bash
cd deploy/docker && ./start.sh
```

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

### Initialize a Fastclaw Agent

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Initialize a new agent with specified provider, model, and API key. This command also starts the gateway if it's not running and creates an admin user on a fresh install.

```bash
fastclaw agents init alpha \
  --provider openai \
  --model openai/gpt-4o-mini \
  --api-key-env OPENAI_API_KEY

```

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

### Install FastClaw CLI

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Installs the FastClaw command-line interface. This command downloads and executes an installation script that places the binary in ~/.local/bin and ensures it's added to your system's PATH.

```bash
curl -fsSL https://raw.githubusercontent.com/fastclaw-ai/fastclaw/main/install.sh | bash
```

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

### Install, Update, and Remove Skills

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Manage skills by installing from the registry, updating existing ones, or removing them. You can install specific versions or update all skills at once.

```bash
fastclaw skill install image-gen
```

```bash
fastclaw skill install image-gen --version 1.1.0
```

```bash
fastclaw skill update image-gen
```

```bash
fastclaw skill update --all
```

```bash
fastclaw skill remove image-gen
```

```bash
fastclaw skill info image-gen
```

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

### Example Response When No Skills Are Found

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/find-skills/SKILL.md

This example shows how the agent responds when no relevant skills are found for a query. It offers direct assistance and suggests creating a new skill.

```text
I searched for skills related to "xyz" but didn't find any matches.
I can still help you with this task directly! Would you like me to proceed?

If this is something you do often, you could create your own skill:
npx skills init my-xyz-skill
```

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

### Build FastClaw from Source

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Commands to build the FastClaw binary and web bundle, install it locally, or create local release artifacts.

```bash
make build           # builds web bundle + Go binary → bin/fastclaw
make install         # installs to ~/.local/bin (PREFIX= to override)
make release-local   # cross-compile darwin/linux/windows → dist/
```

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

### Ref Lifecycle Example

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/snapshot-refs.md

Demonstrates the need to re-snapshot after page changes to obtain valid refs for new elements.

```bash
# Get initial snapshot
camoufox-cli snapshot -i
# - button "Next" [ref=e1]

# Click triggers page change
camoufox-cli click @e1

# MUST re-snapshot to get new refs!
camoufox-cli snapshot -i
# - heading "Page 2" [ref=e1]  <- Different element now!
```

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

### Example Commit Message Format

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/skill-creator/SKILL.md

Format examples using this markdown structure, especially when input and output are distinct.

```markdown
## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication
```

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

### Install FastClaw using Helm

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Install FastClaw via Helm, specifying storage DSN and bind address as configuration values.

```bash
helm install fastclaw deploy/helm/fastclaw \
  --set storage.dsn="postgres://u:p@host:5432/db?sslmode=disable" \
  --set bind=all
```

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

### Launch Benchmark Viewer

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/skills/skill-creator/SKILL.md

Launch the evaluation viewer to review skill performance. This command starts a server and requires specifying the workspace, skill name, and benchmark file. For subsequent iterations, include the previous workspace.

```bash
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
  <workspace>/iteration-N \
  --skill-name "my-skill" \
  --benchmark <workspace>/iteration-N/benchmark.json \
  > /dev/null 2>&1 &
VIEWER_PID=$!
```

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

### Kubernetes Environment Variables Configuration

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Example Kubernetes environment variable configuration for Fastclaw. This setup allows for dynamic configuration via environment variables, including database connection strings and object store details.

```yaml
env:
  - name: FASTCLAW_BIND
    value: "all"
  - name: FASTCLAW_STORAGE_TYPE
    value: "postgres"
  - name: FASTCLAW_STORAGE_DSN
    valueFrom:
      secretKeyRef:
        name: fastclaw-db
        key: dsn
  - name: FASTCLAW_OBJECT_STORE_ENDPOINT
    value: "s3.amazonaws.com"
  - name: FASTCLAW_OBJECT_STORE_BUCKET
    value: "fastclaw-skills"
```

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

### SKILL.md Frontmatter and Structure

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/skills/fastclaw-skill-guide/SKILL.md

Example of the SKILL.md file format, including YAML frontmatter and markdown instructions.

```markdown
---
name: My Skill Name
description: One-line description of what this skill does and when to use it
homepage: https://example.com
metadata:
  fastclaw:
    emoji: "🔧"
    always: false
    os: ["darwin", "linux"]
    requires:
      bins: ["git"]
      anyBins: ["python3", "python"]
      env: ["API_KEY"]
    primaryEnv: "API_KEY"
---

# Skill Title

Step-by-step instructions in markdown...
```

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

### Install Arbitrary npm Package

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/find-skills/SKILL.md

When needing a bare npm package (not a skill), install it within the `/workspace` directory. Avoid global installs for non-skill packages to prevent namespace pollution and ensure persistence across container evictions.

```bash
cd /workspace && npm init -y && npm install <pkg>
```

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

### Manual Test of the Proxy

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/tools/openclaw-plugin-bridge/README.md

Send JSON-RPC requests to the proxy via stdin to test its functionality. This example sends initialization, tool listing, and tool execution requests.

```bash
# Test manually
echo '{"jsonrpc":"2.0","method":"initialize","params":{"config":{}},"id":1}
{"jsonrpc":"2.0","method":"tool.list","id":2}
{"jsonrpc":"2.0","method":"tool.execute","params":{"name":"get_weather","args":{"city":"Tokyo"}},"id":3}' \
| node proxy.js ../../examples/plugins/openclaw-demo/openclaw-plugin.js
```

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

### Search for Presentation Skills

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/find-skills/SKILL.md

Example of searching for a skill to create presentations (e.g., PPTX). The output is cleaned with `sed`.

```bash
npx skills find pptx | sed -E 's/\x1b\[[0-9;]*[a-zA-Z]//g'
```

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

### Install a Skill Globally

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/find-skills/SKILL.md

Use this command to install a skill globally within the FastClaw environment. The `-g` flag ensures the skill is available system-wide, and `-y` bypasses confirmation prompts.

```bash
npx skills add <owner/repo@skill> -g -y
```

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

### Core Browser Automation Workflow

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/SKILL.md

Demonstrates the fundamental steps for interacting with a web page: opening a URL, taking a snapshot to get element references, filling form fields, clicking a button, and taking another snapshot to verify changes. Use snapshot -i for interactive elements.

```bash
camoufox-cli open https://example.com/form
camoufox-cli snapshot -i
# Output: - textbox "Email" [ref=e1]
#         - textbox "Password" [ref=e2]
#         - button "Submit" [ref=e3]

camoufox-cli fill @e1 "user@example.com"
camoufox-cli fill @e2 "password123"
camoufox-cli click @e3
camoufox-cli snapshot -i  # Check result
```

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

### Package Skill for Distribution

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/skill-creator/SKILL.md

Package a skill folder into a .skill file. This command is only available if the `present_files` tool is accessible. After packaging, the user should be directed to the resulting .skill file path for installation.

```bash
python -m scripts.package_skill <path/to/skill-folder>
```

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

### Example Skill: PR Review

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/skills/fastclaw-skill-guide/SKILL.md

Demonstrates a complete SKILL.md for a PR review skill, including frontmatter and step-by-step instructions.

```markdown
---
name: git-pr-review
description: Review pull requests with structured feedback. Use when the user asks to review a PR, check code changes, or provide feedback on a merge request.
---

# PR Review

Review a pull request and provide structured feedback.

## Steps

1. Get the PR diff:
   ```bash
   git diff main...HEAD
   ```

2. For each changed file, check:
   - Code correctness and edge cases
   - Naming and readability
   - Test coverage

3. Output feedback in this format:
   ## Summary
   One-paragraph overview.

   ## Issues
   - **file:line** — description of issue

   ## Suggestions
   - Optional improvements
```

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

### Navigate Browser with Camoufox CLI

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/commands.md

Use these commands to control browser navigation. The 'open' command automatically prepends 'https://' if no protocol is specified and starts the daemon if necessary.

```bash
camoufox-cli open <url>              # Navigate to URL (starts daemon if needed)
                                     # Auto-prepends https:// if no protocol given
```

```bash
camoufox-cli back                    # Go back
```

```bash
camoufox-cli forward                 # Go forward
```

```bash
camoufox-cli reload                  # Reload page
```

```bash
camoufox-cli url                     # Print current URL
```

```bash
camoufox-cli title                   # Print page title
```

```bash
camoufox-cli close                   # Close browser and stop daemon
```

```bash
camoufox-cli close --all             # Close all sessions
```

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

### Search for PDF Resume Skills

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/find-skills/SKILL.md

Example of searching for a skill to create a PDF resume. ANSI color codes are removed using `sed`.

```bash
npx skills find pdf resume | sed -E 's/\x1b\[[0-9;]*[a-zA-Z]//g'
```

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

### Search for React Performance Skills

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/find-skills/SKILL.md

Example of searching for a skill related to React performance. The `sed` command cleans the output.

```bash
npx skills find react performance | sed -E 's/\x1b\[[0-9;]*[a-zA-Z]//g'
```

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

### Build Fastclaw Binary

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Makefile targets for building the Fastclaw project. Includes options for building the web bundle and Go binary, installing locally, and creating local release artifacts.

```bash
make build                  # builds the web bundle and the Go binary → bin/fastclaw
```

```bash
make install                # installs to $HOME/.local/bin (override with PREFIX=)
```

```bash
make release-local          # cross-compile darwin / linux / windows into dist/
```

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

### Camoufox CLI Timeouts for Cold Starts

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/SKILL.md

The initial `camoufox-cli open` command in a fresh sandbox can take 2-3 minutes to spin up the headless Firefox daemon. Set a higher `timeout` (e.g., 180 seconds) for this initial `exec` call to prevent the agent from killing the daemon mid-bring-up. Subsequent calls have a default timeout.

```json
// First camoufox-cli call in a fresh sandbox
{"command": "camoufox-cli open https://example.com && camoufox-cli snapshot -i", "timeout": 180}
```

```json
// Subsequent calls — default timeout is plenty
{"command": "camoufox-cli click @e5 && camoufox-cli snapshot -i"}
```

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

### Generate Skill Evaluation Queries

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/skill-creator/SKILL.md

Create a JSON array of evaluation queries to test skill triggering. Include a mix of 'should_trigger' and 'should_not_trigger' examples that are realistic and specific to user prompts.

```json
[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]
```

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

### Get and Set Agent Configuration

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Use these commands to retrieve or modify configuration settings for a specific agent. This includes model selection, sandbox settings, and provider-specific API keys.

```bash
fastclaw agents config alpha get
```

```bash
fastclaw agents config alpha get model
```

```bash
fastclaw agents config alpha set model openai/gpt-4o
```

```bash
fastclaw agents config alpha set sandbox.enabled true
```

```bash
fastclaw agents config alpha set sandbox.backend docker
```

```bash
fastclaw agents config alpha set sandbox.image fastclaw-ai/sandbox:latest
```

```bash
fastclaw agents config alpha set temperature 0.7
```

```bash
fastclaw agents config alpha set provider.openai.apiKeyEnv OPENAI_API_KEY
```

```bash
fastclaw agents config alpha set provider.anthropic.apiKeyEnv ANTHROPIC_API_KEY
```

```bash
fastclaw agents config alpha set provider.openrouter.apiBase https://openrouter.ai/api/v1
```

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

### Create Agent with OpenAI Provider

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Creates a new agent named 'alpha' using the OpenAI provider and a specified model. It automatically starts the gateway if it's not already running and uses the API key from the OPENAI_API_KEY environment variable.

```bash
# Create agent "alpha" with OpenAI provider, auto-start gateway if needed
fastclaw agents init alpha \
  --provider openai \
  --model openai/gpt-4o-mini \
  --api-key-env OPENAI_API_KEY

# Output:
# Agent "alpha" created
# Agent ID: agt_d3c4a5b6e7f8...
# Owner:    admin
# Provider: saved
# Model:    saved (agent scope)
# URL:      http://localhost:18953
```

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

### Launch Benchmark Viewer (Headless)

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/skills/skill-creator/SKILL.md

Generate a static HTML file for the evaluation viewer in headless environments. Use the --static flag to output to a specified path. Feedback will be saved to feedback.json.

```bash
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
  <workspace>/iteration-N \
  --skill-name "my-skill" \
  --benchmark <workspace>/iteration-N/benchmark.json \
  --static <output_path> \
  > /dev/null 2>&1 &
VIEWER_PID=$!
```

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

### Initialize and Render - JavaScript

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/skill-creator/eval-viewer/viewer.html

Calls the initialization function and then the renderBenchmark function to display the evaluation viewer content.

```javascript
init();
renderBenchmark();
```

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

### Interactive Snapshot Output Example

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/snapshot-refs.md

Example of the output from an interactive snapshot (-i), which filters out non-interactive elements.

```text
- link "Home" [ref=e1]
- link "Products" [ref=e2]
- link "About" [ref=e3]
- button "Sign In" [ref=e4]
- textbox "Email" [ref=e5]
- textbox "Password" [ref=e6]
- button "Log In" [ref=e7]
- link "Privacy Policy" [ref=e8]
```

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

### Create Agent on Pod A, List on Pod B

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/deploy/multi-pod/README.md

This snippet demonstrates creating a new agent via pod A and then verifying its existence by listing agents from pod B. This tests the shared database for agent information.

```bash
curl -sX POST -H "Authorization: Bearer dev-admin-token" \
     -H "Content-Type: application/json" \
     -d '{"id":"test-alpha","model":"ollama/qwen3.5:35b-a3b-int4"}' \
     http://localhost:18953/api/agents

# Pod B sees it (may need a moment — hot-reload is async):
curl -s -H "Authorization: Bearer dev-admin-token" \
     http://localhost:18954/api/agents | jq '.[].id'
```

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

### Organizing Skills by Domain

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/skill-creator/SKILL.md

Demonstrates how to organize skills that support multiple domains or frameworks by creating separate reference files for each variant.

```tree
cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```

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

### Run Python 3 Script

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/skills/code-runner/SKILL.md

For more complex Python scripts, write the code to a file (e.g., `script.py`) and then execute it using `python3 script.py`. Packages can be installed using `pip install package_name`.

```bash
python3 script.py
```

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

### Initializing a New Skill

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/find-skills/SKILL.md

Use this command to initialize a new skill. This is useful when no existing skills match your needs.

```bash
npx skills init my-xyz-skill
```

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

### Skills Management API

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Manage skills, including listing, searching, installing, and deleting them.

```APIDOC
## REST API: Skills Management

### List all installed + bundled skills
```bash
curl http://localhost:18953/api/skills
```

### Search ClawHub registry
```bash
curl -b cookies.txt "http://localhost:18953/api/skills/search?q=web+scraping"
```

### Install a skill from ClawHub (globally shared)
```bash
curl -b cookies.txt -X POST http://localhost:18953/api/skills/install \
  -H "Content-Type: application/json" \
  -d '{"slug":"camoufox-cli","version":"latest"}'
```

### Install from GitHub URL
```bash
curl -b cookies.txt -X POST http://localhost:18953/api/skills/install \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/my-org/my-skill"}'
```

### List skills for a specific agent
```bash
curl -b cookies.txt http://localhost:18953/api/agents/agt_d3c4a5/skills
```

### Delete global skill (admin only)
```bash
curl -b cookies.txt -X DELETE http://localhost:18953/api/skills/camoufox-cli
```

### Delete agent-private skill
```bash
curl -b cookies.txt -X DELETE http://localhost:18953/api/agents/agt_d3c4a5/skills/my-private-skill
```
```

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

### Get Chat History for a Session

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Fetches the chat history for a given agent and session.

```bash
curl -b cookies.txt "http://localhost:18953/api/chat/history?agent=agt_abc&session=sess-abc"
```

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

### Create a ReAct Agent with agent.NewAgent

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Use `agent.NewAgent` to create a ReAct agent from a resolved configuration. For production, `agent.NewAgentWithFullCfg` is recommended for enhanced features like auto-persisting memory and PII scrubbing.

```go
import (
    "github.com/fastclaw-ai/fastclaw/internal/agent"
    "github.com/fastclaw-ai/fastclaw/internal/bus"
    "github.com/fastclaw-ai/fastclaw/internal/config"
    "github.com/fastclaw-ai/fastclaw/internal/provider"
)

mb := &bus.MessageBus{
    Inbound:  make(chan bus.InboundMessage, 100),
    Outbound: make(chan bus.OutboundMessage, 100),
}

rc := config.ResolvedAgent{
    ID:               "agt_myagent",
    Model:            "openai/gpt-4o",
    Home:             "/home/user/.fastclaw/agents/agt_myagent/agent",
    Workspace:        "/home/user/.fastclaw/workspaces/agt_myagent",
    MaxTokens:        8192,
    Temperature:      0.7,
    MaxToolIterations: 30,
}

prov := provider.NewProvider("sk-proj-...", "https://api.openai.com/v1", "openai")
homeDir := "/home/user/.fastclaw"

ag := agent.NewAgent(rc, prov, mb, homeDir)
```

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

### Direct Interaction with Refs

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/snapshot-refs.md

Examples of using camoufox-cli commands to interact with elements directly using their assigned refs.

```bash
# Click the "Sign In" button
camoufox-cli click @e4
```

```bash
# Fill email input
camoufox-cli fill @e5 "user@example.com"
```

```bash
# Fill password
camoufox-cli fill @e6 "password123"
```

```bash
# Submit the form
camoufox-cli click @e7
```

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

### Best Practice: Wait Before Snapshot

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/snapshot-refs.md

Allows slow-loading content to render before taking a snapshot, ensuring all elements are captured.

```bash
camoufox-cli open https://slow-site.com
camoufox-cli wait 3000            # Wait for content to load
camoufox-cli snapshot -i          # Now snapshot
```

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

### Basic Snapshot Command

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/snapshot-refs.md

Generates a full page structure snapshot. Use this to see all elements and their initial refs.

```bash
camoufox-cli snapshot
```

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

### Launch Evaluation Viewer

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/skill-creator/SKILL.md

Launch the evaluation viewer script to review skill performance. This script requires the workspace path, skill name, and benchmark file. Additional arguments can be passed for previous iterations or static output.

```bash
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
  <workspace>/iteration-N \
  --skill-name "my-skill" \
  --benchmark <workspace>/iteration-N/benchmark.json \
  > /dev/null 2>&1 &
VIEWER_PID=$!
```

```bash
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
  <workspace>/iteration-N \
  --skill-name "my-skill" \
  --benchmark <workspace>/iteration-N/benchmark.json \
  --previous-workspace <workspace>/iteration-<N-1> \
  > /dev/null 2>&1 &
VIEWER_PID=$!
```

```bash
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
  <workspace>/iteration-N \
  --skill-name "my-skill" \
  --benchmark <workspace>/iteration-N/benchmark.json \
  --static <output_path> \
  > /dev/null 2>&1 &
VIEWER_PID=$!
```

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

### Essential Commands - Navigation

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/SKILL.md

Commands for navigating web pages, including opening URLs, going back/forward, reloading, and getting current URL/title.

```APIDOC
## Essential Commands

### Navigation
```bash
camoufox-cli open <url>              # Navigate to URL (starts daemon if needed)
camoufox-cli back                    # Go back
camoufox-cli forward                 # Go forward
camoufox-cli reload                  # Reload page
camoufox-cli url                     # Print current URL
camoufox-cli title                   # Print page title
camoufox-cli close                   # Close browser and stop daemon
camoufox-cli close --all             # Close all sessions
```
```

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

### Manage Skills via REST API

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

These commands manage skills, including listing, searching ClawHub, installing from ClawHub or GitHub, and deleting skills.

```bash
# List all installed + bundled skills
curl http://localhost:18953/api/skills
```

```bash
# Search ClawHub registry
curl -b cookies.txt "http://localhost:18953/api/skills/search?q=web+scraping"
```

```bash
# Install a skill from ClawHub (globally shared)
curl -b cookies.txt -X POST http://localhost:18953/api/skills/install \
  -H "Content-Type: application/json" \
  -d '{"slug":"camoufox-cli","version":"latest"}'
```

```bash
# Install from GitHub URL
curl -b cookies.txt -X POST http://localhost:18953/api/skills/install \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/my-org/my-skill"}'
```

```bash
# List skills for a specific agent
curl -b cookies.txt http://localhost:18953/api/agents/agt_d3c4a5/skills
```

```bash
# Delete global skill (admin only)
curl -b cookies.txt -X DELETE http://localhost:18953/api/skills/camoufox-cli
```

```bash
# Delete agent-private skill
curl -b cookies.txt -X DELETE http://localhost:18953/api/agents/agt_d3c4a5/skills/my-private-skill
```

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

### Deploy FastClaw with Docker Compose

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Use this command to start FastClaw and its dependencies (Postgres, shared volume) in detached mode. The gateway will be accessible at http://localhost:18953.

```bash
cd deploy/docker && docker compose up -d
# Gateway: http://localhost:18953
```

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

### Best Practice: Re-snapshot After Navigation

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/snapshot-refs.md

Crucial for maintaining accurate refs after navigating to a new page or after form submissions.

```bash
camoufox-cli click @e5            # Navigates to new page
camoufox-cli snapshot -i          # Get new refs
camoufox-cli click @e1            # Use new refs
```

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

### Best Practice: Snapshot Before Interaction

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/camoufox-cli/references/snapshot-refs.md

Ensures refs are available before attempting to interact with elements. Avoids 'Ref not found' errors.

```bash
# CORRECT
camoufox-cli open https://example.com
camoufox-cli snapshot -i          # Get refs first
camoufox-cli click @e1            # Use ref

# WRONG
camoufox-cli open https://example.com
camoufox-cli click @e1            # Ref doesn't exist yet!
```

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

### FastClaw Daemon Management

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Commands for managing the FastClaw background daemon, including starting, stopping, checking status, viewing logs, and installing/uninstalling as an OS service.

```bash
fastclaw daemon start --port 18953   # start background daemon
fastclaw daemon status               # Status: running, PID: 12345, Uptime: 3h22m
fastclaw daemon stop                 # stop
fastclaw daemon restart              # stop + start
fastclaw daemon logs -f -n 100       # tail daemon.log
fastclaw daemon install              # register as launchd / systemd service
fastclaw daemon uninstall            # remove OS service
```

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

### Start Fastclaw Gateway

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Use these commands to manage the Fastclaw gateway service. The `fastclaw` command runs it in the foreground, while `fastclaw daemon` commands manage it in the background.

```bash
fastclaw

```

```bash
fastclaw daemon start

```

```bash
fastclaw daemon status

```

```bash
fastclaw daemon stop

```

```bash
fastclaw daemon install

```

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

### agent.NewAgent

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Creates a ReAct agent from a resolved configuration. For production use, it's recommended to use `agent.NewAgentWithFullCfg` for a more complete setup including memory, PII scrubbing, and more.

```APIDOC
## `agent.NewAgent` — Create an agent

Creates a ReAct agent from a resolved config. For production use, prefer `agent.NewAgentWithFullCfg` which wires memory auto-persist, PII scrubbing, FTS search, and skills learning.

### Usage Example

```go
import (
    "github.com/fastclaw-ai/fastclaw/internal/agent"
    "github.com/fastclaw-ai/fastclaw/internal/bus"
    "github.com/fastclaw-ai/fastclaw/internal/config"
    "github.com/fastclaw-ai/fastclaw/internal/provider"
)

mb := &bus.MessageBus{
    Inbound:  make(chan bus.InboundMessage, 100),
    Outbound: make(chan bus.OutboundMessage, 100),
}

rc := config.ResolvedAgent{
    ID:               "agt_myagent",
    Model:            "openai/gpt-4o",
    Home:             "/home/user/.fastclaw/agents/agt_myagent/agent",
    Workspace:        "/home/user/.fastclaw/workspaces/agt_myagent",
    MaxTokens:        8192,
    Temperature:      0.7,
    MaxToolIterations: 30,
}

prov := provider.NewProvider("sk-proj-...", "https://api.openai.com/v1", "openai")
homeDir := "/home/user/.fastclaw"

ag := agent.NewAgent(rc, prov, mb, homeDir)
```
```

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

### FastClaw Architecture Overview

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Illustrates the file structure and storage mechanisms used by FastClaw. The database (SQLite by default) stores most configuration and runtime data, while skills are managed on the filesystem.

```text
~/.fastclaw/
  fastclaw.db                # SQLite default — users, agents, sessions,
                             # apikeys, configs, agent_files all live here
  skills/                    # Shared skills (bundled + installed)
  agents/
    <agentId>/agent/skills/        # Agent-private skills (filesystem only)

```

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

### Manage multiple agents with agent.Manager

Source: https://context7.com/fastclaw-ai/fastclaw/llms.txt

Use `agent.Manager` to handle multiple agents, including initialization with various stores and configurations, looking up agents by ID, adding new agents, removing agents, and updating providers.

```go
import (
    "github.com/fastclaw-ai/fastclaw/internal/agent"
    "github.com/fastclaw-ai/fastclaw/internal/store"
    "github.com/fastclaw-ai/fastclaw/internal/session"
)

// Build manager with full store wiring
mgr, err := agent.NewManager(
    resolvedAgents,
    sharedProvider,
    messageBus,
    agent.WithUserID("usr_alice"),
    agent.WithSessionStore(sessionStore),
    agent.WithMemoryStore(memoryStore),
    agent.WithWorkspaceStore(workspaceStore),
    agent.WithDataStore(dataStore),
    agent.WithMeter(usageMeter),
    agent.WithGlobalSkillsCfg(globalSkillsCfg),
)

// Look up an agent
ag := mgr.AgentByID("agt_d3c4a5b6")
if ag == nil {
    log.Fatal("agent not found")
}

// Hot-add a new agent (e.g., after UI creates it)
err = mgr.AddAgent(newRC, sharedProvider, messageBus)

// Remove an agent
mgr.RemoveAgent("agt_old")

// Update provider for all agents (hot-reload on credential change)
mgr.UpdateProviderResolved(newProvider, resolvedAgents)
```

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

### Inspect Agent Status and Files

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/README.md

Commands to list all agents, retrieve agent configurations, and list files associated with a specific agent.

```bash
fastclaw agents ls
```

```bash
fastclaw agents config alpha get
```

```bash
fastclaw agents files ls alpha
```

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

### Get Download URI Utility

Source: https://github.com/fastclaw-ai/fastclaw/blob/dev/internal/agent/bundled_skills/skill-creator/eval-viewer/viewer.html

Generates a download URI for a file. It prioritizes using the data_uri if available, otherwise it constructs a base64 encoded URI for binary data.

```javascript
function getDownloadUri(file) {
  if (file.data_uri) return file.data_uri;
  if (file.data_b64) return "data:application/octet-stream;base64,";
}
```