opencode/picoclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add project documentation and architecture guides

Browse source 
Add comprehensive documentation including:
- CLAUDE.md for build instructions and environment setup
- project-map.md for directory structure and key file overview
- docs/reference/tools-api.md for detailed tools API and architecture
- session-log.md for tracking development decisions
- updates to plugin tool injection documentation regarding security risks
This commit is contained in:
anthrodjear 2026-05-05 05:49:21 +03:00
parent 07107384cb
commit ab23be43a9
5 changed files with 606 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
CLAUDE.md Normal file
View file

@ -0,0 +1,37 @@
# PicoClaw
## Build & Test Commands
```bash
make build # Build for current platform (runs generate first)
make build-all # Cross-compile for all supported platforms
make test # Run Go tests + web tests
make lint # golangci-lint with goolm,stdjson tags
make check # deps + fmt + vet + test + lint-docs
```
## Environment Setup
- Copy `.env.example` to `.env` and configure API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
- Go 1.25.9+ required
- Build tags: `goolm,stdjson` (set via GO_BUILD_TAGS or Makefile)
- CGO_ENABLED=0 by default; CGO_ENABLED=1 only for macOS launcher builds
## Critical Constraints
- **Always run `make generate` before `make build`** — code generation creates required workspace symlinks
- **Never edit `cmd/picoclaw/workspace/` directly** — it's regenerated by `go generate`
- **MIPS builds require ELF e_flags patch** — handled automatically by Makefile
- **loong64 needs manual ztypes_loong64.go** — handled automatically by Makefile
- **WhatsApp native builds** add `whatsapp_native` tag but produce larger binaries
- **Workspace location**: `~/.picoclaw/workspace` (skills, memory stored here at runtime)
- **macOS launcher**: requires CGO_ENABLED=1 and minimal macOS 10.11 target
- **No hardcoded API keys in CLI** — project is migrating to OAuth 2.0 flows
- **Memory target**: core process <20MB for 64MB RAM boards; optimize data structures over storage
## Architecture Notes
- **Protocol-first**: Migrating from vendor-based to protocol-based provider classification (OpenAI-compat, Ollama-compat)
- **Multi-architecture**: x86_64, ARM64, MIPS, RISC-V, LoongArch
- **14+ chat channels** via adapter pattern in pkg/channels/
- **MCP support**: Model Context Protocol server in pkg/mcp/
- **Tools API**: See `docs/reference/tools-api.md` for complete tools documentation

1
docs/architecture/hooks/plugin-tool-injection.md
View file

@ -556,6 +556,7 @@ This provides a flexible and elegant solution for plugin development.
**Important**: The `respond` action bypasses `ApproveTool` approval checks. **Important**: The `respond` action bypasses `ApproveTool` approval checks.
This means: This means:
- A `before_tool` hook can return `respond` for **any tool name**, including sensitive tools (like `bash`) - A `before_tool` hook can return `respond` for **any tool name**, including sensitive tools (like `bash`)
- The tool won't go through the approval process, directly returning the hook-provided result - The tool won't go through the approval process, directly returning the hook-provided result
- This is designed for plugin tools but introduces security risks - This is designed for plugin tools but introduces security risks

453
docs/reference/tools-api.md Normal file
View file

@ -0,0 +1,453 @@
# Tools API Documentation
## Overview
PicoClaw's tools system provides a extensible way for the AI agent to interact with the host system, web, hardware, and external services. Tools are registered in a centralized `ToolRegistry` and can be exposed to LLM providers via JSON Schema definitions.
## Architecture
### Tool Interface
All tools implement the base `Tool` interface (`pkg/tools/registry.go`):
```go
type Tool interface {
Name() string
Description() string
Parameters() map[string]any // JSON Schema
Execute(ctx context.Context, args map[string]any) *ToolResult
}
```
Optional interfaces for enhanced behavior:
- **`AsyncExecutor`** - Tools that support async execution with callback
- **`mediaStoreAware`** - Tools that need access to media storage
- **`PromptMetadataProvider`** - Tools that provide prompt layer/slot metadata
### Tool Registry
The `ToolRegistry` (`pkg/tools/registry.go`) manages all tools:
- **Core Tools**: Registered with `Register(tool)` - always available, no TTL
- **Hidden Tools**: Registered with `RegisterHidden(tool)` - have TTL (Time To Live), can be promoted
- **Tool Definitions**: `GetDefinitions()` returns JSON Schema for LLM providers
- **Provider Format**: `ToProviderDefs()` converts to provider-specific format (OpenAI, Anthropic, etc.)
### Tool Execution Flow
1. Tool called by agent with arguments
2. Arguments validated against tool's JSON Schema
3. Channel/ChatID context injected into `ctx`
4. `Execute()` or `ExecuteAsync()` called
5. Result normalized and returned as `ToolResult`
6. Panics recovered to prevent agent crashes
## Available Tools
### Filesystem Tools
| Tool Name | Description | Category | Config Key |
|-----------|-------------|----------|------------|
| `read_file` | Read file content from workspace or allowed paths | filesystem | `read_file` |
| `write_file` | Create or overwrite files within workspace | filesystem | `write_file` |
| `list_dir` | Inspect directories and enumerate files | filesystem | `list_dir` |
| `edit_file` | Apply targeted edits to existing files | filesystem | `edit_file` |
| `append_file` | Append content to end of existing file | filesystem | `append_file` |
**Implementation**: `pkg/tools/fs/` package
- Path validation against workspace restrictions
- Symlink resolution to prevent escaping workspace
- Configurable allow/deny path patterns
- Max file size limit: 64KB (configurable via `MaxReadFileSize`)
**Expected Arguments** (example for `read_file`):
```json
{
"path": "/path/to/file.txt",
"workspace": "/workspace" // injected automatically
}
```
### Shell/Exec Tool
| Tool Name | Description | Category | Config Key |
|-----------|-------------|----------|------------|
| `exec` | Run shell commands in workspace sandbox | filesystem | `exec` |
**Implementation**: `pkg/tools/shell.go`
- **Security**: Deny patterns block dangerous commands:
- `rm -rf`, `dd`, `shutdown`, `reboot`, `chmod`, `chown`, `sudo`
- Command substitution: `$(...)`, backticks
- Pipe to shell: `\| sh`, `\| bash`
- **Session Management**: Persistent shell sessions via `SessionManager`
- **Timeout**: Configurable command timeout
- **Working Directory**: Restricted to workspace by default
**Expected Arguments**:
```json
{
"command": "ls -la",
"workdir": "/workspace", // optional
"timeout": 30 // seconds, optional
}
```
### Automation Tools
| Tool Name | Description | Category | Config Key |
|-----------|-------------|----------|------------|
| `cron` | Schedule one-time or recurring tasks | automation | `cron` |
**Implementation**: `pkg/tools/cron.go`
- Schedule reminders, shell commands, and jobs
- One-time or recurring (cron expression support)
**Expected Arguments**:
```json
{
"action": "add", // add, list, remove
"schedule": "0 9 * * *", // cron format or "in 5m"
"command": "echo 'reminder'", // optional
"message": "Daily reminder" // optional
}
```
### Web Tools
| Tool Name | Description | Category | Config Key |
|-----------|-------------|----------|------------|
| `web_search` | Search the web using configured providers | web | `web` |
| `web_fetch` | Fetch and summarize webpage contents | web | `web_fetch` |
**Web Search Providers** (configured in `tools.web`):
- **Sogou** - Chinese search engine
- **DuckDuckGo** - Privacy-focused search
- **Brave Search** - Independent search (requires API key)
- **Tavily** - AI-optimized search (requires API key)
- **Perplexity** - AI search engine (requires API key)
- **SearXNG** - Metasearch engine (self-hosted)
- **GLM Search** - Chinese AI search (requires API key)
- **Baidu Search** - Chinese search engine (requires API key)
**Web Search Expected Arguments**:
```json
{
"query": "latest AI news",
"max_results": 5, // optional, default varies by provider
"provider": "brave" // optional, uses default
}
```
**Web Fetch Expected Arguments**:
```json
{
"url": "https://example.com",
"max_chars": 10000 // optional
}
```
### Communication Tools
| Tool Name | Description | Category | Config Key |
|-----------|-------------|----------|------------|
| `message` | Send follow-up message to active chat | communication | `message` |
| `send_file` | Send file or media to active chat | communication | `send_file` |
**Implementation**: `pkg/tools/integration_facade.go` → `pkg/tools/integration/`
**Message Tool Expected Arguments**:
```json
{
"text": "Hello from the agent!",
"channel": "telegram", // injected from context
"chat_id": "123456" // injected from context
}
```
**Send File Expected Arguments**:
```json
{
"path": "/workspace/report.pdf",
"caption": "Here's your file" // optional
}
```
### Skills Tools
| Tool Name | Description | Category | Config Key |
|-----------|-------------|----------|------------|
| `find_skills` | Search external skill registries | skills | `find_skills` |
| `install_skill` | Install skill from registry | skills | `install_skill` |
**Dependencies**: Requires `skills` config to be enabled
**Find Skills Expected Arguments**:
```json
{
"query": "pdf",
"limit": 10 // optional
}
```
**Install Skill Expected Arguments**:
```json
{
"name": "pdf-tools",
"source": "registry-url" // optional
}
```
### Agent/Subagent Tools
| Tool Name | Description | Category | Config Key |
|-----------|-------------|----------|------------|
| `spawn` | Launch background subagent for delegated work | agents | `spawn` |
| `spawn_status` | Query status of spawned subagents | agents | `spawn_status` |
**Dependencies**: Requires `subagent` config to be enabled
**Spawn Tool Expected Arguments**:
```json
{
"task": "Research latest AI papers",
"model": "gpt-4", // optional
"max_tokens": 2000, // optional
"temperature": 0.7, // optional
"async": true // optional, run in background
}
```
**Spawn Status Expected Arguments**:
```json
{
"task_id": "abc123" // optional, returns specific task or all
}
```
### Hardware Tools
| Tool Name | Description | Category | Config Key | Platform |
|-----------|-------------|----------|------------|----------|
| `i2c` | Interact with I2C devices | hardware | `i2c` | Linux only |
| `spi` | Interact with SPI devices | hardware | `spi` | Linux only |
| `serial` | Interact with serial ports | hardware | `serial` | Linux/macOS/Windows |
**Implementation**: `pkg/tools/hardware_facade.go` → `pkg/tools/hardware/`
**I2C Expected Arguments**:
```json
{
"action": "read", // read, write
"bus": "/dev/i2c-1",
"address": 0x48,
"register": 0x00, // optional
"data": [0x01, 0x02] // for write
}
```
**Serial Expected Arguments**:
```json
{
"port": "/dev/ttyUSB0",
"baud": 9600,
"data": "hello" // string or bytes
}
```
### Discovery Tools (Hidden, TTL-based)
| Tool Name | Description | Category | Config Key |
|-----------|-------------|----------|------------|
| `tool_search_tool_regex` | Discover hidden MCP tools by regex | discovery | `mcp.discovery.use_regex` |
| `tool_search_tool_bm25` | Discover hidden MCP tools by semantics | discovery | `mcp.discovery.use_bm25` |
**Dependencies**: Requires `mcp` and `mcp.discovery` to be enabled
## Backend API Endpoints
### Base URL
```
http://localhost:<port>/api
```
### Tool Management
#### List All Tools
```
GET /api/tools
```
**Response**:
```json
{
"tools": [
{
"name": "read_file",
"description": "Read file content from the workspace",
"category": "filesystem",
"config_key": "read_file",
"status": "enabled", // enabled, disabled, blocked
"reason_code": "" // e.g., "requires_skills"
}
]
}
```
#### Enable/Disable Tool
```
PUT /api/tools/{name}/state
```
**Request Body**:
```json
{
"enabled": true
}
```
**Response**:
```json
{
"status": "ok"
}
```
### Web Search Configuration
#### Get Web Search Config
```
GET /api/tools/web-search-config
```
**Response**:
```json
{
"provider": "auto", // auto, sogou, duckduckgo, brave, tavily, etc.
"current_service": "brave",
"prefer_native": false,
"proxy": "",
"providers": [
{
"id": "brave",
"label": "Brave Search",
"configured": true,
"current": true,
"requires_auth": true
}
],
"settings": {
"brave": {
"enabled": true,
"max_results": 10,
"api_key_set": true
}
}
}
```
#### Update Web Search Config
```
PUT /api/tools/web-search-config
```
**Request Body**:
```json
{
"provider": "brave",
"prefer_native": false,
"proxy": "",
"settings": {
"brave": {
"enabled": true,
"max_results": 10,
"api_key": "BSA...", // or "api_keys": ["key1", "key2"]
"base_url": "" // optional for self-hosted
}
}
}
```
## Tool Result Structure
Tools return `*ToolResult` with the following fields:
```go
type ToolResult struct {
ForLLM string // Text returned to LLM for processing
ForUser string // Text shown to end user in chat
MediaURLs []string // Media attachment URLs (media:// or http://)
IsError bool // Whether execution failed
Async bool // True if running asynchronously
Err error // Underlying Go error (not serialized to JSON)
}
```
## MCP (Model Context Protocol) Integration
PicoClaw exposes tools via MCP server (`pkg/mcp/manager.go`):
- External MCP servers can be integrated
- Tools from MCP servers appear as hidden tools with TTL
- Discovery tools (`tool_search_tool_regex`, `tool_search_tool_bm25`) make hidden tools available
- MCP manager handles tool execution via isolated command transport
**MCP Tool Discovery Flow**:
1. MCP server registered with PicoClaw
2. Tools exposed as hidden (TTL=0, not visible to LLM)
3. Agent uses `tool_search_tool_regex` or `tool_search_tool_bm25`
4. Matching tools promoted (TTL set >0)
5. Promoted tools appear in next LLM context
## Configuration
Tools configured in `config.json` under `tools` section:
```json
{
"tools": {
"read_file": {"enabled": true},
"write_file": {"enabled": true},
"exec": {"enabled": true},
"web": {
"enabled": true,
"provider": "brave",
"brave": {
"enabled": true,
"max_results": 10,
"api_keys": ["BSA..."]
}
},
"mcp": {
"enabled": true,
"discovery": {
"enabled": true,
"use_regex": true,
"use_bm25": false
}
}
}
}
```
## Security Considerations
1. **Path Restrictions**: Filesystem tools restrict access to workspace by default
2. **Shell Command Filtering**: Dangerous commands blocked via regex patterns
3. **Tool TTL**: Hidden tools auto-expire to prevent context bloat
4. **Media Store**: File paths converted to `media://` URLs for safe transport
5. **Panic Recovery**: Tool panics recovered to prevent agent crashes
6. **Symlink Resolution**: Prevents escaping workspace via symlinks
## Tool Registration Example
```go
// Register a core tool (always available)
registry.Register(tools.NewReadFileTool(workspace, true, 64*1024))
// Register a hidden tool (TTL-based)
registry.RegisterHidden(tools.NewRegexSearchTool(registry, 5, 10))
// Promote hidden tools (make them available to LLM)
registry.PromoteTools([]string{"tool_search_tool_regex"}, 10) // TTL=10 turns
```

92
project-map.md Normal file
View file

@ -0,0 +1,92 @@
# Project Map
_Generated: 2026-05-05 | Git: 07107384_
## Directory Structure
cmd/ — CLI entry points (picoclaw main, membench, internal subcommands)
pkg/ — Core library packages (agent, channels, providers, tools, etc.)
web/frontend/ — Frontend UI (React/TypeScript with TanStack)
web/backend/ — Backend API server (Go, dashboard auth, middleware)
workspace/ — Runtime workspace (skills, memory)
docs/ — Documentation (architecture, channels, guides, migration, reference)
docs/reference/tools-api.md — Complete tools API documentation: available tools, data structures, backend API endpoints, MCP integration
config/ — Configuration templates and examples
build/ — Build scripts and artifacts
docker/ — Docker containerization files
scripts/ — Automation and utility scripts
examples/ — Example projects (pico-echo-server)
assets/ — Static assets (logo, images)
## Key Files
cmd/picoclaw/main.go — Main CLI entry point using Cobra; registers subcommands (agent, auth, gateway, mcp, migrate, model, skills, etc.)
cmd/picoclaw/internal/ — Internal CLI command implementations (agent, auth, gateway, mcp, migrate, model, skills, status, version, onboard, cron, cliui)
pkg/agent/ — Core agent logic: context management, pipelines (setup/llm/finalize), turn coordination, event handling, hooks, steering, thinking, prompt contributors
pkg/agent/context_manager.go — Manages LLM context lifecycle, caching, and budget enforcement
pkg/agent/pipeline.go — Orchestrates agent execution phases (setup → LLM → tools → finalize)
pkg/channels/ — Multi-platform chat integrations: Discord, Telegram, Slack, WeChat, WeCom, Feishu, DingTalk, IRC, LINE, Matrix, VK, WhatsApp, OneBot, MaixCam, Pico
pkg/providers/ — AI model provider integrations: Anthropic, OpenAI-compatible, Azure, AWS Bedrock, CLI, HTTP API; shared protocol types and OAuth
pkg/config/ — Configuration loading, validation, and environment variable handling
pkg/skills/ — Skills system for extending agent capabilities
pkg/tools/ — Built-in tools: filesystem (fs), hardware interaction, shared utilities, integration tools
pkg/mcp/ — Model Context Protocol (MCP) server implementation for tool/resource exposure
pkg/memory/ — Agent memory management (short-term/long-term, persistence)
pkg/gateway/ — Gateway for routing messages between channels and agents
pkg/auth/ — Authentication and credential management (OAuth, API keys, encryption)
pkg/identity/ — Identity and user/session management
pkg/session/ — Session state management across channels
pkg/state/ — Application state persistence
pkg/credential/ — Secure credential storage (ChaCha20-Poly1305 encryption)
pkg/routing/ — Message routing logic between channels, agents, and models
pkg/bus/ — Internal event bus for decoupled communication
pkg/events/ — Event definitions and handling (device events, system events)
pkg/cron/ — Cron-based scheduling for periodic tasks
pkg/logger/ — Logging infrastructure
pkg/health/ — Health check endpoints and diagnostics
pkg/heartbeat/ — Heartbeat/keepalive mechanism for long-running processes
pkg/updater/ — Self-update functionality (minio/selfupdate)
pkg/migrate/ — Database and config migration utilities
pkg/media/ — Media processing (images, audio)
pkg/audio/asr/ — Automatic Speech Recognition (ASR) providers
pkg/audio/tts/ — Text-to-Speech (TTS) providers
pkg/tokenizer/ — Token counting and management for LLM context budgets
pkg/netbind/ — Network binding utilities for embedded/specific network configs
pkg/fileutil/ — File utility functions
pkg/devices/ — Device management (events, sources) for hardware integrations
pkg/isolation/ — Sandboxing and isolation for security
pkg/seahorse/ — Seahorse integration (encrypted storage)
pkg/constants/ — Package-level constants
web/backend/api/ — Backend API route definitions
web/backend/middleware/ — HTTP middleware (auth, CORS, logging)
web/backend/dashboardauth/ — Dashboard authentication logic
web/backend/model/ — Backend data models
web/backend/launcherconfig/ — Launcher configuration
web/frontend/src/ — Frontend source (components, routes, store, features, hooks, lib, api, i18n)
go.mod — Go 1.25.9 module definition; key deps: Cobra, DiscordGo, Telego, Anthropic SDK, AWS SDK v2, MCP SDK, gRPC, various channel SDKs
go.sum — Dependency checksums
Makefile — Build targets (build, test, lint, release)
.goreleaser.yaml — GoReleaser config for cross-platform releases
.golangci.yaml — GolangCI-Lint configuration
README.md — Project overview: ultra-lightweight AI assistant for $10 hardware, <10MB RAM, inspired by NanoBot
ROADMAP.md — Vision: lightweight, secure, autonomous AI Agent; core optimization, security hardening, protocol-first architecture
CONTRIBUTING.md — Contribution guidelines
LICENSE — MIT License
.env.example — Example environment variables template
.dockerignore / .gitignore — Ignore rules for Docker and Git
## Critical Constraints
- Target: Runs on $10 hardware (e.g., RISC-V SBCs) with <10MB RAM, core process <20MB for 64MB boards
- Go 1.25.9 required (very recent version)
- Self-bootstrapped: AI Agent drove architecture migration and optimization (not a fork)
- Memory optimization takes precedence over storage size
- Security: Prompt injection defense, tool abuse prevention, SSRF protection, filesystem sandbox, context isolation, privacy redaction
- Crypto: Uses ChaCha20-Poly1305 for secret storage (upgrade from older algorithms)
- OAuth 2.0 Flow: Deprecating hardcoded API keys in CLI
- Architecture: Migrating from "Vendor-based" to "Protocol-based" classification (OpenAI-compatible, Ollama-compatible)
- Multi-architecture: x86_64, ARM64, MIPS, RISC-V, LoongArch
- Channel diversity: 14+ chat platforms supported with platform-specific adapters
- Provider diversity: Anthropic, OpenAI-compat, Azure, Bedrock, local (Ollama, vLLM, LM Studio, Mistral)
- Frontend: TypeScript/React with TanStack router/query
- Build: Makefile + GoReleaser for cross-platform binaries
- Workspace: Skills and memory stored in workspace/ directory at runtime
## Hot Files
pkg/agent/agent.go, pkg/agent/pipeline.go, pkg/agent/context_manager.go, pkg/agent/definition.go, pkg/channels/ (multiple files), pkg/providers/ (multiple files), cmd/picoclaw/main.go, pkg/config/, web/backend/api/, web/frontend/src/

23
session-log.md Normal file
View file

@ -0,0 +1,23 @@
## 2026-05-05 00:00 [saved]
Goal: Initial project setup - create memory files for PicoClaw project
Decisions:
- Initialized git repository for staleness tracking (enables precise project-map.md freshness checks)
- Created project-map.md with directory structure, key files, critical constraints, and hot files
- Created CLAUDE.md with build commands, environment setup, critical constraints, and architecture notes
- Project is PicoClaw: ultra-lightweight AI assistant in Go targeting low end hardware with <50MB RAM
Rejected: None (initial setup)
## 2026-05-05 00:01 [saved]
Goal: Document tools implementation and backend API interaction
Decisions:
- Created docs/tools-api.md with comprehensive tools documentation
- Documented all 20+ tools across 8 categories (filesystem, automation, web, communication, skills, agents, hardware, discovery)
- Documented backend API endpoints for tool management (GET/PUT /api/tools, web-search-config)
- Documented tool data structures (Tool interface, ToolResult, SubTurnConfig)
- Documented MCP integration and tool discovery flow
- Documented security considerations and configuration examples
Rejected: None
Open: None
Open: None