openpaw-ai 0.4.0

OpenPaw - Multi-Channel AI Agent Framework with LangGraph

A Friendly LangChain/LangGraph Multi-Agent Runner

---

Pre-1.0 Release (0.4.0) — OpenPaw is actively developed. The API may evolve as we work towards a stable 1.0.0 release. Contributions and feedback are welcome.

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, 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

First Class Document processing -- Docling OCR/ICR turns scanned PDFs, DOCX, and PPTX into markdown automatically. Whisper transcribes voice messages on arrival.

Drop-in custom tools -- Write a @tool function, put it in agent/tools/, restart. Your agent picks it up with zero wiring.

Multi-agent spawning -- Agents spin up background workers for parallel tasks with full lifecycle tracking and result collection.

Dynamic tool assignment -- Spawned sub-agents can be given a tailored tool loadout via allow/deny lists, so each worker gets only the capabilities it needs.

Cron scheduling and heartbeats -- Recurring jobs, one-shot timers, proactive check-ins. Agents can even self-schedule follow-ups at runtime.

Browser automation -- Playwright-driven web interaction via accessibility tree. Agents reference page elements by number, not CSS selectors.

Email integration -- Send and receive email via Gmail with safe-by-default recipient policies. Read inbox, search, reply with threading, and manage attachments.

Deep research -- Integrate with a self-hosted GPT-Researcher instance for multi-source research reports with citations. Agents submit queries via WebSocket and receive comprehensive markdown reports.

Approval gates -- Human-in-the-loop authorization for dangerous operations, with configurable timeouts and channel-native UI.

Multi-channel support -- Connect agents to Telegram, Discord, or both simultaneously. Trigger-based activation lets agents respond to @mentions, keyword triggers, or both in group chats. On-demand context fetch gives agents awareness of recent channel history when triggered.

Session management -- Conversations auto-reset after inactivity (default 3 hours). Auto-compact rotates context when the window fills. Persistent channel logs give agents searchable message history.

Workspace isolation -- Each agent gets its own SOUL.md personality, tools directory, conversation history, channels, and sandboxed filesystem.

Multi-provider LLM support -- Anthropic, OpenAI, AWS Bedrock, xAI, and any OpenAI-compatible endpoint. Switch models at runtime with /model.

Memory and observability -- Vector search for semantic recall, conversation archiving to markdown and JSON, and session logs for every cron, heartbeat, and sub-agent run. Full visibility into what your agents are doing and thinking.

Quick Start

1. Install

pip install openpaw-ai

For development from source:

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)
│   ├── skills/         # Skill directories (SKILL.md format)
│   ├── team/           # Spawn profiles (sub-agent personas)
│   └── tools/          # Custom LangChain @tool functions
├── config/             # Configuration (write-protected)
│   ├── agent.yaml      # Per-workspace settings (model, channel, queue)
│   ├── .env            # API keys and secrets
│   └── crons/          # Scheduled task definitions
├── .openpaw/           # Framework internals (write-protected)
│   ├── conversations.db  # AsyncSqliteSaver checkpoint database
│   ├── sessions.json     # Session/conversation thread state
│   ├── token_usage.jsonl # Token usage metrics (append-only)
│   └── subagents.yaml    # Sub-agent requests and results
├── 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.

AI Code Review

All pull requests are automatically reviewed by GPT-4o via ai-code-review. The AI checks for code quality, security issues, performance concerns, and maintainability.

Reviews run on every PR open and update. Results are posted as inline comments on the pull request.

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