pinchy

Lightweight Rust agent platform designed to run on a Raspberry Pi. Connects to Discord, calls LLMs, runs tools, and supports heartbeat + cron proactive triggers.

Quick Start

1. Set environment variables

export OPENAI_API_KEY="sk-..."      # Required – OpenAI API key
export DISCORD_TOKEN="..."          # Required – Discord bot token
export RUST_LOG="info"              # Optional – log level (debug, trace, pinchy=trace)

2. Build

cargo build --release

3. Run

# Start the daemon (loads ~/.pinchy/config.yaml by default)
cargo run --release

# Use a custom config path
cargo run --release -- --config path/to/config.yaml

4. Scaffold a new agent

cargo run --release -- agent new my_agent

5. Debug CLI

Run with verbose logging to troubleshoot:

RUST_LOG=debug cargo run -- --config ~/.pinchy/config.yaml

Configuration

A minimal config looks like:

models:
  - id: openai-default
    provider: openai
    model: gpt-4o
    api_key: $OPENAI_API_KEY

channels:
  discord:
    token: $DISCORD_TOKEN

agents:
  - id: assistant
    workspace: ./agents/assistant
    model: openai-default
    heartbeat_secs: 300

Environment Variables

Project Structure

src/
├── main.rs          # Entry point, wires everything
├── config/          # Config loading & validation
├── discord/         # Discord channel connector
├── agent/           # Agent runtime, prompt building, sessions
├── models/          # LLM provider trait + implementations
├── tools/           # Built-in tools (read, write, exec)
└── scheduler/       # Heartbeat + cron scheduling

Development

cargo fmt          # Format code
cargo clippy       # Lint
cargo test         # Run tests
cargo build --release --target=aarch64-unknown-linux-gnu  # Cross-compile for Pi

CI

A GitHub Actions workflow (.github/workflows/ci.yml) runs on every push and PR to main:

1. cargo fmt -- --check
2. cargo test
3. cargo build --release

Agents now use a canonical per-agent workspace at agents//workspace. Each workspace contains agent-specific files (SOUL.md, TOOLS.md, HEARTBEAT.md, sessions/) and a BOOTSTRAP.md template to document onboarding. See CONSOLIDATION.md and agents/default/BOOTSTRAP.md for the consolidation plan and bootstrap template.

React Admin UI (In Progress)

A new React frontend is being migrated under web/.

cd web
npm install
npm run dev
npm run build

Production build artifacts are emitted to static/react/ and can be opened at /react/index.html while the legacy UI remains at /.

Browser Automation (Playwright)

• No browser download required: Playwright’s bundled Chromium download is always skipped for all platforms.
• Automatic system browser detection: On first run and onboarding, pinchy auto-detects system Chromium/Chrome in common locations (e.g. /usr/bin/chromium-browser).
• Manual override: Set the environment variable PINCHY_CHROMIUM_PATH to specify a custom browser executable path.
• Onboarding integration: The onboarding wizard will prompt you to confirm or enter a browser path if none is found.
• Agent config: The detected or chosen browser path is saved per agent in config and used automatically.

If no browser is found, browser automation features will be disabled until you install Chromium or set the path.

Example:

export PINCHY_CHROMIUM_PATH=/usr/bin/chromium