openpaw-ai 0.4.2

OpenPaw - Multi-Channel AI Agent Framework with LangGraph

A Friendly LangChain/LangGraph Multi-Agent Runner

---

Alpha Software -- OpenPaw is in active development and should be considered an alpha release. APIs, configuration formats, and behavior may change between versions. Contributions and feedback are welcome, but expect rough edges.

OpenPaw gives each agent its own workspace -- personality files, custom tools, scheduled tasks -- then gets out of the way. It handles the orchestration so you can focus on what your agents actually do.

Agents can ingest documents, browse the web, search the internet, delegate to specialist sub-agents, and manage their own files -- making them well-suited for research, information processing, and long-running autonomous workflows. Give them a schedule and they'll check in on their own.

Read the full documentation

Highlights

Composable sub-agent teams

Every primary agent is a team lead. Drop a YAML into agent/team/ and your agent gains a teammate it can dispatch with spawn_agent(profile="researcher"):

name: researcher
description: "Web research specialist — searches, cross-references, and cites sources."
system_prompt: |
  You are a focused research specialist. Search, cross-reference, and
  summarize findings with source citations.
model: anthropic:claude-sonnet-4-20250514
allowed_tools: [brave_search, read_file, write_file]
timeout_minutes: 10
max_turns: 20

Each teammate gets its own model, tool loadout, skill set, and lifecycle budget. Run several in parallel -- the parent dispatches, they work, results route back when they finish.

Live in-place status updates

Both your primary agent and every sub-agent maintain a single status message that edits in place as work progresses. No chat flood, no scroll-back -- just a live, current view of who's doing what right now. Get actionable insight into your agent teams at a glance. Agents can also call report_progress to announce structured milestones with their own emoji.

🚀 Starting work...
🔎 Running tool: brave_search (langgraph release notes)...
🤖 Dispatched sub-agent: researcher

🤖 Sub-agent: researcher
🔎 Running tool: brave_search (recent papers)...
📝 Running tool: write_file (notes.md)...
✅ Completed

Mid-run responsiveness

Send a follow-up while the agent is mid-task and it sees it. Steer the run ("🔄 Redirecting..."), interrupt completely ("🛑 Stopping..."), or let messages batch quietly ("📨 New messages received..."). One-line emoji notifications keep you in the loop without breaking the agent's flow.

Typing indicators run while the agent is processing; emoji reactions on your original message track success (👍) or failure (👎).

Channels

Telegram + Discord, simultaneously -- One workspace, multiple channels. Trigger-based activation (mentions, keywords, or both) lets agents respond appropriately in group chats. On-demand channel history gives them awareness of recent conversation when triggered.

Workspace identity

Each agent gets its own SOUL (personality), AGENT (capabilities), USER (context), and HEARTBEAT (agent-writable scratchpad) files, plus a sandboxed filesystem. config/ and data/ are write-protected from the agent itself; everything else lives under workspace/.

Skills -- Reusable knowledge blocks (SKILL.md) drop into the workspace and can be selectively granted to specific team members.

Tools that do real work

• Document processing -- Docling OCR/ICR turns scanned PDFs, DOCX, and PPTX into markdown automatically. Whisper transcribes voice messages on arrival.
• Browser automation -- Playwright-driven web interaction via the accessibility tree. Agents reference elements by number, not CSS selectors.
• Email integration -- Send and receive via Gmail with safe-by-default recipient policies. Search, reply with threading, manage attachments.
• Deep research -- Connect to a self-hosted GPT-Researcher instance for multi-source reports with citations.
• Web search -- Brave Search and other providers for direct search-and-summarize.
• Drop-in custom tools -- Write a @tool function, save it to agent/tools/, restart. Auto-discovered, no wiring needed.

Scheduling & autonomy

• Cron and heartbeats -- Recurring jobs from YAML, plus proactive check-ins agents can configure themselves.
• Dynamic scheduling -- schedule_at, schedule_every, request_followup. Your agent can plan its own future.
• Auto-compact -- When the context window fills, the framework summarizes old turns and continues without missing a beat.
• Runtime model switching -- /model anthropic:claude-opus-4-20250514 mid-conversation. No restart.

Safe by default

• Approval gates -- Human-in-the-loop authorization for sensitive operations with configurable timeouts and channel-native UI.
• Recipient policies -- Email defaults to deny-all sends; only addresses on your allowlist go through.
• Sandboxed filesystem -- Custom tools write to workspace/ by default; config/ and data/ are read-only to agents.

Multi-provider LLMs

Anthropic, OpenAI, AWS Bedrock, xAI, Fireworks, and any OpenAI-compatible endpoint. Define providers once in global config and reference by name from any workspace.

Quick Start

1. Install

git clone https://github.com/johnsosoka/OpenPaw.git
cd OpenPaw
poetry install

2. Scaffold a workspace

poetry run openpaw init my_agent \
  --model anthropic:claude-sonnet-4-20250514 \
  --channel telegram

3. Configure

cp config.example.yaml config.yaml

Add your API keys to agent_workspaces/my_agent/config/.env:

ANTHROPIC_API_KEY=your-key-here
TELEGRAM_BOT_TOKEN=your-token-here

4. Run

poetry run openpaw -c config.yaml -w my_agent

CLI Commands

Command	Description
openpaw init <name>	Scaffold a new agent workspace
openpaw init <name> --model <provider:model>	Scaffold with a pre-configured model
openpaw init <name> --channel telegram	Scaffold with channel pre-configured (telegram or discord)
openpaw list	List available workspaces
openpaw -c config.yaml -w <name>	Run a single workspace
openpaw -c config.yaml -w name1,name2	Run multiple workspaces
openpaw -c config.yaml --all	Run all discovered workspaces
openpaw -c config.yaml -w <name> -v	Run with verbose logging

All commands should be prefixed with poetry run when running from the project directory.

Agent Workspace Structure

Each workspace lives under agent_workspaces/<name>/ and is organized into five directories:

agent_workspaces/my_agent/
├── agent/              # Identity and extensions
│   ├── AGENT.md        # Capabilities and behavior guidelines
│   ├── USER.md         # User context and preferences
│   ├── SOUL.md         # Core personality and values
│   ├── HEARTBEAT.md    # Session state scratchpad (agent-writable)
│   ├── tools/          # Custom LangChain @tool functions
│   ├── team/           # Sub-agent profiles (YAML)
│   └── skills/         # Skill directories
├── config/             # Configuration (write-protected)
│   ├── agent.yaml      # Per-workspace settings (model, channel, queue)
│   ├── .env            # API keys and secrets
│   └── crons/          # Scheduled task definitions
├── data/               # Framework-managed state (write-protected)
│   ├── TASKS.yaml      # Persistent task tracking
│   ├── uploads/        # User-uploaded files
│   └── ...             # Conversations DB, session state, token logs
├── memory/             # Archived conversations and session logs
│   ├── conversations/  # Conversation exports (markdown + JSON)
│   └── logs/           # Session logs and channel history
│       ├── channel/    # Persistent channel message logs (JSONL)
│       └── sessions/   # Heartbeat, cron, and sub-agent session logs
└── workspace/          # Agent work area (default write target)
    ├── downloads/      # Browser-downloaded files
    └── screenshots/    # Browser screenshots

The openpaw init command scaffolds this structure with starter templates. Customize the identity files in agent/ to shape your agent's personality and purpose. Configure model, channel, and queue behavior in config/agent.yaml.

The data/ and config/ directories are write-protected from agent filesystem tools. Write operations default to the workspace/ directory unless an explicit path is provided.

In-Chat Commands

Once running, agents respond to framework commands in chat:

Command	Description
/help	List available commands
/status	Show model, context usage, tasks, and token usage
/new	Archive conversation and start fresh
/compact	Summarize, archive, and continue with summary
/model <provider:model>	Switch LLM model at runtime

Documentation

• Getting Started -- Installation, first workspace, and troubleshooting
• Concepts -- How workspaces, scheduling, queues, and tools fit together
• Configuration -- Global and per-workspace configuration reference
• Workspaces -- Workspace structure, identity files, and custom tools
• Scheduling -- Cron jobs, heartbeats, and dynamic scheduling
• Built-ins -- Web search, browser automation, email, voice, sub-agents, and more
• Channels -- Channel adapters and access control
• Queue System -- Queue modes and message handling
• Architecture -- System design, data flows, and architectural decisions

Contributing

Development follows a GitFlow branching model:

• main -- Stable releases only. Protected branch, requires CI to pass.
• develop -- Integration branch. Feature and bugfix PRs target develop.
• Feature branches -- Branch from develop as feature/, bugfix/, docs/, or chore/.

See CONTRIBUTING.md for the full development guide.

Prerequisites

• Python 3.11+
• Poetry 2.0+
• At least one channel bot token: Telegram or Discord
• At least one model provider API key (Anthropic, OpenAI, or AWS credentials for Bedrock)

License

PolyForm Noncommercial 1.0.0