Brownian Code

Autonomous, auditable crypto research from your terminal.

npm | GitHub | Commands | Configuration | Troubleshooting

Brownian Code is a local CLI agent that turns broad crypto questions into auditable research runs. It plans the work, gathers live evidence from Hive MCP and the web, writes the run into a local scratchpad, checks for source gaps, and returns a risk-aware answer you can inspect.

It is built for the questions crypto researchers actually ask:

Compare SOL vs ETH developer activity, TVL, fees, and near-term risk over the last quarter.

Risk-screen this token before I touch it: 0x...

Watch this wallet and tell me what changed since last week.

What are the strongest Base ecosystem narratives right now, and what data contradicts them?

Brownian Code is a crypto-native research agent. Its assumptions are built for crypto from the ground up: on-chain evidence, liquidity, protocol data, token risk, wallets, DEX activity, prediction markets, and explicit source limits.

⚠️ Educational use only — not financial advice. Brownian Code is for educational, entertainment, and informational use. It is not financial, investment, tax, legal, or trading advice. Crypto data can be wrong, stale, incomplete, or unavailable. You are responsible for checking sources and consulting qualified professionals before making financial decisions.

Why Brownian

• Crypto-native evidence instead of generic market summaries: Hive MCP, on-chain data, protocols, wallets, DEX activity, security checks, and prediction markets.
• Agentic but inspectable: tool progress, scratchpads, source context, saved oversized results, and final-answer checks.
• Local-first by default: keys, settings, memory, history, and run artifacts stay under ~/.brownian/ unless a selected live API needs to be called.
• Workflow-ready: built-in skills for risk screens, token fundamentals, protocol due diligence, narrative research, on-chain forensics, X research, and memo writing.

Requirements

• Bun 1.1+ for npm and source installs.
• One LLM provider key, or local Ollama.
• Hive API key for live crypto data.

Install

npm

Install the brownian command from npm. Requires Node 20+ and Bun on your PATH (the CLI launches via the Bun runtime).

npm install -g brownian-code
brownian

Check the install:

brownian --version
brownian doctor

From source

git clone https://github.com/brownian-xyz/brownian-code.git
cd brownian-code
bun install
bun run start

Updates

On startup Brownian checks for a newer release (cached, best-effort) and, when one is available, prints a one-line notice. Run brownian upgrade to apply it (this runs before the app starts, so it updates the install safely), or brownian doctor to see your version and update status. Set BROWNIAN_AUTO_UPDATE=off to silence the notice. Source checkouts always just notify (they never auto-git pull).

First Minute

Brownian Code is bring-your-own-keys. You need one LLM key and a Hive key for live crypto data.

Start the app:

brownian

Add keys from inside the app. Values are masked and saved locally.

/key ANTHROPIC_API_KEY <your-anthropic-key>
/hive

Need keys? Provider dashboard links are in docs/CONFIGURATION.md; the free Hive key is at https://hiveintelligence.xyz/dashboard/keys.

Brownian defaults to Anthropic (claude-sonnet-4-6). Use /model to switch to OpenAI, Google, xAI, OpenRouter, Moonshot, DeepSeek, or local Ollama.

Then ask a real research question:

Compare SOL vs ETH developer activity, TVL, fees, token-holder risk, and near-term catalysts.

Brownian will show tool progress, store a scratchpad, and answer with source context and risk framing. Use /model to switch providers, /keys to see which keys are configured, and /history to revisit previous runs.

What Brownian Does

| Workflow | What happens | |----------|--------------| | Token risk screen | Resolves the asset, checks security/liquidity/holder risk, and separates observed signals from missing context. | | Protocol due diligence | Pulls protocol, TVL, fees, yields, governance, security, and recent-news context before giving a deposit-readiness view. | | Wallet and on-chain forensics | Looks at balances, transfers, counterparties, suspicious patterns, and chain-specific limitations. | | Narrative research | Finds the assets, data, news, and prediction-market context behind a crypto narrative, then ranks the signal and contradictions. | | Investment memo | Produces a structured memo with thesis, catalysts, bear case, risks, and what is still unknown. | | Monitoring | Uses cron, heartbeat, gateway sessions, and Hive stateful monitors for recurring research and alert-style workflows. |

How It Works

1. Plan: classify the request, pick the right workflow, and decide which tools are worth calling.
2. Gather evidence: use Hive MCP for crypto data, web tools for current context, browser scraping when needed, and read-only subagents for broad parallel research.
3. Check itself: track sources, stale data, repeated calls, missing keys, endpoint failures, and unsupported claims.
4. Answer plainly: lead with the finding, cite source categories, explain risks, and say what the data cannot prove.

The goal is not to sound certain. The goal is to make the research trail visible enough that you can trust, challenge, or rerun it.

Data And Tools

Brownian Code uses a compact Hive MCP surface plus typed crypto tools:

• Market data, prices, charts, tickers, trending assets, and chain stats
• Token metadata, contracts, holders, enrichment, and risk checks
• DeFi protocols, TVL, fees, yields, bridges, and stablecoin data
• Wallet balances, transfers, portfolio context, and forensic traces
• DEX pools, swaps, liquidity, trades, NFTs, and prediction markets
• Stateful Hive monitors, memory facts, alerts, and reports when configured

Other runtime tools include web search, web fetch, Playwright browser scraping, local memory, filesystem tools scoped to the project and ~/.brownian/, cron, heartbeat, and SKILL.md workflows.

Local State And Privacy

Brownian is local-first by default.

~/.brownian/
  .env                 # keys saved by /key and /hive
  settings.json        # selected model/provider and update preferences
  scratchpad/          # per-run tool logs
  tool-results/        # oversized tool results recoverable by path
  memory/              # local research memory
  messages/            # chat history
  cron/                # scheduled jobs
  credentials/         # WhatsApp gateway credentials, if used

Live APIs are called only when the selected tool or model needs them. API keys are not written to memory. If you run a hosted gateway, set HIVE_MCP_SUBJECT_SIGNING_SECRET so Hive monitors, memory, alerts, and reports are isolated under pseudonymous downstream subjects.

See docs/CONFIGURATION.md for the full environment variable matrix.

Commands

Shell commands:

brownian
brownian doctor
brownian upgrade --check
brownian upgrade

In-app commands:

| Command | Use it for | |---------|------------| | /help | Commands and shortcuts | | /model | Switch model/provider | | /hive | Set or replace the Hive MCP API key | | /key NAME VALUE | Save an API key locally | | /keys | Show configured keys, masked | | /search | Choose a preferred web search provider | | /rules | Show local research rules | | /memory | Show local memory summary | | /heartbeat | View or update the monitoring checklist | | /history [search] | Browse previous conversations | | /upgrade | Show upgrade status and command | | /clear | Clear conversation history (alias /new) | | /shortcuts | Show keyboard shortcuts |

See docs/COMMANDS.md for the full command reference.

Models

Supported providers:

• OpenAI
• Anthropic
• Google Gemini
• xAI Grok
• OpenRouter
• Moonshot Kimi
• DeepSeek
• Ollama

Brownian routes by model prefix. Examples: gpt-5.5, claude-sonnet-4-5, gemini-3-pro-preview, grok-4-0709, deepseek-reasoner, openrouter:openai/gpt-4o-mini, and ollama:llama3.

Gateway And Scheduled Research

Brownian Code can also run outside the interactive terminal:

bun run gateway:login
bun run gateway
bun run cron:runner

The WhatsApp gateway uses local pairing and session stores. Outbound sends are guarded by access-control checks. Cron jobs live under ~/.brownian/cron/ and can deliver recurring research through the configured gateway channel.

Troubleshooting

Run:

brownian doctor

It checks install type, update status, local state paths, and key setup.

Common fixes:

| Symptom | Fix | |---------|-----| | Bun runtime is required | Install Bun: curl -fsSL https://bun.sh/install \| bash, then restart your terminal and verify with bun --version. | | Missing crypto data | Run /hive or set HIVE_API_KEY / HIVE_MCP_API_KEY | | Missing model key | Run /key OPENAI_API_KEY ..., /key ANTHROPIC_API_KEY ..., or another provider key | | Stale package | Run brownian upgrade --check, then brownian upgrade | | Too much context | Run /clear to start a fresh conversation |

More detail: docs/TROUBLESHOOTING.md.

Development

Use Bun for repository commands:

bun install
bun run dev
bun run typecheck
bun test
bun run smoke:agent

Package check:

npm pack --dry-run

Repository Map

• src/agent/ - agent loop, tool executor, run context, scratchpad, prompts, compaction
• src/tui/ - terminal UI components, controllers, commands, theme
• src/model/, src/providers.ts - provider routing and model registry
• src/tools/crypto/ - Hive MCP crypto tools and typed wrappers
• packages/agent-harness/ - shared Brownian agent policy, skill matching, evidence, verification
• packages/research-core/ - shared research ledger and evidence contracts
• src/memory/ - SQLite memory, hybrid search, embeddings
• src/gateway/ - WhatsApp bridge, routing, sessions, access control
• src/skills/ - built-in research workflows
• src/evals/ - LangSmith evaluation runner

Contributing

Keep pull requests small and focused. Run this before submitting:

bun run typecheck
bun test

Coding-agent guidance lives in AGENTS.md. Product and release readiness standards live in VISION.md.

License

MIT. See LICENSE.