Why RunCode?

| | Claude Code | Cursor | Aider | RunCode | |---|---|---|---|---| | Models | Claude only | Mixed (limited) | Bring your key | 41+ models, one tool | | Pricing | $200/mo subscription | $20/mo + usage | Free + API costs | Pay per request | | Payment | Credit card | Credit card | API keys | USDC — no accounts | | Open source | No | No | Yes | Yes | | Switch models mid-session | No | No | Yes | Yes |

RunCode gives you the same agent capabilities — file editing, shell commands, web search, sub-agents — across every major model provider. You pay only for what you use, with stablecoin. No API keys to manage, no accounts to create, no subscriptions to cancel.

Quick Start

npm install -g @blockrun/runcode
runcode setup base     # Create a wallet (one-time)
runcode                # Launch — picks model interactively

That's it. Fund the wallet address with USDC on Base, or use free models immediately.

Features

Agent Capabilities

RunCode is a full coding agent with 10 built-in tools:

| Tool | Description | |------|-------------| | Read | Read files with line numbers | | Write | Create or overwrite files | | Edit | Targeted find-and-replace edits | | Bash | Run shell commands with timeout | | Glob | Find files by pattern | | Grep | Search file contents (uses ripgrep) | | WebSearch | Search the web | | WebFetch | Fetch and read web pages | | Agent | Spawn sub-agents for parallel tasks | | Task | Track tasks within a session |

Model Selection

Launch with the interactive model picker, or specify directly:

runcode                          # Interactive picker
runcode -m sonnet                # Claude Sonnet 4.6
runcode -m gpt                   # GPT-5.4
runcode -m deepseek              # DeepSeek V3
runcode -m free                  # Nemotron Ultra 253B (free)

Switch models mid-session:

/model              # Interactive picker
/model flash        # Switch to Gemini 2.5 Flash
/cost               # Check session cost

| Shortcut | Model | Price (in/out per 1M) | |----------|-------|----------------------| | sonnet | Claude Sonnet 4.6 | $3 / $15 | | opus | Claude Opus 4.6 | $5 / $25 | | gpt | GPT-5.4 | $2.5 / $15 | | gemini | Gemini 2.5 Pro | $1.25 / $10 | | flash | Gemini 2.5 Flash | $0.15 / $0.6 | | deepseek | DeepSeek V3 | $0.28 / $0.42 | | r1 | DeepSeek R1 | $0.28 / $0.42 | | haiku | Claude Haiku 4.5 | $0.8 / $4 | | mini | GPT-5 Mini | $0.25 / $2 | | nano | GPT-5 Nano | $0.05 / $0.4 | | o3 | O3 | $2 / $8 | | o4 | O4 Mini | $1.1 / $4.4 | | grok | Grok 3 | varies | | free | Nemotron Ultra 253B | FREE | | devstral | Devstral 2 123B | FREE | | qwen-coder | Qwen3 Coder 480B | FREE | | maverick | Llama 4 Maverick | FREE |

Token Optimization

Seven layers of automatic optimization keep context usage low and costs down:

1. Thinking block stripping — removes old reasoning from history
2. Tool result budgeting — caps large outputs at 50K chars with preview
3. Microcompaction — clears old tool results (keeps last 8)
4. Time-based cleanup — clears stale results after 60min idle
5. Auto-compact — summarizes history when approaching context limit
6. Adaptive max_tokens — starts at 8K, escalates to 64K on demand
7. Prompt-too-long recovery — auto-compacts and retries up to 3x

Permission System

By default, read-only tools run automatically. Destructive tools (Write, Edit, Bash) prompt for permission:

  Permission required: Bash
  Execute: rm -rf node_modules

  Allow? [y]es / [n]o / [a]lways:

Use --trust to skip all prompts:

runcode --trust

Configure rules in ~/.blockrun/runcode-permissions.json:

{
  "allow": ["Bash(git *)"],
  "deny": ["Bash(rm -rf *)"]
}

Streaming Tool Execution

Concurrent-safe tools (Read, Glob, Grep) start executing while the model is still streaming. Sequential tools (Write, Edit, Bash) wait for the full response. This reduces latency on multi-tool turns.

Proxy Mode

Use any model through Claude Code by running RunCode as a payment proxy. It translates between OpenAI and Anthropic formats, handles x402 payments, and adds automatic fallback when a model is unavailable.

runcode proxy                    # Start payment proxy on :8402
runcode proxy -m deepseek        # With default model

One-command setup for Claude Code:

runcode init                     # Auto-configures Claude Code + LaunchAgent

This writes the proxy endpoint into Claude Code's config and installs a macOS LaunchAgent so the proxy starts automatically on login. Run runcode uninit to undo.

How it works:

Claude Code → RunCode proxy (:8402) → BlockRun API → 41+ models
                 ↓
          x402 payment (USDC)
          SSE format translation
          Auto-fallback on failure

Payment

RunCode uses the x402 protocol for pay-per-request payments with USDC stablecoins. No accounts, no API keys, no subscriptions.

Supported chains:

• Base (default) — Coinbase L2, low fees
• Solana — also low fees

Setup:

runcode setup base     # or: runcode setup solana

Fund the wallet address with USDC. Free models work without funding.

What does it cost?

| Model | ~Cost per request | |-------|-------------------| | Free models (Nemotron, etc.) | $0 | | DeepSeek V3 | ~$0.001 | | Gemini Flash | ~$0.001 | | Claude Sonnet | ~$0.01 | | GPT-5.4 | ~$0.01 | | Claude Opus | ~$0.05 |

Typical usage: $5-20/month for active development.

Commands

| Command | Description | |---------|-------------| | runcode | Start the agent (interactive model picker) | | runcode -m <model> | Start with a specific model | | runcode --trust | Start in trust mode (no permission prompts) | | runcode --debug | Start with debug logging | | runcode setup [base\|solana] | Create payment wallet | | runcode balance | Check USDC balance | | runcode models | List all models with pricing | | runcode stats | View usage statistics and savings | | runcode config list | View configuration | | runcode proxy | Run as payment proxy for Claude Code | | runcode init | Auto-configure Claude Code + LaunchAgent | | runcode uninit | Remove Claude Code proxy config |

Session Commands

| Command | Description | |---------|-------------| | /model | Interactive model picker | | /model <name> | Switch model (shortcut or full ID) | | /cost | Show session cost and savings | | /help | List all commands | | /exit | Quit |

Architecture

src/
├── agent/                  # Core agent loop, LLM client, token optimization
├── tools/                  # 10 built-in tools (read, write, edit, bash, ...)
├── ui/                     # Terminal UI + model picker
├── proxy/                  # Payment proxy for Claude Code
├── router/                 # Smart model routing
├── commands/               # CLI commands (setup, balance, stats, ...)
├── wallet/                 # Wallet management
├── stats/                  # Usage tracking
├── config.ts               # Global configuration
└── index.ts                # Entry point

Development

git clone https://github.com/BlockRunAI/runcode.git
cd runcode
npm install
npm run build
node dist/index.js --help

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

License

Apache License 2.0

Links

• BlockRun — The AI gateway
• x402 Protocol — Internet-native payments
• npm
• Telegram