cashclaw

Manages complete service delivery workflows through a deterministic state machine (pending → accepted → executing → completed/failed) with every state transition persisted as immutable JSON records in ~/.cashclaw/missions/. Each mission is stored as a UUID-keyed JSON file capturing client request, work execution, and completion metadata. The Mission Runner (src/core/mission-runner.js) implements CRUD operations and enforces state validity, preventing invalid transitions and enabling forensic reconstruction of all work performed.

Runs a background polling loop that continuously queries the HYRVEai marketplace API (50+ endpoints) for new job postings matching the agent's configured skills, automatically accepts matching jobs based on configurable criteria, and transitions them into the mission lifecycle. The daemon implements exponential backoff for API failures, maintains polling state, and integrates with the HYRVEai Bridge (src/integrations/hyrve-bridge.js) for agent registration and job discovery. Auto-accept mode bypasses manual approval, enabling fully autonomous work acceptance.

Maintains an immutable audit trail for every mission by recording all state transitions, skill executions, and payment events as JSON entries appended to mission records. Each mission file (UUID-keyed in ~/.cashclaw/missions/) contains a complete history of events with timestamps, actor information, and state snapshots. The audit trail enables forensic reconstruction of what happened during a mission, when it happened, and why it failed (if applicable). Entries are append-only; historical records cannot be modified or deleted, ensuring compliance with audit requirements.

Provides an interactive CLI wizard (src/cli/commands/init.js) that guides users through agent configuration on first run. The wizard prompts for agent identity (name, description), marketplace credentials (HYRVEai API key), payment settings (Stripe API key, pricing), and skill selection. Validates inputs in real-time, provides helpful error messages, and generates the initial config.json file. The wizard is idempotent; running it again updates configuration without losing existing mission data.

Provides multiple interfaces for querying mission status: CLI commands (cashclaw mission list, cashclaw mission view) and REST API endpoints (/api/missions, /api/missions/:id). Supports filtering by status (pending, accepted, executing, completed, failed), time range, skill type, and earnings. Results can be displayed as formatted tables (CLI) or JSON (API). The status query layer reads from the mission audit trail and aggregates state information without requiring a separate database.

Calculates earnings across configurable time windows (hourly, daily, weekly, monthly) by aggregating completed missions and their associated Stripe payments. The Earnings Tracker (src/core/earnings-tracker.js) implements time-windowed financial aggregations that query the mission audit trail and payment records, computing metrics like total revenue, mission count, average job value, and hourly rates. Results are cached and updated incrementally as new missions complete, enabling real-time earnings dashboards without full recalculation.

Automatically discovers, installs, and registers OpenClaw-compatible skills into the agent's workspace via the OpenClaw Bridge (src/integrations/openclaw-bridge.js). The bridge detects installed skills by scanning the workspace directory structure, validates skill schemas, and registers them into a runtime skill registry that mission execution can invoke. Supports 12 specialized skills for common freelance tasks (code generation, content writing, image processing, etc.), with extensibility for custom skills via the OpenClaw standard interface.

Generates Stripe payment links and invoices for completed missions via the Stripe Bridge (src/integrations/stripe-connect.js). When a mission completes, the system creates a Stripe invoice with mission details (description, amount, client info), generates a unique payment link, and stores the link in the mission record. Supports customer management (creating or retrieving Stripe customers by email), automatic payment collection, and webhook integration for payment confirmation. All payment state is persisted to mission records, enabling reconciliation between work completed and payments received.

Implements a hierarchical command-line interface using Commander.js that routes user commands to business logic handlers. The CLI Entry Point (bin/cashclaw.js) loads the Command Router (src/cli/index.js) which parses commands and delegates to handler files organized by domain (missions, config, skills, status). Supports subcommands (e.g., `cashclaw mission accept`, `cashclaw config set`), global options (verbosity, config path), and help text generation. Each command handler is a separate module that imports core business logic and executes it with parsed arguments.

Provides a web-based dashboard server (src/dashboard/server.js) running on port 3847 that exposes a REST API for querying mission status, earnings, and agent configuration. The dashboard server reads from the same JSON-based state files as the CLI, enabling real-time visibility into agent operations without requiring a separate database. Supports endpoints for mission listing, earnings queries, skill status, and configuration retrieval. The dashboard UI consumes these REST endpoints to display interactive charts, mission timelines, and earnings trends.

Manages agent configuration through JSON files stored in ~/.cashclaw/config.json, with automatic defaults merging via the Config Manager (src/utils/config.js). The system loads user configuration, merges it with built-in defaults, and validates against a configuration schema. Supports hierarchical configuration (global settings, skill-specific settings, marketplace-specific settings) with environment variable overrides. Configuration changes are persisted immediately to disk, enabling runtime updates without process restart.

Integrates with HYRVEai's 50+ API endpoints via the HYRVEai Bridge (src/integrations/hyrve-bridge.js) to register agents on the marketplace, discover job postings, and manage agent availability. The bridge handles authentication (API key-based), implements request/response serialization, and manages the polling daemon that continuously queries for new jobs. Supports filtering jobs by skill category, minimum price, and other criteria. Integration points include agent registration (creating/updating agent profile), job discovery (querying available jobs), and job acceptance (claiming jobs and transitioning them to missions).

Orchestrates the execution of OpenClaw skills during mission execution by invoking registered skills with mission-specific parameters and aggregating results. When a mission transitions to the executing state, the system determines which skills are required based on the job type, invokes each skill with appropriate inputs, and captures outputs for the audit trail. The orchestration layer handles skill invocation errors, implements retry logic for transient failures, and updates mission status based on skill execution results. Supports parallel skill execution for independent tasks and sequential execution for dependent tasks.