Features Reference

Guide to pickle-bot features. See Architecture for implementation details.

Agents

Each agent has a unique personality, system prompt, and LLM settings.

Default agents:

• Pickle - General-purpose assistant
• Cookie - Memory management specialist

Definition format (agents/{id}/AGENT.md):

---
name: Agent Name
description: Brief description for subagent dispatch
llm:                          # Optional: override global settings
  temperature: 0.7
  max_tokens: 4096
allow_skills: true            # Enable skill loading (default: false)
---

System prompt here...

LLM settings use deep merge - only specify what you want to override.

Subagent Dispatch

Agents can delegate to other agents via subagent_dispatch:

subagent_dispatch(agent_id="cookie", task="Remember this: ...")

Each dispatch creates a fresh session that persists to history. Automatically registered when multiple agents exist.

Skills

On-demand capabilities loaded by the LLM. Unlike tools (always available), skills load only when needed.

Definition format (skills/{id}/SKILL.md):

---
name: Brainstorming
description: Turn ideas into designs through dialogue
---

[Detailed instructions...]

Enable in agent:

---
allow_skills: true
---

Create a skill when: workflow has multiple steps, needs domain knowledge, benefits from structure. Create a tool when: simple single operation, programmatic action, always available.

Crons

Scheduled agent invocations.

Definition format (crons/{id}/CRON.md):

---
name: Daily Summary
agent: pickle
schedule: "0 9 * * *"    # 9 AM daily
---

Task description...

Schedule syntax: minute hour day month weekday

• "*/15 * * * *" - Every 15 minutes
• "0 9 * * *" - Daily at 9 AM
• "0 */2 * * *" - Every 2 hours

Requirements: Server mode (picklebot server), minimum 5-minute granularity, sequential execution.

Proactive messaging: Crons can use post_message tool to send to configured default platform.

Memory System

Long-term memories managed by Cookie agent.

Structure:

• topics/ - Timeless facts (preferences, relationships, identity)
• projects/ - Project state and context
• daily-notes/ - Day-specific events

Flows:

• Storage: User shares info → Pickle dispatches to Cookie → Cookie writes to file
• Retrieval: User asks → Pickle dispatches → Cookie searches → Returns context

File format: Simple markdown with headings.

Web Tools

Web Search

Search via websearch tool using Brave Search.

websearch:
  provider: brave
  api_key: "your-brave-api-key"

Get API key at https://brave.com/search/api/

Or using Searxng

websearch:
  provider: searxng
  api_base: "http://..."

Web Read

Read web pages via webread tool using Crawl4AI.

webread:
  provider: crawl4ai

No API key needed - uses local browser.

Channel

Chat via Telegram and Discord with shared conversation history.

Platforms: Telegram, Discord, CLI

Features:

• Switch platforms mid-conversation (history carries over)
• User whitelist for access control
• Proactive messaging via post_message tool

Whitelist config:

telegram:
  allowed_chat_ids: ["123456789"]  # Empty = allow all

Routing

Route different sources to different agents.

Config:

routing:
  bindings:
    - agent: pickle
      value: "platform-telegram:.*"    # All Telegram to pickle
    - agent: cookie
      value: "platform-discord:.*"     # All Discord to cookie

Pattern matching: Regex patterns, most specific wins. Falls back to default_agent if no match.

Slash Commands

Commands for managing conversations and agents. All commands start with /.

Available Commands:

Command	Description
/help or /?	Show available commands
/agent [<id>]	List agents or show agent details
/skills [<id>]	List skills or show skill details
/crons [<id>]	List cron jobs or show cron details
/bindings	Show all routing bindings
/route <pattern> <agent_id>	Create a routing binding (persists)
/compact	Trigger manual context compaction
/context	Show session context information
/clear	Clear conversation and start fresh
/session	Show current session details

Examples:

# List all agents
/agent

# Show specific agent details
/agent pickle

# Create a routing binding
/route platform-telegram:.* pickle

# View all bindings
/bindings

# Clear conversation
/clear

Routing Bindings:

The /route command creates a persistent binding that routes messages matching a source pattern to a specific agent. Bindings are saved to config.user.yaml and survive server restarts.

HTTP API

REST API for programmatic access. Enabled by default in server mode.

api:
  host: "127.0.0.1"
  port: 8000

Endpoints:

Resource	Endpoints
Agents	GET/POST/PUT/DELETE /agents/{id}
Skills	GET/POST/PUT/DELETE /skills/{id}
Crons	GET/POST/PUT/DELETE /crons/{id}
Sessions	GET/DELETE /sessions/{id}
Memories	GET/POST/PUT/DELETE /memories/{path}
Config	GET/PATCH /config

Example:

curl http://localhost:8000/agents
curl http://localhost:8000/agents/pickle

Heartbeat

Continuous work pattern using cron jobs. Create a heartbeat cron that checks active projects periodically:

---
name: Heartbeat
agent: pickle
schedule: "*/30 * * * *"
---

## Active Tasks
- [ ] Monitor project X

Pickle checks project state and takes action autonomously between user interactions.