The Problem

Clients on on‑chain work marketplaces need an autonomous worker that can continuously discover tasks, price them, execute the work with an LLM, and improve from feedback – all without manual supervision. Building such a loop from scratch requires wiring networking, persistence, LLM calls, and a UI dashboard.

What This Does

cashclaw is a single‑process Node.js agent that connects to the Moltlaunch marketplace (or any compatible API) and runs three jobs:

  • Heartbeat – src/heartbeat.ts maintains a WebSocket / REST feed of new tasks.
  • Agent Loop – src/loop/index.ts drives a multi‑turn LLM conversation, invoking tools defined in src/tools/ to quote, accept, or submit work.
  • Self‑Study – src/loop/study.ts generates knowledge entries that are BM25‑searched and injected into future prompts.

The HTTP server (src/agent.ts) exposes JSON endpoints used by the React UI (src/ui/…). Configuration lives in src/config.ts; the UI reads and writes the same JSON file, so any change to the config file ripples through 13 other modules.

How It Is Wired

Execution begins in src/index.ts (main at line 3). main calls the startup routine that:

  1. Loads configuration – loadConfig (in src/config.ts) reads a JSON file via fs.readFileSync. This is the primary hub; 13 modules import it, giving it the highest blast radius.
  2. Starts the agent server – src/agent.ts creates the HTTP server (createServer) and defines helpers (json, readBody, parseJsonBody) that are reused by every API handler.
  3. Initialises the heartbeat – src/heartbeat.ts (start at line 352) opens a WS connection, schedules reconnections, and emits events (emit). The heartbeat calls the LLM only via tool invocations, keeping side‑effects isolated.
  4. Runs the agent loop – runAgentLoop (exported from src/loop/index.ts) is invoked when a new task arrives. The loop: Builds a system prompt (buildSystemPrompt), which loads stored knowledge (loadKnowledge → src/memory/knowledge.ts → fs.readFileSync). Calls the LLM provider (src/llm/index.ts → createAnthropicProvider / createOpenAICompatibleProvider). Each turn may invoke a tool (src/tools/*) that ultimately reaches external binaries (mltl CLI or agentcash). * Writes logs (appendLog in src/memory/log.ts) and updates the knowledge base (storeKnowledge).

The UI (src/ui/App.tsx) is a thin wrapper that calls the API functions defined in src/ui/lib/api.ts (get, post, json). Those functions are the most fan‑in utilities (called from 4 files, 16 types) and therefore a change here affects the entire front‑end.

No circular imports were found; the internal graph contains 38 modules with 81 edges, so dependency tracing is straightforward. The deepest nesting (indentation depth 8) occurs in src/ui/pages/Dashboard.tsx and src/ui/pages/Setup.tsx, making those components harder to maintain.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/cashclaw.git
cd cashclaw

# Install globally (as documented)
npm install -g .

# Install the required Moltlaunch CLI
npm install -g @moltlaunch/cli

# Run the agent (the package registers a `cashclaw` binary)
cashclaw

The command starts the HTTP server on http://localhost:3777 and launches the React setup wizard. The wizard writes a config.json in the user’s config directory; the agent reads it on each start. No additional environment variables are required beyond the LLM API keys, which the UI prompts for during the “LLM” step.

Real‑World Use

A freelancer could fork the repo, replace the Moltlaunch client calls in src/tools/registry.ts with calls to a freelance platform’s API, and point the UI at their own branding. The core loop, knowledge base, and self‑study mechanisms remain unchanged, providing a ready‑made autonomous worker that can be re‑targeted to any task marketplace.

Code Health & Issues

  • High – CI missing – 38 source files, no .github/workflows or other CI config.
  • Medium – Dependabot absent – only one manifest (package.json); no automated security updates.
  • Medium – Test coverage low – 1 test file for 38 source files (≈2 % coverage).
  • High – Duplicated code – 17 similar 6‑line blocks across src/agent.ts, src/moltlaunch/cli.ts, src/ui/lib/api.ts, src/memory/chat.ts, etc.
  • Medium – Hub module – src/config.ts is imported by 13 modules; any change has a wide blast radius.
  • High – Deep nesting – src/ui/pages/Dashboard.tsx and src/ui/pages/Setup.tsx have 8‑level indentation, reducing readability.
  • Medium – Oversized file – src/agent.ts is 606 lines; consider splitting by responsibility.

No license or secret leakage issues were detected; a LICENSE file is present.

The Bottom Line

cashclaw delivers a complete autonomous‑agent pipeline with a clear separation between networking, LLM interaction, and self‑study. The code is functional but suffers from a few maintainability hotspots (large hub config, duplicated helpers, deep UI nesting) and lacks basic CI/testing scaffolding. It is suitable for teams that need a fast prototype of an LLM‑driven worker and are prepared to add tests and CI before production use.