📟 PocketAgent

PocketAgent is a personal AI agent designed to fit right in everyone's pocket—a local-first, lightweight background companion running 24/7.

Built directly on top of the official Anthropic Claude Agent SDK for industrial-grade reasoning and strict session safety, it executes tools, CLI tasks, and automations securely and autonomously.

💡 Inspiration & Lineage

PocketAgent synthesizes the best design patterns from two open-source projects:

• OpenClaw: For its global CLI wrapper, secure gateway tokens, and native OS-level service daemon managers (launchd / systemd).
• Boop Agent: For its dispatcher-executor split, draft-and-confirm toolgates, and tiered memory consolidation debates.

⚡ Core Features

• 🤖 Dispatcher-Executor Split: A lightweight Dispatcher Agent classifies user commands to keep runtime costs low, spawning ephemeral, scoped sub-agents only when complex CLI or shell execution is required.
• 🛡️ Autopilot & Gating: Gates Solana wallet transfers and shell operations. Toggling Autopilot Mode (via Telegram or Dashboard Settings) switches the agent between safety-approved confirmation requests and complete background autonomy.
• 📟 OS-Level Service Auto-Start: PocketAgent automatically registers daemon configurations to run persistently in the background:
  • macOS: ~/Library/LaunchAgents/com.pocketagent.plist (via launchd).
  • Linux: ~/.config/systemd/user/pocketagent.service (via systemd).
• 📟 Tiered Memory & Consolidation: Resolves settings and agent personalities relative to your home directory (~/.pocketagent/workspace/). Employs a post-turn fact extraction loop and a daily three-agent debate (Proposer → Adversary → Judge) to compress facts into MEMORY.md.
• 🔌 Pluggable Architecture: Abstracted wrappers for Messaging Channels (Telegram Bot webhook/polling), Database Adapters (SQLite via better-sqlite3 vs. Convex cloud), and Model Runtimes (Claude SDK vs. custom OpenAI ReAct loop fallbacks).
• 🔑 Secure Gateway: REST API routes and WebSockets stream connections are locked down via a custom POCKETAGENT_GATEWAY_TOKEN to prevent unauthorized remote access.

🛠️ Project Structure

PocketAgent Project Root
│
├── 📁 bin/
│   └── pocketagent            # Bash wrapper CLI (start/stop/logs/enable/doctor)
│
├── 📁 debug/                  # Onboarding Debug Dashboard (React + Vite, ported from Boop)
│
├── 📁 tools/                  # Standalone Agent Tools Directory (monorepo of external CLIs)
│   └── paw-wallet/            # Solana Wallet CLI Project (compiles to pwa-cli)
│
├── 📟 src/
│   ├── index.ts               # Express Server & WebSockets bootloader
│   ├── config.ts              # Loads & validates pocketagent.json via Zod
│   ├── lifecycle.ts           # Workspace seeding / upgrade checks
│   ├── cron.ts                # 30-second loop checking automations
│   ├── heartbeat.ts           # Aborts stalled sub-agents (> 10 mins)
│   │
│   ├── 📁 channels/           # Messaging channel adapters (Telegram, Web)
│   ├── 📁 db/                 # Database Adapters (SQLite with SessionStore integration)
│   ├── 📁 daemon/             # OS Service plist & unit file generators
│   ├── 📁 runtimes/           # Claude SDK adapter & custom OpenAI ReAct loops
│   ├── 📁 stagers/            # Solana wallet transfer draft database helpers
│   ├── 🤖 agents/             # Dispatcher and Executor agents
│   └── 📟 memory/             # Fact extraction and consolidation debates
│
├── 📂 data/                   # Configurations, Pairing, and UUID identity logs
└── 📂 workspace/              # User brain templates (IDENTITY.md, USER.md, MEMORY.md)

🚀 Quickstart Setup

1. Configure the Environment

Create a .env file in the project root:

MODEL_PROVIDER=anthropic
MODEL_NAME=claude-sonnet-4-6
MODEL_API_KEY=your-api-key

TELEGRAM_BOT_TOKEN=your-bot-token
POCKETAGENT_GATEWAY_TOKEN=generate-a-secure-token

# Toggle to bypass all confirmations and run autonomously
BYPASS_ALL_APPROVALS=false
AUTO_APPROVE_THRESHOLD_SOL=0.1

2. Execute CLI Wrapper Commands

Run the global CLI helper from the repository root:

• Start the Agent Daemon:

  ./bin/pocketagent start

• Check Daemon Status:

  ./bin/pocketagent status

• Tail Daemon Log Stream:

  ./bin/pocketagent logs --follow

• Enable OS Boot Auto-Start:

  ./bin/pocketagent enable

3. Run Development Mode

To start both the backend Express/WebSockets server and the React onboarding dashboard simultaneously in development:

npm run dev

This runs the src/dev-orchestrator.ts script, spinning up:

• Express + WebSockets Server (port 1985) with hot-reloading.
• Vite Onboarding Dashboard (port 9600) with query-mutation proxying and real-time WebSocket updates.

📟 Telegram Interaction & Commands

PocketAgent registers a bot menu directly in your Telegram UI:

• /start — Onboarding check-in and connection handshake.
• /status — Check system health, connection logs, and wallet balances.
• /drafts — List pending approvals waiting for your signature.
• /autopilot — Toggle autonomous execution mode on or off.
• /settings — View active providers and model runtimes.