PicoClaw Agent

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.