Franklin Agent
A wallet-backed CLI that spends USDC on models and tools to execute research, coding, and trading tasks.
- Source repo
- BlockRunAI/Franklin
- Stars
- ★ 557
- Last updated
- 3d ago
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 43/100 · Major gaps
At a glance
- Works with
- Platform-specific
- You'll need
- Typical use
- A crypto trader at a terminal wants a BTC or SOL signal based on CoinGecko data and locally calculated RSI, MACD, Bollinger bands, and volatility before reviewing a trade plan.
- Main limitation
- Core model and paid-service access runs through the BlockRun Gateway and its wallet flow, so adoption entails that gateway and payment path.
- Source review
- 43/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
Franklin Agent is a TypeScript command-line agent from BlockRun built around a wallet-funded execution loop. Its Smart Router selects among multiple models, while the BlockRun Gateway supplies model, search, image, and other paid services that settle through x402 USDC micropayments. The CLI includes persistent sessions, session search, cost insights, MCP auto-discovery, and a plugin SDK; its wallet configuration and session history can also be used by its VS Code extension and Telegram entry point. Trading is a primary workflow: it retrieves CoinGecko market data, calculates technical indicators locally, and requires approval of structured plans before trades on Jupiter, 0x, or Polymarket. It fits terminal users who want wallet-bounded spending across models and tools and are willing to use the BlockRun gateway.
After a user states an outcome in the franklin CLI, the runtime follows Intent → Smart Router → Tool Use → Spend Control → Result. It can use Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, ImageGen, MemoryRecall, AskUser, SubAgent, and Trading* tools to inspect and modify files, run commands, retrieve web material, create images, delegate work, and operate trading workflows. TradingSignal fetches market data from CoinGecko and computes RSI, MACD, Bollinger bands, and volatility locally; a real trade first becomes a trade plan with venue, asset, size, slippage, stop condition, rationale, and total spend, then waits for approval. Sessions stream to disk and can be restored or searched with /history, /resume, and /session-search, while /cost and franklin insights report spending. Paid actions settle through wallet-signed x402 micropayments and stop when the wallet balance is exhausted.
- A crypto trader at a terminal wants a BTC or SOL signal based on CoinGecko data and locally calculated RSI, MACD, Bollinger bands, and volatility before reviewing a trade plan.
- A developer wants one command-line session to read src/auth.ts, edit code, run npm test, and expose the cost of each step.
- A researcher needs /goal to compare x402-compatible data APIs within turn and --max-spend limits, with adversarial reviewers checking the evidence behind a completion claim.
- An independent creator wants to generate a startup logo from the CLI through a funded wallet rather than configure an OpenAI API key.
- A user running an always-on machine needs owner-locked Telegram access to resume sessions and send work requests from a phone.
How do you install or deploy this agent?
Node.js 20.19+ is required; the project recommends Node 22 LTS. Install and start:
npm install -g @blockrun/franklinfranklin
Or run without a global installation:
npx @blockrun/franklinFree NVIDIA models are available by default. For paid models and paid tools, run franklin setup base or franklin setup solana, then fund the created wallet address with USDC; use franklin balance to display the address and balance.
How do you use this agent?
Start with franklin, or explicitly select the free profile:
franklin --model freeEnter a task such as “what's BTC looking like today?” or ask it to refactor a file and run tests. Use /model to choose a model, /plan for read-only planning, /execute for execution, and /cost for the session spend; use /goal for longer objectives and /loop for scheduled work. Real trades require review and approval of a trade plan, and approved budgets expire after 15 minutes. For remote access, set TELEGRAM_BOT_TOKEN and TELEGRAM_OWNER_ID, then run franklin telegram.
What are this agent's strengths and limitations?
- Uses wallet balance as a hard budget cap and settles paid actions with x402 USDC micropayments; the documentation describes no monthly fee or overdraft.
- The Smart Router offers auto, eco, premium, and free profiles, and reports model selection, cost, and savings in responses.
- Real-money trading has a non-bypassable trade-plan approval gate, with lifecycle hooks available for daily caps, token blocklists, and spend-ledger vetoes.
- The CLI, VS Code extension, and Telegram channel can share ~/.blockrun/ configuration and session history; sessions persist, resume, and support full-text search.
- Core model and paid-service access runs through the BlockRun Gateway and its wallet flow, so adoption entails that gateway and payment path.
- Paid capabilities depend on USDC on Base or Solana; paid models and tools cannot continue when the balance is empty.
- Node.js 20.19+ is required; the documentation says older Node releases can crash in the Solana dependency path with ERR_REQUIRE_ESM.
- Although trades require approval, the documented execution venues include Jupiter, 0x, and Polymarket, so users still bear responsibility for assessing each proposed trade.
How does this agent compare with similar options?
The project contrasts itself with subscription coding agents, editor IDEs, and chatbots by claiming wallet-native USDC/x402 payments, outcome-based pricing, automatic model routing, and the ability to buy data, search, and image services. Its comparison also names the OpenAI API as a pay-per-call alternative where each attempt is charged.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Franklin Agent This agent | 43 · Major gaps | ★ 557 | 3d ago | TypeScript | — |
| Puppetmaster | 68 · Some gaps | ★ 444 | 4d ago | Python | Codex · Claude Code |
| Agently AI Application Runtime | 63 · Some gaps | ★ 1.7k | 11d ago | Python | OpenAI API · Claude API |
| deepx-code | 63 · Some gaps | ★ 391 | 4d ago | Go | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README claims trades require user approval and provides lifecycle hooks (e.g., daily spend caps, token blacklists) as guardrails; wallet keys never leave the machine (non-custodial). But no code-level evidence provided, and least-privilege principle not detailed. Deductions: lack of code verification, permission model not detailed.
Evidence shows: README describes persistent sessions, crash recovery, model fallback; package.json has test scripts. But no test results or code evidence provided. Deductions: self-consistency unverifiable, dependency availability unproven.
Evidence shows: README describes multiple use cases (trading, research, coding, image generation), supports CLI, VS Code, Telegram; provides free tier. But capability boundaries not explicit, trigger precision not detailed. Deductions: capability boundaries vague, trigger conditions imprecise.
Evidence shows: README well-structured, provides quick start, troubleshooting, project layout; Apache-2.0 license present; version number exists. But changelog missing, known limitations not explicit. Deductions: no changelog, known limitations not listed.
Evidence shows: README claims actionable outputs (e.g., trading signals, code refactoring), provides cost breakdowns; YOPO model claims pay-per-outcome. But cost-benefit unverified, marginal value not quantified. Deductions: cost-benefit unproven, marginal value not quantified.
Evidence shows: README contains specific numbers (e.g., model counts, savings percentages), but no data sources provided; brand numbers workflow exists but unverified. Deductions: claims lack traceability, facts and inferences not separated.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- This agent can autonomously spend USDC, posing financial loss risk; ensure spend caps and review trade plans.
- Dependencies include a tarball URL from GitHub, increasing supply chain risk; consider pinning versions and auditing.
- Publisher identity is unverified; proceed with caution.