PicoClaw Agent

PicoClaw is a lightweight personal AI assistant and agent framework with a native CLI, chat gateway, MCP integration, installable skills, session routing, scheduled jobs, and self-evolution.

Use this skill when the job is about PicoClaw itself: onboarding, configuration, debugging, adding features, extending the CLI, changing routing/session behavior, working on skills or MCP support, or contributing to this repository.

Operating Stance

When this skill is active, stay fully subordinate to PicoClaw's real architecture:

• Prefer PicoClaw commands, config keys, workspace layout, and docs.
• Follow PicoClaw source and docs for behavior, naming, and workflows.
• Treat repository code and checked-in docs as the source of truth.

Quick Start

# Initialize ~/.picoclaw/config.json and ~/.picoclaw/workspace
picoclaw onboard

# Authenticate a provider
picoclaw auth login --provider openai

# Inspect or switch the default model
picoclaw model
picoclaw model my-default-model

# One-shot prompt
picoclaw agent -m "Hello"

# Interactive CLI chat
picoclaw agent

# Start the gateway for chat channels
picoclaw gateway

# Inspect runtime/config health
picoclaw status

# Explore installed skills and MCP servers
picoclaw skills list
picoclaw mcp list

Command Surface

Core CLI

picoclaw onboard
picoclaw agent [-m MESSAGE] [--session KEY] [--model MODEL] [--debug]
picoclaw gateway [--debug] [--no-truncate] [--allow-empty] [--host HOST]
picoclaw status
picoclaw version
picoclaw migrate

Configuration and Models

# Show or change the default configured model alias
picoclaw model
picoclaw model <model_name>

# Add a model from an OpenAI-compatible endpoint
picoclaw model add --api-base URL --api-key KEY
picoclaw model add -b http://localhost:8000/v1 -k dummy -m my-model -n local

# Reset config to factory defaults (preserves sensitive keys)
picoclaw config reset
picoclaw config reset --force

Notes:

• There is no general picoclaw config edit or picoclaw config set.
• Advanced edits are usually done by editing ~/.picoclaw/config.json directly.

Authentication

picoclaw auth login --provider openai
picoclaw auth login --provider anthropic --setup-token
picoclaw auth login --provider antigravity --device-code
picoclaw auth models
picoclaw auth status
picoclaw auth logout --provider openai
picoclaw auth weixin
picoclaw auth wecom --timeout 10m

Skills

picoclaw skills list
picoclaw skills show <name>
picoclaw skills search "query"
picoclaw skills install owner/repo/path
picoclaw skills install --registry clawhub <slug>
picoclaw skills remove <name>
picoclaw skills list-builtin
picoclaw skills install-builtin

Skill loading priority is:

1. ~/.picoclaw/workspace/skills
2. ~/.picoclaw/skills
3. builtin embedded skills

MCP

picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
picoclaw mcp add --deferred github --env-file .env.github -- npx -y @modelcontextprotocol/server-github
picoclaw mcp list
picoclaw mcp list --status
picoclaw mcp show github
picoclaw mcp test github
picoclaw mcp edit
picoclaw mcp remove github

Notes:

• picoclaw mcp is a configuration manager for tools.mcp.servers.
• It does not keep servers running by itself; the host/gateway loads them later.

Cron

picoclaw cron list
picoclaw cron add --name "Daily summary" --message "Summarize today's logs" --cron "0 18 * * *"
picoclaw cron add --name "Ping" --message "heartbeat" --every 300 --deliver
picoclaw cron enable <job-id>
picoclaw cron disable <job-id>
picoclaw cron remove <job-id>

Notes:

• The current CLI picoclaw cron add supports recurring jobs only: --every or --cron.
• One-shot at_seconds jobs exist in the cron system, but not as a first-class CLI flag today.

Providers

PicoClaw supports 30+ LLM providers through model_list.

Credential patterns in PicoClaw are:

• model_list[].api_keys for most hosted APIs
• picoclaw auth login --provider ... for the built-in auth helper flows (openai, anthropic, antigravity)
• local or self-hosted endpoints for providers like ollama, lmstudio, vllm, and litellm
• external platform credentials for providers like bedrock, azure, and github-copilot

picoclaw auth login does not cover every provider. For most providers, the normal path is adding a model_list entry with provider, model, and api_keys.

Common Provider Matrix

Additional OpenAI-Compatible Vendors

PicoClaw also carries first-class metadata or routing support for additional vendors such as:

• venice
• vivgrid
• longcat
• modelscope
• mimo
• novita
• byteplus
• shengsuanyun
• avian
• zai-coding
• gpt4free

For the full provider matrix, default API bases, protocol families, and vendor-specific examples, read docs/guides/providers.md.

Built-in Tool Families

PicoClaw tools are configured under tools in config.json and registered dynamically at runtime.

Important activation rules:

• most tools are enabled or disabled individually through tools.*
• agent-level allowlists can further restrict tool visibility
• turn_profile.tools can narrow tool exposure for a request or agent
• deferred MCP tools can stay hidden until unlocked by tool discovery

Runtime Tool Families

Tool Registration Notes

• send_tts is registered only when a TTS provider is available.
• spawn and spawn_status require subagent support to be enabled.
• delegate is auto-registered only when more than one agent exists.
• MCP discovery tools are relevant only when deferred MCP discovery is enabled.
• message can be configured for outbound media as well as plain text.

For per-tool configuration, read docs/reference/tools_configuration.md.

Specialized Subagents and Spawn

PicoClaw has a first-class subagent model for long-running work, isolated subproblems, and multi-agent specialization.

The core idea is:

• use spawn for background work that should continue without blocking the current turn
• use subagent for an isolated synchronous sub-task when the parent needs the result now
• use delegate to hand a task to a specific peer agent with its own identity, model, workspace, and tools
• use spawn_status or /subagents to inspect what is currently running

Choosing the Right Subagent Tool

Specialized Peer Agents

Specialized subagents are configured through the multi-agent system, not through ad hoc prompts alone.

The two important layers are:

• config.json defines which peer agents exist and which ones a given agent is allowed to spawn via subagents.allow_agents
• each agent's AGENT.md defines the identity that makes that peer worth spawning: name, description, tools, skills, MCP servers, and optional model overrides

Minimal shape:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "subagents": {
          "allow_agents": ["research"]
        }
      },
      {
        "id": "research"
      }
    ]
  }
}

Example AGENT.md for a specialist:

---
name: Research Agent
description: Specialist for deep web research, evidence gathering, and synthesis.
tools: [web_search, web_fetch, message]
skills: [deep-research]
---

Automatic Agent Discovery

When an agent has the spawn tool and at least one allowed peer, PicoClaw injects a lightweight agent registry into the system prompt automatically.

That means:

• the model can see eligible peer agents without calling a separate list_agents tool
• only spawnable peers are shown
• the current agent is omitted
• discovery uses the peer agent's stable id, name, and description

In practice, this is what makes targeted spawn(..., agent_id="research") or delegate(agent_id="research", ...) reliable.

Operational Behavior

Subagent execution semantics that matter:

• subagents run in isolated ephemeral session history, so their reasoning and intermediate steps do not pollute the parent conversation
• spawn returns immediately and launches background work in a goroutine
• subagent waits for completion and returns the result directly
• delegate is synchronous and runs as the target peer agent instead of a generic child task
• spawn_status is scoped to the current conversation when channel/chat context exists
• all subagents still share the same workspace security boundary; they do not bypass sandbox or path restrictions

Runtime limits and lifecycle rules:

• nested sub-turn depth is limited to 3
• concurrency is limited to 5 sub-turns per parent turn
• waiting for a concurrency slot times out after 30 seconds
• spawned background tasks are marked critical so they can survive graceful parent completion
• hard aborts still cascade to child and grandchild sub-turns

Practical Patterns

Use spawn when:

• the task will take a while
• the result can arrive later
• the current turn should keep moving

Use subagent when:

• you need isolation from the parent context
• you want an independent attempt at a bounded subproblem
• the parent must wait for the answer before planning the next step

Use delegate when:

• a named peer agent is clearly better suited for the task
• that peer has a narrower tool/skill/model setup
• you want the task to run in the peer's own workspace/runtime identity

Examples

Background specialist research:

spawn(
  task="Search the web for the latest PicoClaw MCP integration patterns and summarize them.",
  label="mcp-research",
  agent_id="research"
)

Synchronous isolated check:

subagent(
  task="Review this config for risky tool exposure and return only the concrete findings."
)

Synchronous handoff to a named peer:

delegate(
  agent_id="research",
  task="Collect three primary-source references for current provider authentication behavior."
)

Observability

For live visibility:

• call spawn_status to inspect one task or list visible tasks in the current conversation
• use /subagents in chat channels to show the active subagent tree for the current session

Voice, Transcription, and TTS

PicoClaw can transcribe inbound audio and synthesize outbound speech, but voice setup is model-driven like the rest of the runtime.

The important pattern is:

• ASR uses voice.model_name
• TTS uses voice.tts_model_name
• both resolve through named entries in model_list
• secrets belong in .security.yml, not inline in voice

STT (Voice -> Text)

Voice and audio messages from supported channels can be transcribed automatically at the agent level.

Recommended setup:

1. add an ASR-capable model entry to model_list
2. set voice.model_name to that entry's model_name
3. store the matching API key in .security.yml
4. optionally set voice.echo_transcription if you want the transcript echoed back in chat

Example:

{
  "model_list": [
    {
      "model_name": "voice-groq",
      "model": "groq/whisper-large-v3-turbo"
    }
  ],
  "voice": {
    "model_name": "voice-groq",
    "echo_transcription": true
  }
}

model_list:
  voice-groq:
    api_keys:
      - "gsk_your_groq_key"

Common ASR Routes

Detection behavior that matters:

• voice.model_name is the preferred and recommended path
• if it resolves to an ElevenLabs model, PicoClaw uses the ElevenLabs transcriber
• if it resolves to a Whisper-compatible model, PicoClaw uses the Whisper transcription path
• if it resolves to an audio-capable multimodal model, PicoClaw can use audio-model transcription
• if voice.model_name is omitted, PicoClaw still performs compatibility scanning across model_list for legacy auto-detected ASR entries

TTS (Text -> Voice)

Outbound speech is driven by voice.tts_model_name and exposed through send_tts when a provider is available.

Recommended setup:

1. add a TTS-capable model entry to model_list
2. set voice.tts_model_name to that entry's model_name
3. store the API key in .security.yml
4. if the provider needs model-specific TTS fields, add them under model_list[].extra_body
5. enable send_tts in the tool configuration if you want the agent to emit speech files

Example:

{
  "model_list": [
    {
      "model_name": "openai-tts",
      "model": "openai/tts-1"
    }
  ],
  "voice": {
    "tts_model_name": "openai-tts"
  }
}

model_list:
  openai-tts:
    api_keys:
      - "sk-openai-your-key"

Example with OpenRouter MAI Voice 2:

{
  "model_list": [
    {
      "model_name": "mai-voice-2",
      "provider": "openrouter",
      "model": "microsoft/mai-voice-2",
      "api_base": "https://openrouter.ai/api/v1",
      "extra_body": {
        "voice": "en-US-Harper:MAI-Voice-2",
        "response_format": "mp3"
      }
    }
  ],
  "voice": {
    "tts_model_name": "mai-voice-2"
  }
}

model_list:
  mai-voice-2:
    api_keys:
      - "sk-or-your-openrouter-key"

Current TTS Provider Paths

Operational notes:

• the preferred selection path is voice.tts_model_name
• if that is missing, PicoClaw can still scan model_list for the first API-backed model whose ID contains tts
• the current OpenAI-style TTS request defaults to voice: alloy and response_format: opus
• you can override voice and response_format for a specific TTS model through model_list[].extra_body
• if a provider rejects response_format, PicoClaw retries once without that field
• send_tts is only registered when TTS detection succeeds

In-Session Slash Commands

PicoClaw's shared slash command registry lives under pkg/commands.

Use these when helping users inside chat channels:

/start
/help
/show model
/show channel
/show agents
/show mcp <server>
/list models
/list channels
/list agents
/list skills
/list mcp
/subagents
/use <skill> [message]
/use clear
/btw <question>

Semantics that matter:

• /use <skill> <message> forces one installed skill for a single request.
• /use <skill> arms that skill for the next message in the same chat session.
• /use clear cancels the pending skill override.
• /btw <question> asks an isolated side question without mutating the main session history.
• /subagents shows the currently active subagent tree for the session.
• Unknown slash commands pass through to normal LLM handling instead of hard-failing.

Telegram auto-registers supported top-level commands like /start, /help, /show, /list, /use, and /btw.

Key Paths and Environment

Important Files

~/.picoclaw/config.json          Main config
~/.picoclaw/.security.yml       Sensitive values stored outside config.json
~/.picoclaw/auth.json           OAuth/token store
~/.picoclaw/workspace/          Default workspace
~/.picoclaw/workspace/skills/   Workspace skills
~/.picoclaw/workspace/sessions/ Session history
~/.picoclaw/workspace/cron/     Scheduled jobs store

Default workspace layout:

~/.picoclaw/workspace/
├── sessions/
├── memory/
├── state/
├── cron/
├── skills/
├── AGENT.md
├── HEARTBEAT.md
├── IDENTITY.md
├── SOUL.md
└── USER.md

Important Environment Variables

PICOCLAW_CONFIG=/path/to/config.json
PICOCLAW_HOME=/path/to/picoclaw-home
PICOCLAW_BUILTIN_SKILLS=/path/to/custom-builtin-skills
PICOCLAW_LOG_LEVEL=debug
PICOCLAW_GATEWAY_HOST=0.0.0.0

Use PICOCLAW_CONFIG when the user reports "wrong config file" behavior. Use PICOCLAW_HOME when the user wants a portable or service-managed install.

PicoClaw-Native Concepts

Model Configuration

PicoClaw is model-centric. The key fields are:

• agents.defaults.model_name
• model_list
• optional provider
• runtime model

Important behavior:

• agents.defaults.model_name must match a model_name entry in model_list.
• If provider is set, PicoClaw sends model to that provider unchanged.
• If provider is omitted, legacy provider/model parsing is still supported.

Sessions and Routing

Session behavior is configured primarily through:

• session.dimensions
• session.identity_links
• agents.dispatch.rules[*].session_dimensions

Available dimensions:

• space
• chat
• topic
• sender

Baseline separation still includes:

• agent
• channel
• account

So even a tiny session.dimensions list does not create one giant global memory across every platform.

Skills

Skills are plain directories with SKILL.md. The loader requires:

• a valid lowercase-or-hyphen skill name
• a non-empty description
• a SKILL.md file in the skill directory

Prefer this format:

workspace/skills/<skill-name>/SKILL.md

PicoClaw only relies on name and description frontmatter fields for loading and matching.

MCP Discovery

PicoClaw supports always-loaded and deferred MCP tools.

Use:

• --deferred when tools should stay hidden until explicitly discovered
• picoclaw mcp show <name> to inspect active tools
• /list mcp and /show mcp <server> from chat channels when debugging live agents

Self-Evolution

The evolution block controls self-evolution:

• enabled
• mode: observe, draft, apply
• state_dir
• min_task_count
• min_success_ratio
• cold_path_trigger
• cold_path_times

Use observe first. Use draft when the team wants reviewable candidate skill changes. Use apply only when automatic workspace skill updates are acceptable.

Notes:

• cold_path_trigger: manual has no general user-facing CLI/API trigger yet.

Debugging Workflow

Start with the most PicoClaw-native path:

1. Check picoclaw status.
2. Confirm which config file is active.
3. Inspect agents.defaults.model_name and model_list.
4. Run picoclaw gateway --debug for runtime visibility.
5. Add --no-truncate only when full prompt or tool payload inspection is necessary.
6. For skill issues, inspect the skill directory and frontmatter.
7. For MCP issues, use picoclaw mcp list, show, and test.
8. For routing/session issues, inspect session.dimensions and agents.dispatch.rules.

Useful runtime facts:

• --no-truncate only works with --debug.
• gateway health endpoints expose /health, /ready, and /reload.
• tool_feedback can publish visible tool-execution notices directly into chats.

Where to Find Logs

For gateway and runtime debugging, PicoClaw writes logs under its home directory:

~/.picoclaw/logs/gateway.log
~/.picoclaw/logs/gateway_panic.log

If PICOCLAW_HOME is overridden, use:

$PICOCLAW_HOME/logs/gateway.log
$PICOCLAW_HOME/logs/gateway_panic.log

In practice, check these places first:

• ~/.picoclaw/logs/ for persisted gateway logs
• the terminal running picoclaw gateway or picoclaw agent
• Docker stdout/stderr via docker compose -f docker/docker-compose.yml logs -f
• launcher or service logs if PicoClaw is being run under another supervisor

Useful controls:

• picoclaw gateway --debug for detailed runtime logs
• picoclaw gateway --debug --no-truncate for full prompt/tool payload inspection
• gateway.log_level or PICOCLAW_LOG_LEVEL to raise verbosity to debug or info

Special case:

• the standalone picoclaw agent command uses console logging unless PICOCLAW_LOG_FILE is set explicitly
• process hooks can write JSONL file logs when PICOCLAW_HOOK_LOG_FILE is set; this is hook-specific and separate from the main gateway log path

Repository Map

When contributing code, these paths matter most:

• cmd/picoclaw/main.go — root CLI wiring
• cmd/picoclaw/internal/agent/ — direct CLI agent command
• cmd/picoclaw/internal/gateway/ — gateway startup and flags
• cmd/picoclaw/internal/auth/ — auth flows, QR onboarding
• cmd/picoclaw/internal/model/ — default model switching and model add
• cmd/picoclaw/internal/skills/ — install/list/show/remove/search commands
• cmd/picoclaw/internal/mcp/ — MCP CLI configuration manager
• cmd/picoclaw/internal/cron/ — cron CLI
• pkg/commands/ — shared slash command registry
• pkg/agent/ — prompt assembly, sessions, routing, tool execution, hooks
• pkg/skills/ — skill loading, metadata, registry installs
• pkg/mcp/ — MCP runtime integration
• pkg/config/ — config schema, defaults, migration, persistence
• docs/guides/configuration.md — user-facing config reference
• docs/guides/session-guide.md — session behavior recipes
• docs/reference/mcp-cli.md — authoritative MCP CLI behavior
• docs/reference/cron.md — cron behavior and limitations
• docs/operations/debug.md — debugging workflow
• docs/operations/troubleshooting.md — known misconfiguration patterns
• docs/architecture/agent-self-evolution.md — evolution design and safety

Contribution Rules

When changing PicoClaw:

• Prefer extending existing CLI groups and shared registries instead of adding parallel one-off flows.
• Keep docs aligned with code for CLI flags, slash commands, and config behavior.
• If you add or change a slash command, inspect pkg/commands and the chat-channel docs that mention command availability.
• If you touch skills behavior, validate load order, naming rules, and frontmatter assumptions.
• If you touch routing or session logic, re-check both docs/guides/session-guide.md and architecture docs so behavior and docs stay consistent.
• If you touch MCP, remember the CLI manages config while the runtime host manages execution.

Common Troubleshooting

"model ... not found in model_list"

Check that:

• agents.defaults.model_name matches a configured model_name
• the target model_list entry is enabled
• the provider and model fields use PicoClaw's model-centric rules

OpenRouter free is not a valid model ID

Prefer explicit provider config:

{
  "provider": "openrouter",
  "model": "free"
}

Not:

{
  "model": "free"
}

Skill not appearing

Check:

• directory name is a valid skill name
• SKILL.md exists
• frontmatter name and description are present and sane
• the skill lives under workspace, global, or builtin roots

MCP server exists but tools do not show up

Check:

• tools.mcp.enabled is true
• the server is enabled
• deferred discovery settings match expectations
• picoclaw mcp test <name> succeeds
• /show mcp <server> or picoclaw mcp show <name> exposes tools

Agent remembers too much or too little

Check:

• session.dimensions
• any per-rule session_dimensions
• whether the issue is really session isolation versus summarization

Config edits do not seem to apply

Check:

• PICOCLAW_CONFIG
• PICOCLAW_HOME
• whether the user edited config.json or .security.yml
• whether they are testing the CLI path, gateway path, or both

Load These Docs Next

Read these only when the task needs them:

• docs/guides/configuration.md for config, routing, skills, turn profiles, and evolution
• docs/guides/session-guide.md for session isolation recipes
• docs/reference/tools_configuration.md for tool-specific config
• docs/reference/mcp-cli.md for MCP CLI flags and storage behavior
• docs/reference/cron.md for schedule types and security gates
• docs/operations/debug.md for runtime inspection
• docs/operations/troubleshooting.md for common provider/model mistakes

If the task is code-level rather than user-facing, read the matching package under cmd/picoclaw/internal/, pkg/commands/, pkg/agent/, pkg/skills/, or pkg/mcp/ before proposing behavior changes.