picoclaw-agent · diff
git:20261004.911e913 to git:20261006.e43d0e2
26 added, 1001 removed. Audit A to A.
---
name: picoclaw-agent
- description: "Configure, extend, debug, or contribute to PicoClaw itself. Use when the task is about PicoClaw CLI commands, config.json, gateway, auth, models, skills, MCP servers, cron, routing, sessions, self-evolution, built-in slash commands, or repository internals. Use PicoClaw-native workflows, terminology, paths, and configuration."
+ description: "Configure, extend, debug, or contribute to PicoClaw itself. Use for PicoClaw CLI, configuration, providers, channels, tools, MCP, agent runtime, skills, sessions, routing, cron, or repository internals. Follow the repository documentation and source of truth."
metadata: {"nanobot":{"emoji":"🦞"}}
---
# 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
-
- ```bash
- # 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
-
- ```bash
- picoclaw onboard
- picoclaw agent [-m MESSAGE] [--session KEY] [--model MODEL] [--debug]
- picoclaw gateway [--debug] [--no-truncate] [--allow-empty] [--host HOST]
- picoclaw status
- picoclaw update
- picoclaw version
- picoclaw migrate
- ```
-
- `picoclaw update` installs the latest stable release from this repository's
- GitHub Releases. Restart the process after it reports success.
-
- ### Configuration and Models
-
- ```bash
- # 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
-
- ```bash
- 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
-
- ```bash
- 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
-
- ```bash
- 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
-
- ```bash
- 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
-
- | Provider | `provider` value | Auth path in PicoClaw |
- | --- | --- | --- |
- | OpenAI | `openai` | OAuth helper via `picoclaw auth login --provider openai`, or `model_list[].api_keys` |
- | Anthropic | `anthropic` | API key in `model_list[].api_keys`, or helper flow via `picoclaw auth login --provider anthropic` |
- | Anthropic Messages API | `anthropic-messages` | API key in `model_list[].api_keys` |
- | Google Gemini | `gemini` | API key in `model_list[].api_keys` |
- | OpenRouter | `openrouter` | API key in `model_list[].api_keys` |
- | Zhipu / GLM | `zhipu` | API key in `model_list[].api_keys` |
- | DeepSeek | `deepseek` | API key in `model_list[].api_keys` |
- | VolcEngine / Doubao | `volcengine` | API key in `model_list[].api_keys` |
- | Qwen / DashScope | `qwen` | API key in `model_list[].api_keys` |
- | Moonshot / Kimi | `moonshot` | API key in `model_list[].api_keys` |
- | MiniMax | `minimax` | API key in `model_list[].api_keys` |
- | Mistral | `mistral` | API key in `model_list[].api_keys` |
- | Groq | `groq` | API key in `model_list[].api_keys` |
- | NVIDIA NIM | `nvidia` | API key in `model_list[].api_keys` |
- | Cerebras | `cerebras` | API key in `model_list[].api_keys` |
- | Azure OpenAI | `azure` | `api_key` in `model_list`, or Microsoft Entra ID if built with `azidentity` support |
- | AWS Bedrock | `bedrock` | AWS credentials plus Bedrock-enabled build (`go build -tags bedrock`) |
- | Antigravity | `antigravity` | OAuth helper via `picoclaw auth login --provider antigravity` |
- | GitHub Copilot | `github-copilot` | External Copilot gRPC endpoint, default `localhost:4321` |
- | Ollama | `ollama` | Local endpoint, no API key required |
- | LM Studio | `lmstudio` | Local endpoint, API key optional |
- | vLLM | `vllm` | Local OpenAI-compatible endpoint |
- | LiteLLM | `litellm` | Proxy endpoint and whichever credential model the proxy expects |
- | Claude CLI | `claude-cli` | Local Claude CLI provider, configured by workspace/runtime |
- | Codex CLI | `codex-cli` | Local Codex CLI provider, configured by workspace/runtime |
-
- ### 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
-
- | Family | Runtime tool names | What they provide |
- | --- | --- | --- |
- | Filesystem | `read_file`, `write_file`, `list_dir`, `search_files`, `edit_file`, `append_file` | Read, search, write, list, and patch workspace files |
- | Web | `web_search`, `web_fetch` | Search the web and fetch readable page content |
- | Command execution | `exec` | Shell command execution with deny-pattern guardrails |
- | Scheduling | `cron` | Scheduled jobs, reminders, recurring tasks, and command jobs |
- | Planning | `todo` | Maintain a session-scoped task checklist |
- | Skills registry | `find_skills`, `install_skill` | Search and install skills from configured registries |
- | MCP | `mcp_<server>_<tool>` | Tools contributed by connected MCP servers |
- | MCP discovery | `tool_search_tool_bm25`, `tool_search_tool_regex` | Discover deferred hidden MCP tools on demand |
- | Hardware | `i2c`, `spi`, `serial` | Hardware access for supported devices and boards |
- | Messaging | `message`, `reaction` | Send outbound messages and reactions through channel integrations |
- | Media | `send_file`, `load_image`, `send_tts`, `image_generate` | Send files, load local images into context, synthesize speech, and generate images |
- | Subagents | `spawn`, `subagent`, `spawn_status`, `delegate` | Background tasks, synchronous sub-turns, task status, multi-agent delegation |
-
- ### 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`.
-
- ### Search, planning, and image generation
-
- `search_files` is enabled by default and searches file contents with a regular
- expression or filenames with a glob. It searches only the configured readable
- filesystem sandbox (`restrict_to_workspace`, `allow_read_paths`). Use the tool's
- `target: "content"` or `target: "files"`; `file_glob`, `output_mode`, `context`,
- `limit`, and `offset` narrow or paginate results. Keep it in an agent's
- `AGENT.md` tool allowlist if that file explicitly restricts tools.
-
- `todo` is also enabled by default. It reads or replaces the current agent and
- chat-session plan; a write replaces the whole list, and `todos: []` clears it.
- Plans survive turns and conversation compaction but are in memory only, so a
- process restart or config reload clears them. It neither runs nor schedules
- tasks. Explicit tool allowlists must include `todo`.
-
- Image generation is opt-in. Add an image-capable model to `model_list`, store
- its key in `.security.yml`, then select the model alias in `tools.image_generate`:
-
- ```json
- {
- "model_list": [
- {
- "model_name": "muse-image",
- "provider": "openrouter",
- "model": "meta/muse-image",
- "api_base": "https://openrouter.ai/api/v1"
- }
- ],
- "tools": {
- "image_generate": {"enabled": true, "model_name": "muse-image"}
- }
- }
- ```
-
- ```yaml
- model_list:
- muse-image:
- api_keys: ["YOUR_OPENROUTER_API_KEY"]
- ```
-
- OpenAI, Gemini, and OpenRouter image models are supported. The generated image
- is sent to the current chat. OpenAI and Gemini accept `aspect_ratio`;
- OpenRouter uses the model's default image shape. See
- `docs/tools/image-generation.md` for supported models and details.
-
- ## 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
-
- | Tool | Execution style | Best use |
- | --- | --- | --- |
- | `spawn` | Async background task | Web research, API polling, long scans, work that can report back later |
- | `subagent` | Sync isolated sub-turn | Focused analysis, transformation, or verification that must return before the parent continues |
- | `delegate` | Sync handoff to named peer agent | Work that should run as a specialized agent rather than as a generic child turn |
- | `spawn_status` | Inspection/status only | Check running, completed, failed, or canceled spawned tasks |
-
- ### 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:
-
- ```json
- {
- "agents": {
- "list": [
- {
- "id": "main",
- "default": true,
- "subagents": {
- "allow_agents": ["research"]
- }
- },
- {
- "id": "research"
- }
- ]
- }
- }
- ```
-
- Example `AGENT.md` for a specialist:
-
- ```md
- ---
- 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:
-
- ```text
- spawn(
- task="Search the web for the latest PicoClaw MCP integration patterns and summarize them.",
- label="mcp-research",
- agent_id="research"
- )
- ```
-
- Synchronous isolated check:
-
- ```text
- subagent(
- task="Review this config for risky tool exposure and return only the concrete findings."
- )
- ```
-
- Synchronous handoff to a named peer:
-
- ```text
- 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:
-
- ```json
- {
- "model_list": [
- {
- "model_name": "voice-groq",
- "model": "groq/whisper-large-v3-turbo"
- }
- ],
- "voice": {
- "model_name": "voice-groq",
- "echo_transcription": true
- }
- }
- ```
-
- ```yaml
- model_list:
- voice-groq:
- api_keys:
- - "gsk_your_groq_key"
- ```
-
- ### Common ASR Routes
-
- | Route | Example model | Notes |
- | --- | --- | --- |
- | Groq Whisper | `groq/whisper-large-v3-turbo` | Fast OpenAI-compatible Whisper transcription and a common default choice |
- | OpenAI Whisper | `openai/whisper-1` | Standard Whisper transcription through the OpenAI-compatible audio endpoint |
- | ElevenLabs Scribe | `provider: elevenlabs`, `model: scribe_v1` | Uses PicoClaw's dedicated ElevenLabs transcription path |
- | Audio-capable chat models | `gemini/gemini-2.5-flash`, `openai/gpt-4o-audio-preview` | Multimodal audio transcription path; some model combinations are still evolving |
-
- 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:
-
- ```json
- {
- "model_list": [
- {
- "model_name": "openai-tts",
- "model": "openai/tts-1"
- }
- ],
- "voice": {
- "tts_model_name": "openai-tts"
- }
- }
- ```
-
- ```yaml
- model_list:
- openai-tts:
- api_keys:
- - "sk-openai-your-key"
- ```
-
- Example with OpenRouter MAI Voice 2:
-
- ```json
- {
- "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"
- }
- }
- ```
-
- ```yaml
- model_list:
- mai-voice-2:
- api_keys:
- - "sk-or-your-openrouter-key"
- ```
-
- ### Current TTS Provider Paths
-
- | Provider path | Example model | Notes |
- | --- | --- | --- |
- | OpenAI-compatible speech | `openai/tts-1` | Best-supported path; PicoClaw sends an OpenAI-style `/audio/speech` request |
- | Xiaomi MiMo | `mimo/mimo-v2-tts` | Dedicated MiMo TTS provider path with MP3 output |
-
- 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
- - automatic voice mode also requires `tools.send_tts.enabled: true`
-
- ### Automatic voice replies
-
- In a chat session, `/voice status` shows its current mode. Use `/voice on` to
- send synthesized speech when replying to an audio message, `/voice tts` to
- synthesize every reply, and `/voice off` to stop. Configure a working TTS
- model under `voice.tts_model_name` and enable `tools.send_tts` first. The mode
- is session-scoped and is not persisted across process restarts.
-
-
- ## In-Session Slash Commands
-
- PicoClaw's shared slash command registry lives under `pkg/commands`.
-
- Use these when helping users inside chat channels:
-
- ```text
- /start
- /help
- /show model
- /show channel
- /show agents
- /show mcp <server>
- /list models
- /list channels
- /list agents
- /list skills
- /list mcp
- /subagents
- /voice [off|on|tts|status]
- /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.
- - `/voice` controls automatic TTS for the current chat session; see
- [Automatic voice replies](#automatic-voice-replies).
- - 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
-
- ```text
- ~/.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:
-
- ```text
- ~/.picoclaw/workspace/
- ├── sessions/
- ├── memory/
- ├── state/
- ├── cron/
- ├── skills/
- ├── AGENT.md
- ├── HEARTBEAT.md
- ├── IDENTITY.md
- ├── SOUL.md
- └── USER.md
- ```
-
- ### Important Environment Variables
-
- ```bash
- 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:
-
- ```text
- 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.
-
- ### Repeated tool-call detection
-
- Enable the per-turn guard under `agents.defaults.loop_detection` to warn on
- repeated identical tool calls and stop a sustained loop:
-
- ```json
- {
- "agents": {
- "defaults": {
- "loop_detection": {
- "enabled": true,
- "repeat_threshold": 3,
- "critical_threshold": 6,
- "window_size": 20
- }
- }
- }
- }
- ```
-
- Defaults are disabled, warning at 3 repeats, stopping at 6, with a history
- window of 20. Calls count as identical only when both tool name and complete
- arguments match. This complements `max_tool_iterations`; see
- `docs/guides/configuration.md` for the details.
-
- ### Low-power profile
-
- For constrained devices, enable the static profile in `config.json`:
-
- ```json
- {
- "power": {
- "low_power": true,
- "low_power_heartbeat_interval": 120,
- "poll_interval_multiplier": 5
- }
- }
- ```
-
- It lengthens heartbeat and maintenance polling intervals and lets the agent
- wait for inbound events instead of waking every 100 ms. Protocol keepalives
- remain active. These settings can also be supplied through
- `PICOCLAW_POWER_LOW_POWER`, `PICOCLAW_POWER_LOW_POWER_HEARTBEAT_INTERVAL`, and
- `PICOCLAW_POWER_POLL_INTERVAL_MULTIPLIER`.
-
- ### Bounded log files
-
- Gateway and file logs rotate at 2 MiB by default and keep 3 backups. Configure
- `gateway.log_max_size_mb` (1–1024) and `gateway.log_max_backups` (0–100; zero
- keeps no archives). The limits also apply to heartbeat and `PICOCLAW_LOG_FILE`
- logs; restart the gateway after changing them. Environment overrides are
- `PICOCLAW_GATEWAY_LOG_MAX_SIZE_MB` and
- `PICOCLAW_GATEWAY_LOG_MAX_BACKUPS`.
-
- ### Web UI conversation forks
-
- In the Web UI, choose **Fork from this message** on an assistant reply to open a
- new session containing the conversation through that reply. A fork label links
- back to its source session. Long histories load in pages as the user scrolls;
- neither feature needs configuration.
-
- ## 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:
-
- ```text
- ~/.picoclaw/logs/gateway.log
- ~/.picoclaw/logs/gateway_panic.log
- ```
-
- If `PICOCLAW_HOME` is overridden, use:
-
- ```text
- $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/guides/custom-builds.md` — selective channel builds and omitting Seahorse
- - `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.
-
- ### Custom channel builds
-
- Build tags can omit unused channel drivers and optionally Seahorse. For
- example, build a Telegram-only executable without Seahorse with:
-
- ```bash
- make build GO_BUILD_TAGS='goolm,stdjson,custom_channels,channel_telegram,no_seahorse'
- ```
-
- `custom_channels` replaces the default channel set; each desired driver needs
- its `channel_<name>` tag, and omitted drivers cannot be enabled later through
- config. Read `docs/guides/custom-builds.md` for the full tag list and platform
- notes. Custom WhatsApp Native builds need both `channel_whatsapp_native` and
- `whatsapp_native`.
-
- ## 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:
-
- ```json
- {
- "provider": "openrouter",
- "model": "free"
- }
- ```
-
- Not:
-
- ```json
- {
- "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:
+ Use this skill for work on PicoClaw or this repository.
- - `PICOCLAW_CONFIG`
- - `PICOCLAW_HOME`
- - whether the user edited `config.json` or `.security.yml`
- - whether they are testing the CLI path, gateway path, or both
+ ## Working rules
- ## Load These Docs Next
+ - Treat the [repository README](https://github.com/afjcjsbx/picoclaw/blob/main/README.md), [documentation index](https://github.com/afjcjsbx/picoclaw/blob/main/docs/README.md), and current source as the source of truth.
+ - Do not restate or copy documentation into answers, prompts, or new docs. Read the relevant page and link to it.
+ - For code changes, trace the existing implementation and callers before editing. If docs do not cover a behavior, inspect the relevant package and say so instead of guessing.
+ - Prefer links below; for channel-specific behavior, follow the channel guide to `docs/channels/<name>/README.md`.
- Read these only when the task needs them:
+ ## Documentation map
- - `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/guides/custom-builds.md` for channel selection and reduced binaries
- - `docs/operations/debug.md` for runtime inspection
- - `docs/operations/troubleshooting.md` for common provider/model mistakes
+ | Topic | Canonical reference |
+ | --- | --- |
+ | Getting started, CLI, project overview | [README](https://github.com/afjcjsbx/picoclaw/blob/main/README.md), [Docker and quick start](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/docker.md) |
+ | Configuration, environment, workspace, routing, sandbox | [Configuration guide](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/configuration.md) |
+ | Secrets and credential storage | [Security configuration](https://github.com/afjcjsbx/picoclaw/blob/main/docs/security/security_configuration.md), [credential encryption](https://github.com/afjcjsbx/picoclaw/blob/main/docs/security/credential_encryption.md) |
+ | Config migrations and schema changes | [Config versioning](https://github.com/afjcjsbx/picoclaw/blob/main/docs/reference/config-versioning.md), [model-list migration](https://github.com/afjcjsbx/picoclaw/blob/main/docs/migration/model-list-migration.md) |
+ | Providers, model list, model routing, voice models | [Providers and models](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/providers.md), [Antigravity setup](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/ANTIGRAVITY_USAGE.md), [rate limiting](https://github.com/afjcjsbx/picoclaw/blob/main/docs/reference/rate-limiting.md) |
+ | Channels, gateway, platform setup | [Chat apps guide](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/chat-apps.md); channel-specific docs live under [`docs/channels/`](https://github.com/afjcjsbx/picoclaw/tree/main/docs/channels) |
+ | Tools, execution policies, skills, MCP settings | [Tools configuration](https://github.com/afjcjsbx/picoclaw/blob/main/docs/reference/tools_configuration.md), [image generation](https://github.com/afjcjsbx/picoclaw/blob/main/docs/tools/image-generation.md) |
+ | MCP transports, discovery, server configuration and CLI | [Tools configuration — MCP](https://github.com/afjcjsbx/picoclaw/blob/main/docs/reference/tools_configuration.md#mcp-tool), [MCP CLI](https://github.com/afjcjsbx/picoclaw/blob/main/docs/reference/mcp-cli.md) |
+ | Agent loop and runtime internals | [Architecture index](https://github.com/afjcjsbx/picoclaw/blob/main/docs/architecture/README.md), [agent refactor notes](https://github.com/afjcjsbx/picoclaw/blob/main/docs/architecture/agent-refactor/README.md), [runtime events](https://github.com/afjcjsbx/picoclaw/blob/main/docs/architecture/runtime-events.md), [steering](https://github.com/afjcjsbx/picoclaw/blob/main/docs/architecture/steering.md) |
+ | Sessions, context isolation, routing | [Session guide](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/session-guide.md), [session system](https://github.com/afjcjsbx/picoclaw/blob/main/docs/architecture/session-system.md), [routing system](https://github.com/afjcjsbx/picoclaw/blob/main/docs/architecture/routing-system.md) |
+ | Subagents, spawn, background tasks | [Spawn and async tasks](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/spawn-tasks.md), [SubTurn architecture](https://github.com/afjcjsbx/picoclaw/blob/main/docs/architecture/subturn.md) |
+ | Self-evolution | [Configuration guide](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/configuration.md), [self-evolution architecture](https://github.com/afjcjsbx/picoclaw/blob/main/docs/architecture/agent-self-evolution.md) |
+ | Cron and scheduled jobs | [Cron reference](https://github.com/afjcjsbx/picoclaw/blob/main/docs/reference/cron.md) |
+ | Build tags, supported hardware | [Custom builds](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/custom-builds.md), [hardware compatibility](https://github.com/afjcjsbx/picoclaw/blob/main/docs/guides/hardware-compatibility.md) |
+ | Logs, debugging, troubleshooting | [Debugging](https://github.com/afjcjsbx/picoclaw/blob/main/docs/operations/debug.md), [troubleshooting](https://github.com/afjcjsbx/picoclaw/blob/main/docs/operations/troubleshooting.md) |
+ | Contributing and development workflow | [CONTRIBUTING](https://github.com/afjcjsbx/picoclaw/blob/main/CONTRIBUTING.md) |
- 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.