OpenPaw

Overview

OpenPaw is a multi-channel AI agent framework built on LangGraph and LangChain. It gives each agent its own workspace — complete with personality files, custom tools, scheduled tasks, and sandboxed filesystem — then gets out of the way. Agents can ingest documents, browse the web, search the internet, and manage their own files, making them well-suited for research, information processing, and long-running autonomous workflows.

The framework handles orchestration so you can focus on what your agents actually do. Give them a schedule and they'll check in on their own.

Features

First-Class Document Processing

• Docling OCR/ICR — Automatically converts scanned PDFs, DOCX, and PPTX into markdown
• Whisper Transcription — Transcribes voice messages on arrival
• File Persistence — All uploads saved to workspace with date partitioning

Multi-Agent Orchestration

• Sub-Agent Spawning — Spin up background workers for parallel tasks with full lifecycle tracking
• Dynamic Tool Assignment — Tailored tool loadouts via allow/deny lists for each worker
• Concurrency Control — Up to 8 concurrent sub-agents with configurable limits

Scheduling & Autonomy

• Cron Jobs — YAML-defined recurring tasks with timezone-aware scheduling
• Dynamic Scheduling — Agents self-schedule follow-ups at runtime
• Heartbeat Check-ins — Proactive agent wake-ups with configurable active hours
• HEARTBEAT_OK Protocol — Silent suppression when nothing requires attention

Communication & Channels

• Multi-Channel Support — Connect to Telegram, Discord, or both simultaneously
• Trigger-Based Activation — Respond to @mentions, keywords, or DMs
• Context Awareness — On-demand fetch of recent channel history when triggered
• Approval Gates — Human-in-the-loop authorization for dangerous operations

Memory & Persistence

• Conversation Persistence — SQLite-backed conversations survive restarts
• Auto-Compact — Automatic context summarization when thresholds are reached
• Session Archives — Conversations exported as markdown + JSON
• Vector Search — Semantic recall over conversation archives (optional)

Workspace Isolation

• Sandboxed Filesystem — Each agent has isolated read/write access
• Identity Files — Separate AGENT.md, USER.md, SOUL.md, HEARTBEAT.md
• Custom Tools — Drop-in @tool functions with auto-discovery
• Protected Internals — Framework state inaccessible to agents

Architecture

OpenPaw uses a layered architecture with a stability contract: dependencies flow downward only.

        CLI
         │
    runtime/orchestrator
         │
    workspace/runner ──── channels/
         │               └── builtins/
     agent/runner       └── stores/
         │
       model/

Core Components

Message Flow

1. Channel Adapter — Receives platform event, validates sender, runs processor pipeline
2. Command Router — Checks for slash commands (executed immediately)
3. Queue Manager — Assigns to lane (main/subagent/cron), applies queue mode logic
4. Message Processor — Dequeues, runs auto-compact check, invokes agent
5. Middleware Stack — Queue-aware behavior, approval gating
6. Agent Execution — LangGraph ReAct loop with tool calls
7. Response Delivery — Returns via channel adapter, logs metrics

Queue Modes

Usage

Quick Start

# Clone and install
git clone https://github.com/johnsosoka/OpenPaw.git
cd OpenPaw
poetry install
 
# Scaffold a workspace
poetry run openpaw init my_agent \
  --model anthropic:claude-sonnet-4-20250514 \
  --channel telegram
 
# Configure
cp config.example.yaml config.yaml
# Add API keys to agent_workspaces/my_agent/config/.env
 
# Run
poetry run openpaw -c config.yaml -w my_agent

Workspace Structure

agent_workspaces/my_agent/
├── agent/              # Identity and extensions
│   ├── AGENT.md        # Capabilities and behavior
│   ├── USER.md         # User context
│   ├── SOUL.md         # Core personality
│   ├── HEARTBEAT.md    # Session scratchpad
│   ├── tools/          # Custom @tool functions
│   └── skills/         # Skill directories
├── config/             # Configuration
│   ├── agent.yaml      # Per-workspace settings
│   ├── .env            # API keys
│   └── crons/          # Scheduled tasks
├── data/               # Framework state
│   ├── TASKS.yaml      # Persistent tasks
│   └── uploads/        # User files
├── memory/             # Archives and logs
│   ├── conversations/  # Conversation exports
│   └── logs/           # Session logs
└── workspace/          # Agent work area
    ├── downloads/      # Browser downloads
    └── screenshots/    # Browser captures

In-Chat Commands

Custom Tool Example

from langchain_core.tools import tool
 
@tool
def get_current_sprint(project: str) -> str:
    """Return current sprint goals for a Jira project.
 
    Args:
        project: The Jira project key
 
    Returns:
        Summary of current sprint goals
    """
    return fetch_sprint_data(project)

Drop the file in agent/tools/ — it auto-loads on restart.

Technology Stack

• Python 3.11+ — Core runtime
• LangGraph — ReAct agent loop with checkpointing
• LangChain — Model abstraction and tool framework
• SQLite + sqlite-vec — Conversation persistence and semantic search
• APScheduler — Cron and heartbeat scheduling
• python-telegram-bot — Telegram channel adapter
• discord.py — Discord channel adapter
• Playwright — Browser automation
• Docling — Document OCR and conversion
• Poetry — Dependency management

Multi-Provider LLM Support

OpenPaw supports multiple LLM providers through a unified interface:

• Anthropic — Claude models
• OpenAI — GPT models
• AWS Bedrock — Amazon-hosted models
• xAI — Grok models
• OpenAI-Compatible — Any compatible endpoint

Switch models at runtime with /model provider:model — no restart required.

Documentation

Full documentation available at: https://johnsosoka.github.io/OpenPaw/

License

PolyForm Noncommercial 1.0.0