OpenCrowd

A local CLI agent with its own USDC wallet. Give it a task and a local spend cap; it uses local tools when it can, buys external capabilities through one enforced purchase lifecycle when it can't, and records work, costs, receipts, and reviews on your machine.

Try it in 60 seconds (no crypto required)

npx opencrowd --demo

Demo mode runs the real enforced lifecycle — discovery, inspection, reputation check, approval, payment, receipt, required review — over in-memory mock adapters. No real money moves and nothing touches the network.

Installation and startup

npm install -g opencrowd   # or: npx opencrowd
opencrowd

The TUI renders immediately from local state; the AgentCash and CrowdCode vendors, wallet balance, and model catalog initialize concurrently in the background. opencrowd doctor diagnoses local dependencies, provider authentication, the wallet, vendor connections, and the network explicitly.

First launch is two steps — there is no wallet setup:

1. Fund the wallet — it already exists (AgentCash creates it automatically at ~/.agentcash/wallet.json; OpenCrowd, AgentCash, and CrowdCode all draw one balance). Scan the QR or tap the MetaMask link to send a few dollars of USDC on Base. The wallet is the agent's entire blast radius: it can never spend more than you put in.
2. Give it a task — type what you want. The agent discovers paid x402/MPP services, checks their CrowdCode reputation, and pays per call through the enforced lifecycle.

❯ find a service that returns live weather and get today's forecast

  → find_paid_service "live weather forecast"
  → inspect_paid_service POST api.weatherstation.xyz/forecast
  $ paid $0.02 → api.weatherstation.xyz (paid_success) · saved forecast.json
  → review_paid_service rating=5

  Today: 72°F, clear. Full forecast saved to artifacts.
  summary: spent $0.05, remaining $19.95, services 1, artifacts 1

Providers

The default provider is BlockRun, an OpenAI-compatible route paid per request with x402 USDC from the shared AgentCash wallet. It needs no API key or prepaid provider balance. If a BlockRun call fails transiently twice, the legacy OpenRouter x402 proxy (openrouter-x402-proxy) handles one ledgered rescue call; after three rescues the primary is parked for the rest of the process. In ask mode the rescue requires confirmation, while auto mode proceeds within the session budget automatically.

Venice is the wallet-native backup (opencrowd config set provider venice or /provider venice): SIWX authentication, prepaid Venice credit topped up with USDC, at most one bounded automatic top-up per exhausted call. OpenRouter direct is also available with OPENROUTER_API_KEY. The OpenRouter x402 proxy, Venice, and direct OpenRouter remain explicitly selectable.

Model preferences are per provider (auto resolves from the live catalog at session start; resolved IDs are recorded on the session so run --session reproduces them exactly). Change the running session with /provider, /model, and /submodel; change future-session defaults with opencrowd config set.

Wallet

There is one wallet: AgentCash's. OpenCrowd shows public addresses, balances, and funding links (/wallet, /fund) and never manages, copies, or exports keys. See SECURITY.md for the enforcement model.

Spending limits

By default, each model or paid tool call can spend up to $1 automatically, and each user query can spend up to $10 across its model calls, tools, retries and subagents. Every new query receives a fresh allowance; conversation history and lifetime spending remain available.

Open /wallet → spending limits to save defaults, or use:

opencrowd wallet limits --per-call 1 --per-query 10

A call above either threshold pauses before payment. Approve that call once, approve it and increase the current query budget, or decline. Increasing a query budget leaves saved defaults unchanged; later calls still respect the per-call limit. Changing a budget does not move funds.

Headless runs return waiting_for_approval with the pending amount. Resume the saved query without repeating completed work:

opencrowd resume <session-id> --approve-once --workspace <dir>
opencrowd resume <session-id> --query-budget 20 --workspace <dir>
opencrowd resume <session-id> --decline --workspace <dir>

Cloud applies the same thresholds in its payment gateway and exposes them in Wallet → spending limits. Cloud and CLI save settings independently.

Approval

Spending thresholds apply to model and paid tool calls. External services also retain reputation checks, explicit service blocks and method restrictions. auto is the default and still asks for spending above either threshold. Legacy ask adds service confirmations; off disables external-service purchases in the CLI. Stored rules remain available through /approvals; old monetary service/session caps are replaced by query spending limits.

Every confirmed paid service call requires a signed CrowdCode review before the next purchase; pending reviews survive restarts.

Commands

The generated, drift-checked reference is docs/commands.md (/help and opencrowd --help render the same registry). One-shot and scripting forms:

opencrowd run --budget 1.00 "Find a service and summarize options"
opencrowd run --session <session-id> "Follow up on the previous result"
opencrowd config show
opencrowd wallet balance
opencrowd doctor
opencrowd evals gaia --tier smoke --harness opencrowd,claude,codex
opencrowd evals suite --set all --tag baseline --model openai/gpt-5.6-luna --subagent-model off
opencrowd evals evolve --baseline-report <run>/report.json --generations 2 --candidates 2

evals suite runs the 40-task suite (15 real-usage tasks derived from CrowdCode demand, 15 seeded GAIA level 2/3, 10 seeded AssistantBench) and reports accuracy alongside on-chain LLM and service spend, turns, paid calls, and unnecessary purchases. evals evolve is the meta-harness: it derives a service knowledge tree (L0.md in the prompt, INDEX.md + category pages under artifacts/knowledge/) from CrowdCode review evidence, mutates it against held-in failures, keeps the quality-vs-cost Pareto frontier, and never shows the proposer a held-out task. evals suite uses the runtime's knowledge tree by default (the snapshot bundled with @opencrowd/agent-runtime, or OPENCROWD_KNOWLEDGE_DIR); pass --knowledge <tree dir> to evaluate a candidate or --knowledge none for the static-prompt baseline.

The agent loads the same tree in normal runs: L0.md becomes the prompt's capability index and the category pages land under artifacts/knowledge/. Set OPENCROWD_KNOWLEDGE_DIR=none to disable it or point it at another tree; the loaded version is recorded on the session.

Headless runs

opencrowd run --headless --prompt "..." --output json

Headless execution never waits for UI input: the approval mode comes from --approval ask|auto|off (or the configured default), and in ask mode un-ruled purchases are denied with a clear error instead of hanging. The JSON output includes the outcome, final message, spend split, turn count, resolved model policy, artifacts, and service calls — the same contract the eval runner uses.

Local state

| What | Where | | --- | --- | | Config (defaults for future sessions) | ~/.config/opencrowd/config.json | | Wallet | ~/.agentcash/wallet.json (owned by AgentCash; never copied) | | Approval rules | ~/.config/opencrowd/approvals.json | | Sessions, conversation, ledger, artifacts | ./sessions/<session-id>/ | | Purchase receipts (append-only) | ./sessions/<session-id>/purchases.jsonl |

Conversations persist per session and are automatically compacted when they outgrow the model's context window (archives kept under sessions/<id>/context/). /clear archives context while keeping the session's spend, models, and policy; /new starts fresh.

Development

npm install
npm run typecheck
npm test
npm run smoke        # build + bundle + demo + headless smoke tests
npm run deadcode     # knip: unused files, exports, dependencies

Package layout (see docs/architecture.md for the full contract): packages/core (vendor-neutral sessions, budget, storage, tool contracts), packages/economy (typed AgentCash/CrowdCode adapters and the enforced purchase lifecycle), packages/agent-runtime (LLM loop, providers, subagents, DI runtime), packages/evals (GAIA benchmark runner), apps/cli (the opencrowd binary, TUI, and command registry).

See CONTRIBUTING.md. Licensed MIT.