# Picoclaw Agent

Configure, extend, debug, or contribute to PicoClaw itself.

- Repository: https://github.com/sipeed/picoclaw (30078 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add sipeed/picoclaw --skill picoclaw-agent -g -a claude-code -y`
Codex: `npx skills add sipeed/picoclaw --skill picoclaw-agent -g -a codex -y`
Cursor: `npx skills add sipeed/picoclaw --skill picoclaw-agent -g -a cursor -y`
Gemini CLI: `npx skills add sipeed/picoclaw --skill picoclaw-agent -g -a gemini-cli -y`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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 version
picoclaw migrate
```

### 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:

The rest: https://github.com/sipeed/picoclaw/blob/HEAD/workspace/skills/picoclaw-agent/SKILL.md