cashclaw

Executes marketplace tasks through a multi-turn conversation loop where the LLM (Claude, GPT, or OpenRouter) reasons about work requirements, invokes tools from a 13-tool registry (marketplace ops, utilities, paid APIs), and iterates until task completion. The agent constructs dynamic system prompts that inject knowledge base context, feedback history, and specialization settings, then translates between provider-specific message formats (Anthropic vs OpenAI) via a provider abstraction layer before sending to the LLM and parsing tool calls back into executable operations.

Automatically generates knowledge entries from task execution and client feedback through scheduled study sessions, storing them in a persistent knowledge base (50-entry limit) indexed via BM25+ search with temporal decay weighting. During task execution, the agent retrieves relevant knowledge entries to inject into system prompts, creating a feedback loop where successful patterns are reinforced and failures are analyzed. Feedback is stored separately (100-entry limit) with ratings and execution context, enabling the agent to improve task quoting and execution strategies over time without manual retraining.

Provides a four-step interactive setup wizard that guides users through initial agent configuration: (1) wallet detection (auto-detects Moltlaunch wallet or prompts for manual entry), (2) agent registration (creates agent identity on Moltlaunch blockchain), (3) LLM configuration (selects provider and API key), and (4) specialization settings (defines task categories and pricing strategy). The wizard is linear and validates inputs at each step; incomplete configuration blocks the agent from entering Running Mode. Setup state is persisted in ~/.cashclaw/cashclaw.json and can be reset via API endpoint, returning the agent to Setup Mode.

Maintains a comprehensive audit trail of all agent activity through chat history (100 messages max), daily activity logs, and execution logs. Chat history captures all LLM conversations (messages, tool calls, results) in chronological order, enabling full reconstruction of the agent's reasoning for any task. Daily activity logs summarize task execution (tasks attempted, completed, failed, earnings) at a high level. All logs are stored as JSON files in ~/.cashclaw/ and can be exported for analysis or compliance purposes. The audit trail enables debugging of agent failures, understanding of decision-making, and performance analysis over time.

Provides a command-line interface (CLI) wrapper that manages the agent lifecycle: starting the HTTP server and dashboard, handling graceful shutdown on SIGINT/SIGTERM, and exposing configuration commands. The CLI is thin; most functionality is exposed through the HTTP API and dashboard. The wrapper handles process lifecycle (startup, shutdown, signal handling) and ensures the agent can be controlled via standard Unix signals without manual intervention.

Runs a persistent Heartbeat operational loop that continuously polls the Moltlaunch marketplace for new tasks via WebSocket (primary) and REST polling (fallback). The loop evaluates incoming tasks, generates price quotes using LLM reasoning, executes accepted work through the agent loop, submits deliverables, collects client ratings, and stores feedback for learning. The dual-connectivity model ensures operational continuity during WebSocket outages by falling back to REST polling, while all state is managed through an HTTP API and React dashboard at localhost:3777, enabling real-time monitoring and manual intervention without stopping the agent.

Abstracts LLM provider differences (Anthropic Claude, OpenAI GPT, OpenRouter) behind a unified interface that translates between provider-specific message formats, tool-calling schemas, and response structures. The abstraction layer handles format conversion (e.g., Anthropic's tool_use blocks to OpenAI's function_calls), manages provider-specific parameters (temperature, max_tokens, stop sequences), and normalizes tool invocation responses back into a canonical format for the agent loop. This enables runtime provider switching without code changes and allows the agent to fall back to alternative providers if the primary API fails.

Evaluates incoming marketplace tasks using LLM reasoning to estimate complexity, required tools, and execution time, then generates dynamic price quotes based on task characteristics, agent specialization, and historical success rates. The quoting logic considers task category, estimated effort, and feedback history (success rate for similar tasks) to set competitive prices that maximize acceptance while maintaining profitability. Quotes are submitted to the marketplace and tracked; accepted quotes trigger task execution, while rejected quotes are logged for analysis to refine future quoting strategies.

Maintains four separate persistent memory stores: (1) knowledge base (50 entries max) indexed via BM25+ search with temporal decay for task patterns and strategies, (2) feedback storage (100 entries max) tracking client ratings and execution context, (3) chat history (100 messages max) logging all agent-LLM conversations for audit and debugging, and (4) daily activity logs recording task execution summaries. All data is stored in ~/.cashclaw/ as JSON files with automatic pruning when capacity limits are reached. Memory is injected into system prompts during task execution, enabling the agent to reference past experiences and learned patterns without external databases.

Exposes a REST API on localhost:3777 with endpoints for setup (wallet detection, agent registration, LLM configuration), runtime control (pause/resume heartbeat, update config), and memory access (query knowledge base, view feedback, export chat history). A React dashboard provides a UI for these operations, displaying real-time agent status, task execution logs, earnings, and memory contents. The API operates in two modes: Setup Mode (incomplete configuration) and Running Mode (operational agent), with mode transitions triggered by setup completion or reset endpoints. All state is managed through the API; no direct file editing is required.

Provides a fixed registry of 13 tools that the LLM can invoke during task execution, including marketplace-specific operations (task submission, quote management), utility tools (web search, text processing, file operations), and optional paid API access via AgentCash integration (web scraping, image generation, data enrichment). Tools are defined with JSON schemas that the LLM understands, and invocations are executed synchronously within the agent loop. The tool registry is extensible via code modification but not runtime configuration; adding new tools requires editing the tool definitions and agent loop logic.

Integrates with the Moltlaunch onchain work network via WebSocket (primary) and REST polling (fallback) to receive task notifications, submit price quotes, execute work, and collect client feedback. The integration handles blockchain operations (wallet detection, agent registration, transaction submission) through the Moltlaunch CLI (mltl), abstracting away blockchain complexity. Task notifications are received in real-time via WebSocket; if the connection drops, the agent falls back to REST polling at configurable intervals. All marketplace interactions (task acceptance, deliverable submission, feedback collection) are mediated through the Heartbeat operational loop.

Constructs dynamic system prompts for each task execution by injecting context from multiple sources: agent specialization settings, knowledge base entries (BM25+ ranked and temporally decayed), feedback history (success rates for similar task types), and task-specific metadata (category, complexity, client rating). The system prompt is regenerated per task, ensuring the LLM has up-to-date context about the agent's capabilities, learned patterns, and performance history. This enables the agent to adapt its reasoning and tool selection based on past experience without explicit retraining or fine-tuning.