🦞 ClawAgents

A lean, full-stack agentic AI framework — ~2,500 LOC

ClawAgents is a production-ready agentic framework that gives LLMs the ability to read, write, and execute code — with built-in planning, memory, sandboxing, and a gateway server. It supports OpenAI GPT-5, Google Gemini, and Anthropic Claude out of the box, with a pluggable provider architecture for any LLM.

Built by extracting and unifying the best architectural patterns from OpenClaw (~5,800 files) and DeepAgents (~1,400 LOC core), ClawAgents delivers the same power at a fraction of the complexity.

Installation

pip install clawagents              # Core (OpenAI only)
pip install clawagents[gemini]      # + Google Gemini support
pip install clawagents[anthropic]   # + Anthropic Claude support
pip install clawagents[all]         # All providers + tiktoken

Version 6.8.1 — Prompt architecture and packaged-surface polish (May 2026). Adds shared prompt assembly helpers, preserves cache-boundary behavior across memory/skill injection, refreshes the OpenHarness comparison, and keeps the v6.8.0 operational surfaces plus v6.7.1 compact tool-discovery recovery and v6.7.0 security hardening. See Changelog.

New In v6.8.1

clawagents --dry-run --profile ollama --task "inspect this repo"

• Shared prompt assembly centralizes system prompt construction, lesson preambles, cache-boundary placement, and dynamic memory/skill injection in clawagents.prompts.
• Legacy hook compatibility keeps dict-shaped before_llm messages working while exposing reusable prompt helpers for downstream integrations.
• OpenHarness comparison adds HKUDS/OpenHarness as a peer in the feature matrix with conservative full/partial markers.
• Dry-run previews report provider resolution, auth readiness, inspectable tools, likely matching tools, and next actions without calling an LLM or executing tools.
• Provider profiles give stable aliases for common backends while still letting explicit create_claw_agent() parameters override profile values.
• Background task tools expose long-running command management (task_create, task_status, task_output, task_stop, task_list) through the normal tool registry.
• Plugin compatibility loading reads plugin.json / .claude-plugin/plugin.json metadata, skills, commands, hooks, and MCP server declarations without executing plugin code.
• MCP auth refresh lets agents update MCP server auth material and reconnect configured servers deliberately.

30-Second Quick Start

The fastest way to get going — scaffolds a .env, a run_agent.py starter script, and an AGENTS.md memory file:

pip install clawagents
cd ~/my-project         # any project directory
clawagents --init       # creates .env, run_agent.py, AGENTS.md

Then edit .env with your API key and run:

python run_agent.py

That's it. The generated run_agent.py includes commented-out examples for every provider (OpenAI, Gemini, Azure, Ollama, vLLM).

Where does .env go?

ClawAgents loads .env from the directory you run the command from (your current working directory). Different projects can have different configurations.

~/my-project/
├── .env              ← ClawAgents reads this when you run from ~/my-project/
├── run_agent.py
├── AGENTS.md
└── src/

Three ways to configure (in priority order, highest → lowest):

1. create_claw_agent() parameters — explicit values passed to the factory always win.
2. .env file values — loaded with override=True, so they take precedence over any pre-existing shell env vars. This is intentional: it prevents the "stale OPENAI_API_KEY exported from ~/.zshrc silently shadows the fresh key in .env" bug class.
3. Shell environment variables — used as a fallback when no .env is found, or for keys the .env doesn't define.

Where ClawAgents looks for .env (first match wins):

1. $CLAWAGENTS_ENV_FILE — explicit absolute path (handy for CI / Docker / multi-project setups).
2. ./.env — the directory you ran the command from.
3. ../.env — parent directory (monorepo-friendly).

A ready-to-use template is included in the repo:

cp .env.example .env   # then fill in your API key

Or run clawagents --init to generate one interactively.

CLI One-Liner

clawagents --task "List all Python files and summarize the project"

Minimal Python Code

import asyncio
from clawagents import create_claw_agent

async def main():
    agent = create_claw_agent("gpt-5-mini")  # or "gemini-3-flash", "llama3.1", etc.
    result = await agent.invoke("List all Python files in src/")
    print(result.result)

asyncio.run(main())

Examples

See the examples/ directory for ready-to-run scripts:

Configuration

1. Configure your environment

Create a .env file (or run clawagents --init to generate one):

PROVIDER=gemini                    # or "openai"
GEMINI_API_KEY=AIza...             # Your Gemini API key
GEMINI_MODEL=gemini-3-flash-preview
STREAMING=1
CONTEXT_WINDOW=1000000
MAX_TOKENS=8192
TEMPERATURE=0                      # Model-specific overrides apply (see below)

# Optional: RL-inspired agent improvements
CLAW_TRAJECTORY=1                  # Enable trajectory logging + scoring
CLAW_RETHINK=1                     # Enable consecutive-failure detection
CLAW_LEARN=1                       # Enable PTRL (lessons from past runs)

PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5-nano
STREAMING=1
CONTEXT_WINDOW=1000000
MAX_TOKENS=8192
TEMPERATURE=0                      # 0 for deterministic output
CLAW_TRAJECTORY=1
CLAW_RETHINK=1
CLAW_LEARN=1

2. One-line agent

from clawagents import create_claw_agent

agent = create_claw_agent("gemini-3-flash")
result = await agent.invoke("List all Python files in src/")
print(result.result)

3. With custom instructions

agent = create_claw_agent(
    "gpt-5",
    instruction="You are a senior code reviewer. Be thorough and concise."
)
result = await agent.invoke("Review this codebase and suggest improvements")

4. With trajectory logging & rethink

agent = create_claw_agent(
    "gpt-5-mini",
    trajectory=True,   # logs every turn + scores the run
    rethink=True,       # auto-injects "rethink" after 3 consecutive failures
)
result = await agent.invoke("Refactor the auth module and add tests")
# Run summary written to .clawagents/trajectories/runs.jsonl

5. With PTRL (Prompt-Time Reinforcement Learning)

agent = create_claw_agent(
    "gpt-5-mini",
    learn=True,    # enables all 3 PTRL layers (implies trajectory=True)
    rethink=True,  # enhanced rethink uses past lessons
)
result = await agent.invoke("Build the data pipeline")
# After the run: lessons extracted and saved to .clawagents/lessons.md
# Next run: lessons injected into system prompt automatically

6. With Advisor Model (smart model guides cheap model)

# GPT-5.4-nano executes, GPT-5.4 advises 2-3 times per task
agent = create_claw_agent(
    "gpt-5.4-nano",
    advisor_model="gpt-5.4",
)

# Cross-provider: Haiku executes, GPT-5.4 advises
agent = create_claw_agent(
    "claude-haiku-4-5",
    advisor_model="gpt-5.4",
    advisor_api_key="sk-...",
)

The advisor is consulted at three points: (1) after initial orientation, before committing to an approach, (2) when stuck (consecutive failures trigger rethink), and (3) before declaring the task complete. Set ADVISOR_MODEL in .env or pass advisor_model in code.

7. Multi-Sample Comparison (GRPO-inspired)

agent = create_claw_agent("gpt-5-mini", rethink=True)
# Run the task 3 times, pick the best based on objective scoring
result = await agent.compare("Fix the bug in app.py", n_samples=3)
print(result["best_result"])   # best answer
print(result["best_score"])    # objective score
print(result["all_scores"])    # all samples with scores

8. Azure OpenAI

agent = create_claw_agent(
    "gpt-4o",                    # your Azure deployment name
    api_key="your-azure-key",
    base_url="https://myresource.openai.azure.com/",
    api_version="2024-12-01-preview",
    learn=True,
)
result = await agent.invoke("Analyze the codebase")

Or via .env:

PROVIDER=openai
OPENAI_API_KEY=your-azure-key
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=https://myresource.openai.azure.com/
OPENAI_API_VERSION=2024-12-01-preview

9. AWS Bedrock (via OpenAI-compatible gateway)

Use Bedrock Access Gateway or LiteLLM proxy to expose Bedrock models as an OpenAI-compatible API:

agent = create_claw_agent(
    "anthropic.claude-3-sonnet-20240229-v1:0",
    base_url="http://localhost:8080/v1",
    api_key="bedrock",           # gateway handles AWS auth
)

Or via .env:

OPENAI_API_KEY=bedrock
OPENAI_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
OPENAI_BASE_URL=http://localhost:8080/v1

10. Local Models (Ollama / vLLM / LM Studio)

Any OpenAI-compatible local server works out of the box:

# Ollama (default port 11434)
agent = create_claw_agent("llama3.1", base_url="http://localhost:11434/v1")

# vLLM
agent = create_claw_agent("Qwen/Qwen3-8B", base_url="http://localhost:8000/v1")

# LM Studio
agent = create_claw_agent("local-model", base_url="http://localhost:1234/v1")

Or via .env:

# No API key needed for local models — just omit OPENAI_API_KEY
OPENAI_MODEL=llama3.1
OPENAI_BASE_URL=http://localhost:11434/v1

Tip: For local models that emit <think>...</think> tokens (Qwen3, DeepSeek), thinking content is automatically detected, stripped from output, and preserved in trajectory records (Feature H).

11. MCP Servers (Model Context Protocol)

Wire any external MCP server into the agent and its tools become first-class clawagents tools — no boilerplate. Three transports are supported (stdio, HTTP+SSE, Streamable HTTP):

from clawagents import create_claw_agent, MCPServerStdio

agent = create_claw_agent(
    "gpt-5-mini",
    mcp_servers=[
        MCPServerStdio(
            params={"command": "python", "args": ["-m", "my_mcp_server"]},
            name="my-mcp",
            cache_tools_list=True,
        ),
    ],
)
result = await agent.invoke("Use the my-mcp tools to do X")

Install the optional dependency once: pip install 'clawagents[mcp]'. If mcp_servers= is non-empty without the SDK installed, the factory raises a clear ImportError. The manager connects each server, lists its tools, bridges them into the existing ToolRegistry, and registers a shutdown finalizer. Every lifecycle phase (Idle → Connecting → Initializing → DiscoveringTools → Ready → Invoking → Errored / Shutdown) emits a tracing span, so MCP activity is visible in the standard tracing exporters.

For HTTP-based servers:

from clawagents import MCPServerSse, MCPServerStreamableHttp

mcp_servers = [
    MCPServerSse(params={"url": "https://example.com/mcp/sse"}),
    MCPServerStreamableHttp(params={"url": "https://example.com/mcp"}),
]

12. Browser tools

Give the agent a Playwright-backed browser. Install once: pip install 'clawagents[browser]' && playwright install chromium.

from clawagents import create_claw_agent
from clawagents.browser import create_browser_tools

agent = create_claw_agent(
    "gpt-5-mini",
    tools=create_browser_tools(),  # navigate / snapshot / click / type / screenshot / ...
)
result = await agent.invoke("Open https://example.com and summarise the page")

create_browser_tools() lazily instantiates a sandboxed BrowserSession on first use, applies SSRF + scheme checks before every navigation, and registers a shutdown hook so the headless Chromium is torn down when the agent exits. Cloud providers (Browserbase, browser-use) plug in via BrowserConfig(provider="browserbase") — see clawagents.browser.providers.get_provider().

13. Scheduled jobs / cron

Run agent prompts on a schedule. Interval (every 5m) and one-shot (@once) schedules work out of the box; cron expressions (0 9 * * *) require pip install 'clawagents[cron]'.

from clawagents import create_claw_agent, Scheduler, create_job

# Persisted to ~/.clawagents/<profile>/cron/jobs.json
create_job("Summarise overnight logs", "0 9 * * *", name="daily-summary")
create_job("Heartbeat ping", "every 5m")

async def run_prompt(job: dict) -> str:
    agent = create_claw_agent("gpt-5-nano")
    return (await agent.invoke(job["prompt"])).result

scheduler = Scheduler(runner=run_prompt)
await scheduler.start()        # poll every 30s, dispatch due jobs
# ... later ...
await scheduler.stop()

list_jobs(), pause_job(), trigger_job(), and remove_job() round out the management API. Each successful run records its output under ~/.clawagents/<profile>/cron/runs/<job_id>/<timestamp>.json so you can audit history.

14. ACP adapter

Serve a ClawAgents agent over Zed's Agent Client Protocol (JSON-RPC over stdio) so any ACP-compatible client (Zed, Cursor with ACP plugin, custom UIs) can drive the agent. Install: pip install 'clawagents[acp]'.

from clawagents import create_claw_agent, AcpServer

agent = create_claw_agent("gpt-5-mini")
AcpServer(agent=agent).serve()  # blocks on stdin/stdout until EOF

Streaming chunks (AgentMessageChunk, AgentThoughtChunk), tool-call updates, and permission prompts are all bridged to ACP SessionUpdate events. Pass permission_requester= to wire HITL approval into the host UI.

15. RL fine-tuning hooks

Capture agent runs as training-ready trajectories and export them to TRL / SLIME / Atropos / generic JSONL. The recorder works without any RL framework installed; trl and atropos are only needed when you actually drive a trainer.

from clawagents import create_claw_agent, RLRecorder
from clawagents.rl import export_jsonl

recorder = RLRecorder(task="Fix the bug in app.py", model="gpt-5-mini")
agent = create_claw_agent("gpt-5-mini", on_event=recorder.observe)
result = await agent.invoke("Fix the bug in app.py")
recorder.finalise(final=result.result, reward=1.0 if result.status == "done" else 0.0)

export_jsonl([recorder.trajectory], "runs.jsonl")

For online rollouts, swap export_jsonl for the AtroposAdapter HTTP submitter, or hand the trajectory to to_trl_sft() / to_trl_dpo() for offline SFT / DPO fine-tuning.

16. CLI

# Scaffold a project (generates .env, run_agent.py, AGENTS.md)
clawagents --init

# Check your configuration
clawagents --doctor

# Run a task directly
clawagents --task "Find all TODO comments in the codebase"

# Inspect past run trajectories
clawagents --trajectory        # last run
clawagents --trajectory 5      # last 5 runs

# Start the gateway server
clawagents --serve --port 3000

# Show all options
clawagents --help

Typical First-Time Flow

pip install clawagents           # 1. Install
clawagents --init                # 2. Scaffold .env, run_agent.py, AGENTS.md
# edit .env with your API key    # 3. Configure
clawagents --doctor              # 4. Verify setup
clawagents --task "hello world"  # 5. Run your first task
python run_agent.py              # 6. Or use the generated script

CLI Reference

🏆 Performance: ClawAgents vs Traditional Frameworks

ClawAgents v5.10 outperforms traditional multi-layer agentic frameworks through architectural simplicity. Here's how it stacks up against DeepAgents (LangGraph/LangChain-based) in head-to-head benchmarks.

Benchmark Results (February 2026)

TypeScript — 5 tasks × 2 models × 2 frameworks (20/20 ✅)

Per-Task Breakdown

Python — 18/20 completed (DeepAgents hung on GPT-5 multi_step)

* DeepAgents 0-tool results mean the model answered without using filesystem tools — faster but lower-quality (unverified answers). ClawAgents consistently uses tools to verify answers.

Why ClawAgents Wins

Traditional Stack (DeepAgents):           ClawAgents:
┌─────────────────────────┐               ┌──────────────────┐
│  Your Code              │               │  Your Code       │
├─────────────────────────┤               ├──────────────────┤
│  LangGraph              │               │  ClawAgents      │
├─────────────────────────┤               │  (direct SDK)    │
│  LangChain              │               └────────┬─────────┘
├─────────────────────────┤                        │
│  ChatOpenAI / ChatGemini│                        ▼
├─────────────────────────┤               ┌──────────────────┐
│  Responses API          │               │  Responses API   │
└─────────────────────────┘               └──────────────────┘
        4 layers                                1 layer

Feature Matrix

Compares ClawAgents v6.8.1 against four peer agent frameworks: Hermes Agent (metaspartan/hermes-agent), DeepAgents (langchain-ai/deepagents), and OpenClaw, plus OpenHarness (HKUDS/OpenHarness). The v6.8.1 prompt/packaging polish, v6.8.0 OpenHarness-inspired operational surfaces, v6.7.1 compact tool-discovery recovery, v6.7.0 security fixes, and v6.5/v6.6 Hermes-parity areas now ship together in the current release — every row in the ClawAgents column is ✅. ◐ means partial or comparable coverage rather than exact feature parity.

Architecture

Core Components

clawagents/
├── agent.py              # ClawAgent class, create_claw_agent factory
├── __main__.py            # CLI entrypoint (--init, --doctor, --task, --serve, --trajectory)
├── config/
│   ├── config.py          # EngineConfig, .env discovery, model resolution
│   └── features.py        # 15 feature flags (CLAW_FEATURE_* env vars)
├── providers/
│   ├── llm.py             # LLMProvider ABC + OpenAI/Gemini/Anthropic implementations
│   └── fallback.py        # FallbackProvider — 3-tier failover + quarantine (v6.0)
├── tools/
│   ├── registry.py        # ToolRegistry, LazyTool, parallel execution, LRU cache (v6.0)
│   ├── filesystem.py      # ls, read_file, write_file, edit_file, grep, glob
│   ├── advanced_fs.py     # tree, diff, insert_lines
│   ├── exec.py            # Shell command execution with dangerous command blocking
│   ├── subagent.py        # Sub-agent delegation with state isolation (v6.0)
│   ├── skills.py          # SKILL.md loading with constraint documents (v6.0)
│   ├── think.py           # Structured reasoning (no side effects)
│   ├── web.py             # URL fetching with HTML cleanup
│   ├── todolist.py        # write_todos, update_todo
│   ├── compose.py         # ComposeTool — deterministic multi-tool pipelines
│   ├── interactive.py     # ask_user (stdin-based)
│   ├── cache.py           # ResultCacheManager (SHA-256, TTL-based)
│   ├── validate.py        # JSON Schema param validation + lenient coercion
│   └── permissions.py     # Declarative permission rules (glob-based)
├── graph/
│   ├── agent_loop.py      # Core ReAct loop, HookResult, context management (v6.0)
│   ├── coordinator.py     # Coordinator/swarm orchestration mode
│   └── forked_agent.py    # Background forked agent pattern
├── sandbox/
│   ├── backend.py         # SandboxBackend protocol (15+ methods)
│   ├── local.py           # LocalBackend (pathlib + asyncio)
│   ├── memory.py          # InMemoryBackend (VFS for testing)
│   └── credential_proxy.py # Credential proxy for sandboxed agents (v6.0)
├── trajectory/            # RL-inspired run analysis
│   ├── recorder.py        # TrajectoryRecorder, scoring, quality grading
│   ├── lessons.py         # PTRL — post-run self-analysis + lesson injection
│   ├── verifier.py        # Deterministic verification, task-type detection
│   ├── compare.py         # GRPO-inspired multi-sample comparison
│   ├── judge.py           # LLM-as-Judge verification
│   └── background_memory.py # Continuous memory extraction
├── session/
│   ├── persistence.py     # Append-only JSONL session events
│   └── heartbeat.py       # Session heartbeat + auto-cleanup (v6.0)
├── memory/                # AGENTS.md discovery + LLM compaction
├── channels/              # Multi-channel messaging (Telegram, WhatsApp, Signal)
├── hooks/                 # External shell hook system
├── errors/                # Error taxonomy + recovery recipes
├── gateway/               # HTTP + WebSocket gateway server
├── process/               # Lane-based command queue with barriers (v6.0)
├── utils/                 # Atomic file writes (v6.0)
└── logging/               # Structured diagnostic logging

Built-in Tools

Every agent includes these — no setup needed:

Tool Examples

# The agent autonomously emits tool calls like:

# List a directory
{"tool": "ls", "args": {"path": "src/"}}
# → Returns:  drwxr-xr-x  4.0 KB  2026-02-24  components/
#             -rw-r--r--  1.2 KB  2026-02-24  main.py

# Read a file with pagination
{"tool": "read_file", "args": {"path": "src/main.py", "offset": 0, "limit": 50}}
# → Returns:  1 | import asyncio
#             2 | from clawagents import create_claw_agent
#             ...

# Write a new file (parent directories auto-created)
{"tool": "write_file", "args": {"path": "src/utils/helpers.py", "content": "def greet(name):\n    return f'Hello, {name}!'"}}
# → Returns:  ✅ Wrote 45 bytes to src/utils/helpers.py

# Edit an existing file by pattern match
{"tool": "edit_file", "args": {
    "path": "src/main.py",
    "old": "print('hello')",
    "new": "print('Hello, World!')"
}}
# → Returns:  ✅ 1 replacement made in src/main.py

# Recursive grep across all Python files
{"tool": "grep", "args": {"pattern": "TODO", "path": "src/", "include": "*.py"}}
# → Returns:  src/agent.py:42:  # TODO: add retry logic
#             src/tools/web.py:15:  # TODO: handle redirects

# Single-file search
{"tool": "grep", "args": {"pattern": "class.*Tool", "path": "src/tools/registry.py"}}
# → Returns:  15: class ToolResult:
#             24: class Tool(Protocol):

# Find files by pattern
{"tool": "glob", "args": {"pattern": "**/*.md", "path": "."}}
# → Returns:  ./README.md (15.3 KB)
#             ./docs/ARCHITECTURE.md (4.1 KB)
#             ./AGENTS.md (892 B)

# Run any shell command
{"tool": "execute", "args": {"command": "python -m pytest tests/ -v"}}
# → Returns full stdout/stderr with exit code

# With custom timeout (in milliseconds)
{"tool": "execute", "args": {"command": "pip install requests", "timeout": 60000}}

# Dangerous commands are auto-blocked
{"tool": "execute", "args": {"command": "rm -rf /"}}
# → Error: Blocked potentially destructive command

# The agent can reason without side effects
{"tool": "think", "args": {
    "thought": "The user wants me to refactor the database layer. Let me plan: 1) Read the current schema, 2) Identify coupled components, 3) Extract a repository pattern, 4) Update tests."
}}
# → [Thought recorded] — no files touched, no commands run

# Create a structured plan
{"tool": "write_todos", "args": {
    "todos": ["Read the existing codebase", "Fix the auth bug", "Add unit tests", "Update docs"]
}}
# → ## Progress: 0/4 complete
#   0. [ ] Read the existing codebase
#   1. [ ] Fix the auth bug
#   2. [ ] Add unit tests
#   3. [ ] Update docs

# Mark steps complete as you go
{"tool": "update_todo", "args": {"index": 0}}
# → ## Progress: 1/4 complete
#   0. [x] Read the existing codebase
#   1. [ ] Fix the auth bug
#   ...

# Delegate to a fresh sub-agent with isolated context
{"tool": "task", "args": {
    "description": "Analyze all Python files in src/ and create a summary of the module structure",
    "max_iterations": 10
}}
# → [Sub-agent completed: 6 tool calls, 4 iterations]
#   The src/ directory contains 3 modules: ...

# With named specialized sub-agents (configured at creation)
{"tool": "task", "args": {
    "description": "Review this pull request for security issues",
    "agent": "security-reviewer"
}}

from clawagents import create_claw_agent
from clawagents.tools.subagent import SubAgentSpec

agent = create_claw_agent(
    "gemini-3-flash",
    subagents=[
        SubAgentSpec(
            name="researcher",
            description="Deep research on a topic",
            system_prompt="You are a thorough researcher. Always cite sources.",
            max_iterations=15,
        ),
        SubAgentSpec(
            name="coder",
            description="Write and test code",
            system_prompt="You are a senior engineer. Write clean, tested code.",
            max_iterations=10,
        ),
    ],
)

# Fetch and read a web page (HTML stripped automatically)
{"tool": "web_fetch", "args": {"url": "https://docs.python.org/3/library/asyncio.html"}}
# → [200] https://docs.python.org/3/library/asyncio.html
#   asyncio — Asynchronous I/O ...

# Fetch a JSON API
{"tool": "web_fetch", "args": {"url": "https://api.github.com/repos/python/cpython", "timeout": 10}}
# → Returns raw JSON response

from clawagents import create_claw_agent, ask_user_question_tool

async def my_ui(questions):
    # Render questions with your UI of choice; return a dict keyed by header.
    return {
        q["header"]: {"question": q["question"], "answer": q["options"][0]}
        for q in questions
    }

agent = create_claw_agent("gpt-5", tools=[ask_user_question_tool(on_ask=my_ui)])

from clawagents.media.images import sanitize_image_block, sanitize_tool_output

clean_block = sanitize_image_block(block, max_dim=1200, max_bytes=5 * 1024 * 1024)
clean_output = sanitize_tool_output(tool_result_blocks)  # walks a list of content blocks

Custom Tools

Create your own tools by implementing the Tool protocol:

from clawagents import create_claw_agent
from clawagents.tools.registry import Tool, ToolResult

class DatabaseQueryTool:
    name = "query_db"
    description = "Run a read-only SQL query against the application database."
    parameters = {
        "sql": {"type": "string", "description": "The SQL SELECT query", "required": True},
        "limit": {"type": "number", "description": "Max rows to return. Default: 100"},
    }

    async def execute(self, args):
        sql = args.get("sql", "")
        limit = int(args.get("limit", 100))
        # ... your database logic here ...
        rows = await run_query(sql, limit=limit)
        return ToolResult(success=True, output=format_table(rows))

# Register custom tools alongside built-ins
agent = create_claw_agent("gpt-5", tools=[DatabaseQueryTool()])

You can also wrap LangChain tools directly:

from langchain_community.tools import WikipediaQueryRun

agent = create_claw_agent("gpt-5", tools=[WikipediaQueryRun()])
# LangChain tools are automatically adapted via LangChainToolAdapter

Skills System

Skills are reusable instruction sets that teach the agent domain-specific knowledge — without polluting the system prompt. They use a progressive disclosure pattern: the agent loads skill instructions on demand via the use_skill tool.

Skill Directory Structure

your-project/
├── skills/                  # Auto-discovered (or .skills/, skill/, .skill/, Skills/)
│   ├── code_review/
│   │   └── SKILL.md         # ← Skill defined as a folder + SKILL.md
│   ├── sql_expert.md         # ← Skill defined as a single .md file
│   └── deploy_checklist.md
├── AGENTS.md                 # Project memory (auto-injected)
└── src/
    └── ...

Writing a Skill

Every skill is a Markdown file with optional YAML frontmatter:

Example 1 — skills/code_review/SKILL.md

---
name: code_review
description: "Perform thorough code reviews following team standards"
allowed-tools: read_file grep glob think
---

# Code Review Skill

When reviewing code, follow these steps:

## 1. Structure Check
- Verify the file follows our module pattern (one class per file)
- Check imports are grouped: stdlib → third-party → local
- Ensure `__init__.py` exports are up to date

## 2. Logic Review
- Look for unhandled edge cases (empty inputs, None values)
- Verify error messages are actionable
- Check that async functions are properly awaited

## 3. Security
- No hardcoded secrets or API keys
- SQL queries use parameterized statements
- User input is sanitized before use

## 4. Output Format
Provide your review as:
- ✅ **Approved** — no issues found
- ⚠️ **Changes requested** — list specific issues with file:line references
- 🚫 **Blocked** — critical issues that must be fixed

Example 2 — skills/sql_expert.md (single-file skill)

---
name: sql_expert
description: "Write optimized SQL queries for PostgreSQL"
allowed-tools: execute read_file think
---

# SQL Expert

You are a PostgreSQL expert. When writing queries:

## Rules
1. Always use explicit `JOIN` syntax (never implicit joins in WHERE)
2. Use CTEs (`WITH` clauses) for complex multi-step queries
3. Add `EXPLAIN ANALYZE` when the user asks about performance
4. Use parameterized queries — never interpolate user values
5. Default to `LIMIT 100` unless the user specifies otherwise

## Patterns

### Pagination
Use keyset pagination for large tables:
```sql
SELECT * FROM events
WHERE id > :last_seen_id
ORDER BY id
LIMIT 50;

Aggregation

Always include the raw count alongside percentages:

SELECT
    status,
    COUNT(*) AS n,
    ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) AS pct
FROM orders
GROUP BY status
ORDER BY n DESC;

**Example 3 — `skills/deploy_checklist.md`**

```markdown
---
name: deploy_checklist
description: "Step-by-step production deployment checklist"
---

# Deployment Checklist

Before deploying to production, complete every step:

- [ ] All tests pass: `pytest tests/ -v`
- [ ] No lint errors: `ruff check src/`
- [ ] Version bumped in `pyproject.toml`
- [ ] CHANGELOG.md updated
- [ ] Docker image builds: `docker build -t app:latest .`
- [ ] Smoke test on staging environment
- [ ] Database migrations reviewed and tested
- [ ] Rollback plan documented

How Skills Work at Runtime

# Skills are auto-discovered from ./skills/ directory
agent = create_claw_agent("gemini-3-flash")

# Or specify custom skill directories
agent = create_claw_agent("gpt-5", skills=["./my-skills", "./shared-skills"])

When skills are available, the agent gets two additional tools:

# 1. List available skills
{"tool": "list_skills", "args": {}}
# → Available skills (3):
#   - **code_review**: Perform thorough code reviews following team standards
#     → Allowed tools: read_file, grep, glob, think
#   - **sql_expert**: Write optimized SQL queries for PostgreSQL
#     → Allowed tools: execute, read_file, think
#   - **deploy_checklist**: Step-by-step production deployment checklist

# 2. Load a specific skill's instructions
{"tool": "use_skill", "args": {"name": "sql_expert"}}
# → Returns the full skill content, injected into the agent's context

The agent decides on its own when to use a skill. If you ask it to "write a query to find all overdue orders," and a sql_expert skill exists, it will load the skill first, then write the query following those rules.

API Reference

create_claw_agent(model, instruction, ...)

All parameters are optional — zero-config usage (create_claw_agent()) works if you have a .env with at least one API key.

Model & Provider

Agent Behavior

LLM Tuning

PTRL & Trajectory

Priority: Explicit parameter > environment variable > default value. You never need to set both.

Hooks & Access Control

agent = create_claw_agent("gemini-3-flash", instruction="Code reviewer")

# Block dangerous tools at runtime
agent.block_tools("execute", "write_file")

# Or whitelist only safe tools
agent.allow_only_tools("read_file", "ls", "grep", "glob")

# Inject context into every LLM call
agent.inject_context("Always respond in Spanish")

# Limit tool output size
agent.truncate_output(3000)

Advanced — raw hooks:

agent.before_llm = lambda messages: messages        # modify messages before LLM
agent.before_tool = lambda name, args: True          # return False to block
agent.after_tool = lambda name, args, result: result # modify tool results

Instance Methods

Auto-Discovery

The agent factory automatically discovers project files:

Bundled Skills

ClawAgents ships with two complementary bundled skills that work together:

How they complement each other:

• ByteRover is a fast, serverless notebook for the agent. Use brv curate to persist decisions ("We chose Postgres for ACID compliance") and brv query to recall them. No infrastructure needed — context is stored as Markdown in .brv/context-tree/.
• OpenViking is a structured context database. Use ov add-resource to ingest entire repos or doc sites, then ov find for semantic search across all indexed content. Results are organized in a virtual filesystem (viking://) with three tiers: L0 (abstract, ~100 tokens), L1 (overview, ~2k tokens), L2 (full content) — the agent loads only what it needs, saving tokens.

Typical workflow: OpenViking retrieves context → agent works on the task → ByteRover curates the decisions made.

OpenViking prerequisites:

1. Install: pip install openviking --upgrade
2. Configure: create ~/.openviking/ov.conf with embedding model and VLM settings (see OpenViking docs)
3. Start server: openviking-server
4. The ov CLI must be on your PATH — the skill auto-enables when detected |

Override with explicit paths:

agent = create_claw_agent(
    "gpt-5",
    memory="./docs/AGENTS.md",
    skills=["./my-skills", "./shared-skills"]
)

Memory & Context Management

Project Memory

Loads AGENTS.md (and CLAWAGENTS.md) from the working directory and injects their content into every LLM call. Use for project-level context and conventions.

Auto-Compaction

When the conversation exceeds 75% of CONTEXT_WINDOW:

1. Full history offloaded to .clawagents/history/compacted_<ts>_<N>msgs.json
2. Older messages summarized into a single placeholder message tagged [System — Compacted History]
3. Last 20 messages kept intact

This provides unlimited conversation length with full audit trail preservation.

Gateway Server

Launch an HTTP server with one line:

from clawagents.gateway import start_gateway

start_gateway(port=3000)            # binds to 127.0.0.1 by default (loopback only)
start_gateway(port=3000, host="0.0.0.0")  # explicit LAN exposure — REQUIRES auth

Bind & auth

The gateway binds to 127.0.0.1 (loopback) by default in v6.2+. To expose it on the LAN, pass host="0.0.0.0" or set GATEWAY_HOST=0.0.0.0 (the env var wins over the host= argument), and also set GATEWAY_API_KEY=<secret> to require Bearer auth. Starting on a non-loopback address without an API key prints a loud warning at startup — anyone on the network can otherwise hit /chat, /chat/stream, and /ws.

Endpoints

Lane-Based Concurrency

4 lanes with configurable max_concurrent per lane:

• main — primary user requests
• cron — scheduled tasks
• subagent — sub-agent delegation
• nested — nested sub-agent calls

Trust Boundaries & Hardening

A few surfaces are deliberately powerful — they exist for trusted operators, and you should treat them as such when running ClawAgents in environments with untrusted prompts or LAN exposure:

• execute tool — runs arbitrary commands inside the configured sandbox. Pair with the LocalBackend(cwd=...) constraint and ideally a containerized runtime; the tool's blocklist is a guardrail, not a security boundary.
• External hooks (CLAW_FEATURE_EXTERNAL_HOOKS=1, CLAW_HOOK_*) execute shell commands defined in your env or .clawagents/hooks.json. Anyone who controls those configs has code execution. Treat hooks as trusted-only.
• web_fetch tool — refuses loopback / RFC1918 / link-local / multicast IPs by default to block SSRF. Set CLAWAGENTS_WEB_ALLOW_PRIVATE=1 only in trusted dev environments.
• Gateway — defaults to loopback (127.0.0.1) bind. Set GATEWAY_API_KEY if you bind to 0.0.0.0.

Sandbox Backends

ClawAgents uses a pluggable sandbox protocol for all file and shell operations:

from clawagents.sandbox import InMemoryBackend, LocalBackend

# Production: real filesystem
agent = create_claw_agent("gpt-5", sandbox=LocalBackend())

# Testing: pure in-memory VFS
mem = InMemoryBackend()
mem.seed({"src/main.py": "print('hello')", "README.md": "# My Project"})
agent = create_claw_agent("gpt-5", sandbox=mem)
snapshot = mem.snapshot()  # deterministic state capture

Environment Variables

All environment variables are optional. They serve as defaults when the corresponding create_claw_agent() parameter is not provided. Explicit parameters always take priority.

General

Provider & Model — set at least one API key (or OPENAI_BASE_URL for local models)

LLM Tuning

PTRL & Trajectory Flags — all off by default, opt-in with 1/true/yes

Claude Code Features — mostly off by default, opt-in with 1/true/yes

v5.28.0 Features — inspired by claw-code-main (Rust reference)

External Hook Env Vars (requires CLAW_FEATURE_EXTERNAL_HOOKS=1)

Testing

# Install with dev dependencies
pip install -e ".[dev]"

# Run all tests
python -m pytest -q

# Hermetic runner — exactly the environment CI uses (pinned xdist=4,
# TZ=UTC, LANG=C.UTF-8, PYTHONHASHSEED=0, credentials scrubbed)
bash scripts/run_tests.sh

# Run benchmarks (requires API keys)
python -m pytest tests/ -v -m benchmark

# Static type check
python -m mypy

The test suite includes regression tests for every Hermes-inspired pattern landed in the v6.5/v6.6 line — tests/test_subagent_depth.py, tests/test_compaction_hardened.py, tests/test_mcp_env_scrub.py, tests/test_paths.py, tests/test_redact.py, tests/test_steer.py, tests/test_transport.py, tests/test_commands.py, tests/test_aux_models.py, tests/test_background.py — and the four v6.6 feature suites (tests/test_browser.py, tests/test_cron.py, tests/test_acp.py, tests/test_rl.py). Current v6.8.1 coverage adds tests/test_prompts.py for shared prompt assembly and legacy hook injection, while v6.8.0 added tests/test_openharness_inspired_surfaces.py for dry-run previews, provider profiles, structured permission decisions, background task tools, plugin metadata compatibility loading, and MCP auth/reconnect helpers. v6.7.1 added tests/test_infra_improvements.py for compact tool discovery, structured tool failure observations, recovery hints, and infrastructure behavior, alongside the v6.3/v6.4 regression sets and the broad tests/simulated_test.py parity sweep.

Changelog

v6.8.1 — Prompt architecture and release packaging polish (May 2026)

Patch release focused on keeping the Python and TypeScript packages aligned for installed users after the OpenHarness-inspired operational surface work.

• Prompt assembly module — clawagents.prompts now owns system prompt construction, lesson preambles, __CACHE_BOUNDARY__ placement, and dynamic memory/skill prompt injection.
• Hook compatibility — prompt injection remains compatible with the legacy dict-shaped messages used by older before_llm integrations.
• OpenHarness comparison — the feature matrix now includes HKUDS/OpenHarness with conservative full/partial markers.

Release verification: Python 851 passed, 3 skipped plus bytecode compilation; TypeScript sibling: 526 passed, 4 skipped, tsc --noEmit, and build.

v6.8.0 — OpenHarness-inspired operational surfaces (May 2026)

Minor release focused on making ClawAgents easier to inspect, configure, recover, and integrate without changing the core agent loop contract.

• Static readiness previews — clawagents --dry-run --profile <name> --task "<prompt>" reports resolved provider settings, auth readiness, inspectable tools, likely matching tools, and next actions without calling a model or executing tools.
• Named provider profiles — built-in openai, gemini, anthropic, and ollama profiles plus project/user profile files give stable provider aliases. Explicit factory parameters still take precedence.
• Structured permission decisions — permission evaluation now returns a reusable decision object with allow/confirmation/reason fields and feeds the registry hard-block path for plan-mode and sensitive-path decisions.
• Background task tools — the registry can expose task create/status/output /stop/list tools backed by the existing background job manager, so long-running work can be tracked instead of blocking an agent turn.
• Plugin compatibility loader — metadata-only loading for plugin.json and .claude-plugin/plugin.json reads plugin manifests, markdown skills/commands, hooks, and MCP server declarations without executing arbitrary plugin code.
• MCP auth/reconnect helper — MCP manager configs can be updated with new environment/header auth material and reconnected deliberately.

Release verification: Python 844 passed, 3 skipped plus bytecode compilation and dry-run smoke; TypeScript sibling: 520 passed, 4 skipped, tsc --noEmit, build, and matching dry-run smoke.

v6.7.1 — Tool discovery and compact-agent recovery (April 2026)

Patch release focused on generalizable low-latency tool use for compact models. tool_discover is registered by default so agents can inspect the available tool universe before committing to a call, and lookup now searches tool names, descriptions, and keyword metadata. That makes discovery robust when a model remembers the action it needs but not the exact tool name.

Native-tool failures now keep useful output in the observation stream instead of reducing everything to a generic error. The built-in execute tool returns structured JSON for nonzero exits (command, exit_code, stdout, stderr, output, timed_out), and repeated identical execute failures include a recovery hint that nudges the agent to inspect the captured output or change command strategy.

Planning/todo guidance was also tightened so quick read-only or single-step tasks do not pay unnecessary planning overhead, while multi-step repair tasks still get explicit progress tracking. Focused release verification covers the infra-improvement regression tests and bytecode compilation for Python, plus TypeScript typecheck and matching infra-improvement tests.

v6.7.0 — Security hardening across validator, web_fetch, redact, sandbox (April 2026)

Minor release. Adversarial probing of the v6.6.4 surfaces uncovered a cluster of bypasses; this release closes them. Test totals after this release: Python 835 passed, 3 skipped; TypeScript 511 passed, 4 skipped plus parity checks; tsc --noEmit clean. 49 new regression tests ride alongside the fixes (44 Python, 5 TypeScript).

Bash validator hardening — validate_bash now walks every shell clause, including the contents of (...), $(...), backticks, and bash -c '<cmd>'/sh -c '<cmd>' wrappers; the strictest verdict across all clauses wins. The previous head-only inspection meant ls && rm -rf /var/log, (rm -rf /), echo $(rm -rf /), and bash -c 'rm -rf /' all silently passed. Additional shapes now BLOCK: rm -rf "$HOME" / rm -rf $HOME/x and any rm of a system directory (/etc, /var, /usr, /home, …); tee /dev/sda and tee /etc/passwd / tee -a /etc/sudoers; quoted block-device redirects (>'/dev/sda'); FD-prefixed redirects (1>/dev/sda); find -exec sh -c '…' and find -execdir; chmod -R 777 /; sed --in-place (long form, previously unrecognised). Null bytes and unprintable control characters in any command are also BLOCK (closes the C-string truncation evasion).

Web fetch SSRF — DNS-rebinding TOCTOU eliminated — web_fetch now resolves the host once per hop and connects to the validated IP directly, sending the original hostname via the Host header and SNI. A controlled DNS server can no longer return a public address to the validator and a private one (loopback, 169.254.169.254 / cloud metadata) to the actual fetch. Body reads are bounded at 4 MiB and truncated streamingly so a hostile server can't OOM the agent. Each redirect hop gets its own timeout. Location headers that downgrade HTTPS → HTTP across a redirect are refused.

Obfuscation detector — host-suffix bypass closed — the curl-pipe- shell installer allowlist used \b-anchored regexes, but . is a non-word character so brew\.sh\b matched brew.sh.evil.com. Allowlist is now keyed on parsed hostname (with required path prefix for raw.githubusercontent.com), not regex.

edit_file empty-target corruption — target="" plus replace_all=true previously inserted the replacement between every character of the file, silently corrupting it. Now refused.

Redaction coverage — redact() now scrubs PEM private-key blocks (any -----BEGIN […] PRIVATE KEY----- / END block), Authorization: Bearer <token> / Authorization: Basic … headers, AWS secret access keys (the previous regex covered only the access-key ID), URL basic-auth credentials (https://user:pass@host), and shorter generic-secret values. The Docker sandbox env-name policy now reuses is_secret_name() from redact.py plus a small extras regex covering vendor-prefixed shapes (GITHUB_PAT, STRIPE_SK_LIVE, DATABASE_URL, DSN); the previous end-anchored regex missed AWS_SECRET_ACCESS_KEY, GITHUB_PAT, DATABASE_PASSWORD_PROD, etc. and forwarded them into containers via -e.

Subprocess timeouts no longer orphan children — the local sandbox now starts each shell in a new session and SIGKILLs the whole process group on timeout, so long-running grandchildren of sh -c don't outlive the parent.

Concurrency — RunContext.iteration_budget lazy-init is serialised under an asyncio.Lock; sub-agents sharing a context can no longer clobber each other's budget. Callsite is await run_context.ensure_iteration_budget(size).

Other quality fixes — RetryPolicy.shouldRetry now correctly allows maxRetries=N to perform N retries (was off-by-one); jitter is clamped to [0, 1] to prevent zero-delay retry storms; the MCP manager tracks connected servers so a partial-failure start() doesn't double-register tools on retry, and shutdown errors are aggregated into a thrown Error instead of a span no caller observes; compressMessagesSafe no longer produces two consecutive same-role messages when the head is empty (Anthropic rejects that). The overbroad "curl http" / "wget http" legacy substring (which also matched https:// because https starts with http) is removed — the bash validator's NETWORK classification now applies cleanly.

v6.6.4 — Keyword discovery and infrastructure parity (April 2026)

Patch release for the v6.6 line. Test totals after this release: Python 786 passed, 3 skipped; TypeScript 509 passed, 4 skipped plus 49 parity checks; tsc --noEmit clean.

• Keyword-backed compact discovery — tools can now declare explicit keyword aliases, tool_discover searches names, descriptions, and those aliases, and tool_describe/registry inspection expose the metadata so compact tool universes stay useful even when the model uses a near-synonym.
• Bounded tool profiles — catalog helpers can publish smaller tool views for focused agents while preserving the full registry for callers that need it.
• Infrastructure parity — Docker sandbox support, resumable RunResult metadata, SQLite result caching for safe cacheable tools, explorer helpers, gym-style eval aliases, and next-state trajectory export helpers now ship in both the Python and TypeScript packages.
• Cache safety defaults — read/search-style filesystem outputs remain uncached by default to avoid persisting sensitive repository contents, while explicitly cacheable pure tools can reuse results across runs.

v6.6.3 — Efficiency and release hardening (April 2026)

Patch release for the v6.6 line. Test totals after this release: Python 778 passed, 3 skipped; TypeScript 497 passed, 4 skipped plus 49 parity checks; tsc --noEmit clean. Real .env smoke tests passed for Gemini and OpenAI, including read-only read_file tool use and task subagent delegation in both ports.

• Non-blocking local filesystem backend — async LocalBackend file, directory, and stat operations now offload synchronous pathlib work with asyncio.to_thread(), so parallel-safe tool calls can yield the event loop instead of serializing on local disk I/O.
• Append-only run summaries — trajectory finalization now appends one JSONL row to runs.jsonl instead of reading and atomically rewriting the full historical log for every run.
• Bounded session preload — agent session hydration now passes a default preload limit of 200 prior messages to session backends, with session_preload_limit=None available when callers explicitly want the full persisted history.
• Cross-package efficiency parity — the TypeScript sibling now caps large in-process diffs and single-file grep matches, and its session preload uses the same bounded default.

v6.6.1 — Approval, proxy, ACP, and release hardening (April 2026)

Patch/security release for the v6.6 line. Test totals after this release: Python 769 passed, 3 skipped; TypeScript 489 passed, 4 skipped; mypy clean, tsc --noEmit clean.

• Parallel tool approvals — batched/native tool execution now checks RunContext approval state before dispatch, so sticky denials and pending approvals cannot be bypassed by a multi-tool response.
• Credential proxy SDK mode — the sandbox credential proxy now forwards provider SDK path requests such as /v1/models, restricts upstream origins, and refuses redirects that would leak injected credentials across origins or protocol downgrades.
• Lazy tool schema parity — factory-published schemas now match the implementation arguments for edit_file, grep, and tree (target / replacement, glob_filter, max_depth).
• ACP default runner parity — AcpServer.serve(create_claw_agent(...)) now accepts real ClawAgents instances via invoke() and normalizes AgentState.result into protocol messages.
• Hermetic runner override — CLAW_TEST_WORKERS is preserved before the runner scrubs credentials and other CLAW_* variables.

v6.6.0 — Hermes-parity feature release: browser tools, scheduler, ACP, RL hooks (April 2026)

Feature release. Four big Hermes-side capabilities now ship on both Python and TypeScript ports, each behind an optional dependency so the core install stays slim. Test totals after this release: Python 762 passed, TypeScript 478 passed, mypy clean, tsc --noEmit clean.

• 🌐 Browser tools (clawagents.browser) — Playwright-driven browser control for agents that need to read or interact with the live web. BrowserSession exposes a stable async API (navigate, snapshot, click, type_text, fill_form, scroll, wait_for_selector, screenshot, close) over a pluggable provider (LocalProvider for Playwright; BrowserbaseProviderStub / BrowserUseProviderStub ready to be filled in for cloud back-ends). create_browser_tools() adapts the session into ClawAgents tools with per-action accessibility-tree snapshots so the model sees the page through the same axtree Hermes uses. Playwright is an optional peer (pip install clawagents[browser]); importing the module without it works fine — only session.start() raises MissingPlaywrightError. MAX_NODES = 800-cap on snapshots, navigation allow-/deny-lists, and a renderSnapshot() helper for prompt-friendly trees.
• ⏰ Cron / scheduled jobs (clawagents.cron) — minimal but production-shaped scheduler for agent-driven cron, one-shots, and intervals. parse_schedule() handles every 30s, at 2026-04-23T18:00, and 5-field cron expressions; cron support uses the optional croniter package and degrades cleanly when missing. Scheduler provides create_job / get_job / pause_job / resume_job / trigger_job / remove_job plus a run_due driver that emits JobNotifier events (job_started, job_finished, job_failed, job_skipped). Job store is plain JSON on disk; runners can be any callable, so users can wire it to agent.invoke(...) or shell. Mirrors Hermes' "agents as a workflow engine" pattern.
• 🔌 ACP adapter (clawagents.acp) — bridges any ClawAgents agent to Zed's Agent Client Protocol over stdio so editors / IDEs that speak ACP can drive a ClawAgents agent the same way they drive Claude Code or Codex. AcpServer.serve() registers an AgentSessionFactory, accepts ACP initialize / newSession / prompt / cancel requests, and translates ClawAgents stream events into ACP session/update messages (agent_message_chunk, agent_thought_chunk, tool_call.start / .complete, permission). Per-session AgentSession wraps prompt history, permission callbacks, and StopReason propagation. The optional agent-client-protocol package is loaded lazily — importing clawagents.acp works without it; only serve() raises MissingAcpDependencyError. Round-trip tested against Hermes' reference message shape.
• 🎯 RL fine-tuning hooks (clawagents.rl) — capture live agent runs as training-ready trajectories and export them to TRL, Atropos, SLIME, or generic JSONL. RLRecorder plugs into agent.on_event and assembles a Trajectory (system / user / assistant + tool_calls / tool messages) in correct ChatML order, with config knobs for max_tool_result_chars, redact_tool_args, and capture_system_prompt. Pluggable RewardScorers (Contains, ExactMatch, Regex, LengthPenalty, Composite) attach a scalar reward + per-component breakdown. Export helpers: export_jsonl, to_chatml, to_trl_sft, to_trl_dpo, to_atropos_rollout. Lazy TrlAdapter and AtroposAdapter only import trl / atropos when the user actually drives a trainer or rollout collector — install hints surface as MissingRLDependencyError.

Backwards compatibility: All four features are additive and opt-in. Importing the new submodules has no side effects; nothing in the core create_claw_agent() / agent.invoke() path changed. The optional peers (playwright, croniter, agent-client-protocol, trl, atropos) are only required at the moment you actually session.start() / parse a cron expression / serve() over ACP / build a TRL dataset.

v6.5.0 — Hermes-inspired hardening: depth, isolation, heartbeats, path-scoped parallelism (April 2026)

Architecture/correctness release. Ten patterns ported from the Hermes agent are now live on both Python and TypeScript ports — every change comes with regression tests on both. Test totals after this release: Python 662 passed, TypeScript 370 passed, mypy clean, tsc --noEmit clean.

Tier 1 — runtime safety & isolation:

• 🪜 Subagent depth limits (graph/coordinator, tools/subagent, graph/forked_agent) — RunContext now tracks subagent_depth. The task tool refuses to delegate when the parent is already at depth >= 2, returning a structured error instead of silently spawning a third tier. Forks inherit the depth counter; the cap mirrors Hermes' "no recursive delegation" rule and prevents exponential subagent fan-out.
• 🧠 Memory-isolated forks/subagents (graph/forked_agent, memory/loader) — both forked_agent and the built-in task tool now accept skip_memory=True (default for forks). When set, memory loaders are bypassed so a sandboxed fork cannot see the parent's AGENTS.md/skills/notes — closing a previously-silent context-leak path. Forks also get their own IterationBudget so a runaway research fork cannot starve the parent's remaining turns.
• 💓 Activity heartbeats (session/heartbeat, gateway/server, graph/agent_loop) — long-running tool calls now emit periodic tool_heartbeat events (tool_name, call_id, elapsed_s) every ~20s through run_with_heartbeat. Gateway clients can use these to keep WebSocket channels alive and surface progress, eliminating false timeouts on slow shell/web/sandbox calls. Best-effort: emitter exceptions are swallowed so they never mask the real result.
• ⏱️ Per-agent IterationBudget (iteration_budget, graph/agent_loop, graph/forked_agent) — replaces the implicit max_turns counter with an explicit IterationBudget object that lives on RunContext. Subagents and forks each get their own budget sized from delegation.max_iterations (default DEFAULT_DELEGATION_MAX_ITERATIONS), so one chatty fork can't drain the parent's turn pool. Surfaces the same consume()/refund()/exhausted shape Hermes uses, making it easy to tee budgets across recursive delegation.
• 🌿 Path-scoped parallel tool execution (tools/registry) — execute_tools_parallel no longer fans out blindly. Tools are tagged parallel_safe (read-only by default for read_file / list_dir / glob / search_files / grep / web_fetch) with optional path_scoped_arg ("path", "url", …); the registry partitions calls into ordered batches so reads run concurrently while any writer or path-scope collision serialises behind them. Capped at MAX_PARALLEL_TOOL_WORKERS = 8 to keep file-handle pressure bounded. Mirrors Hermes' parallel-read / serial-write contract.

Tier 2 — extensibility & cache-discipline:

• 🔌 Plugin hook expansion (plugins) — new top-level Plugin + PluginManager (from clawagents import Plugin, PluginManager). Plugins compose three hook families with priority-based ordering: pre_tool (first-deny veto / args-rewrite, alias before_tool), transform_tool_result (sequential post-execution rewrite, alias after_tool), and before_llm (prompt-massage). Replaces the previous "single hook wins" model with a deterministic chain that's easy to unit-test.
• 📁 display_clawagents_home() (paths) — runtime helper that resolves the package install root and rewrites it to a placeholder (<clawagents-home>) for tool descriptions, error messages, and traces. Makes prompt cache hits stable across user homes / dev / CI by stripping absolute paths from anything that ends up in the LLM context window.
• 🧊 Prompt-cache-aware CommandDef (commands) — slash-command definitions now carry an explicit cache_impact ("none" | "soft_break" | "hard_break") and parse a --now flag (/skills install foo --now) so users can opt into immediate state mutation; default is cache_impact="none", --now upgrades to "hard_break" and forces a fresh prompt build. Mirrors Hermes' "deferred by default to preserve prompt cache" contract.
• 📜 Prompt-cache policy (AGENTS.md) — new top-level rule documents the cache invariants (stable system prompt prefix, no per-turn timestamps in cached blocks, deferred slash-command state mutations, display_clawagents_home() for paths) so contributors keep the cache hit rate above the 80%+ Hermes target.

Tier 3 — testing infrastructure:

• 🧪 Hermetic test runner + pinned xdist (scripts/run_tests.sh, pyproject.toml) — canonical CI-mirrored runner that pins pytest-xdist to 4 workers (override via CLAW_TEST_WORKERS), forces TZ=UTC / LANG=C.UTF-8 / PYTHONHASHSEED=0, and scrubs credentials plus non-runner CLAW_* env vars before pytest sees them. Gives every contributor the exact environment CI runs in, eliminating local-vs-CI flakes. Mirrored by clawagents/scripts/run_tests.sh for the TypeScript port (node:test --test-concurrency=4 via tsx).

Backwards compatibility: All 10 features are additive. Existing create_claw_agent() / agent.invoke() call sites keep working; the new machinery activates automatically (depth tracking, heartbeats, parallel-safe tagging) or via opt-in (Plugin, --now, skip_memory, IterationBudget).

v6.4.1 — Public-API export polish (no behavior change)

Patch release. Surfaces PromptHook and PromptHookVerdict at the top-level clawagents package (Python) and clawagents module (TypeScript) so users can from clawagents import PromptHook instead of reaching into clawagents.hooks.prompt_hook. No code-path changes; both ports remain at 516/226 passing.

v6.4.0 — Tracing, MCP, Handoffs, Plan Mode (April 2026)

Big feature release. Nine new subsystems shipped on both Python and TypeScript ports — every change comes with regression tests on both. Test totals: Python 516 passed, TypeScript 226 passed, mypy clean, tsc --noEmit clean.

Tier 1 — production interop & safety:

• 🔭 Tracing infrastructure (clawagents.tracing) — hierarchical Span model with 8 kinds (agent / turn / generation / tool / handoff / guardrail / subagent / custom), pluggable TracingProcessor + TracingExporter ABCs, batched BatchTraceProcessor with background flush, ready-made JsonlSpanExporter / ConsoleSpanExporter / NoopSpanExporter, and agent_span / turn_span / generation_span / tool_span / handoff_span context managers. Spans propagate via Python contextvars (TS: AsyncLocalStorage). Replaces flat trajectory JSONL — drop in OTLP/Langfuse/Logfire by writing one exporter.
• 🔌 MCP (Model Context Protocol) integration (clawagents.mcp) — full client supporting stdio, SSE, and Streamable-HTTP transports. MCPServerStdio / MCPServerSse / MCPServerStreamableHttp follow openai-agents-python's shape; MCPServerManager lifecycles a list of servers; MCPBridgedTool adapts MCP tools into ToolRegistry so they coexist with native tools, hooks, and approval flows. SDK is an optional dep (pip install clawagents[mcp] / npm install @modelcontextprotocol/sdk). 11 lifecycle phases tracked per server with tracing spans.
• 🔁 Handoffs + Agent.as_tool() — fills the previously-stub on_handoff lifecycle hook. Handoff dataclass + handoff() builder lets one agent transfer control to another (with optional input_filter for history trimming). agent.as_tool(tool_name=…, tool_description=…) is the complementary primitive: expose any agent as a callable tool to a parent agent. Built-in remove_all_tools filter strips tool calls/results before handoff. New HandoffOccurredEvent typed stream event.
• 🛡️ Exec safety v2 (clawagents.permissions, clawagents.tools.{plan_mode,bash_validator,exec_obfuscation}) — three security upgrades shipped together: (1) PermissionMode enum (DEFAULT|PLAN|ACCEPT_EDITS|BYPASS) on RunContext plus enter_plan_mode / exit_plan_mode built-in tools — write-class tools refuse in PLAN. (2) Bash semantic validator classifies every command (READ_ONLY|WRITE|DESTRUCTIVE|NETWORK|PROCESS|PACKAGE|SYSTEM_ADMIN|UNKNOWN) with a 47-row corpus and decision (ALLOW|WARN|BLOCK). (3) Command obfuscation detector catches base64/hex/printf decode-then-exec, <(curl …), curl … | sh, eval decoders, and 9 other patterns — with an allowlist for known-safe installers (rustup, brew, nvm, …).
• 🪝 Hook event taxonomy expansion + PromptHook — extended RunHooks with 8 additive events: on_pre_compact, on_post_compact, on_subagent_start, on_subagent_end, on_user_prompt_submit, on_session_start, on_session_end, on_tool_failure. New PromptHook(prompt, model) evaluates a guardrail using a small/cheap model with strict-JSON {"ok":bool, "reason":str} verdict — write a natural-language guardrail in settings.json instead of Python code. Fails open on timeout/error so a noisy hook can't deadlock the agent.

Tier 2 — ergonomics & correctness:

• ❓ AskUserQuestion structured tool (clawagents.tools.ask_user_question) — structured HITL primitive: 1-3 multi-choice questions per call, 2-4 options each, implicit "Other (please specify)" always appended. Renders cleanly to Telegram inline buttons / WhatsApp quick-replies. Delegates rendering via on_ask callback.
• ⚙️ Settings hierarchy (clawagents.settings) — user → project → local → flag → policy precedence, deep-merged. Policy layer (/etc/clawagents/policy-settings.json) ALWAYS wins, so even runtime flags can't override an MDM-style enforced rule. Repo root walks up looking for .git/pyproject.toml/package.json. get_setting("hooks.before_tool") for dotted-path access.
• 🖼️ Image sanitization (clawagents.media.images) — clamps tool-result base64 image blocks to ≤1200px / ≤5MB before transcript ingest, walking quality steps (90, 75, 60) until under limit. Closes a silent-failure path on Anthropic's 5MB limit. Pillow is optional (pip install clawagents[media]).

Tier 3 — testing infrastructure:

• 🎭 Mock-provider parity harness (clawagents.testing.mock_provider) — deterministic fake LLM service (MockLLMService) bound to 127.0.0.1:0. Real provider clients point at it via OPENAI_BASE_URL / ANTHROPIC_BASE_URL env vars. Routes via X-Parity-Scenario: header or PARITY_SCENARIO: <name> system message. Five built-in scenarios. Pure stdlib, zero new deps.

v6.5 backlog (deferred): Anthropic prompt-cache tracking + cache-break detection, auth-profile rotation with cooldowns, multi-provider routing prefix + LiteLLM extension, file checkpoint snapshots, cache-TTL provider eligibility map, tool_use_behavior / StopAtTools, granular lifecycle payload widening, skills hot-reload watcher, finalize cleanup hook, edit_scope allowlist in skills, multi-tier numeric verifier reward, replayable per-task archives.

v6.3.0.post1 — Docs Re-publish (no code changes)

PEP 440 post-release. Identical code to 6.3.0; re-published so the PyPI page shows the corrected README (version badge, feature-matrix header, latest-release callout). pip install clawagents resolves to this artifact.

v6.3.0 — Sandbox & Security Hardening, Strict Type Checking

Security/correctness release. Eleven bugs fixed across both the Python and TypeScript ports, plus a full mypy cleanup. All tests green: 334 passed, mypy clean (0 errors, exit 0).

Security fixes:

• Sandbox escape via symlink (TS) — LocalBackend.safePath was lexical-only (path.resolve), so an agent that ran ln -s /etc evil could read /etc/* through the symlink. Now uses realpathSync for both cwd and resolved paths so symlinks are followed before the containment check. Python was already safe via Path.resolve().
• SSRF gap (TS) — web_fetch's IPv6 link-local check only matched fe8X, missing fe9X/feaX/febX. Now matches the full fe80::/10 range (/^fe[89ab]/i). Python uses ipaddress.is_link_local, no change needed.
• > /dev/null blocked legitimate use (both) — BLOCKED_PATTERNS had "> /dev/null" (typo for "> /dev/sd"), which blocked the common shell idiom cmd > /dev/null. Removed.
• rm / regex parity (TS) — DANGEROUS_RE was missing the * quantifier on the flag group, so rm / (no flags) slipped past while Python's regex blocked it. Aligned.
• wget http / curl http parity (TS) — added to TS BLOCKED_PATTERNS to match Python. Agents should use the web_fetch tool (with SSRF guards) for HTTP, not raw shell utilities.

Correctness fixes:

• Multimodal system message crashed context shedding (Py) — _preflight_context_check called .replace() and string-slicing on system messages without checking if content was a list[dict] (multimodal). Now guards each tier with isinstance(content, str) and emits a warn event if the system message is multimodal.
• Arbitrary role from pre_llm hook (Py) — external hooks could pass any string as role, blowing up Pydantic validation in LLMMessage. Now coerces unknown roles to "user" and emits a warn.
• Parallel native tool-call indexing (Py) — when before_tool rejected a call OR returned updated_args, native_tool_call_objects was indexed by approved-list index (off-by-one) and the identity check tc is approved_calls[i] failed (because updated_args constructs a new ParsedToolCall). Tool-call IDs sent back to the LLM were wrong, causing native function-calling failures. Now tracks (orig_idx, call) pairs through the approval loop.
• Subagent env-mutation race (Py) — concurrent subagent runs with credential_proxy enabled raced on os.environ. The second run captured the first's overrides as its "original" env, then stamped them back into place after the first run had already stopped its proxy. Wrapped the env-mutate / run / env-restore window in an asyncio.Lock. No-proxy path is unaffected.
• classify_error rejected BaseException (Py) — asyncio.CancelledError and similar inherit from BaseException, not Exception. Widened classify_error, _extract_status, and ErrorDescriptor.original to accept BaseException.
• Gemini provider None parts iteration (Py) — streaming chunks could surface None for candidate.content.parts after a hasattr check that says only the attribute exists. Switched to getattr(getattr(_cand, "content", None), "parts", None) and explicit truthiness check.

Type checking:

• Full mypy cleanup: 46 errors → 0. Real bugs fixed (None-iter, AsyncOpenAI/AsyncAzureOpenAI mismatch, missing telegram updater check, kwargs widening). False positives addressed by renaming reused variables, adding explicit dict[str, Any] annotations on union-typed locals, and parameters: Dict[str, Dict[str, Any]] annotations on tool implementations to satisfy the Tool protocol.
• Added [tool.mypy] block to pyproject.toml with warn_unused_ignores = true and ignore_missing_imports = true. Run python -m mypy — clean run shows Success: no issues found in 72 source files. Mypy now exits non-zero on errors so CI can gate on it.

Regression coverage added:

• tests/test_exec_safety.py — denylist behavior (legitimate idioms allowed, destructive patterns blocked)
• tests/test_agent_loop_bugs.py — multimodal shedding paths + role coercion
• tests/test_parallel_native_indexing.py — both rejection-skip and updated-args indexing paths
• tests/test_subagent_env_race.py — concurrent credential-proxy runs don't corrupt env

v6.2.1 — Release Hardening, Redirect-Safe web_fetch, and Parity Smokes

Patch release focused on making the v6.2 line safer to install, test, and operate.

• Redirect-aware SSRF protection — web_fetch disables automatic redirects and manually revalidates every hop before network I/O. Public-to-private redirects to loopback, RFC1918, link-local, reserved, multicast, or cloud metadata IPs are refused by default.
• Hermetic SSRF regression tests — added tests/test_web_fetch_ssrf.py covering public-to-private redirects, redirect loops, direct private IP refusal, and legitimate public-to-public redirects.
• Local-source pytest resolution — pyproject.toml now sets pythonpath = ["src"] and testpaths = ["tests"], so local test runs cannot accidentally import an older installed wheel from site-packages.
• Cross-package parity smoke — added scripts/smoke_gemma4.py, mirroring the TypeScript smoke script and printing provider, base URL, and stored model for Ollama/Gemma4, gpt-5.4, gemini-3.1-pro, and claude-opus-4-6.
• Release verification — python -m pytest reports 319 passed, 2 skipped; the SSRF-specific suite reports 5 passed.

v6.2.0 — OpenAI-Agents Parity, Ollama/Gemma4 First-Class Routing, 63 Model Profiles

A substantial additive release. Everything is backward compatible — existing create_claw_agent() calls, env vars, and tool registrations work unchanged.

1. Ten OpenAI-Agents-SDK parity surfaces (all additive, all new modules)

2. Ollama & Gemma 4 first-class routing

create_provider() now auto-routes 24 Ollama-family prefixes to http://localhost:11434/v1 with no config needed. Use either the bare tag (gemma4:e4b) or the explicit routing form (ollama/gemma4:e4b).

Override with OPENAI_BASE_URL if you run Ollama on a different host/port. API key is auto-set to the placeholder "ollama".

3. 63 model profiles + model-aware context budget

The _MODEL_PROFILES table now covers frontier (GPT-5.4 → 400K, Gemini 3.1 → 1M, Claude 4.6 Opus), Ollama (Gemma4 e2b/e4b → 128K, 26b/31b → 256K), and a long tail of OSS variants. _resolve_context_budget() walks insertion order for deterministic prefix matching (most-specific first).

4. Cross-package parity — the TypeScript sibling clawagents (see x1jiang/clawagents) has the identical 24-entry Ollama prefix list, 63-entry model profile table with the same (window, ratio) values, and the same create_provider routing logic. Parity can be exercised manually with the matching smoke scripts in each repo (clawagents_py/scripts/smoke_gemma4.py and clawagents/scripts/smoke-gemma4.ts); both print the same provider, base URL and stored model for gemma4:*, ollama/..., gpt-5.4, gemini-3.1-pro and claude-opus-4-6. The GitHub Actions workflow added in v6.2.1 runs pytest, python -m build, and twine check on every push.

5. Quality / debug pass

• Async agent loop hardening — new turn-started events, tighter cancellation semantics, cleaner state hand-off to sub-agents.
• Added tests/test_openai_agents_surfaces.py — full coverage for RunContext, Usage, Hooks, Guardrails, StreamEvents, Retry, FunctionTool, Session backends.
• Test suite: 314 passed, 2 skipped.

New public exports (from clawagents): RunContext, ApprovalRecord, Usage, RequestUsage, RunHooks, AgentHooks, composite_hooks, InputGuardrail, OutputGuardrail, input_guardrail, output_guardrail, GuardrailBehavior, GuardrailResult, GuardrailTripwireTriggered, StreamEvent (+ 10 concrete event types), stream_event_from_kind, RetryPolicy, DEFAULT_RETRY_POLICY, function_tool, InMemorySession, JsonlFileSession, SQLiteSession.

v6.1.1 — Credential Isolation & Lazy Tool Provisioning

v6.1.0 — Advisor Model: Smart Model Guides Cheap Model

Pair a stronger "advisor" model with a cheaper "executor" model. The executor runs every turn; the advisor is consulted 2-3 times per task for strategic guidance. Cross-provider supported — any model can advise any other model.

agent = create_claw_agent(
    "gpt-5.4-nano",
    advisor_model="gpt-5.4",
)

v6.0.0 — Production Hardening: 17 Improvements

High Priority

Medium Priority

New files: providers/fallback.py, sandbox/credential_proxy.py, utils/atomic_write.py, session/heartbeat.py, tests/test_cross_provider.py

New feature flags: transcript_archival (off), credential_proxy (off)

New exports: HookResult, FallbackProvider, CredentialProxy, SessionHeartbeat, LazyTool, atomic_write_text, atomic_write_bytes

v5.28.0 — Error Taxonomy, Prompt Caching, Session Persistence & External Hooks

Four production-grade features ported from the claw-code-main Rust reference implementation:

Also:

• Anthropic cache token extraction — cache_creation_tokens and cache_read_tokens now populated from both streaming and non-streaming Anthropic responses.
• AgentState.session_file — New field tracks the session JSONL path when persistence is enabled.
• New public exports — ErrorClass, ErrorDescriptor, classify_error, get_recovery_recipe, SessionWriter, SessionReader, list_sessions, HooksConfig, ExternalHookRunner, load_hooks_config.

v5.27.3 — Gemini Signature Regression Coverage

• Gemini signature regression test — Added targeted tests for _serialize_gemini_parts to ensure thought_signature is propagated to sibling parallel function_call parts.
• Parallel integration test reliability — Fixed integration test fixture validation mismatch so large-output parallel execution is validated correctly.

v5.27.2 — Gemini 3 Thought Signature Fix

• Gemini 3 Propagation — Propagated thought_signature to all parallel function_call parts in the response, preventing 400 INVALID_ARGUMENT during multi-tool execution.

v5.27.1 — Timeout Bugfix

• Fixed NameError — Added timeout_s parameter to ClawAgent.invoke to prevent an exception when a global timeout is not provided.

v5.27.0 — Claude Code Architectural Patterns

Ported 10 production-grade architectural patterns from Anthropic's Claude Code directly into ClawAgents. These features are controllable via environment variables or constructor injection:

v5.26.0 — Bundled OpenViking Skill, Updated ByteRover Skill

v5.25.0 — Gemini Streaming Fix

v5.24.0 — Zero-Config Channel Auto-Detection

v5.23.0 — WebSocket Gateway, Multi-Channel Messaging (Telegram, WhatsApp, Signal)

Full multi-platform messaging support inspired by OpenClaw's channel architecture:

from clawagents import create_claw_agent, ChannelRouter
from clawagents.channels.telegram import TelegramAdapter
from clawagents.channels.whatsapp import WhatsAppAdapter

router = ChannelRouter(lambda: create_claw_agent("gpt-5-mini"))
router.register(TelegramAdapter())
router.register(WhatsAppAdapter())
await router.start_all({
    "telegram": {"bot_token": "123456:ABC..."},
    "whatsapp": {"mode": "baileys", "auth_dir": ".whatsapp-auth"},
})

v5.22.0 — Tool Result Caching, Parameter Validation & ComposeTool

3 features inspired by ToolUniverse's tool management patterns:

v5.21.0 — Context Engine, Loop Detection & Compaction Overhaul

8 improvements inspired by the latest OpenClaw architecture:

v5.20.4 — Gemini MALFORMED_FUNCTION_CALL Retry

v5.20.3 — GPT-5 Temperature Corrections

v5.20.0 — Temperature & Compaction Fixes

v5.19.0 — Anthropic Provider, Security, Architecture Overhaul

v5.18.0 — Doctor, Trajectory Inspector & Config Improvements

v5.17.0 — Quick Start Scaffold & Examples

v5.16.0 — LLM-as-Judge & Thinking Token Preservation

v5.15.0 — Deterministic Verification & GRPO-Inspired Comparison

v5.14.0 — SkyRL-Inspired PTRL Improvements

v5.13.0 — Prompt-Time Reinforcement Learning (PTRL)

v5.12.1 — Streamlit / Jupyter Compatibility

v5.12.0 — Gemini 3 Thought Signature Support

v5.11.0 — Configurable Limits

v5.10.0 — Discrete Reward Bands & Weighted Scoring

v5.9.0 — Trajectory Logging & Rethink

v5.8.0 — JSON Resilience

v5.7.0 — Model-Specific Temperature

v5.6.0 — LLM Parameter Fixes

v5.5.0 — Foundation

Trajectory Logging & RL-Inspired Scoring

ClawAgents includes an optional trajectory system inspired by reinforcement learning techniques from CUDA-Agent and OpenClaw-RL. Enable it with trajectory=True or CLAW_TRAJECTORY=1.

What gets logged

Every agent run records:

• Turn-level data: tool calls, arguments, success/failure, output previews
• Weighted turn scores: execution tools (shell, code runners) weighted 2× higher than generic tools
• Run summary: total turns, tool calls, successes/failures, elapsed time

Discrete reward bands

Each run receives a score from -1 to +3:

Quality grading

Runs are classified for downstream filtering:

Anti-gaming protections

Tools like think, todolist, use_skill, list_skills, and update_todo are excluded from scoring — they can't inflate success rates.

Consecutive-failure rethink

With rethink=True or CLAW_RETHINK=1, the agent monitors tool outcomes in real-time. After 3 consecutive meaningful failures, it injects a system message:

"You have had 3 consecutive tool failures. Stop and rethink your approach before continuing."

This simple mechanism prevents the agent from spiraling into repeated failed attempts.

Output

Run summaries are appended to .clawagents/trajectories/runs.jsonl:

{
  "run_id": "a1b2c3d4",
  "model": "gpt-5-mini",
  "total_turns": 8,
  "tool_calls": 12,
  "successes": 10,
  "failures": 2,
  "run_score": 2,
  "quality": "clean",
  "elapsed_ms": 45230,
  "turns": [...]
}

Roadmap

• Docker sandbox backend (protocol ready)
• Semantic browser automation (accessibility tree)
• Prompt caching (Anthropic-style)
• Persistent memory learning from trajectory data (advanced — RFT-style rule extraction)
• Post-run self-analysis + lesson extraction ✅ (v5.13 — PTRL)
• Pre-run lesson injection ✅ (v5.13 — PTRL)
• Enhanced mid-run rethink with past lessons ✅ (v5.13 — PTRL)
• Trajectory logging + discrete reward bands ✅ (v5.9–5.10)
• Consecutive-failure rethink injection ✅ (v5.9)
• Weighted execution scoring + quality grading ✅ (v5.10)
• JSON repair + truncated JSON retry ✅ (v5.8)
• Model-specific temperature override ✅ (v5.7)
• Configurable temperature / max_completion_tokens ✅ (v5.6)
• Pluggable sandbox backend ✅ (v5.5)
• Lane-based queue serialization ✅ (v5.5)
• Skill progressive disclosure ✅ (v5.5)
• Gateway HTTP server ✅ (v5.5)

License

MIT

Built with 🦞 by the ClawAgents team