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

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:

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:

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

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

Session Commands

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?

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