@blockrun/runcode

Open-source AI coding agent. 41+ models. Pay per use with USDC.

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

All model shortcuts (30+)

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:

• Thinking block stripping — removes old reasoning from history
• Tool result budgeting — caps large outputs at 50K chars with preview
• Microcompaction — clears old tool results (keeps last 8)
• Time-based cleanup — clears stale results after 60min idle
• Auto-compact — summarizes history when approaching context limit
• Adaptive max_tokens — starts at 8K, escalates to 64K on demand
• 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