Personal AI assistant platform. Security-first, multi-channel, programmable.
Quick Start · How It Works · Channels · Security · Features · Docs · Contributing
Built on four pillars:
- Broad connectivity — 16 messaging channels, tunnel exposure, and a skills system with OpenClaw-compatible skill format.
- Resilient concurrency — OTP-style supervision trees, process isolation, backpressure, and live steering for long-running agent sessions.
- Security-first defaults — trait-based architecture where every defense layer is on by default, hybrid memory search, and encrypted secrets at rest.
- Agent reliability — mandatory tool call validation, state snapshots with diff-based verification, LLM-as-a-judge outcome assessment, and crash recovery via session notes (in-flight tasks resume after restart). Inspired by the Agent World Model research.
npm install -g @ch4p/cli
ch4p onboard
ch4p agentOr clone and build from source:
git clone https://github.com/ch4p-labs/ch4p.git && cd ch4p
corepack pnpm install
corepack pnpm -r build
node apps/cli/dist/index.js agentOther ways to run: Docker ·
corepack pnpm bundle(standalone binary) ·ch4p install(system daemon)
Channels (CLI, Telegram, Discord, Slack, Teams, iMessage, ...) Canvas (tldraw, A2UI)
│ │
Gateway ─── HTTP server, session routing, cron, webhooks ─── WS bridge ───┘
│
Agent Runtime ─── session, context, steering, worker pool
│
Engine ─── native LLM · echo · CLI subprocess
│
Provider ─── Anthropic · OpenAI · Google · OpenRouter · Ollama · Bedrock
Three modes:
| Mode | Command | Description |
|---|---|---|
| REPL | ch4p agent |
Interactive chat with teal-branded UI and optional --voice wake |
| Gateway | ch4p gateway |
Multi-channel server on port 18789 |
| Canvas | ch4p canvas |
Spatial browser workspace with infinite tldraw canvas |
Every subsystem is a trait interface — swap any component via config, zero code changes.
| Interface | Purpose |
|---|---|
IProvider |
LLM API abstraction (stream, complete, list models) |
IChannel |
Messaging surface (start, stop, send, onMessage) |
IMemoryBackend |
Persistent memory (store, recall, forget) |
ITool |
Agent tool (execute, validate, abort, state snapshots) |
IEngine |
Execution engine (startRun, resume) |
ISecurityPolicy |
Security enforcement (path/command validation, audit) |
IObserver |
Observability (session, tool, LLM, security events) |
ITunnelProvider |
Public URL exposure (start, stop, getPublicUrl) |
IVerifier |
Task-level outcome verification (format + semantic checks) |
IIdentityProvider |
On-chain agent identity and reputation (interface stable; implementation planned) |
packages/
core/ # Trait interfaces, types, errors, utilities
agent/ # Agent runtime: session, context, steering, worker pool
providers/ # LLM providers: Anthropic, OpenAI, Google, OpenRouter, Ollama, Bedrock
engines/ # Execution engines: native (LLM), echo (testing), subprocess (CLI wrappers)
channels/ # 16 messaging adapters (see Channels table below)
canvas/ # A2UI components, canvas state, WS protocol, CanvasTool, CanvasChannel
gateway/ # HTTP server, session routing, WebSocket bridge, cron, webhooks
tools/ # bash, file ops, grep, glob, web fetch/search, browser, memory, delegate, mesh, MCP
memory/ # Hybrid search: SQLite FTS5 + vector embeddings
security/ # Filesystem scope, command allowlist, secrets, I/O sanitization
supervisor/ # OTP-style supervision trees, health monitoring
observability/ # Console, file, multi-observer logging
skills/ # Skill discovery, YAML frontmatter, registry (OpenClaw compatible)
voice/ # STT (Whisper, Deepgram), TTS (ElevenLabs), always-on voice wake
tunnels/ # Cloudflare, Tailscale, ngrok
plugin-x402/ # x402 HTTP micropayment plugin: gateway middleware + agent tool
apps/
cli/ # CLI entry point (standalone binary via bun compile)
web/ # Canvas workspace: React + tldraw SPA
16 messaging adapters, each implementing IChannel:
| Channel | Transport | Edit streaming |
|---|---|---|
| CLI | stdio | — |
| Telegram | HTTP polling | ✓ |
| Discord | WebSocket gateway | ✓ |
| Slack | Socket Mode WS | — |
| Matrix | Long-poll sync | — |
| Webhook | — | |
| Signal | JSON-RPC subprocess | — |
| iMessage | sqlite3 polling + JXA | — |
| BlueBubbles | REST API + webhook | — |
| Teams | Bot Framework webhook | — |
| Google Chat | Service account webhook | ✓ |
| Zalo OA | Open API v3 webhook | — |
| Zalo Personal | REST bridge | — |
| IRC | Raw TCP/TLS | — |
| WebChat | WebSocket | ✓ |
| macOS Native | osascript dialogs | — |
Nine defense layers, all on by default:
- Filesystem scoping — operations constrained to workspace root, symlink escape detection
- Command allowlist — only approved commands execute, shell metacharacter injection blocked
- Encrypted secrets — AES-256-GCM with PBKDF2 key derivation
- Output sanitization — 25 regex patterns strip API keys, tokens, credentials from responses
- Input validation — prompt injection, jailbreak, and data exfiltration detection
- Autonomy levels —
readonly/supervised/fullcontrol - SSRF protection — private IP blocking, DNS checks, cloud metadata guards
- Secure file permissions — transcripts
0o600, log dirs0o700 - Pairing token expiration — 30-day TTL with automatic eviction
| Feature | Description |
|---|---|
| Hybrid verification | FormatVerifier + LLMVerifier two-phase check after each task, both on by default |
| State snapshots | Tools capture observable state before/after execution for diff-based verification |
| Auto-memory | Recall relevant memories before each message, store learnings after each run |
| Hybrid memory search | SQLite FTS5 BM25 + cosine vector similarity, configurable blend; OpenAI → Ollama → noop provider chain with automatic fallback |
| Crash recovery | Session notes survive gateway restarts; agent resumes in-flight tasks from where it left off |
| Canvas workspace | Spatial tldraw interface with 11 A2UI component types, bidirectional interaction |
| Skills | Curated instruction sets loaded on-demand via progressive disclosure (OpenClaw compatible) |
| Mesh orchestration | Swarm-style parallel sub-agents across engines, bounded concurrency, partial failure tolerance |
| Config-driven routing | Named agents with own system prompt/model/tools, channel + regex dispatch rules |
| Cron & webhooks | Built-in 5-field cron scheduler and POST /webhooks/:name trigger |
| Browser tool | Playwright-based navigation, clicking, typing, screenshots, JS eval with SSRF protection |
| MCP client | Connect to any Model Context Protocol server, discover and proxy tools |
| Voice wake | Opt-in always-on mic with VAD, wake word filtering, STT into agent loop |
| Worker pool | Heavyweight tools run in pooled threads (4 workers, 60s timeout) |
| Message chunking | Auto-split at word boundaries per platform limits (Telegram 4096, Discord 2000, etc.) |
| Permission forwarding | Subprocess permission prompts surface in chat, user replies route to stdin |
| x402 micropayments | Server 402 enforcement + client auto-pay on Base/USDC (ERC-8004 compatible) |
| Daemon installer | ch4p install — zero-sudo systemd (Linux) or launchd (macOS), auto-restart |
| Alternative LLMs | Ollama, LiteLLM proxy, or CLI passthrough — setup guide |
corepack pnpm -r build # Build all packages
npx vitest run # Run all tests
corepack pnpm audit # Check vulnerabilities
corepack pnpm --filter @ch4p/core build # Build single package- 19 packages in a pnpm monorepo (use
corepack pnpm— pnpm is not on PATH) - TypeScript strict mode, ES2023 target, NodeNext module resolution
- ESM-only (all imports use
.jsextension) - Zero required external runtime dependencies for core, security, and CLI
- 86 test files, 2457 tests, 0 vulnerabilities
Config lives in ~/.ch4p/config.json. The onboarding wizard (ch4p onboard) creates it interactively, or write it manually:
{
"agent": {
"provider": "anthropic",
"model": "claude-sonnet-4-6"
},
"providers": {
"anthropic": {
"apiKey": "${ANTHROPIC_API_KEY}"
}
},
"autonomy": { "level": "supervised" },
"memory": { "backend": "sqlite" }
}Environment variables referenced as ${VAR_NAME} are resolved at load time. ~/.ch4p/.env is loaded automatically at startup.
See Configuration Reference for all options.
Full Diataxis-style docs in docs/:
| Category | Guides |
|---|---|
| Tutorials | Getting Started · First Channel |
| How-to | Add Tool · Add Channel · Add Provider · Add Verifier |
| Security · Deploy Gateway · Memory · Canvas | |
| Web Search · Browser · Skills · MCP | |
| Cron & Webhooks · Voice · Observability | |
| Mesh · Routing · x402 · iMessage | |
| Alt LLM Setups · Test Channels | |
| Reference | Interfaces · Configuration · CLI · Security |
| Explanation | Architecture · Concurrency · Security Model · Memory |
See CONTRIBUTING.md for development setup, code standards, and how to submit changes.
For vulnerability reporting, see SECURITY.md. Do not open public issues for security concerns — use GitHub's private reporting.