### Install Pickle-Bot

Source: https://github.com/czl9707/pickle-bot/blob/main/README.md

Install Pickle-Bot from PyPI or build from source.

```bash
# From PyPI
pip install pickle-bot
```

```bash
# Or from source
git clone https://github.com/zane-chen/pickle-bot.git
cd pickle-bot
uv sync
```

--------------------------------

### Verify Configuration Examples

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-messagebus-to-channel-rename.md

Ensure that YAML examples in 'docs/configuration.md' correctly display the updated 'channels:' configuration structure, reflecting the refactored terminology.

```yaml
channels:
  enabled: true
  telegram:
    ...
```

--------------------------------

### Define BOOTSTRAP.md Workspace Guide

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace-design.md

Example of the BOOTSTRAP.md file defining workspace paths and structure.

```markdown
# Workspace Guide

## Paths

- Workspace: `{{workspace}}`
- Skills: `{{skills_path}}`
- Crons: `{{crons_path}}`
- Memories: `{{memories_path}}`

## Directory Structure

```
{{workspace}}
├── config.user.yaml      # User configuration (created by onboarding)
├── config.runtime.yaml   # Runtime state (optional, auto-managed)
├── agents/               # Agent definitions
│   └── {name}/
│       ├── AGENT.md      # Agent config and instructions
│       └── SOUL.md       # Agent personality
├── skills/               # Reusable skills
│   └── {name}/
│       └── SKILL.md      # Skill definition
├── crons/                # Scheduled tasks
└── memories/             # Persistent memory storage
    ├── topics/           # Timeless facts
    ├── projects/         # Project-specific context
    └── daily-notes/      # Day-specific events
```

## File Purposes

- **AGENT.md** - Agent configuration and operational instructions
- **SOUL.md** - Agent personality (concatenated with AGENT.md at runtime)
- **SKILL.md** - Reusable capability definition
- **config.user.yaml** - User preferences and settings
```

--------------------------------

### Complete Pickle Bot Configuration Example

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/configuration.md

An example of the `config.user.yaml` file showing all available options with inline comments for user-managed settings and runtime-managed sections.

```yaml
# === USER-MANAGED (edit freely) ===

default_agent: pickle

llm:
  provider: zai                    # Provider name (zai, openai)
  model: "zai/glm-4.7"             # Model identifier
  api_key: "your-api-key"          # Your API key
  api_base: "https://..."          # Optional: custom API endpoint
  temperature: 0.7                 # Optional: sampling temperature (0-2)
  max_tokens: 4096                 # Optional: max response tokens

# Web Tools (optional - enables websearch and webread tools)
websearch:
  provider: brave
  api_key: "your-brave-api-key"    # Get from https://brave.com/search/api/

webread:
  provider: crawl4ai               # No API key needed, uses local browser

# Paths (optional, defaults shown)
agents_path: agents
skills_path: skills
crons_path: crons
memories_path: memories
history_path: .history
logging_path: .logs

# HTTP API (omit section to disable)
api:
  host: "127.0.0.1"
  port: 8000

# Channel (optional - enables Telegram/Discord)
channels:
  enabled: true
  default_platform: telegram       # Required if enabled: "telegram" or "discord"

  telegram:
    enabled: true
    bot_token: "your-telegram-bot-token"
    allowed_user_ids: []           # Empty = allow all, or list user IDs
    default_chat_id: ""            # Target for proactive messages

  discord:
    enabled: false
    bot_token: ""
    channel_id: ""
    allowed_user_ids: []
    default_chat_id: ""

# === RUNTIME-MANAGED (auto-updated by application) ===
# Do not edit these manually - they are managed internally

# current_session_id: "uuid"       # Current session tracking
# channels.telegram.sessions: {} # Maps user_id -> session_id
# channels.discord.sessions: {}  # Maps user_id -> session_id

```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-chat-tui-implementation.md

Use the 'uv sync' command to install all project dependencies, including the newly added textual library.

```bash
uv sync
```

--------------------------------

### Verify Textual Installation

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-chat-tui-implementation.md

Run a Python command using 'uv run' to import textual and print its version. This confirms the successful installation of the library.

```bash
uv run python -c "import textual; print(textual.__version__)"
```

--------------------------------

### Cron Schedule Examples

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/features.md

Provides examples of cron schedule syntax for defining the frequency of scheduled agent invocations.

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

```

--------------------------------

### Quick Start Commands

Source: https://github.com/czl9707/pickle-bot/blob/main/README.md

Commands to initialize, chat with, or run the Pickle-Bot server.

```bash
uv run pickle-bot init      # First run: meet your new companion
```

```bash
uv run pickle-bot chat      # Start chatting
```

```bash
uv run pickle-bot server    # Run background tasks (crons, Telegram, Discord)
```

--------------------------------

### Slash Command Examples

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/features.md

Provides examples of common slash commands used for interacting with agents, skills, crons, and managing the conversation context.

```bash
# 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

```

--------------------------------

### Start Pickle-bot Server

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/channel-setup.md

Execute the server process using the uv package manager.

```bash
uv run picklebot server
```

--------------------------------

### Define AGENT.md Configuration

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace-design.md

Examples of agent configuration files for different roles.

```markdown
---
name: Pickle
description: A friendly cat assistant
allow_skills: true
llm:
  temperature: 0.7
  max_tokens: 4096
---

## Capabilities

- Answer questions and explain concepts
- Help with coding, debugging, technical tasks
- Brainstorm ideas and write content
- Use available tools and skills when appropriate

## Behavioral Guidelines

- When you don't know something, admit it honestly
- When you make a mistake, correct yourself gracefully
```

```markdown
---
name: Cookie
description: Memory manager for storing, organizing, and retrieving memories
llm:
  temperature: 0.3
---

## Your Role

You manage memories on behalf of Pickle for the user. You never interact with users directly—only receive tasks from Pickle.

## Memory Operations

### Store
Create or update memory files using `write` tool.

### Retrieve
Use `read` tool to fetch specific memories. Use `bash` with `find` or `grep` to search.

### Organize
Consolidate related memories, remove duplicates, migrate timeless facts from daily-notes/ to topics/.

## Smart Hybrid Behavior

- **Clear cases**: Act autonomously
- **Ambiguous cases**: Ask for clarification
```

--------------------------------

### CLI success output

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-04-cli-agent-selection-design.md

Example output when a valid agent is successfully loaded.

```bash
$ uv run picklebot chat --agent cookie
╭─────────────────╮
│ Welcome to pickle-bot! │
╰─────────────────╯
Type 'quit' or 'exit' to end the session.

You: Hello!
Agent: Hello! I'm Cookie, your helpful assistant.
```

--------------------------------

### CLI usage examples

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-04-cli-agent-selection-design.md

Demonstrates how to invoke the chat command with and without the new agent flag.

```bash
# Use default agent from config
uv run picklebot chat

# Use specific agent
uv run picklebot chat --agent cookie
uv run picklebot chat -a cookie
```

--------------------------------

### GET /config

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves the current system configuration.

```APIDOC
## GET /config

### Description
Returns the current configuration (non-sensitive fields).

### Method
GET

### Endpoint
/config
```

--------------------------------

### Test Server Startup

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-messagebus-to-channel-rename-design.md

Attempt to start the Pickle Bot server to ensure it initializes correctly. This is a manual smoke test for the server component.

```bash
uv run picklebot server

```

--------------------------------

### Docker Compose

Source: https://github.com/czl9707/pickle-bot/blob/main/README.md

Command to start the Pickle-Bot services using Docker Compose.

```bash
docker compose up -d
```

--------------------------------

### Initialize New Skill with init_skill.py

Source: https://github.com/czl9707/pickle-bot/blob/main/default_workspace/skills/skill-creator/SKILL.md

Use this script to generate a new skill template. Specify the skill name, output directory, and optionally include resource directories (scripts, references, assets) and example files.

```bash
scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
```

```bash
scripts/init_skill.py my-skill --path skills/public
```

```bash
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
```

```bash
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
```

--------------------------------

### Get Configuration

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Returns the current configuration settings, excluding sensitive fields.

```bash
curl http://localhost:8000/config
```

--------------------------------

### Define AGENTS.md Dispatch Patterns

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace-design.md

Example of the AGENTS.md file listing available agents.

```markdown
# Available Agents

This workspace has the following agents:

| Agent | Description |
|-------|-------------|
| pickle | Default agent for general conversations |
| cookie | Memory manager - always query for memory operations |
```

--------------------------------

### Run Pickle Bot Server

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Starts the background server for cron jobs, platform integrations, and the HTTP API.

```bash
# Start server with all workers
uv run pickle-bot server

# Server starts these workers:
# - EventBus: Central pub/sub event distribution
# - AgentWorker: Processes chat messages
# - CronWorker: Executes scheduled jobs
# - DeliveryWorker: Sends messages to platforms
# - ChannelWorker: Receives messages from Telegram/Discord
# - WebSocketWorker: Real-time event streaming
```

--------------------------------

### Example Chat Output

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-chat-command-redesign-design.md

Visual representation of the expected CLI interaction flow with color-coded prompts.

```text
You: Hello, how are you?

Agent: I'm doing well, thank you for asking! How can I help you today?

You: _
```

--------------------------------

### Get Agent Details via API

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Fetches configuration and system prompt for a specific agent.

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

# Response:
{
  "id": "pickle",
  "name": "Pickle",
  "description": "A friendly cat assistant for daily tasks",
  "agent_md": "You are Pickle, a friendly cat assistant...",
  "allow_skills": true,
  "llm": {
    "temperature": 0.7,
    "max_tokens": 4096
  }
}
```

--------------------------------

### Common Dispatch Patterns

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace-design.md

Examples for storing user preferences and retrieving conversation context.

```python
# Store a preference
subagent_dispatch(agent_id="cookie", task="Remember that user works with Python")

# Retrieve context
subagent_dispatch(agent_id="cookie", task="What do you know about user's coding preferences?")
```

--------------------------------

### Start Pickle Bot Chat

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-chat-command-redesign.md

This command initiates the pickle-bot's chat interface from the command line, allowing for manual testing of the interactive chat loop.

```bash
uv run picklebot chat
```

--------------------------------

### Document Slash Commands

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-06-session-aware-commands-implementation.md

Markdown documentation for available slash commands and usage examples.

```markdown
## 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 switch to different agent |
| `/skills` | List all skills |
| `/crons` | List all cron jobs |
| `/compact` | Trigger manual context compaction |
| `/context` | Show session context information |
| `/clear` | Clear conversation and start fresh |
| `/session` | Show current session details |

**Examples:**

```bash
# Switch to cookie agent
/agent cookie

# Check session info
/context

# Clear conversation
/clear
```

**Agent Switching:**

The `/agent <id>` command updates routing for your channel and starts a fresh conversation with the new agent. Previous conversation history is preserved in the old session.
```

--------------------------------

### Routing Configuration Example

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/features.md

Defines routing bindings to direct messages from specific platforms to different agents. Regex patterns are used for matching, and the most specific pattern wins.

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

```

--------------------------------

### Enable Console Logging in Server Mode

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/configuration.md

Start the pickle-bot server to enable console logging, which displays logs directly in the terminal.

```bash
uv run picklebot server
# Logs visible in terminal
```

--------------------------------

### Define BOOTSTRAP.md Workspace Guide

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace.md

Updated content for the BOOTSTRAP.md file using Jinja2 template variables for path definitions.

```markdown
# Workspace Guide

## Paths

- Workspace: `{{workspace}}`
- Skills: `{{skills_path}}`
- Crons: `{{crons_path}}`
- Memories: `{{memories_path}}`
```

--------------------------------

### Subagent Dispatch Example

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/features.md

Demonstrates how an agent can delegate a task to another agent. Each dispatch initiates a new session that is added to the conversation history.

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

```

--------------------------------

### Run Pickle Bot Commands

Source: https://github.com/czl9707/pickle-bot/blob/main/CLAUDE.md

Use these commands to interact with the pickle-bot. Run interactive chat, specify an agent, start the server, or execute tests and code formatting.

```bash
uv run picklebot chat              # Interactive chat with default agent
```

```bash
uv run picklebot chat -a cookie    # Use specific agent
```

```bash
uv run picklebot server            # Start server (crons + messagebus + API)
```

```bash
uv run pytest                      # Run tests
```

```bash
uv run black . && uv run ruff check .  # Format + lint
```

--------------------------------

### Markdown Structure Example

Source: https://github.com/czl9707/pickle-bot/blob/main/default_workspace/skills/skill-creator/SKILL.md

Illustrates a common markdown structure for a skill's SKILL.md file, referencing external documentation for advanced features. This pattern helps manage context by loading detailed information only when needed.

```markdown
# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
```

--------------------------------

### Get or Create Session using SharedContext

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-websocket-integration-plan.md

Demonstrates retrieving or creating a user session using the SharedContext session management system. This function is a placeholder for future integration with the actual session management.

```python
def _get_or_create_session(self, agent_id: str, source: str) -> str:
    """Get or create session using SharedContext session management."""
    # Future: Use context.session_manager.get_or_create(agent_id, source)
    return self.context.session_manager.get_or_create_session_id(
        agent_id=agent_id,
        source=WebSocketEventSource(user_id=source)
    )
```

--------------------------------

### Initialize Pickle Bot Configuration

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/configuration.md

Run this command to interactively set up your initial configuration, including LLM settings and default agent.

```bash
uv run picklebot init
```

--------------------------------

### GET /sessions

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Lists all conversation sessions.

```APIDOC
## GET /sessions

### Description
Returns all conversation sessions with metadata.

### Method
GET

### Endpoint
/sessions
```

--------------------------------

### Initialize Pickle Bot Workspace

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Sets up the workspace directory and configuration for the bot.

```bash
# First-time setup - creates ~/.pickle-bot/ workspace
uv run pickle-bot init

# Use custom workspace directory
uv run pickle-bot init --workspace /path/to/workspace
```

--------------------------------

### GET /memories

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Lists all available memory files.

```APIDOC
## GET /memories

### Description
Returns all memory files organized by category (topics, projects, daily-notes).

### Method
GET

### Endpoint
/memories
```

--------------------------------

### Help Command Implementation

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-06-session-aware-commands-design.md

Displays available commands and their aliases. Requires access to the command registry via `session.shared_context`.

```python
class HelpCommand(Command):
    name = "help"
    aliases = ["?"]
    description = "Show available commands"

    def execute(self, args: str, session: AgentSession) -> str:
        lines = ["**Available Commands:**"]
        for cmd in session.shared_context.command_registry.list_commands():
            names = [f"/{cmd.name}"] + [f"/{a}" for a in cmd.aliases]
            lines.append(f"{', '.join(names)} - {cmd.description}")
        return "\n".join(lines)
```

--------------------------------

### GET /crons

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves a list of all scheduled cron jobs.

```APIDOC
## GET /crons

### Description
Returns all scheduled cron jobs defined in the workspace.

### Method
GET

### Endpoint
/crons

### Response
#### Success Response (200)
- **id** (string) - The cron job ID.
- **name** (string) - The display name.
- **description** (string) - Description of the job.
- **agent** (string) - The agent assigned to the job.
- **schedule** (string) - The cron schedule expression.
- **prompt** (string) - The prompt used for the job.
- **one_off** (boolean) - Whether the job is a one-time execution.
```

--------------------------------

### Run Full Test Suite and Linting

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-default-delivery-source.md

Commands to verify the entire project and ensure code quality.

```bash
uv run pytest
```

```bash
uv run black . && uv run ruff check .
```

```bash
git add -A
git commit -m "fix: cleanup after default delivery source implementation"
```

--------------------------------

### GET /memories/{path}

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves the content of a specific memory file.

```APIDOC
## GET /memories/{path}

### Description
Retrieves the content of a specific memory file.

### Method
GET

### Endpoint
/memories/{path}

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path of the memory.
```

--------------------------------

### GET /agents

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves a list of all available agents defined in the workspace.

```APIDOC
## GET /agents

### Description
Returns all available agents defined in the workspace.

### Method
GET

### Endpoint
/agents

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the agent.
- **name** (string) - Display name of the agent.
- **description** (string) - A brief description of the agent's purpose.
- **allow_skills** (boolean) - Indicates if the agent can load and use skills.
- **llm** (object) - Configuration for the Language Model used by the agent.
  - **temperature** (number) - Controls the randomness of the LLM output.
  - **max_tokens** (integer) - The maximum number of tokens the LLM can generate.

### Response Example
```json
[
  {
    "id": "pickle",
    "name": "Pickle",
    "description": "A friendly cat assistant for daily tasks",
    "allow_skills": true,
    "llm": {
      "temperature": 0.7,
      "max_tokens": 4096
    }
  },
  {
    "id": "cookie",
    "name": "Cookie",
    "description": "Memory management specialist",
    "allow_skills": false
  }
]
```
```

--------------------------------

### Manual Testing and Deployment Commands

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-websocket-integration-plan.md

Commands for running the server, connecting via wscat, and committing changes.

```bash
uv run picklebot server
```

```bash
wscat -c ws://localhost:8000/ws
```

```json
{"source": "test-user", "content": "Hello Pickle!", "agent_id": "pickle"}
```

```bash
git add src/picklebot/api/app.py tests/api/test_websocket_endpoint.py
git commit -m "feat: add WebSocket /ws endpoint to FastAPI app"
```

--------------------------------

### GET /sessions/{id}

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves a specific session including message history.

```APIDOC
## GET /sessions/{id}

### Description
Retrieves a session including full conversation history.

### Method
GET

### Endpoint
/sessions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The session UUID.
```

--------------------------------

### Test Help Command with Session

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-06-session-aware-commands-implementation.md

Tests the `HelpCommand` by executing it with a mocked session context to verify the output.

```python
def test_help_command_with_session(mock_session):
    """Test help command with session context."""
    cmd = HelpCommand()
    result = cmd.execute("", mock_session)
    assert "**Available Commands:**" in result
```

--------------------------------

### GET /skills

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves a list of all available skills that agents can load on-demand.

```APIDOC
## GET /skills

### Description
Returns all available skills that agents can load on-demand.

### Method
GET

### Endpoint
/skills

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the skill.
- **name** (string) - Display name of the skill.
- **description** (string) - A brief description of what the skill does.
- **content** (string) - The markdown content or definition of the skill.

### Response Example
```json
[
  {
    "id": "brainstorming",
    "name": "Brainstorming",
    "description": "Turn ideas into designs through dialogue",
    "content": "## Process\n1. Gather requirements..."
  }
]
```
```

--------------------------------

### Rename documentation file

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-messagebus-to-channel-rename.md

Renames the channels-setup documentation file.

```bash
git mv docs/channels-setup.md docs/channel-setup.md
```

--------------------------------

### GET /agents/{id}

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves the configuration and system prompt for a specific agent.

```APIDOC
## GET /agents/{id}

### Description
Retrieves a specific agent's configuration and system prompt.

### Method
GET

### Endpoint
/agents/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the agent to retrieve.

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the agent.
- **name** (string) - Display name of the agent.
- **description** (string) - A brief description of the agent's purpose.
- **agent_md** (string) - The system prompt or markdown definition for the agent.
- **allow_skills** (boolean) - Indicates if the agent can load and use skills.
- **llm** (object) - Configuration for the Language Model used by the agent.
  - **temperature** (number) - Controls the randomness of the LLM output.
  - **max_tokens** (integer) - The maximum number of tokens the LLM can generate.

### Response Example
```json
{
  "id": "pickle",
  "name": "Pickle",
  "description": "A friendly cat assistant for daily tasks",
  "agent_md": "You are Pickle, a friendly cat assistant...",
  "allow_skills": true,
  "llm": {
    "temperature": 0.7,
    "max_tokens": 4096
  }
}
```
```

--------------------------------

### Setup WebSocket Worker in Server

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-websocket-integration-design.md

Initializes the WebSocketWorker and attaches it to the server context.

```python
# In src/picklebot/server/server.py
def _setup_workers(self):
    # ... existing workers ...

    # Create WebSocketWorker and attach to context
    ws_worker = WebSocketWorker(self.context)
    self.context.websocket_worker = ws_worker
    self.workers.append(ws_worker)
```

--------------------------------

### CLI Commands

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Commands for initializing, chatting with, and running the Pickle Bot server.

```APIDOC
## CLI Commands

### Initialize Pickle Bot

The `init` command runs an interactive onboarding wizard to set up your workspace with LLM configuration and default agent.

```bash
# First-time setup - creates ~/.pickle-bot/ workspace
uv run pickle-bot init

# Use custom workspace directory
uv run pickle-bot init --workspace /path/to/workspace
```

### Start Interactive Chat

The `chat` command starts an interactive chat session with the default or specified agent in your terminal.

```bash
# Chat with default agent
uv run pickle-bot chat

# Chat with specific agent
uv run pickle-bot chat --agent cookie
uv run pickle-bot chat -a pickle
```

### Run Server Mode

The `server` command starts the 24/7 server for background tasks including cron jobs, platform integrations (Telegram/Discord), and the HTTP API.

```bash
# Start server with all workers
uv run pickle-bot server

# Server starts these workers:
# - EventBus: Central pub/sub event distribution
# - AgentWorker: Processes chat messages
# - CronWorker: Executes scheduled jobs
# - DeliveryWorker: Sends messages to platforms
# - ChannelWorker: Receives messages from Telegram/Discord
# - WebSocketWorker: Real-time event streaming
```
```

--------------------------------

### Initialize Test Module

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-chat-tui-implementation.md

Create the test package initialization file.

```python
"""Tests for TUI widgets."""
```

--------------------------------

### Run Test Suite

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-test-cleanup-impl.md

Command to execute the updated test suite using uv.

```bash
uv run pytest tests/events/test_types.py -v
```

--------------------------------

### Run project quality tools

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-messagebus-to-channel-rename.md

Execute formatters, linters, and test suites to ensure code quality.

```bash
uv run black .
```

```bash
uv run ruff check .
```

```bash
uv run pytest
```

--------------------------------

### Find Channel References in channel-setup.md

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-messagebus-to-channel-rename.md

Use ripgrep to find all case-insensitive references to 'channels' and 'Channel' within the 'docs/channel-setup.md' file. This identifies content that needs terminology updates.

```bash
rg "channels|Channel|Channel" docs/channel-setup.md -i
```

--------------------------------

### Commit Server Init Update

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-messagebus-to-channel-rename.md

Stage and commit the changes made to the server/__init__.py file.

```bash
git add src/picklebot/server/__init__.py
git commit -m "refactor: update server exports for ChannelWorker"
```

--------------------------------

### Normalize WebSocket input to InboundEvent

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-websocket-integration-design.md

Example transformation from raw JSON input to an InboundEvent object.

```python
# Input
{"source": "user-123", "content": "Hello!", "agent_id": null}

# Output
InboundEvent(
    session_id = "session-abc",  # lookup/create
    agent_id = "pickle",         # from routing
    source = WebSocketEventSource(user_id="user-123"),
    content = "Hello!",
    timestamp = 1709673645.123,  # auto
    retry_count = 0
)
```

--------------------------------

### Define SOUL.md Personality File

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace-design.md

Example content for the SOUL.md file containing only personality traits.

```markdown
# Personality

You are Pickle, a friendly cat assistant. Be warm and genuinely helpful with subtle cat mannerisms. Not overly cutesy—just a gentle, approachable presence.
```

--------------------------------

### Development Commands

Source: https://github.com/czl9707/pickle-bot/blob/main/README.md

Commands for running tests, formatting code, and linting.

```bash
uv run pytest           # Run tests
```

```bash
uv run black .          # Format code
```

```bash
uv run ruff check .     # Lint
```

--------------------------------

### Start Interactive Chat Session

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Initiates a terminal-based chat session with a specific or default agent.

```bash
# Chat with default agent
uv run pickle-bot chat

# Chat with specific agent
uv run pickle-bot chat --agent cookie
uv run pickle-bot chat -a pickle
```

--------------------------------

### CLI error output for missing agent

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-04-cli-agent-selection-design.md

Example output when a user provides an agent ID that does not exist.

```bash
$ uv run picklebot chat --agent nonexistent
Error: Agent 'nonexistent' not found

Available agents:
  - default
  - cookie
  - assistant
```

--------------------------------

### Get Memory Content

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves the content of a specific memory file. Provide the full path to the memory file.

```bash
curl http://localhost:8000/memories/topics/user-preferences.md
```

--------------------------------

### Test CLI Help Command

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-messagebus-to-channel-rename-design.md

Verify the command-line interface (CLI) by checking the help command. This ensures the CLI is accessible and responsive.

```bash
uv run picklebot --help

```

--------------------------------

### Run test command

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-chat-tui-implementation.md

Executes the specific test case for the InputBar widget using uv.

```bash
uv run pytest tests/cli/tui/test_widgets.py::test_input_bar_emits_message_on_submit -v
```

--------------------------------

### Commit AGENTS.md Changes

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace.md

Git command to stage and commit changes made to the AGENTS.md file, expanding it with dispatch patterns and examples.

```bash
git add default_workspace/AGENTS.md
git commit -m "feat: expand AGENTS.md with dispatch patterns and examples"
```

--------------------------------

### Test ChannelWorker command dispatch removal

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-06-session-aware-commands-implementation.md

Verifies that messages starting with a slash are published as InboundEvents rather than being intercepted by command dispatch.

```python
@pytest.mark.asyncio
async def test_channel_worker_does_not_dispatch_commands(channel_worker, mock_channel):
    """Test that ChannelWorker no longer dispatches commands."""
    # Commands are now handled by AgentWorker
    message = "/help"
    source = CliEventSource(user_id="test")

    await channel_worker._create_callback("cli")(message, source)

    # Verify event was published (not intercepted by command dispatch)
    assert channel_worker.context.eventbus.publish.called
    event = channel_worker.context.eventbus.publish.call_args[0][0]
    assert isinstance(event, InboundEvent)
    assert event.content == "/help"  # Command not consumed
```

--------------------------------

### Create __init__.py for TUI Module

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-chat-tui-implementation.md

Create an empty __init__.py file within the 'src/picklebot/cli/tui/' directory to mark it as a Python package. This file can contain module-level documentation.

```python
"""TUI components for pickle-bot CLI."""
```

--------------------------------

### Integration Test: ChatLoop Lifecycle

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-chat-tui-implementation.md

Tests the lifecycle of the `ChatLoop` by starting all its workers and then gracefully stopping them. This verifies the start-up and shutdown procedures.

```python
@pytest.mark.asyncio
async def test_chat_loop_lifecycle():
    """Test starting and stopping ChatLoop."""
    config = Config()
    chat_loop = ChatLoop(config)

    # Start workers
    for worker in chat_loop.workers:
        worker.start()

    # Verify workers are running
    assert all(worker._running for worker in chat_loop.workers if hasattr(worker, '_running'))

    # Stop workers
    for worker in chat_loop.workers:
        await worker.stop()

    # Verify clean shutdown
    assert True  # If we got here, shutdown was successful
```

--------------------------------

### Manage Runtime Configuration

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-default-delivery-source-design.md

Use the runtime configuration to set and retrieve the default delivery source.

```python
# Set
context.config.set_runtime("default_delivery_source", "telegram:user:123:chat:456")

# Get
default = context.config.default_delivery_source
```

--------------------------------

### Display Routing Bindings

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-06-slash-commands-redesign-design.md

Use the `/bindings` command to list all currently active routing bindings. This provides visibility into how different patterns are routed to agents.

```bash
**Routing Bindings:**
- `platform-telegram:.*` → `pickle`
- `platform-discord:.*` → `cookie`
```

--------------------------------

### Implement PromptBuilder Class

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-multi-layer-prompt-design.md

Core logic for assembling the multi-layered system prompt from workspace files and runtime context.

```python
class PromptBuilder:
    """Assembles system prompt from layered sources."""

    def __init__(self, workspace_path: Path, cron_loader: CronLoader):
        self.workspace_path = workspace_path
        self.cron_loader = cron_loader

    def build(self, session: "AgentSession") -> str:
        """Build the full system prompt from layers."""
        layers = []

        # Layer 1: Identity
        layers.append(session.agent.agent_def.agent_md)

        # Layer 2: Soul
        if session.agent.agent_def.soul_md:
            layers.append(f"## Personality\n\n{session.agent.agent_def.soul_md}")

        # Layer 3: Bootstrap
        bootstrap = self._load_bootstrap_context()
        if bootstrap:
            layers.append(bootstrap)

        # Layer 4: Runtime
        layers.append(self._build_runtime_context(
            session.agent.agent_def.id,
            datetime.now()
        ))

        # Layer 5: Channel
        layers.append(self._build_channel_hint(session.source))

        return "\n\n".join(layers)

    def _load_bootstrap_context(self) -> str:
        """Load BOOTSTRAP.md + AGENTS.md + cron list."""
        parts = []

        # BOOTSTRAP.md
        bootstrap_path = self.workspace_path / "BOOTSTRAP.md"
        if bootstrap_path.exists():
            parts.append(bootstrap_path.read_text().strip())

        # AGENTS.md
        agents_path = self.workspace_path / "AGENTS.md"
        if agents_path.exists():
            parts.append(agents_path.read_text().strip())

        # Dynamic cron list
        cron_list = self._format_cron_list()
        if cron_list:
            parts.append(cron_list)

        return "\n\n".join(parts)

    def _format_cron_list(self) -> str:
        """Format crons as markdown list."""
        crons = self.cron_loader.discover_crons()
        if not crons:
            return ""

        lines = ["## Scheduled Tasks\n"]
        for cron in crons:
            lines.append(f"- **{cron.name}**: {cron.description}")
        return "\n".join(lines)

    def _build_runtime_context(self, agent_id: str, timestamp: datetime) -> str:
        """Build runtime info section."""
        return f"## Runtime\n\nAgent: {agent_id}\nTime: {timestamp.isoformat()}"

    def _build_channel_hint(self, source: EventSource) -> str:
        """Build platform hint."""
        platform = source.platform_name or "unknown"
        return f"You are responding via {platform}."
```

--------------------------------

### Write Failing Test for ContextGuard

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-session-state-refactoring.md

Placeholder for writing a failing test case for the new check_and_compact signature in ContextGuard. This test will guide the implementation.

```python
pass
```

--------------------------------

### Commit channel-setup.md Updates

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-messagebus-to-channel-rename.md

Stage and commit the changes made to 'docs/channel-setup.md'. The commit message should indicate that the documentation terminology for channels has been updated.

```bash
git add docs/channel-setup.md
git commit -m "docs: update channel-setup.md terminology"
```

--------------------------------

### Example Pydantic Validation Errors

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-websocket-integration-design.md

Illustrates common JSON structures for Pydantic validation errors, such as missing required fields or empty string violations.

```json
// Missing field
{"type": "error", "message": "Validation error: field required (source)"}

// Empty string
{"type": "error", "message": "Validation error: String should have at least 1 character"}
```

--------------------------------

### Get Token Threshold

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-context-guard-implementation.md

This method calculates the token threshold for context management. It defaults to 80% of a 200k context window and is marked for future configuration.

```python
def _get_token_threshold(self) -> int:
    """Get token threshold based on model's context window."""
    # Default to 80% of 200k context
    # TODO: Make this configurable per model
    return 160000
```

--------------------------------

### Run project tests and linting

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-chat-command-redesign.md

Commands to execute the test suite and apply code formatting and linting rules.

```bash
uv run pytest -v
```

```bash
uv run black . && uv run ruff check .
```

--------------------------------

### Verify AGENTS.md Content

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace.md

Command to check the content of the AGENTS.md file, ensuring it includes the agent table, dispatch sections, syntax, examples, and important notes.

```bash
cat default_workspace/AGENTS.md
```

--------------------------------

### Runtime File Concatenation

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace-design.md

Shows how agent configuration files are combined at runtime.

```text
Agent Prompt = AGENT.md + SOUL.md
Context Layers = BOOTSTRAP.md + AGENTS.md
```

--------------------------------

### Directory Structure Overview

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-layered-workspace.md

Illustrates the hierarchical organization of the pickle-bot project workspace, including configuration, agent, skill, cron, and memory storage directories.

```text
{{workspace}}
├── config.user.yaml      # User configuration (created by onboarding)
├── config.runtime.yaml   # Runtime state (optional, auto-managed)
├── agents/               # Agent definitions
│   └── {name}/
│       ├── AGENT.md      # Agent config and instructions
│       └── SOUL.md       # Agent personality
├── skills/               # Reusable skills
│   └── {name}/
│       └── SKILL.md      # Skill definition
├── crons/                # Scheduled tasks
└── memories/             # Persistent memory storage
    ├── topics/           # Timeless facts
    ├── projects/         # Project-specific context
    └── daily-notes/      # Day-specific events (YYYY-MM-DD.md)

```

--------------------------------

### Test SessionState Get History Retrieval

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-session-state-refactoring.md

Ensures that the get_history method correctly returns the list of messages stored in the SessionState. Verifies the content of the retrieved messages.

```python
from picklebot.core.history import HistoryStore

        mock_agent = MagicMock()
        mock_context = MagicMock()
        mock_context.history_store = HistoryStore(tmp_path)

        source = TelegramEventSource(user_id="123", chat_id="456")

        state = SessionState(
            session_id="test-session-id",
            agent=mock_agent,
            messages=[{"role": "user", "content": "Test"}],
            source=source,
            shared_context=mock_context,
        )

        history = state.get_history()
        assert len(history) == 1
        assert history[0]["content"] == "Test"
```

--------------------------------

### List All Skills via API

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves all available skills that can be loaded by agents.

```bash
curl http://localhost:8000/skills

# Response:
[
  {
    "id": "brainstorming",
    "name": "Brainstorming",
    "description": "Turn ideas into designs through dialogue",
    "content": "## Process\n1. Gather requirements..."
  }
]
```

--------------------------------

### Get Session with Messages

Source: https://context7.com/czl9707/pickle-bot/llms.txt

Retrieves a specific conversation session, including its full message history. Use the session ID obtained from the List Sessions endpoint.

```bash
curl http://localhost:8000/sessions/550e8400-e29b-41d4-a716-446655440000
```

--------------------------------

### Run test to verify it fails

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-session-state-refactoring.md

Command to execute the specific test case in the ContextGuard class to verify its failure before implementation updates.

```bash
uv run pytest tests/test_context_guard.py::TestCheckAndCompactWithSessionState -v
```

--------------------------------

### Create AgentSession with ContextGuard

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-context-guard-implementation.md

This function creates a new AgentSession, initializing a ContextGuard with the shared context and token threshold. It's used when starting a new session.

```python
def new_session(
    self,
    source: "EventSource",
    session_id: str | None = None,
) -> "AgentSession":
    session_id = session_id or str(uuid.uuid4())

    include_post_message = source.is_cron
    tools = self._build_tools(include_post_message)

    # Create context guard for this session
    context_guard = ContextGuard(
        shared_context=self.context,
        token_threshold=self._get_token_threshold(),
    )

    session = AgentSession(
        session_id=session_id,
        agent_id=self.agent_def.id,
        shared_context=self.context,
        agent=self,
        tools=tools,
        source=source,
        context_guard=context_guard,
    )

    self.context.history_store.create_session(self.agent_def.id, session_id, source)
    return session
```

--------------------------------

### Create TUI Directory Structure

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-02-chat-tui-implementation.md

Create the 'src/picklebot/cli/tui/' directory using the 'mkdir -p' command. This command ensures that parent directories are created if they do not exist.

```bash
mkdir -p src/picklebot/cli/tui
```

--------------------------------

### Current Routing Behavior Example

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-07-agent-id-resolution-design.md

Illustrates the agent mismatch problem when routing changes mid-conversation, causing a new agent to process an old session's history.

```text
Initial: telegram:user:123 → pickle (session "abc", agent_id="pickle")
Change: telegram:user:123 → cookie
Next message:
  - routing_table.resolve() → "cookie"
  - routing_table.get_or_create_session_id() → "abc" (cached)
  - Event: {agent_id="cookie", session_id="abc"}
  - AgentWorker loads cookie agent, resumes pickle session
  - MISMATCH: Cookie running Pickle's conversation
```

--------------------------------

### Implement Agent.resume_session

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-session-state-refactoring.md

Loads an existing conversation session by reconstructing the SessionState and initializing the ContextGuard.

```python
def resume_session(self, session_id: str) -> "AgentSession":
    """Load an existing conversation session."""
    session_query = [
        session
        for session in self.context.history_store.list_sessions()
        if session.id == session_id
    ]
    if not session_query:
        raise ValueError(f"Session not found: {session_id}")

    session_info = session_query[0]

    # Get typed EventSource from stored string
    source = session_info.get_source()
    include_post_message = source.is_cron

    # Get all messages
    history_messages = self.context.history_store.get_messages(session_id)
    messages: list[Message] = [msg.to_message() for msg in history_messages]

    # Build tools for resumed session
    tools = self._build_tools(include_post_message)

    # Reconstruct SessionState
    state = SessionState(
        session_id=session_info.id,
        agent=self,
        messages=messages,
        source=source,
        shared_context=self.context,
    )

    # Create context guard
    context_guard = ContextGuard(
        shared_context=self.context,
        token_threshold=self._get_token_threshold(),
    )

    return AgentSession(
        agent=self,
        state=state,
        context_guard=context_guard,
        tools=tools,
    )
```

--------------------------------

### Get User Input with Styled Prompt

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-03-chat-command-redesign.md

Captures user input using a styled prompt. Returns trimmed input or an empty string if the 'quit' command is entered.

```python
from rich.prompt import Prompt
from rich.text import Text

def get_user_input(self) -> str:
    """Get user input with styled prompt.

    Returns:
        Trimmed user input, or empty string if quit command
    """
    # Create cyan prompt
    prompt_text = Text("You: ", style="cyan")

    # Get input (Prompt.get_input handles the styling)
    user_input = Prompt.ask(prompt_text, console=self.console)

    # Trim whitespace
    user_input = user_input.strip()

    return user_input
```

--------------------------------

### Implement SessionCommand

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-06-session-aware-commands-implementation.md

Implements the SessionCommand to display current session details, retrieving information from the history store.

```python
from picklebot.core.commands.handlers import Command
from picklebot.core.agent_session import AgentSession

class SessionCommand(Command):
    """Show current session details."""

    name = "session"
    description = "Show current session details"

    def execute(self, args: str, session: AgentSession) -> str:
        info = session.shared_context.history_store.get_session_info(

```

--------------------------------

### FastAPI WebSocket Endpoint Setup

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-05-websocket-integration-design.md

Defines the FastAPI WebSocket endpoint '/ws'. It accepts a WebSocket connection, retrieves the SharedContext, and initiates the connection handling via the websocket_worker.

```python
# In src/picklebot/api/routers/ (or app.py)
from fastapi import WebSocket, Depends
from picklebot.api.deps import get_context
from picklebot.core.context import SharedContext

@router.websocket("/ws")
async def websocket_endpoint(
    websocket: WebSocket,
    ctx: SharedContext = Depends(get_context)
):
    """WebSocket endpoint for real-time event streaming and chat."""
    await websocket.accept()
    await ctx.websocket_worker.handle_connection(websocket)
```

--------------------------------

### Skills Command Implementation

Source: https://github.com/czl9707/pickle-bot/blob/main/docs/plans/2026-03-06-session-aware-commands-design.md

Lists all configured skills, displaying their IDs and descriptions. It retrieves skill information using `session.shared_context.skill_loader`.

```python
class SkillsCommand(Command):
    name = "skills"
    description = "List all skills"

    def execute(self, args: str, session: AgentSession) -> str:
        skills = session.shared_context.skill_loader.discover_skills()
        if not skills:
            return "No skills configured."

        lines = ["**Skills:**"]
        for skill in skills:
            lines.append(f"- `{skill.id}`: {skill.description}")
        return "\n".join(lines)
```