ForgeClaw

Important

Fork note

This branch is a personal fork that currently carries additional features and behavior on top of upstream/main, including:

Image generation support: provider-backed image generation tool and pluggable image generation provider wiring.
Local coding tools: apply_patch for guarded file edits, search_files for workspace search with optional gitignore override, and update_plan for explicit task progress.
Task-board workflow tracking: durable task_board boards with explicit local/manual step updates, so composite workflows can keep truthful step status without pretending work is still queued.
Planning and search providers: Gemini web search provider, related web-search UI/config support, and safer provider behavior around unsupported range filters.
Agent / subagent runtime fixes: async follow-up origin preservation, direct async error surfacing, final-reply delivery after interim progress messages, improved spawn / delegate delivery semantics, and durable task status behavior.
Runtime delivery coordination: typed async completion handling, legacy synthetic system-message adapter isolation, delivery-mode routing (user_only, parent_only, user_and_parent), duplicate/restart idempotency, and task-registry-backed spawn_status / task_status.
Unified tool delivery intents: declarative ToolResult delivery intents and outbound payloads (immediate_continue, final_handled, parent_only, silent) so tools like message and generated-media tools share one delivery coordinator path.
Durable background task registry: bounded persistent records for spawn, delegate, and cron executions, including delivery status, completion IDs, restart reconciliation, and user-visible task_status diagnostics.
Seahorse context hardening: LCM-style summary-prefix pressure compaction, formatted-summary budgeting, non-history prompt/tool budget reservation, coverage-root assembly, capped summary output, less noisy XML text escaping, and fail-closed oversized-context behavior.
Agent capability policy: frontmatter-based per-agent tools / mcpServers filtering, replacing the older config-level per-agent tool filter layer.
MCP transport safety: fatal MCP transport / JSON-RPC framing errors fail fast instead of triggering speculative fallback tool calls after a broken MCP response.
Telegram / channel fixes: forum topic preservation for final replies and message-tool sends, media-group album handling, topic-aware trigger overrides, typing / feedback cleanup, and real MinEditInterval throttling for tool-feedback edits.
Media/message delivery ownership: message-tool media sending with explicit media_enabled configuration, generated-media continuation for multi-image tasks, cleaner forwardable media captions, and reduced duplicate “done” replies after file/media delivery.
Tooling and workflow fixes: relative script paths allowed in the exec guard, head/tail truncation for oversized command output, session-scoped Seahorse retrieval tools, cron feedback suppression plus cron execution records, session reset command, and tool-feedback controls.
Provider auth support: OpenAI OAuth support for Codex and transcription flows.

Treat this branch as deployment-specific until the corresponding changes are merged upstream.

ForgeClaw

A fast, hackable agent runtime for personal automation, MCP tools, and multi-agent workflows.

ForgeClaw is a personal fork of PicoClaw. It keeps PicoClaw's small Go runtime as the base, but carries deployment-specific changes for day-to-day agent workflows: durable task state, better tool delivery semantics, MCP-heavy integrations, media handling, and context-management hardening.

This repository is not the upstream PicoClaw project. Treat it as an experimental fork optimized for one actively used deployment.

Features

Go-native agent runtime with chat channels, local tools, MCP servers, providers, hooks, cron, and subagents.
Durable workflow state through task-registry-backed spawn_status, task_status, cron records, and task_board.
Unified tool delivery intents for intermediate user-visible output, final handled output, parent-only handoffs, and silent tool results.
Media-aware workflows including generated images, file delivery, multimodal input, and reduced duplicate final replies.
Context-management hardening through Seahorse compaction improvements and fail-closed oversized-context behavior.
Provider and search extensions including OpenAI OAuth support and additional web-search/provider behavior.

Upstream

ForgeClaw tracks upstream PicoClaw as:

upstream https://github.com/sipeed/picoclaw.git
origin   git@github.com:bogdanovich/forgeclaw.git

Install

Build from source

Prerequisites:

Go 1.25+
Node.js 22+ and pnpm 10.33.0+ for Web UI / launcher builds

git clone https://github.com/bogdanovich/forgeclaw.git

cd forgeclaw
make deps

# Install frontend dependencies
(cd web/frontend && pnpm install --frozen-lockfile)

# Build the core binary for the current platform
make build

# Build the Web UI Launcher (required for WebUI mode)
make build-launcher

# Build core binaries for all Makefile-managed platforms
make build-all

# Build for Raspberry Pi Zero 2 W
# 32-bit: make build-linux-arm
# 64-bit: make build-linux-arm64
make build-pi-zero

# Build and install
make install

🚀 Quick Start Guide

🌐 WebUI Launcher (Recommended for Desktop)

The WebUI Launcher provides a browser-based interface for configuration and chat. This is the easiest way to get started — no command-line knowledge required.

picoclaw-launcher
# Open http://localhost:18800 in your browser

Tip

Remote access / Docker / VM: Add the -public flag to listen on all interfaces:

picoclaw-launcher -public

Getting started:

Open the WebUI, then: 1) Configure a Provider (add your LLM API key) -> 2) Configure a Channel (e.g., Telegram) -> 3) Start the Gateway -> 4) Chat!

For more details, see the local documentation in docs/.

Docker (alternative)

# 1. Clone this repo
git clone https://github.com/bogdanovich/forgeclaw.git
cd forgeclaw

# 2. First run — auto-generates docker/data/config.json then exits
#    (only triggers when both config.json and workspace/ are missing)
docker compose -f docker/docker-compose.yml --profile launcher up
# The container prints "First-run setup complete." and stops.

# 3. Set your API keys
vim docker/data/config.json

# 4. Start
docker compose -f docker/docker-compose.yml --profile launcher up -d
# Open http://localhost:18800

Docker / VM users: The Gateway listens on 127.0.0.1 by default. Set PICOCLAW_GATEWAY_HOST=0.0.0.0 or use the -public flag to make it accessible from the host.

# Check logs
docker compose -f docker/docker-compose.yml logs -f

# Stop
docker compose -f docker/docker-compose.yml --profile launcher down

# Update
docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml --profile launcher up -d

macOS — First Launch Security Warning

macOS may block picoclaw-launcher on first launch because it is downloaded from the internet and not notarized through the Mac App Store.

Step 1: Double-click picoclaw-launcher. You will see a security warning:

"picoclaw-launcher" Not Opened — Apple could not verify "picoclaw-launcher" is free of malware that may harm your Mac or compromise your privacy.

Step 2: Open System Settings → Privacy & Security → scroll down to the Security section → click Open Anyway → confirm by clicking Open Anyway in the dialog.

After this one-time step, picoclaw-launcher will open normally on subsequent launches.

📱 Android

Give your decade-old phone a second life. Turn it into a small always-on AI assistant.

Option 1: APK Install

Preview:

Download the APK from picoclaw.io and install directly. No Termux required.

Option 2: Termux

For a full command-line setup checklist, see the Android Termux Guide.

Terminal Launcher (for resource-constrained environments)

For minimal environments where only the picoclaw core binary is available (no Launcher UI), you can configure everything via the command line and a JSON config file.

1. Initialize

picoclaw onboard

This creates ~/.picoclaw/config.json and the workspace directory.

2. Configure (~/.picoclaw/config.json)

{
  "agents": {
    "defaults": {
      "model_name": "gpt-5.4"
    }
  },
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4"
      // api_key is now loaded from .security.yml
    }
  ]
}

See config/config.example.json in the repo for a complete configuration template with all available options.

Please note: config.example.json format is version 0, with sensitive codes in it, and will be auto migrated to version 1+, then, the config.json will only store insensitive data, the sensitive codes will be stored in .security.yml, if you need manually modify the codes, please see docs/security/security_configuration.md for more details.

3. Chat

# One-shot question
picoclaw agent -m "What is 2+2?"

# Interactive mode
picoclaw agent

# Start gateway for chat app integration
picoclaw gateway

🔌 Providers (LLM)

PicoClaw supports 30+ LLM providers through the model_list configuration. Use the protocol/model format:

Provider	Protocol	API Key	Notes
OpenAI	`openai/`	Required	GPT-5.4, GPT-4o, o3, etc.
Anthropic	`anthropic/`	Required	Claude Opus 4.6, Sonnet 4.6, etc.
Google Gemini	`gemini/`	Required	Gemini 3 Flash, 2.5 Pro, etc.
OpenRouter	`openrouter/`	Required	200+ models, unified API
Zhipu (GLM)	`zhipu/`	Required	GLM-4.7, GLM-5, etc.
DeepSeek	`deepseek/`	Required	DeepSeek-V3, DeepSeek-R1
Volcengine	`volcengine/`	Required	Doubao, Ark models
Qwen	`qwen/`	Required	Qwen3, Qwen-Max, etc.
Groq	`groq/`	Required	Fast inference (Llama, Mixtral)
Moonshot (Kimi)	`moonshot/`	Required	Kimi models
Minimax	`minimax/`	Required	MiniMax models
Mistral	`mistral/`	Required	Mistral Large, Codestral
NVIDIA NIM	`nvidia/`	Required	NVIDIA hosted models
Cerebras	`cerebras/`	Required	Fast inference
Novita AI	`novita/`	Required	Various open models
Xiaomi MiMo	`mimo/`	Required	MiMo models
Ollama	`ollama/`	Not needed	Local models, self-hosted
vLLM	`vllm/`	Not needed	Local deployment, OpenAI-compatible
LiteLLM	`litellm/`	Varies	Proxy for 100+ providers
Azure OpenAI	`azure/`	API key or Entra ID**	Enterprise Azure deployment
GitHub Copilot	`github-copilot/`	OAuth	Device code login
Antigravity	`antigravity/`	OAuth	Google Cloud AI
AWS Bedrock*	`bedrock/`	AWS credentials	Claude, Llama, Mistral on AWS

* AWS Bedrock requires build tag: go build -tags bedrock. Set api_base to a region name (e.g., us-east-1) for automatic endpoint resolution across all AWS partitions (aws, aws-cn, aws-us-gov). When using a full endpoint URL instead, you must also configure AWS_REGION via environment variable or AWS config/profile.

** Azure OpenAI uses api_key when set. If api_key is omitted, the provider falls back to Microsoft Entra ID via DefaultAzureCredential (env vars, workload identity, managed identity, Azure CLI, etc.). The Entra ID path requires build tag: go build -tags azidentity.

Local deployment (Ollama, vLLM, etc.)

Ollama:

{
  "model_list": [
    {
      "model_name": "local-llama",
      "model": "ollama/llama3.1:8b",
      "api_base": "http://localhost:11434/v1"
    }
  ]
}

vLLM:

{
  "model_list": [
    {
      "model_name": "local-vllm",
      "model": "vllm/your-model",
      "api_base": "http://localhost:8000/v1"
    }
  ]
}

For full provider configuration details, see Providers & Models.

💬 Channels (Chat Apps)

Talk to your PicoClaw through 19+ messaging platforms:

Channel	Setup	Protocol	Docs
Telegram	Easy (bot token)	Long polling	Guide
Discord	Easy (bot token + intents)	WebSocket	Guide
WhatsApp	Easy (QR scan or bridge URL)	Native / Bridge	Guide
Weixin	Easy (Native QR scan)	iLink API	Guide
QQ	Easy (AppID + AppSecret)	WebSocket	Guide
Slack	Easy (bot + app token)	Socket Mode	Guide
Matrix	Medium (homeserver + token)	Sync API	Guide
DingTalk	Medium (client credentials)	Stream	Guide
Feishu / Lark	Medium (App ID + Secret)	WebSocket/SDK	Guide
LINE	Medium (credentials + webhook)	Webhook	Guide
WeCom	Easy (QR login or manual)	WebSocket	Guide
VK	Easy (group token)	Long Poll	Guide
IRC	Medium (server + nick)	IRC protocol	Guide
OneBot	Medium (WebSocket URL)	OneBot v11	Guide
MQTT	Easy (broker + agent_id)	MQTT pub/sub	Guide
MaixCam	Easy (enable)	TCP socket	Guide
Pico	Easy (enable)	Native protocol	Built-in
Pico Client	Easy (WebSocket URL)	WebSocket	Built-in

All webhook-based channels share a single Gateway HTTP server (gateway.host:gateway.port, default 127.0.0.1:18790). Feishu uses WebSocket/SDK mode and does not use the shared HTTP server.

Log verbosity is controlled by gateway.log_level (default: warn). Supported values: debug, info, warn, error, fatal. Can also be set via PICOCLAW_LOG_LEVEL. See Configuration for details.

For detailed channel setup instructions, see Chat Apps Configuration.

🔧 Tools

🔍 Web Search

PicoClaw can search the web to provide up-to-date information. Configure in tools.web:

Search Engine	API Key	Free Tier	Link
DuckDuckGo	Not needed	Unlimited	Built-in fallback
Gemini Google Search	Required	Varies	Gemini with Google Search grounding
Baidu Search	Required	1500/month (daily allocation)	AI-powered, China-optimized
Tavily	Required	1000 queries/month	Optimized for AI Agents
Brave Search	Required	2000 queries/month	Fast and private
Kagi Search	Required	Paid/limited by API setup	Premium search results
Perplexity	Required	Paid	AI-powered search
SearXNG	Not needed	Self-hosted	Free metasearch engine
GLM Search	Required	Varies	Zhipu web search

⚙️ Other Tools

PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See Tools Configuration for details.

🎯 Skills

Skills are modular capabilities that extend your Agent. They are loaded from SKILL.md files in your workspace.

Install skills from ClawHub:

picoclaw skills search "web scraping"
picoclaw skills install <skill-name>

Configure skill registries:

Add to your config.json:

{
  "tools": {
    "skills": {
      "registries": {
        "clawhub": {
          "auth_token": "your-clawhub-token"
        },
        "github": {
          "base_url": "https://github.com",
          "auth_token": "your-github-token",
          "proxy": ""
        }
      }
    }
  }
}

tools.skills.github.* is deprecated. Use tools.skills.registries.github.* instead.

For more details, see Tools Configuration - Skills.

🔗 MCP (Model Context Protocol)

PicoClaw natively supports MCP — connect any MCP server to extend your Agent's capabilities with external tools and data sources.

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        }
      }
    }
  }
}

You can manage common MCP setups directly from the CLI instead of editing JSON by hand:

picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
picoclaw mcp list
picoclaw mcp test filesystem

picoclaw mcp is a configuration manager: it updates config.json under tools.mcp.servers, but it does not keep the server process running itself.

Use picoclaw mcp edit when you need advanced fields that are not covered by picoclaw mcp add. For example, picoclaw mcp add supports --deferred and --env-file, while picoclaw mcp edit is still useful for direct JSON editing and uncommon MCP settings.

For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see Tools Configuration - MCP. For CLI usage and examples, see MCP Server CLI.

🖥️ CLI Reference

Command	Description
`picoclaw onboard`	Initialize config & workspace
`picoclaw auth weixin`	Connect WeChat account via QR
`picoclaw agent -m "..."`	Chat with the agent
`picoclaw agent`	Interactive chat mode
`picoclaw gateway`	Start the gateway
`picoclaw status`	Show status
`picoclaw version`	Show version info
`picoclaw model`	View or switch the default model
`picoclaw mcp list`	List configured MCP servers
`picoclaw mcp add ...`	Add or update an MCP server entry
`picoclaw mcp test`	Probe a configured MCP server
`picoclaw mcp edit`	Open config for advanced MCP editing
`picoclaw mcp remove`	Remove an MCP server entry
`picoclaw cron list`	List all scheduled jobs
`picoclaw cron add ...`	Add a scheduled job
`picoclaw cron disable`	Disable a scheduled job
`picoclaw cron remove`	Remove a scheduled job
`picoclaw skills list`	List installed skills
`picoclaw skills install`	Install a skill
`picoclaw migrate`	Migrate data from older versions
`picoclaw auth login`	Authenticate with providers

⏰ Scheduled Tasks / Reminders

PicoClaw supports scheduled reminders and recurring tasks through the cron tool:

One-time reminders: "Remind me in 10 minutes" -> triggers once after 10min
Recurring tasks: "Remind me every 2 hours" -> triggers every 2 hours
Cron expressions: "Remind me at 9am daily" -> uses cron expression

See docs/reference/cron.md for current schedule types, execution modes, command-job gates, and persistence details.

📚 Documentation

For detailed guides beyond this README:

Topic	Description
Docker & Quick Start	Docker Compose setup, Launcher/Agent modes
Chat Apps	All 18+ channel setup guides
Configuration	Environment variables, workspace layout, security sandbox
MCP Server CLI	Add, list, test, edit, and remove MCP server entries from the CLI
Scheduled Tasks and Cron Jobs	Cron schedule types, deliver modes, command gates, job storage
Providers & Models	30+ LLM providers, model routing, model_list configuration
Spawn & Async Tasks	Quick tasks, long tasks with spawn, async sub-agent orchestration
Hooks	Event-driven hook system: observers, interceptors, approval hooks
Steering	Inject messages into a running agent loop between tool calls
SubTurn	Subagent coordination, concurrency control, lifecycle
Troubleshooting	Common issues and solutions
Tools Configuration	Per-tool enable/disable, exec policies, MCP, Skills
Hardware Compatibility	Tested boards, minimum requirements

Contributing

This is a personal fork. Changes intended for upstream should usually be proposed to the upstream PicoClaw project. Fork-specific changes should keep this deployment focus clear and avoid adding unrelated product or community marketing back into this README.

For local development guidelines, see CONTRIBUTING.md.

Name		Name	Last commit message	Last commit date
Latest commit History 2,760 Commits
.forgeclaw		.forgeclaw
.github		.github
assets		assets
cmd		cmd
config		config
docker		docker
docs		docs
examples/pico-echo-server		examples/pico-echo-server
integration		integration
pkg		pkg
scripts		scripts
web		web
workspace		workspace
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yaml		.golangci.yaml
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
go.mod		go.mod
go.sum		go.sum

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ForgeClaw

A fast, hackable agent runtime for personal automation, MCP tools, and multi-agent workflows.

Features

Upstream

Install

Build from source

🚀 Quick Start Guide

🌐 WebUI Launcher (Recommended for Desktop)

📱 Android

🔌 Providers (LLM)

💬 Channels (Chat Apps)

🔧 Tools

🔍 Web Search

⚙️ Other Tools

🎯 Skills

🔗 MCP (Model Context Protocol)

🖥️ CLI Reference

⏰ Scheduled Tasks / Reminders

📚 Documentation

Contributing

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

ForgeClaw

A fast, hackable agent runtime for personal automation, MCP tools, and multi-agent workflows.

Features

Upstream

Install

Build from source

🚀 Quick Start Guide

🌐 WebUI Launcher (Recommended for Desktop)

📱 Android

🔌 Providers (LLM)

💬 Channels (Chat Apps)

🔧 Tools

🔍 Web Search

⚙️ Other Tools

🎯 Skills

🔗 MCP (Model Context Protocol)

🖥️ CLI Reference

⏰ Scheduled Tasks / Reminders

📚 Documentation

Contributing

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages