DOCSEARCHbyAlgolia
Submit Docs

FastClaw Documentation

repository·dev·Indexed 23 days ago

https://github.com/fastclaw-ai/fastclaw

A lightweight AI Agent runtime written in Go for creating and managing multi-agent systems. FastClaw features LLM orchestration, sandboxed tool execution, memory management, and multi-channel connectivity for Telegram, Discord, and Slack. It supports stateless gateway architectures using Postgres and MinIO, per-key agent scoping, and a system for bundled and custom skills. The platform includes a web dashboard for managing agents, models, and API keys, and provides an OpenAI-compatible API for chat completions.

Tokens
50.7K
Snippets
108
Records
277
Agent score
76%

What's inside FastClaw

  1. Use the image-gen skill for visualizations

    dev

    The image-gen skill allows for the generation of images, charts, plots, and visualizations within a headless sandbox using Python. It is triggered when a user asks to draw, plot, chart, visualize data, or create images.

    Key Requirements:

    • Use the /tmp/ directory to save generated images.
    • Never use GUI-based libraries like turtle, tkinter, or pygame.
    • Always output the final image as inline base64 markdown to ensure it renders in the chat interface.
    --- 
name: image-gen
description: Generate images, charts, plots, and visualizations. Use when the user asks to draw, plot, chart, visualize data, or create images.
metadata:
  fastclaw:
    always: false
---

  2. Manage persistent identities in camoufox-cli

    dev

    By default, camoufox-cli generates a fresh random fingerprint for every launch. To maintain a consistent device identity (fingerprint, OS, canvas, and font seeds) across multiple sessions, use the --persistent [path] flag.

    When to use persistent identity

    • Account-bound tasks: When a website requires device stability to prevent flagging.
    • Parallel independent identities: When running multiple distinct personas simultaneously.
    • Cookie persistence: When standard cookie import/export is insufficient because the site also checks hardware/browser fingerprints.

    When to skip

    • One-off web scraping.
    • Quick debugging sessions.

    Important Notes

    • Resetting an identity: To reset a persistent identity, simply delete the directory specified in the [path].
    • Dynamic settings: --locale and proxy-derived geolocation/timezone are stored in the profile but are refreshed whenever you pass the flags. --proxy and --no-geoip are never stored; you must pass them with every launch.
    # Parallel identities, each with its own fingerprint + cookies
camoufox-cli --session a --persistent ~/.camoufox-cli/profiles/alice open https://app.example.com
camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob   open https://app.example.com

# Reset an identity: just remove the directory
rm -rf ~/.camoufox-cli/profiles/alice

  3. Handling JS-heavy sites and Single Page Apps (SPAs)

    dev

    On JS-heavy sites (like Google Maps or modern SPAs), the DOM body often contains the application bundle rather than the rendered UI. Using camoufox-cli text body will return large amounts of JavaScript code instead of visible text.

    Best Practice: Use camoufox-cli snapshot -i instead of text body. The snapshot -i command uses the aria tree to expose the rendered, accessible labels (e.g., business names, ratings, buttons) that are actually visible to a user.

    If the snapshot is taken before the JS has finished rendering, use wait commands to ensure the content is present before snapshotting.

    # CORRECT for SPAs
camoufox-cli open "https://www.google.com/maps/search/insurance+agent+austin+tx/"
camoufox-cli snapshot -i

  4. Core workflow for browser automation with camoufox-cli

    dev

    Browser automation with camoufox-cli follows a specific lifecycle of navigation, discovery, interaction, and cleanup. Because element references (@e1, @e2, etc.) are temporary and invalidated whenever the DOM changes or a new page loads, you must follow this pattern:

    1. Navigate: Open a URL.
    2. Snapshot: Use snapshot -i to discover interactive elements and their assigned references.
    3. Interact: Use the discovered references (e.g., @e1) to click, fill, or select.
    4. Re-snapshot: Crucial step. Always take a new snapshot after any action that changes the page (navigation, form submission, or dynamic content loading) to get fresh references.
    5. Close: Close the browser when the task is complete to prevent leaked processes.
    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

  5. Understand the Coding-Agent Project Runtime mental model

    dev

    The coding-agent runtime is a layer that allows FastClaw to scaffold projects from templates, run dev servers in long-lived sandboxes, and provide live preview URLs. It operates on a two-layer model:

    1. Project: Represents the persistent source tree (a shared workspace folder) and chat grouping. It is created by the user and persists in the projects table.
    2. Project Runtime: Represents the running instance of a project (a long-lived dev-server container + preview URL). It is booted on demand and exists in the project_runtimes table.

    A runtime is 1:1 with a project, keyed by (user_id, agent_id, project_id). Because the runtime container and the agent's sandbox bind-mount the same host directory (workspaces/<agent>/projects/<pid>/), agent file edits are instantly visible to the dev server, enabling Hot Module Replacement (HMR) without manual file syncing.

  6. How persistent identity works in camoufox-cli

    dev

    The --persistent [path] option allows you to reuse the same browser fingerprint, OS characteristics, canvas/font seeds, locale, and proxy-derived timezone/geolocation across different launches.

    All this data is stored in <path>/camoufox-cli.json. To reset your identity, simply delete the directory.

    Note: --locale will overwrite the stored locale, and --proxy will re-derive timezone/geolocation each launch, but the --proxy and --no-geoip settings themselves are not stored in the persistent profile.

  7. Understand Bundled Skills and Installation

    dev

    Bundled skills are pre-packaged capabilities that ship with the FastClaw binary. On every boot, the system runs InstallBundledSkills, which installs these skills to ~/.fastclaw/skills/.

    FastClaw also supports custom skills located in:

    • FASTCLAW_HOME/skills/ (Product-level skills)
    • Per-agent skill directories (Agent-specific skills)

    Anything placed in these directories is treated as part of the runtime's baseline capabilities.

  8. How skill discovery and loading works

    dev

    Skill Discovery Order

    Skills are discovered from multiple directories in the following precedence order (higher overrides lower):

    1. Agent workspace: {agentDir}/skills/
    2. Team: {teamDir}/skills/
    3. User installed: ~/.fastclaw/skills/
    4. OpenClaw compatible: ~/.openclaw/skills/
    5. System bundled: npm global locations
    6. Extra dirs: Configured in fastclaw.json

    Three-Level Loading (Progressive Disclosure)

    To manage context window efficiency, skills use a three-level loading strategy:

    1. Metadata (name + description): Always included in the system prompt context (~100 words).
    2. SKILL.md body: Loaded only when the agent explicitly calls the load_skill tool. It is recommended to keep this under 500 lines.
    3. Bundled resources: Files in references/ or assets/ are loaded on demand via file tools (unlimited size).

    If your SKILL.md is approaching 500 lines, move detailed content to the references/ directory and use clear pointers within the instructions.

  9. How openclaw-proxy works

    dev

    The openclaw-proxy acts as a bridge between FastClaw's JSON-RPC protocol and OpenClaw TypeScript plugins. It functions by loading an OpenClaw plugin, capturing its register() calls (such as tools and channels), and exposing them via standard input/output (stdin/stdout) using the FastClaw JSON-RPC protocol.

    Data Flow: FastClaw Gateway $\leftrightarrow$ JSON-RPC (stdin/stdout) $\leftrightarrow$ openclaw-proxy $\leftrightarrow$ OpenClaw Plugin (JS/TS)

  10. Use the Code Runner Skill

    dev

    The code-runner skill allows you to execute code in a sandbox environment using the exec tool. It is designed for running, testing, or debugging code in various programming languages. Use this skill whenever a user request implies a need for code execution.

    Key behaviors:

    • Code is executed immediately.
    • Missing packages are installed automatically without user intervention.
    • Complete output is returned to the user.
    • If execution fails, the skill is designed to analyze the error and attempt an automatic fix.
    --- 
name: code-runner
description: Execute code in multiple programming languages. Use when the user asks to run, test, or debug code in Python, JavaScript, shell, or other languages.
metadata:
  fastclaw:
    always: true
---

  11. How the Skill Creator workflow works

    dev

    The Skill Creator is designed to guide users through an iterative lifecycle of skill development. The process typically follows these stages:

    1. Decide & Draft: Define the skill's purpose and write an initial draft.
    2. Test: Create test prompts and run them using an agent with access to the new skill.
    3. Evaluate: Perform qualitative and quantitative evaluations. Use the eval-viewer/generate_review.py script to visualize results and metrics.
    4. Iterate: Rewrite the skill based on user feedback and benchmark flaws.
    5. Optimize: Once satisfied, use a skill description improver to optimize triggering accuracy.

    Users can jump into any stage of this loop depending on their current progress.

  12. How skill triggering works in Claude

    dev

    Skills are provided to Claude in an available_skills list containing their name and description. Claude decides whether to use a skill based on whether the task matches the description.

    Key behaviors to note:

    • Complexity Requirement: Claude often handles simple, one-step tasks (like "read this PDF") using its own built-in tools. It is more likely to trigger a skill for complex, multi-step, or highly specialized queries.
    • Testing Strategy: When creating evaluation queries, avoid simple requests like "read file X". Instead, use substantive queries that represent tasks where a user would clearly benefit from a specialized skill.