PandaClaw

What is PandaClaw?

PandaClaw is a deliberate, reasoning-first, vision-native personal AI assistant built on Bun. Unlike traditional agents that act instantly, PandaClaw operates with strict planning, multi-agent worker coordination, Git transaction boundaries, and a live visual canvas dashboard.

It features an integrated multi-channel gateway (Telegram, Slack, WebChat) with native voice parsing, a 3-way classifier for dynamic query routing, and cross-platform full-device automation across macOS, Windows, and Linux.

GROQ_API_KEY=YOUR_GROQ_KEY
OPENROUTER_API_KEY=YOUR_OR_KEY
NVIDIA_NIM_KEY=YOUR_NIM_KEY
PANDACLAW_PORT=18789

Reactor Loop

PandaClaw never rushes. Every task moves through a strict six-step reasoning pipeline before a single file is touched.

┌─────────────┐
│   OBSERVE   │  Index codebase, load memory & Knowledge Graph
└──────┬──────┘
       │
┌──────▼──────┐
│   REASON    │  Evaluate goal status and R1 thought budget
└──────┬──────┘
       │
┌──────▼──────┐
│    PLAN     │  Topological task graph generation & critical path
└──────┬──────┘
       │
┌──────▼──────┐
│   EXECUTE   │  Run workers (low risk → auto, high risk/git tx → approve)
└──────┬──────┘
       │
┌──────▼──────┐
│  VALIDATE   │  Verify output correctness & syntax critique
└──────┬──────┘
       │
┌──────▼──────┐
│   REFLECT   │  Record success/failure, update episodic graph
└─────────────┘

The 3-Way Classifier routes queries dynamically: simple queries use a snappier direct answering path, complex queries use the DeepSeek R1 reasoning compiler, and action queries enter agentic tool-use loops with full filesystem and shell access.

Core Architecture

PandaClaw v3 is built around eight interconnected systems that make it a truly deliberate AI agent:

🔒 1. Sandboxing & Git-Backed Rollbacks

All filesystem mutations run on a temporary git branch (pandaclaw-tx-<uuid>). If validation fails or you decline the changes, the workspace rolls back instantly. Arbitrary scripts execute in a native Bun.spawn sandbox with stripped environment secrets and strict timeouts.

🐝 2. Coordinator-Worker Swarm

The coordinator decomposes your goal into a dependency tree of sub-tasks. Tasks are processed concurrently by specialized workers: researcher (web search, codebase reading), coder (source code modification), verifier (syntax checks, test execution), and visualizer (spatial layout, UI reports). The R1 Reasoning Compiler parses DeepSeek <think> traces.

🧠 3. PandaGraph Semantic Memory

Persistent chat history is saved per-chatId to .pandaclaw/chats.jsonl. Semantic facts are extracted as triplet relationships (subject, predicate, object) in .pandaclaw/graph_memory.json. TF-IDF semantic recall retrieves relevant facts locally in under 1ms. After 12 turns, the oldest 4 are pruned and summarized into .pandaclaw/COMPACTED_MEMORY.md.

🔌 4. Pluggable Dynamic Skills Loader

PandaClaw recursively scans the skills/ folder at startup. Any dynamic tool exported as a ToolDefinition is automatically registered, giving the agent customizable capabilities without modifying core code.

🎙️ 5. Native Voice & Audio Processing

Converts speech buffers (OGG, OPUS, MP3, WAV, MPEG) into text in under 1 second using Groq's whisper-large-v3 endpoint. Voice messages from paired Telegram users are automatically downloaded, transcribed, and processed in the agent pipeline.

🎨 6. Local Visual Web Canvas

A premium glassmorphic dashboard at http://localhost:18789 with real-time chat, visual canvas overlay for bounding box coordinates, interactive agent drawing (draw_rect, render_html, clear_canvas), and live websocket logs with Accept/Decline approval for file mutations.

⚡ 7. Pluggable Gateway & Local Fallback

Abstracted channel adapters support Telegram, Slack, and WebChat. If external LLMs rate limit or fail, calls automatically fall back to a local Ollama endpoint (qwen3:0.6b) for continuous operation. The 3-Way Classifier routes queries as simple, complex, or action.

🕹️ 8. Cross-Platform Full-Device Automation

Dynamic OS detection adapts commands across macOS, Windows, and Linux. Includes native macOS screen capture, advanced web orchestration (list/switch/scroll browser tabs), simulated keystrokes and hotkeys, and system controls for volume, brightness, and clipboard.

Getting started

Three ways to install PandaClaw. The one-liner is recommended for first-time users.

Option 1 — Automated Script (Recommended)

Run the automated script for your operating system to check/install Bun, clone the app, install dependencies, and register the binary.

# One-liner for macOS and Linux
$ curl -fsSL https://pandaclaw.vercel.app/install.sh | bash

# One-liner for Windows (PowerShell)
PS> irm https://pandaclaw.vercel.app/install.ps1 | iex

Option 2 — npm or Bun

# Using Bun (native runtime)
$ bun add -g pandaclaw-cli

Option 3 — Manual Clone

$ git clone https://github.com/senapati484/pandaclaw.git
$ cd pandaclaw && bun install

Prerequisites

• Bun runtime (curl -fsSL https://bun.sh/install | bash)
• Git for rollback safety
• An LLM API key (Groq for audio, OpenRouter or NVIDIA NIM for chat)

Configuration

After installation, run the interactive setup wizard to configure LLM providers:

$ pandaclaw setup

The wizard will prompt for your Groq API key (for voice/audio transcription), OpenRouter or NVIDIA NIM API key (for chat/reasoning). PandaClaw supports two configuration layers:

• Global config at ~/.pandaclaw/config.json
• Local config at .pandaclaw/config.json (project-scoped, takes precedence)

Environment variables like GROQ_API_KEY, OPENROUTER_API_KEY, and NVIDIA_NIM_KEY override file-based config at runtime.

Directory Layout

PandaClaw organizes its internal state and configuration under .pandaclaw/ (local) and ~/.pandaclaw/ (global):

.pandaclaw/
├── config.json           # Local configuration (overrides global)
├── chats.jsonl           # Persistent chat history per chatId
├── graph_memory.json     # PandaGraph semantic triple relationships
├── COMPACTED_MEMORY.md   # Summarized memory after turn pruning
└── skills/               # Pluggable dynamic tools

~/.pandaclaw/
├── config.json           # Global configuration
└── skills/               # Global skill definitions

Usage

Launch the PandaClaw agent pipeline and visual dashboard with these commands:

$ pandaclaw setup            # Interactive LLM provider configuration
$ pandaclaw wakeup          # Launch the agent pipeline
$ bun run dashboard          # Start the visual web canvas at localhost:18789

Architecture

PandaClaw coordinates five atomic systems via its Reactor Loop:

• PandaGraph Memory Engine — Semantic triple extraction, TF-IDF recall, and turn-based compaction
• Coordinator-Worker Swarm — Goal decomposition into dependency trees with four specialized workers (researcher, coder, verifier, visualizer)
• 3-Way Classifier — Routes queries as simple (direct answer), complex (DeepSeek R1 reasoning), or action (agentic tool-use)
• Gateway Channel Adapters — Abstracted multi-channel support (Telegram, Slack, WebChat)
• Sandboxed Execution Layer — Git-backed transactional filesystem mutations with Accept/Decline approval workflow

Channels

PandaClaw integrates with three gateway channels through abstracted adapters:

• ✈️ Telegram: Message @pandaclawbot to interact. No custom bot token needed — a shared default bot is built into the codebase. Supports text, voice messages, and inline commands.
• 💬 Slack: Integrate PandaClaw into your Slack workspace for team-accessible AI assistance.
• 🌐 WebChat Dashboard: A premium glassmorphic interface at http://localhost:18789 with real-time chat, visual canvas, websocket logs, and Accept/Decline approval for filesystem mutations.

Risk Safety Model

PandaClaw classifies every tool invocation by risk level. High-risk operations require manual confirmations via the dashboard or Telegram gateway.

* Medium-risk writes auto-commit on git branch pandaclaw-tx-<uuid> and can be rolled back if validation fails.