@blockrun/runcode

██████╗ ██╗ ██╗███╗ ██╗ ██████╗ ██████╗ ██████╗ ███████╗ ██╔══██╗██║ ██║████╗ ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██████╔╝██║ ██║██╔██╗ ██║██║ ██║ ██║██║ ██║█████╗ ██╔══██╗██║ ██║██║╚██╗██║██║ ██║ ██║██║ ██║██╔══╝ ██║ ██║╚██████╔╝██║ ╚████║╚██████╗╚██████╔╝██████╔╝███████╗ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

RunCode

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

runcode is a terminal-based AI coding agent that connects to 41+ LLM models through BlockRun. It reads your code, edits files, runs commands, searches the web, and manages tasks — all from your terminal. You pay per request with USDC via the x402 protocol. No API keys, no accounts, no subscriptions.

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

30+ shortcuts:

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

runcode also includes a proxy mode for use with Claude Code or other tools:

runcode proxy                    # Start payment proxy on :8402
runcode proxy -m deepseek        # With default model
runcode init                     # Auto-configure Claude Code + LaunchAgent

Architecture

User input → runcode CLI
  → Terminal UI (markdown rendering, model picker, spinners)
  → Permission check (allow / deny / ask)
  → Agent loop
    → Token optimization pipeline
    → BlockRun API (direct, with x402 payment)
      → 41+ models (Claude, GPT, Gemini, DeepSeek, Grok, ...)
    → Streaming tool execution
    → Context compaction (when needed)
  → Loop until task complete

src/
├── agent/                  # Core agent system
│   ├── loop.ts             # Agent loop + interactive session
│   ├── llm.ts              # API client + x402 payment + SSE parsing
│   ├── types.ts            # Type definitions
│   ├── context.ts          # System prompt assembly
│   ├── tokens.ts           # Token estimation
│   ├── compact.ts          # Auto-compaction
│   ├── optimize.ts         # 5-layer token optimization
│   ├── permissions.ts      # Tool permission system
│   └── streaming-executor.ts # Parallel tool execution
├── tools/                  # 10 built-in tools
│   ├── read.ts, write.ts, edit.ts, bash.ts
│   ├── glob.ts, grep.ts
│   ├── webfetch.ts, websearch.ts
│   ├── subagent.ts, task.ts
│   └── index.ts
├── ui/                     # Terminal interface
│   ├── terminal.ts         # Streaming output + markdown
│   └── model-picker.ts     # Interactive model selection
├── proxy/                  # Proxy mode (for Claude Code)
│   ├── server.ts           # HTTP proxy + payment handling
│   ├── fallback.ts         # Auto-fallback chain
│   └── sse-translator.ts   # OpenAI → Anthropic format
├── router/                 # Smart routing engine
│   └── index.ts
├── commands/               # CLI commands
├── config.ts               # Global configuration
└── index.ts                # Entry point

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

Session Commands

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

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.

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