ClawGear: Technical Design Document

Version: 0.2.0-draft Date: 2026-03-09 Status: Draft - Pending Review (updated with OpenFang repo deep-dive)

---

Table of Contents

1. Executive Summary
2. Source Analysis: What We Take From Each Project
3. Vision & Problem Statement
4. Architecture Overview
5. Core Systems Design
6. Organizational Model
7. Agent Runtime & Execution 7B. Workflow Engine & Trigger System
8. Communication & Protocol Stack
9. Memory & Knowledge Architecture
10. Security Model
11. Autonomous Operations (Hands)
12. Multi-Channel Integration
13. Skills & Marketplace
14. Observability & Governance
15. Desktop & Device Integration
16. Tech Stack Decisions
17. Monorepo Structure
18. Database Schema Design
19. API Design
20. Migration & Compatibility
21. Development Phases
22. Open Questions

---

1. Executive Summary

ClawGear is an open-source CEO Agent Operating System that combines the best architectural decisions from three leading agent platforms:

Feature Domain	Best-in-Class Source	What We Take
Performance & Security	OpenFang (Rust, 16 security layers, 180ms cold start)	WASM sandbox, Merkle audit trails, security-first design
Business Orchestration	Paperclip (org charts, budgets, atomic checkout)	Corporate hierarchy, governance, budget enforcement, goal alignment
Personal Agent UX	OpenClaw (290K stars, 20+ channels, device integration)	Multi-channel routing, device nodes, skills ecosystem, session management

The thesis: No existing project does all three well. OpenFang has the best runtime but no business orchestration. Paperclip has the best business model but limited runtime and no channels. OpenClaw has the best UX and ecosystem but no corporate hierarchy or budget controls.

ClawGear is the CEO agent that runs a business -- it orchestrates teams of specialized agents, enforces budgets, aligns work to goals, communicates across every channel, and does it all with production-grade security and performance.

---

2. Source Analysis

From OpenFang (Rust Agent OS)

ADOPT:

• Rust kernel for the core runtime (performance, safety, single binary)
• WASM dual-metered sandbox (fuel + epoch) for tool execution isolation
• 16-layer defense-in-depth security model
• Merkle hash-chain audit trail (cryptographic tamper evidence)
• Ed25519 manifest signing for agent/skill integrity
• OFP-style P2P mutual authentication (HMAC-SHA256)
• 4-tier model routing (frontier/smart/fast/lightweight)
• "Hands" concept -- autonomous background operations with SOPs
• Taint tracking for information flow control
• GCRA rate limiting
• Secret zeroization
• SQLite + sqlite-vec hybrid search (vector + BM25)
• Context compaction with pre-compaction memory flush

ADAPT:

• Tauri desktop app -> adopt but with a richer dashboard (Paperclip-style)
• 40 channel adapters -> start with OpenClaw's mature adapters, expand later
• FangHub marketplace -> merge with ClawHub model, unified registry

ADOPT (additional from repo deep-dive):

• Workflow engine with sequential, fan-out, collect, conditional, and loop execution modes
• Variable substitution system ({{input}}, {{named_var}}) for step chaining
• Error handling modes per step: fail, skip, retry (with max_retries)
• Trigger engine with event-driven automation (pattern matching on kernel event bus)
• 10 trigger patterns: All, Lifecycle, AgentSpawned, AgentTerminated, System, SystemKeyword, MemoryUpdate, MemoryKeyPattern, ContentMatch
• agent.toml template format for declarative agent configuration (30 bundled templates)
• Multi-runtime skill system: Python, WASM, Node.js, PromptOnly, Builtin
• skill.toml manifest with JSON Schema input validation for tool definitions
• Python SDK (SkillHandler) for easy skill development
• Capability-based security with enum patterns: FileRead("/data/*"), NetConnect("*.openai.com:443"), ToolInvoke(tool_id)
• Child agent capability inheritance (no privilege escalation)
• KernelHandle trait pattern to avoid circular deps between runtime and kernel
• AppState bridge pattern between kernel and API routes
• Alpine.js SPA dashboard in static HTML (lightweight, no build step for dashboard)
• Config via TOML with #[serde(default)] pattern for zero-config defaults
• Per-agent hourly token quota via UsageTracker with rolling 1-hour window
• 10-phase graceful shutdown sequence
• JavaScript and Python SDKs for external integrations

SKIP:

• Proprietary OFP protocol as the primary protocol -> use A2A + MCP as primary, OFP as optional P2P layer
• 14-crate structure -> simplify to fewer, more focused crates
• Alpine.js dashboard -> use React for richer interactivity (Paperclip-style)

From Paperclip (Business Orchestration)

ADOPT:

• Company/team/agent org chart hierarchy with reporting lines
• Atomic task checkout with database-level concurrency control
• Heartbeat execution model (agents wake, check, act, sleep)
• Three-tier budget enforcement (company -> agent -> project) with auto-pause
• Goal ancestry alignment (company mission -> team goals -> agent goals -> tasks)
• Governance controls (approval gates, config versioning, rollback)
• Board authority model with human-in-the-loop escalation
• Ticket/conversation threading for work tracking
• "Bring your own agent" adapter pattern
• Multi-company isolation with portable company templates
• Immutable append-only activity log
• Per-agent runtime state persistence across heartbeats
• Issue status state machine with side effects
• Cost event tracking with billing codes

ADAPT:

• PostgreSQL schema -> keep for the orchestration layer but pair with SQLite for agent-local memory
• TypeScript services -> rewrite critical paths in Rust, keep TypeScript for API/UI layers
• Drizzle ORM patterns -> adopt the schema patterns, implement in our stack
• Adapter registry -> extend with OpenClaw's richer adapter model

SKIP:

• Express.js API server -> use Axum (Rust) for the core API
• PGlite embedded mode -> SQLite for embedded, Postgres for production orchestration

From OpenClaw (Personal Agent Platform)

ADOPT:

• WebSocket Gateway protocol (v3) with typed JSON-RPC
• Multi-channel routing with deterministic binding rules
• Device node architecture (camera, screen, location, notifications)
• Canvas + A2UI agent-driven visual workspace
• Browser automation via CDP (Playwright layer)
• Skills as SKILL.md files with frontmatter metadata
• ClawHub-style community marketplace (13K+ skills)
• Session management with hierarchical session keys
• Model failover with auth profile rotation and backoff
• Hot-reload configuration pipeline (JSON5 + Zod validation)
• DM/group policies with pairing-based access control
• Context pruning strategies (FIFO, relevance, hybrid, cache-ttl)
• Operator/Node role separation
• Per-session Docker sandboxing for non-main sessions
• JSONL transcript persistence

ADAPT:

• Pi Agent runtime -> support as one adapter among many, not the only runtime
• Single-user architecture -> extend to multi-company multi-user (Paperclip model)
• 127.0.0.1 loopback binding -> add production-grade auth for remote deployments
• Companion apps -> integrate with Tauri desktop, add mobile companion nodes

SKIP:

• Tight coupling to Pi Agent SDK -> abstract the agent runtime interface
• CalVer versioning -> use SemVer for clarity

---

3. Vision & Problem Statement

Problem

Running a business with AI agents today requires stitching together:

• An agent framework (LangGraph, CrewAI, AutoGen) for agent execution
• A project manager (Linear, Jira) for task tracking
• A communication layer (Slack bots, Discord bots) for channels
• A monitoring stack (custom dashboards) for observability
• Manual budget tracking and no real governance

None of these integrate natively. There is no system where a CEO agent can:

1. Understand the company mission and decompose it into goals
2. Hire and manage a team of specialized agents
3. Assign work aligned to goals with budget constraints
4. Monitor execution with cryptographic audit trails
5. Communicate across every channel the business uses
6. Operate autonomously on schedules while respecting human approval gates

Vision

ClawGear is the operating system for AI-run businesses. A single deployment provides:

• CEO Agent: Strategic planning, goal decomposition, team management
• Org Chart: Hierarchical agent teams with roles, reporting lines, permissions
• Work System: Tickets, conversations, atomic checkout, heartbeat execution
• Budget Control: Per-agent and per-company spending limits with auto-enforcement
• Goal Alignment: Every task traces to the company mission
• Governance: Approval gates, config versioning, board oversight
• Multi-Channel: 20+ messaging platforms, unified inbox
• Device Integration: Camera, screen, browser, mobile companion nodes
• Security: 16-layer defense-in-depth, WASM sandboxing, Merkle audits
• Performance: Sub-200ms cold start, <50MB idle memory, single binary core

---

4. Architecture Overview

+-----------------------------------------------------------------------+
|                          ClawGear System                               |
|                                                                        |
|  +------------------+  +-------------------+  +---------------------+  |
|  |   Tauri Desktop  |  |   Web Dashboard   |  |   Mobile Nodes      |  |
|  |   (Native App)   |  |   (React UI)      |  |   (iOS/Android)     |  |
|  +--------+---------+  +---------+---------+  +----------+----------+  |
|           |                      |                       |             |
|           +----------------------+-----------------------+             |
|                                  |                                     |
|                          WebSocket Gateway                             |
|                     (Typed JSON-RPC Protocol)                          |
|                                  |                                     |
|  +-------------------------------+-------------------------------+     |
|  |                                                               |     |
|  |                      Rust Kernel (Axum)                       |     |
|  |                                                               |     |
|  |  +-------------+  +--------------+  +----------------------+  |     |
|  |  | Orchestrator|  | Agent Runtime|  | Security Engine      |  |     |
|  |  | - Org Chart |  | - WASM Sbox  |  | - 16 Layers          |  |     |
|  |  | - Goals     |  | - Heartbeat  |  | - Merkle Audit       |  |     |
|  |  | - Budgets   |  | - Adapters   |  | - Taint Tracking     |  |     |
|  |  | - Governance|  | - Model Tier |  | - RBAC               |  |     |
|  |  +-------------+  +--------------+  +----------------------+  |     |
|  |                                                               |     |
|  |  +-------------+  +--------------+  +----------------------+  |     |
|  |  | Work System |  | Memory       |  | Communication        |  |     |
|  |  | - Issues    |  | - SQLite+Vec |  | - 20+ Channels       |  |     |
|  |  | - Checkout  |  | - Embeddings |  | - A2A Protocol       |  |     |
|  |  | - Threads   |  | - Compaction |  | - MCP Client/Server  |  |     |
|  |  | - State     |  | - KV Store   |  | - P2P (OFP)          |  |     |
|  |  +-------------+  +--------------+  +----------------------+  |     |
|  |                                                               |     |
|  +---------------------------------------------------------------+     |
|                                  |                                     |
|          +-------------------+---+---+-------------------+             |
|          |                   |       |                   |             |
|  +-------+------+  +--------+---+  ++-------+  +-------+--------+    |
|  | PostgreSQL   |  | SQLite     |  | Canvas |  | Browser        |    |
|  | (Orchestr.)  |  | (Agent Mem)|  | (A2UI) |  | (CDP/Playwright)|   |
|  +--------------+  +------------+  +--------+  +----------------+    |
+-----------------------------------------------------------------------+

Dual-Database Strategy

Database	Purpose	Rationale
PostgreSQL	Orchestration data: companies, agents, issues, goals, budgets, approvals, audit logs, cost events	ACID transactions for atomic checkout, multi-company isolation, relational integrity for org charts and goal hierarchies
SQLite + sqlite-vec	Per-agent memory: embeddings, session transcripts, knowledge graphs, KV store	Agent-local, zero-config, portable, fast hybrid search (vector + BM25), no network overhead

This mirrors how a real company works: the corporate systems (ERP, HR, PM) run on a central database, while each employee keeps their own notes, files, and knowledge locally.

---

5. Core Systems Design

5.1 The Kernel

The kernel is the central coordinator, written in Rust. Inspired by OpenFang's 18-step boot sequence, it owns:

• Agent Lifecycle: spawn, configure, heartbeat, pause, resume, terminate
• Work Distribution: atomic issue checkout, assignment, delegation
• Budget Metering: cost event ingestion, threshold checks, auto-pause
• Model Routing: 4-tier selection, provider failover, auth profile rotation
• Security Enforcement: RBAC capability gates, taint propagation, rate limiting
• Event Bus: typed internal events for cross-system coordination (lifecycle, system, memory, content events)
• Scheduler: cron-based heartbeat triggers with skip conditions
• Workflow Engine: multi-step agent pipelines with fan-out, conditional, loop support
• Trigger Engine: event-driven automation via pattern matching on the event bus
• Usage Tracker: per-agent rolling 1-hour token quotas with QuotaExceeded enforcement

The kernel uses the KernelHandle trait pattern (from OpenFang) to avoid circular dependencies between runtime and kernel crates. An AppState struct bridges the kernel to API routes.

5.2 The Gateway

WebSocket-based control plane (adapted from OpenClaw's v3 protocol):

• Typed JSON-RPC: All messages validated against schemas
• Role-Based Connections: Operator (human/CLI), Node (device), Agent (internal)
• Hot-Reload Config: JSON5 + Zod validation, hybrid hot-apply/restart modes
• Presence Tracking: Connected clients, agent status, session metadata
• Event Streaming: Real-time events for dashboard, CLI, mobile clients

5.3 The API Layer

REST + WebSocket + SSE via Axum:

• REST: CRUD for all orchestration entities (companies, agents, issues, goals, etc.)
• WebSocket: Bidirectional agent communication, dashboard live updates
• SSE: Streaming agent responses for web clients
• OpenAI-Compatible: /v1/chat/completions and /v1/models for interop
• MCP Server: Expose ClawGear tools to external MCP clients
• A2A Server: Agent Card discovery and task delegation

---

6. Organizational Model

Adopted from Paperclip, enhanced with OpenFang's security model.

6.1 Company

Company
  - name, description, status (active|paused|archived)
  - issuePrefix (e.g., "CG"), issueCounter (auto-increment)
  - budgetMonthlyCents, spentMonthlyCents
  - requireBoardApprovalForNewAgents (default: true)
  - missionGoalId -> Goal (root company goal)

6.2 Agent Hierarchy

CEO Agent (role: ceo)
  |-- CTO Agent (role: cto, reportsTo: CEO)
  |     |-- Engineer Agent (role: engineer, reportsTo: CTO)
  |     |-- DevOps Agent (role: devops, reportsTo: CTO)
  |-- CMO Agent (role: cmo, reportsTo: CEO)
  |     |-- Social Media Agent (role: social, reportsTo: CMO)
  |     |-- Content Agent (role: content, reportsTo: CMO)
  |-- CFO Agent (role: cfo, reportsTo: CEO)
        |-- Analyst Agent (role: analyst, reportsTo: CFO)

Each agent has:

• Identity: id, name, title, role, icon, company scope
• Hierarchy: reportsTo (self-referencing FK), reporting tree
• Capabilities: declared tool set (immutable after creation, RBAC-enforced)
• Budget: individual budgetMonthlyCents, spentMonthlyCents
• Adapter: which runtime executes this agent (Claude Code, Codex, process, HTTP, etc.)
• Model Tier: preferred model tier (frontier/smart/fast/lightweight)
• Status: idle -> running -> idle | error -> idle | paused | terminated (irreversible)
• Permissions: canCreateAgents, canApproveStrategy, canDelegateWork, etc.
• Ed25519 Manifest: signed capability declaration for tamper-proof identity

6.3 Goal Alignment

Company Mission (level: company)
  |-- Team Goal: "Ship v2.0" (level: team, owner: CTO)
  |     |-- Agent Goal: "Build auth system" (level: agent, owner: Engineer)
  |     |     |-- Task Goal: "Implement JWT middleware" (level: task)
  |     |-- Agent Goal: "Set up CI/CD" (level: agent, owner: DevOps)
  |-- Team Goal: "Grow audience 10x" (level: team, owner: CMO)
        |-- Agent Goal: "Launch Twitter campaign" (level: agent, owner: Social)

Every issue links to a goal. Agents always see the full ancestry chain when picking up work, providing strategic context for tactical decisions.

6.4 Projects

Projects group related issues under a goal with:

• Lead agent assignment
• Target date
• Status tracking
• Color coding for dashboard visualization

---

7. Agent Runtime & Execution

7.1 Heartbeat Model (from Paperclip)

Agents do not run continuously. They execute in heartbeats:

Trigger (schedule | assignment | mention | manual)
  -> Wake agent
  -> Load runtime state (session, context snapshot)
  -> Execute heartbeat procedure:
       1. Identify self (read agent config, role, permissions)
       2. Check assignments (GET /issues?assignee=me&status=in_progress)
       3. Checkout new work if idle (POST /issues/:id/checkout)
       4. Read issue thread (full goal ancestry + comments)
       5. Execute work (tool calls, code generation, research)
       6. Post status updates (comments on the issue)
       7. Delegate if needed (create child issues, assign to reports)
       8. Report costs (POST /cost-events)
       9. Transition issue status
  -> Persist runtime state
  -> Sleep

7.2 Atomic Task Checkout (from Paperclip)

UPDATE issues
SET assignee_agent_id = $agent_id,
    status = 'in_progress',
    started_at = NOW(),
    checkout_run_id = $run_id
WHERE id = $issue_id
  AND status IN ('todo', 'backlog')
  AND (assignee_agent_id IS NULL OR assignee_agent_id = $agent_id);
-- 0 rows updated = 409 Conflict

• Idempotent: self-checkout returns success
• Stale run adoption: terminated runs release locks
• Wakeup logic: only wake assignee when checkout is by another agent

7.3 WASM Sandbox (from OpenFang)

All tool execution runs inside a Wasmtime WASM sandbox:

• Fuel metering: deterministic instruction counting, prevents compute abuse
• Epoch metering: wall-clock timeout, catches blocking/stalling
• Watchdog thread: kills runaway executions
• Workspace confinement: file I/O restricted to agent's workspace directory
• Subprocess isolation: env_clear() + selective passthrough, process tree kill
• Direct argv execution: shlex parsing, no shell interpreter (prevents injection)

7.4 Adapter System (from Paperclip + OpenClaw)

"Bring your own agent" -- ClawGear orchestrates, agents execute:

Adapter	Description	Session Support
claude_code	Claude Code CLI	Yes (resume sessions)
codex	OpenAI Codex CLI	Yes
cursor	Cursor IDE CLI	Yes
openclaw	OpenClaw gateway webhook	Yes
openfang	OpenFang A2A delegation	Yes
process	Generic process spawner	No
http	Generic HTTP webhook	No
custom	User-defined adapter	Configurable

Each adapter implements:

execute(ctx: AdapterContext) -> AdapterResult
testEnvironment(ctx) -> EnvironmentTestResult
sessionCodec? -> serialize/deserialize session state

7.5 Model Routing (from OpenFang + OpenClaw)

4-tier intelligent routing with failover:

Tier	Use Case	Examples
Frontier	CEO strategy, complex reasoning	Claude Opus, GPT-5
Smart	General tasks, coding, analysis	Claude Sonnet, Gemini 2.5 Flash
Fast	Quick responses, high throughput	Llama 3.3 70B, Gemini Flash
Lightweight	Simple queries, cost-sensitive	Small models via Groq/DeepSeek

Failover chain: auth profile rotation -> provider fallback -> tier downgrade. Backoff: rate-limit errors get short cooldowns, billing errors get exponential backoff (5h -> 10h -> 20h -> 24h cap).

---

7B. Workflow Engine & Trigger System

Adopted from OpenFang, integrated with ClawGear's organizational model.

7B.1 Workflow Engine

The workflow engine enables multi-step agent pipelines -- orchestrated sequences where each step routes work to a specific agent. Workflows compose complex behaviors without requiring code changes.

Workflow Definition:

name = "quarterly-report-pipeline"
description = "Generate quarterly business report"

[[steps]]
name = "gather-metrics"
agent_role = "analyst"           # resolved via org chart
prompt = "Pull Q4 metrics for: {{input}}"
timeout_secs = 300
output_var = "metrics"

[[steps]]
name = "market-research"
agent_role = "researcher"
mode = "fan_out"                 # runs in parallel with next fan_out
prompt = "Research market trends for: {{input}}"
output_var = "market"

[[steps]]
name = "competitor-analysis"
agent_role = "researcher"
mode = "fan_out"
prompt = "Analyze competitor activity for: {{input}}"
output_var = "competitors"

[[steps]]
name = "collect"
mode = "collect"                 # joins all fan_out outputs

[[steps]]
name = "draft-report"
agent_role = "writer"
prompt = "Draft Q4 report.\nMetrics: {{metrics}}\nMarket: {{market}}\nCompetitors: {{competitors}}"
output_var = "draft"

[[steps]]
name = "review-loop"
agent_role = "ceo"
mode = "loop"
max_iterations = 3
until = "APPROVED"
prompt = "Review report. Respond APPROVED if ready, else provide revision notes:\n\n{{input}}"
error_mode = "retry"
max_retries = 2

Execution Modes:

Mode	Behavior
sequential	Default. Previous output becomes {{input}}
fan_out	Consecutive fan_out steps run in parallel via join_all
collect	Joins all preceding fan_out outputs with separator
conditional	Executes only if previous output contains condition substring
loop	Repeats up to max_iterations, stops early on until match

Error Handling (per step):

Mode	Behavior
fail	Abort workflow immediately
skip	Silently skip, continue with unchanged {{input}}
retry	Retry up to max_retries times with fresh timeout per attempt

ClawGear Enhancement over OpenFang: Workflows resolve agents via org chart roles, not just agent IDs. The CEO can define a workflow that uses "the analyst" and "the researcher" -- if those agents are replaced, the workflow still works. Cost events from workflow runs are attributed to the workflow's parent goal.

7B.2 Trigger Engine

Event-driven automation via pattern matching on the kernel's internal event bus.

Trigger Definition:

agent_id = "<ceo-agent-uuid>"
pattern = { agent_terminated = {} }     # any agent crash/termination
prompt_template = "ALERT: {{event}}. Assess impact and reassign work."
max_fires = 0                            # unlimited
enabled = true

Event Patterns:

Pattern	Matches
all	Every event on the bus
lifecycle	Any agent lifecycle event
agent_spawned { name_pattern }	Agent creation matching pattern
agent_terminated	Any agent termination or crash
system	Health checks, quotas, system events
system_keyword { keyword }	System events containing keyword
memory_update	Any memory change
memory_key_pattern { key_pattern }	Memory updates by key pattern
content_match { substring }	Event descriptions containing substring
budget_threshold { percent }	Budget utilization crosses threshold (ClawGear addition)
approval_pending { type }	New approval request of specified type (ClawGear addition)
issue_status_change { from, to }	Issue transitions (ClawGear addition)

ClawGear Additions over OpenFang: Three new trigger patterns (budget_threshold, approval_pending, issue_status_change) integrate with the organizational model. The CEO agent can set up triggers like:

• "Alert me when any agent hits 80% budget"
• "Notify me when a strategy approval is pending"
• "Escalate when any issue moves to blocked"

When a trigger fires, {{event}} in the prompt template is replaced with a human-readable event description. Triggers with max_fires > 0 auto-disable after reaching the count.

---

8. Communication & Protocol Stack

8.1 Three-Protocol Architecture (from OpenFang)

Protocol	Purpose	Transport
MCP	Tool interoperability	JSON-RPC 2.0 over HTTP
A2A	Inter-agent task delegation	HTTP + SSE (Google standard)
P2P	Direct instance-to-instance	HMAC-SHA256 authenticated frames

8.2 MCP (Model Context Protocol)

• Client mode: Connect to external MCP servers to use their tools
• Server mode: Expose ClawGear tools to other MCP-compatible systems
• Tools namespaced as mcp_{server}_{tool} to prevent collisions

8.3 A2A (Agent-to-Agent)

• GET /.well-known/agent.json -- Agent Card discovery
• POST /a2a/tasks/send -- Delegate tasks to external agents
• GET /a2a/tasks/{id} -- Poll task status
• POST /a2a/tasks/{id}/cancel -- Abort delegated tasks
• Used for cross-deployment agent coordination

8.4 Internal Agent-to-Agent (from OpenClaw)

Within a ClawGear deployment, agents coordinate via session tools:

• sessions_list -- discover active agents
• sessions_history -- fetch transcripts
• sessions_send -- inter-agent messaging
• sessions_spawn -- create subagent instances

These map to the org chart: an agent can message its reports, its manager, or peers.

---

9. Memory & Knowledge Architecture

9.1 Dual-Store Design

PostgreSQL (Orchestration Memory):

• Company state, org charts, issues, goals, budgets
• Cost events, audit logs, approval history
• Config revisions for rollback
• Shared across all agents in a company

SQLite + sqlite-vec (Agent Memory):

• Per-agent knowledge base with vector embeddings
• Session transcripts (JSONL)
• Hybrid search: cosine similarity (70%) + BM25 keyword (30%)
• Agent-scoped KV store for persistent state
• Workspace-confined file index with delta tracking

9.2 Context Management (from OpenClaw + OpenFang)

Compaction: When context approaches the model's window limit:

1. Pre-compaction memory flush -- agent writes durable memories before truncation
2. LLM-based summarization of older messages
3. High-relevance messages preserved (hybrid pruning)

Pruning strategies (per-session configurable):

• fifo -- remove oldest messages first
• relevance -- use embeddings to keep most relevant
• hybrid -- FIFO but protect high-relevance messages
• cache-ttl -- prune expired cached tool outputs

Knowledge graphs: Built incrementally by autonomous Hands (Collector, Lead, Researcher). Graph-based fact linking across agent interactions.

9.3 Session Persistence

• Session keys follow OpenClaw's hierarchical model: agent:{agentId}:main, agent:{agentId}:{channel}:dm:{peer}, etc.
• Runtime state persisted across heartbeats (Paperclip model)
• JSONL transcript mirroring for durability and debugging
• Cross-channel canonical sessions (OpenFang) -- same conversation context regardless of channel

---

10. Security Model

16-layer defense-in-depth combining the strongest elements from all three projects:

#	Layer	Source	Description
1	WASM Dual-Metered Sandbox	OpenFang	Fuel + epoch metering with watchdog thread
2	Merkle Hash-Chain Audit	OpenFang	Cryptographically linked, tamper-evident action log
3	Taint Tracking	OpenFang	Information flow labels propagated source-to-sink
4	Ed25519 Manifest Signing	OpenFang	Signed agent identity and capability declarations
5	SSRF Protection	OpenFang	Block private IPs, cloud metadata, DNS rebinding
6	Secret Zeroization	OpenFang	Zeroizing<String> auto-wipes secrets from memory
7	P2P Mutual Auth	OpenFang	HMAC-SHA256 nonce-based, constant-time verification
8	RBAC Capability Gates	OpenFang	Immutable capability sets, enforced regardless of prompt
9	Security Headers	OpenFang	CSP, HSTS, X-Frame-Options, X-Content-Type-Options
10	Subprocess Sandbox	OpenFang	env_clear(), process tree isolation, direct argv exec
11	Prompt Injection Scanner	OpenFang	Detects override attempts, exfiltration patterns
12	Loop Guard	OpenFang	SHA256 tool call dedup with circuit breaker
13	Budget Enforcement	Paperclip	Auto-pause agents at 100% budget, warn at 80%
14	Approval Gates	Paperclip	Human-in-the-loop for hiring, strategy, purchases
15	DM/Group Policies	OpenClaw	Pairing-based access control, allowlists
16	Per-Session Docker Sandbox	OpenClaw	Non-main sessions run in isolated containers

Human-in-the-Loop Escalation

ClawGear enforces mandatory human approval for:

• Hiring new agents (when requireBoardApprovalForNewAgents is on)
• CEO strategy proposals before execution
• Financial transactions and purchases (Browser Hand approval gate)
• Social media posts (Twitter Hand approval queue)
• Budget increases
• Agent termination

Secret Management

• Agent API keys stored as SHA-256 hashes only (plaintext shown once)
• Company secrets versioned with SHA-256 verification and revocation
• Encrypted at rest via AES-256-GCM with per-instance master key
• Secret redaction in all logs, API responses, and exports

---

11. Autonomous Operations (Hands)

Adopted from OpenFang, integrated with Paperclip's governance model.

Hands are self-contained autonomous capability packages that run on schedules without user prompting. Each Hand bundles:

1. HAND.toml -- declarative config (tools, settings, metrics, requirements)
2. System Prompt -- multi-phase operational runbook with decision trees
3. SKILL.md -- domain expertise and methodology
4. Execution Engine -- background process with SOPs, knowledge graphs, dashboard reporting

Built-in Hands (Phase 1)

Hand	Domain	Governance Integration
Researcher	Deep research with CRAAP methodology	Reports findings as issue comments
Lead	ICP-based lead generation and scoring	Creates issues for high-score leads, tracks costs
Collector	OSINT intelligence monitoring	Critical alerts escalate to CEO agent
Clip	Video-to-short-form content pipeline	Content enters approval queue before publishing
Twitter	X/Twitter account management	All posts require approval gate
Browser	Web automation and workflows	Purchases require explicit human approval
Predictor	Forecasting with Brier score calibration	Predictions attached to strategic goals

Hands + Governance

Unlike standalone OpenFang, ClawGear Hands operate within the organizational model:

• Every Hand action is logged to the Merkle audit trail
• Hands respect agent budget limits
• Hand outputs create issues in the work system
• Approval gates are enforced by the kernel, not by the Hand itself
• Hand costs are attributed to the owning agent's budget

---

12. Multi-Channel Integration

Adopted from OpenClaw's mature adapter system, extended with Paperclip's multi-company routing.

Channel Adapters (Phase 1)

Channel	Library	Priority
Slack	@slack/bolt	P0 (launch)
Discord	discord.js	P0 (launch)
Telegram	grammY	P0 (launch)
WhatsApp	@whiskeysockets/baileys	P1
Microsoft Teams	Bot Framework	P1
WebChat	Built-in	P0 (launch)
Email	IMAP/SMTP	P1
Matrix	matrix-js-sdk	P2
IRC	irc-framework	P2

Routing Model

Inbound message
  -> Channel adapter normalizes to internal format
  -> Company resolution (multi-tenant: which company?)
  -> Binding lookup: (channel, account, peer/group) -> agentId
  -> DM/Group policy enforcement
  -> Session resolution (hierarchical session key)
  -> Agent heartbeat trigger
  -> Response routed back to originating channel

Bindings are deterministic (no LLM reasoning for routing). Most specific binding wins.

Multi-Company Channel Isolation

Each company has its own set of channel bindings. A Slack workspace binds to one company. Cross-company message routing is impossible by design.

---

13. Skills & Marketplace

13.1 Skill Format (Dual Format)

ClawGear supports two skill formats to cover all use cases:

Format A: SKILL.md (Expert Knowledge / Prompt-Only)

For injecting domain expertise and procedures into agent context:

---
name: customer-onboarding
version: 1.0.0
triggers:
  - "onboard new customer"
  - "customer setup"
permissions:
  tools: [browser, email]
  filesystem: [read, write]
sha256: <hash for integrity verification>
---

# Customer Onboarding

## When to Use
When a new customer signs up and needs account setup...

## Procedure
1. Verify customer details via CRM API
2. Create account in the system
3. Send welcome email
4. Schedule onboarding call
...

Format B: skill.toml (Executable Tools)

For skills that provide new tool capabilities with code execution:

[skill]
name = "crm-integration"
version = "0.1.0"
description = "CRM operations for customer management"
author = "clawgear-community"
license = "MIT"
tags = ["crm", "customers", "sales"]

[runtime]
type = "python"              # python | wasm | node | prompt_only | builtin
entry = "src/main.py"

[[tools.provided]]
name = "crm_create_customer"
description = "Create a new customer record in the CRM"
input_schema = { type = "object", properties = { name = { type = "string" }, email = { type = "string" } }, required = ["name", "email"] }

[[tools.provided]]
name = "crm_lookup_customer"
description = "Look up customer by email or ID"
input_schema = { type = "object", properties = { query = { type = "string" } }, required = ["query"] }

[requirements]
tools = ["web_fetch"]
capabilities = ["NetConnect(*.salesforce.com:443)"]

13.1B Multi-Runtime Skill Execution (from OpenFang)

Runtime	Language	Sandboxing	Best For
python	Python 3.8+	Subprocess isolation (env_clear)	Easy implementation, data processing
wasm	Rust, C, Go (compiled)	Wasmtime sandbox (fuel + epoch)	Security-critical tools, untrusted code
node	JavaScript/TypeScript	Subprocess isolation	OpenClaw skill compatibility
prompt_only	Markdown (SKILL.md)	N/A	Expert knowledge injection
builtin	Rust	N/A (compiled into binary)	Core tools, performance-critical

Skills communicate via JSON over stdin/stdout (Python/Node) or WASM host calls. The skill receives { "tool": "name", "input": {...}, "agent_id": "...", "agent_name": "..." } and returns { "result": "..." } or { "error": "..." }.

13.1C Agent Template Format (from OpenFang)

Declarative agent.toml for reusable agent definitions:

[agent]
name = "sales-assistant"
version = "0.1.0"
description = "Handles prospect outreach and pipeline management"
module = "builtin:chat"

[model]
tier = "smart"                      # frontier | smart | fast | lightweight
max_tokens = 8192
temperature = 0.3

[fallback]
tier = "fast"

[schedule]
enabled = true
interval_secs = 120

[resources]
max_llm_tokens_per_hour = 500000

[capabilities]
tools = ["email_send", "crm_lookup_customer", "crm_create_customer", "memory_store", "memory_recall"]
memory_read = ["self.*", "shared.leads.*"]
memory_write = ["self.*"]
agent_messaging = ["ceo", "cmo"]    # can message these agents
skills = ["crm-integration", "email-templates"]

30 bundled templates cover common roles: analyst, architect, coder, customer-support, debugger, devops-lead, doc-writer, email-assistant, ops, orchestrator, researcher, sales-assistant, security-auditor, social-media, test-engineer, writer, and more.

13.2 Skill Injection (from Paperclip)

During each heartbeat, the adapter injects relevant skills into the agent's context:

1. Skills directory is resolved (workspace > user > bundled)
2. A manifest (names, descriptions, paths) is injected into the system prompt
3. The agent reads full SKILL.md on-demand when relevant
4. Environment variables auto-injected: CLAWGEAR_AGENT_ID, CLAWGEAR_COMPANY_ID, CLAWGEAR_API_URL, CLAWGEAR_RUN_ID

13.3 GearHub Marketplace

Unified marketplace combining OpenFang's FangHub and OpenClaw's ClawHub concepts:

• Publishing: Ed25519 signing + SHA-256 verification
• Discovery: Search, browse by category, featured/trending
• Installation: clawgear skill install <name> with integrity verification
• Security: Automated scanning for malicious patterns (addressing ClawHub's CVE-2026-25253 and the ClawHavoc incident)
• Compatibility: Import from FangHub and ClawHub registries

---

14. Observability & Governance

14.1 Dashboard (React + Vite)

View	Description
Org Chart	Visual hierarchy with agent status indicators
Goal Tree	Company mission -> team -> agent -> task decomposition
Issue Board	Kanban/list view with filters, search, assignment
Agent Detail	Heartbeat history, cost breakdown, session transcripts
Budget Monitor	Per-agent and per-company spend vs. limits
Audit Trail	Searchable Merkle-verified action log
Approval Queue	Pending approvals for board review
Channel Status	Connected channels, message throughput, errors
Hand Dashboard	Autonomous operation metrics, outputs, schedules
System Health	API latency, memory usage, provider status

14.2 Audit Trail (from OpenFang + Paperclip)

Every action is double-logged:

1. Activity Log (PostgreSQL): append-only table with actor, action, entity, details (sanitized). Real-time events via WebSocket.
2. Merkle Hash-Chain (Rust kernel): cryptographically linked entries. Tampering breaks the chain. Verifiable via GET /api/audit/verify.

14.3 Cost Tracking

Cost Event:
  - provider, model, inputTokens, outputTokens
  - costCents (computed from model pricing)
  - companyId, agentId, issueId, projectId, goalId
  - billingCode (optional attribution tag)
  - occurredAt timestamp

Atomic increment of agent and company spentMonthlyCents on every cost event. Auto-pause at 100%, warning at 80%. Board can override.

14.4 Governance Controls

Control	Description
Approval Gates	Configurable gates for hiring, strategy, purchases, publishing
Config Versioning	Every agent config change creates a revision with before/after snapshots
Rollback	Restore any prior agent configuration revision
Board Override	Pause/resume/terminate any agent, reassign any task, edit any budget
Company Portability	Export/import company templates with secret scrubbing and collision handling

---

15. Desktop & Device Integration

15.1 Tauri 2.0 Desktop App (from OpenFang)

• Dual-thread model: main thread (WebView + system tray) + background server thread (full kernel)
• System tray: show window, open in browser, status indicator, quit
• Close-to-tray: window close hides instead of quitting
• Notifications: kernel events forwarded as native OS notifications
• Single instance: prevents multiple concurrent instances

15.2 Device Nodes (from OpenClaw)

Mobile and desktop companion apps connect as Node clients to the Gateway:

Capability	Methods
Camera	snap, record clip
Screen	record, screenshot
Location	get current position
Notifications	system.notify with priority levels
Canvas	A2UI rendering surface
Voice	push-to-talk, wake word

Node pairing: device sends pair request -> operator approves -> JWT token issued -> token rotatable/revocable.

15.3 Browser Automation (from OpenClaw)

Three-layer architecture:

1. Browser Layer: isolated Chromium instance (separate from personal browser)
2. Control Layer: HTTP API using Playwright on top of CDP
3. Agent Layer: tool interface for AI model access

Extension Relay mode enables controlling existing browser tabs with logged-in sessions.

15.4 Canvas + A2UI (from OpenClaw)

Agent-driven visual workspace:

1. Agent generates HTML with A2UI attributes
2. Canvas server pushes to connected clients
3. User interactions on A2UI elements become tool calls back to the agent
4. Agent processes actions and updates the display

Runs as a separate process for crash isolation.

---

16. Tech Stack Decisions

Layer	Technology	Rationale
Core Kernel	Rust	Performance (180ms cold start, 40MB idle), memory safety, single binary deployment
HTTP Framework	Axum 0.8	Async Rust, tower middleware ecosystem, proven in OpenFang
WASM Runtime	Wasmtime	Mature, dual-metering support, OpenFang-proven
Orchestration DB	PostgreSQL 17+	ACID for atomic checkout, relational integrity, multi-tenant
Agent Memory DB	SQLite + sqlite-vec	Zero-config, fast hybrid search, agent-local
Desktop App	Tauri 2.0	Native performance, small binary, Rust backend
Web Dashboard	React + Vite	Ecosystem, component libraries, fast dev cycle
API Types	TypeScript (shared)	Type safety between API server and dashboard
CLI	Rust (clap)	Same binary as kernel, fast startup
Schema Validation	Zod (TypeScript) + serde (Rust)	Runtime validation for configs and API payloads
Messaging	Platform-specific SDKs	grammY, @slack/bolt, discord.js, baileys
Testing	Rust: cargo test / TS: Vitest	Native test runners for each language
Build	Cargo workspaces + pnpm	Monorepo management for Rust + TypeScript

Language Boundary

• Rust: kernel, runtime, security, memory, CLI, desktop shell
• TypeScript: web dashboard, channel adapters (wrapping platform SDKs), shared API types, skill processing
• Bridge: The Rust kernel exposes a REST/WebSocket API. TypeScript code communicates via HTTP/WS, never through FFI. Clean process boundary.

---

17. Monorepo Structure

clawgear/
  crates/
    clawgear-kernel/        # Core orchestrator, scheduler, budget, RBAC
    clawgear-runtime/       # Agent execution, WASM sandbox, adapters, tools
    clawgear-api/           # Axum HTTP/WS/SSE server, OpenAI-compat, MCP, A2A
    clawgear-memory/        # SQLite + sqlite-vec, embeddings, compaction, KV
    clawgear-security/      # Merkle audit, taint tracking, Ed25519 signing
    clawgear-channels/      # Channel adapter bridge (Rust side)
    clawgear-wire/          # P2P protocol, HMAC-SHA256 mutual auth
    clawgear-hands/         # Autonomous Hands, HAND.toml parser, lifecycle
    clawgear-cli/           # CLI with TUI dashboard
    clawgear-desktop/       # Tauri 2.0 app shell
    clawgear-migrate/       # Migration from OpenFang/OpenClaw/Paperclip
  packages/
    @clawgear/db/           # Drizzle ORM schema + migrations (PostgreSQL)
    @clawgear/shared/       # API types, validators, constants (TypeScript)
    @clawgear/adapters/     # Agent adapters (Claude Code, Codex, etc.)
      claude-code/
      codex/
      openclaw-gateway/
      openfang-a2a/
      process/
      http/
    @clawgear/channels/     # Channel adapters (TypeScript side)
      slack/
      discord/
      telegram/
      whatsapp/
      webchat/
  apps/
    dashboard/              # React + Vite web UI
    macos/                  # Tauri macOS specifics
    ios/                    # Mobile companion (Swift)
    android/                # Mobile companion (Kotlin)
  skills/
    clawgear/               # Core heartbeat skill
    create-agent/           # Agent hiring skill
    memory-management/      # Memory/knowledge skill
  hands/
    researcher/             # HAND.toml + SKILL.md + system prompt
    lead/
    collector/
    clip/
    twitter/
    browser/
    predictor/
  docs/                     # Documentation (Mintlify)
  docker/                   # Dockerfiles (main, sandbox, browser)
  TDD.md                    # This document

---

18. Database Schema Design

PostgreSQL (Orchestration)

Key tables (Drizzle ORM, UUIDs, company-scoped):

companies
  id, name, description, status, issuePrefix, issueCounter,
  budgetMonthlyCents, spentMonthlyCents,
  requireBoardApprovalForNewAgents, createdAt, updatedAt

agents
  id, companyId, name, title, role, icon, status,
  reportsTo -> agents.id (self-ref),
  capabilities (JSONB), permissions (JSONB),
  adapterType, adapterConfig (JSONB),
  modelTier, modelOverride,
  budgetMonthlyCents, spentMonthlyCents,
  manifestSignature (Ed25519),
  createdAt, updatedAt

goals
  id, companyId, parentId -> goals.id (self-ref),
  level (company|team|agent|task), status,
  ownerAgentId, title, description,
  createdAt, updatedAt

projects
  id, companyId, goalId, leadAgentId,
  name, description, status, targetDate, color,
  createdAt, updatedAt

issues
  id, companyId, projectId, goalId, parentId -> issues.id,
  issueNumber, identifier (computed: prefix + number),
  title, description, status, priority,
  assigneeAgentId, checkoutRunId, executionLockedAt,
  billingCode, requestDepth,
  startedAt, completedAt, cancelledAt,
  createdAt, updatedAt

issue_comments
  id, companyId, issueId, authorAgentId, authorUserId,
  body, createdAt

heartbeat_runs
  id, companyId, agentId, invocationSource,
  status (queued|running|succeeded|failed|cancelled|timed_out),
  sessionIdBefore, sessionIdAfter, contextSnapshot (JSONB),
  logSha256, usageJson, resultJson,
  startedAt, finishedAt

cost_events
  id, companyId, agentId, issueId, projectId, goalId,
  provider, model, inputTokens, outputTokens, costCents,
  billingCode, occurredAt

approvals
  id, companyId, type, status (pending|approved|rejected|cancelled),
  requestedByAgentId, payload (JSONB),
  decidedByUserId, decisionNote, decidedAt,
  createdAt

agent_config_revisions
  id, companyId, agentId, beforeConfig (JSONB), afterConfig (JSONB),
  changedKeys (text[]), source (patch|rollback),
  rolledBackFromRevisionId, createdAt

activity_log (append-only)
  id, companyId, actorType, actorId, action,
  entityType, entityId, agentId, runId,
  details (JSONB, sanitized), createdAt

company_secrets
  id, companyId, name, currentVersionId, createdAt

company_secret_versions
  id, secretId, version (monotonic), encryptedValue,
  sha256, revokedAt, createdAt

agent_wakeup_requests
  id, companyId, agentId, source, triggerDetail,
  coalescedCount, idempotencyKey,
  requestedAt, claimedAt, finishedAt

agent_runtime_state
  agentId (PK), sessionId, stateJson (JSONB),
  lastRunId, lastRunStatus,
  cumulativeTokens, cumulativeCostCents, updatedAt

workflows
  id, companyId, name, description,
  steps (JSONB -- array of WorkflowStep),
  createdByAgentId, goalId,
  createdAt, updatedAt

workflow_runs
  id, companyId, workflowId,
  state (pending|running|completed|failed),
  input, output,
  stepResults (JSONB -- array of StepResult),
  triggeredByAgentId, costCents,
  startedAt, finishedAt

triggers
  id, companyId, agentId,
  pattern (JSONB -- TriggerPattern enum),
  promptTemplate, enabled,
  fireCount, maxFires,
  createdAt

skills
  id, companyId, name, version, description,
  runtimeType (python|wasm|node|prompt_only|builtin),
  entryPath, manifestHash (SHA-256),
  signatureEd25519, installedFrom (local|gearhub|fanghub|clawhub),
  createdAt

SQLite (Per-Agent Memory)

files
  path, sourceType, contentHash, indexedAt

chunks
  id, fileId, text, lineStart, lineEnd, contentHash,
  embeddingModel, embedding (BLOB)

chunks_vec (virtual, sqlite-vec)
  rowid, embedding (float vector)

chunks_fts (virtual, FTS5)
  text

kv_store
  key, value, updatedAt

sessions
  key, transcript (JSONL path), lastActiveAt, pruneAfter

---

19. API Design

REST Endpoints (grouped)

System

• GET /api/health -- public health check (minimal)
• GET /api/health/detail -- authenticated detailed diagnostics
• GET /api/status -- system status, agent count, uptime
• POST /api/shutdown -- graceful shutdown

Companies

• GET/POST /api/companies -- list/create
• GET/PATCH/DELETE /api/companies/:id -- read/update/delete
• GET /api/companies/:id/costs/summary -- budget utilization
• GET /api/companies/:id/costs/by-agent -- per-agent costs
• POST /api/companies/:id/export -- export company template
• POST /api/companies/import -- import company template

Agents

• GET/POST /api/companies/:cid/agents -- list/create
• GET/PATCH /api/companies/:cid/agents/:id -- read/update
• POST /api/companies/:cid/agents/:id/terminate -- irreversible termination
• POST /api/companies/:cid/agents/:id/pause -- pause agent
• POST /api/companies/:cid/agents/:id/resume -- resume agent
• GET /api/companies/:cid/agents/:id/config-revisions -- config history
• POST /api/companies/:cid/agents/:id/config-revisions/:rid/rollback -- rollback

Issues

• GET/POST /api/companies/:cid/issues -- list/create
• GET/PATCH /api/companies/:cid/issues/:id -- read/update
• POST /api/companies/:cid/issues/:id/checkout -- atomic checkout
• POST /api/companies/:cid/issues/:id/release -- release assignment
• GET/POST /api/companies/:cid/issues/:id/comments -- thread

Goals

• GET/POST /api/companies/:cid/goals -- list/create
• GET/PATCH /api/companies/:cid/goals/:id -- read/update

Approvals

• GET /api/companies/:cid/approvals -- list pending
• POST /api/companies/:cid/approvals/:id/approve -- approve
• POST /api/companies/:cid/approvals/:id/reject -- reject

Heartbeats

• POST /api/companies/:cid/agents/:id/heartbeat -- trigger heartbeat
• GET /api/companies/:cid/agents/:id/runs -- run history
• GET /api/companies/:cid/agents/:id/runs/:rid -- run detail
• POST /api/companies/:cid/agents/:id/runs/:rid/cancel -- cancel run

Workflows

• GET/POST /api/companies/:cid/workflows -- list/create workflow definitions
• POST /api/companies/:cid/workflows/:id/run -- execute workflow (sync, blocks until complete)
• GET /api/companies/:cid/workflows/:id/runs -- list execution history
• GET /api/companies/:cid/workflows/:id/runs/:rid -- run detail with step results

Triggers

• GET/POST /api/companies/:cid/triggers -- list/create triggers
• PUT /api/companies/:cid/triggers/:id -- enable/disable trigger
• DELETE /api/companies/:cid/triggers/:id -- remove trigger

Hands

• POST /api/hands/:name/activate -- start autonomous execution
• POST /api/hands/:name/deactivate -- stop
• GET /api/hands/:name/status -- current status and metrics
• GET /api/hands -- list all hands

Skills & Marketplace

• GET /api/skills -- list installed skills
• POST /api/skills/install -- install from GearHub
• GET /api/gearhub/search -- search marketplace
• GET /api/gearhub/browse -- browse categories

Audit

• GET /api/audit/recent -- recent audit entries
• GET /api/audit/verify -- Merkle chain verification

MCP

• POST /mcp -- JSON-RPC 2.0 MCP endpoint

A2A

• GET /.well-known/agent.json -- Agent Card
• POST /a2a/tasks/send -- delegate task
• GET /a2a/tasks/:id -- poll task
• POST /a2a/tasks/:id/cancel -- cancel task

OpenAI-Compatible

• POST /v1/chat/completions -- chat completions
• GET /v1/models -- model list

WebSocket

GET /api/agents/:id/ws -- bidirectional agent communication

Events: connected, thinking, text_delta, tool_start, tool_result, response, agents_updated, error, pong

Commands: /new, /compact, /model, /stop, /usage, /think, /models

SSE

POST /api/agents/:id/message/stream -- streaming responses

Events: chunk, tool_use, tool_result, done (with usage stats)

CLI Commands

# Core
clawgear init                                    # Interactive setup
clawgear start                                   # Launch kernel + dashboard
clawgear status                                  # System status

# Company management
clawgear company create <name>                   # Create company
clawgear company list                            # List companies

# Agent management
clawgear agent spawn <template> --company <id>   # Create from template
clawgear agent list --company <id>               # List agents
clawgear agent chat <name>                       # Interactive chat session
clawgear agent pause <name>                      # Pause agent
clawgear agent resume <name>                     # Resume agent

# Work management
clawgear issue create <title> --company <id>     # Create issue
clawgear issue list --company <id>               # List issues
clawgear issue assign <id> --agent <name>        # Assign to agent

# Workflows
clawgear workflow list --company <id>            # List workflows
clawgear workflow create <file> --company <id>   # Create from TOML file
clawgear workflow run <id> <input>               # Execute workflow

# Triggers
clawgear trigger list --company <id>             # List triggers
clawgear trigger create <agent> <pattern_json>   # Create trigger
clawgear trigger delete <id>                     # Remove trigger

# Hands
clawgear hand activate <name>                    # Start autonomous execution
clawgear hand deactivate <name>                  # Stop
clawgear hand status <name>                      # Check progress
clawgear hand list                               # Show all Hands

# Skills
clawgear skill install <name>                    # Install from GearHub
clawgear skill create                            # Scaffold new skill
clawgear skill list                              # List installed
clawgear skill publish                           # Publish to GearHub
clawgear skill search <query>                    # Search GearHub

# Migration
clawgear migrate --from openfang                 # Migrate from OpenFang
clawgear migrate --from openclaw                 # Migrate from OpenClaw
clawgear migrate --from paperclip                # Migrate from Paperclip
clawgear migrate --dry-run                       # Preview changes

---

20. Migration & Compatibility

ClawGear provides one-command migration from all three source projects:

clawgear migrate --from openfang    # Migrate agents, memory, skills
clawgear migrate --from openclaw    # Migrate config, sessions, skills
clawgear migrate --from paperclip   # Migrate companies, agents, issues

Source	What Migrates
OpenFang	Agent configs, memory DBs, skills, Hands, FangHub installs
OpenClaw	Config.yml, sessions, memory files, ClawHub skills, channel configs
Paperclip	Companies, org charts, issues, goals, budgets, adapters, skills

Marketplace Compatibility

GearHub can install skills from:

• GearHub native registry
• FangHub (OpenFang compatibility layer)
• ClawHub (OpenClaw compatibility layer)

---

21. Development Phases

Phase 0: Foundation

• Rust workspace setup with core crates
• PostgreSQL schema (Drizzle) for orchestration entities
• SQLite memory store with sqlite-vec
• Basic Axum API server with auth
• CLI skeleton (clawgear init, clawgear start)

Phase 1: Orchestration Core

• Company/agent/goal/project CRUD
• Org chart with reporting hierarchy
• Issue system with atomic checkout
• Heartbeat execution engine
• Budget enforcement with auto-pause
• Activity log (append-only)
• Basic web dashboard (React + Vite)

Phase 2: Agent Runtime

• WASM sandbox with dual metering
• Adapter system (Claude Code, process, HTTP)
• Model routing with 4-tier selection
• Provider failover with auth profile rotation
• Session persistence across heartbeats
• Skill injection system
• Agent-to-agent internal messaging

Phase 3: Security Hardening

• Merkle hash-chain audit trail
• Ed25519 manifest signing
• Taint tracking
• SSRF protection + secret zeroization
• Prompt injection scanner
• Loop guard + session repair
• RBAC capability gates
• GCRA rate limiting

Phase 4: Communication

• WebSocket Gateway (typed JSON-RPC)
• Channel adapters: Slack, Discord, Telegram, WebChat
• Multi-company channel routing
• DM/group policies with pairing
• SSE streaming for web clients

Phase 5: Autonomous Operations

• Hands framework (HAND.toml, lifecycle management)
• Researcher, Lead, Collector Hands
• Browser Hand with approval gates
• Twitter Hand with approval queue
• Hand dashboard with metrics

Phase 6: Desktop & Devices

• Tauri 2.0 desktop app
• Device node pairing protocol
• Camera, screen, location integration
• Canvas + A2UI visual workspace
• Browser automation (CDP/Playwright)

Phase 7: Ecosystem

• GearHub marketplace
• Skill publishing with Ed25519 signing
• FangHub/ClawHub import compatibility
• Migration engine (OpenFang, OpenClaw, Paperclip)
• Company template export/import

Phase 8: Scale & Polish

• Additional channel adapters (WhatsApp, Teams, Matrix, etc.)
• Mobile companion apps (iOS, Android)
• Performance optimization pass
• Documentation (Mintlify)
• Community infrastructure

---

22. Open Questions

These need to be resolved before or during implementation:

#	Question	Options	Impact
1	Should the TypeScript layer be a separate process or embedded via wasm-bindgen?	A) Separate process (REST/WS bridge) B) Embedded via wasm-bindgen C) Neon (Rust<->Node.js)	Architecture, deployment complexity
2	Which embedded DB for development mode?	A) PGlite (Paperclip approach) B) SQLite with a Postgres-compat layer C) Always require Postgres	Developer experience vs. production parity
3	Should Hands be compiled into the binary or loaded dynamically?	A) Compiled (OpenFang approach) B) Dynamic plugins C) Hybrid (core compiled, custom dynamic)	Extensibility vs. security vs. binary size
4	How should the CEO agent's strategic planning work?	A) Predefined strategy templates B) LLM-driven goal decomposition C) Human-defined goals, AI-optimized execution	Autonomy level
5	What is the licensing model?	A) MIT B) Apache-2.0 C) Dual MIT/Apache (OpenFang approach) D) AGPL-3.0	Community adoption vs. protection
6	Should we support OpenClaw's Pi Agent as a first-class runtime or only via the adapter?	A) First-class (embed Pi Agent) B) Adapter only (webhook)	Complexity vs. ecosystem compatibility
7	How do we handle the ClawHub security problem (12-20% malicious skills)?	A) Manual review + automated scanning B) Reputation system + sandboxed execution C) Curated registry only	Ecosystem openness vs. safety
8	Multi-tenancy model for SaaS deployment?	A) Database-per-company B) Schema-per-company C) Row-level isolation (current design) D) Not a goal (self-hosted only)	Scale, isolation, operational complexity

---

Appendix A: Competitive Comparison

Feature	ClawGear	OpenFang	Paperclip	OpenClaw
Language	Rust + TypeScript	Rust	TypeScript	TypeScript
Org Chart	Yes	No	Yes	No
Goal Alignment	Yes	No	Yes	No
Budget Enforcement	Yes	No	Yes	No
Approval Gates	Yes	Partial (Hands)	Yes	No
WASM Sandbox	Yes	Yes	No	No
Merkle Audit	Yes	Yes	No	No
Multi-Channel	Yes (20+)	Yes (40)	No	Yes (20+)
Device Nodes	Yes	No	No	Yes
Browser Automation	Yes	Yes	No	Yes
Canvas/A2UI	Yes	No	No	Yes
Autonomous Hands	Yes	Yes	No	No
Atomic Checkout	Yes	No	Yes	No
Heartbeat Model	Yes	No	Yes	No
Model Routing	4-tier	4-tier	Via adapter	Failover chains
Agent Adapters	8+	N/A (native)	8	N/A (Pi native)
Skills Marketplace	GearHub	FangHub	Directory	ClawHub (13K+)
MCP Support	Client + Server	Client + Server	No	Client
A2A Protocol	Yes	Yes	No	No
Desktop App	Tauri 2.0	Tauri 2.0	No	Native (Swift)
Mobile App	iOS + Android	No	No	iOS + Android
Security Layers	16	16	~5	~8
Cold Start	<200ms target	180ms	~2s	~1s
Idle Memory	<50MB target	40MB	~150MB	~100MB

---

Appendix B: Key Design Principles

1. Business-first: Every technical decision serves the goal of running a business autonomously.
2. Defense-in-depth: Security is not a feature, it's 16 layers that are always on.
3. Human-in-the-loop: Autonomy within guardrails. Humans approve strategy, hiring, and spending.
4. Goal alignment: Work without purpose is waste. Every task traces to the mission.
5. Budget discipline: Agents that overspend get paused. No exceptions.
6. Adapter agnostic: The best agent for the job might be Claude, GPT, or a shell script. ClawGear doesn't care.
7. Channel native: A business communicates everywhere. One inbox to rule them all.
8. Audit everything: If it happened, it's in the Merkle chain. Cryptographically.
9. Single binary core: The kernel is one binary. No dependency hell.
10. Composable autonomy: Hands operate independently but within the governance framework.