Ronin

ronin 🐼

> A masterless, terminal-native Claude agent. ronin is a Claude-Code-style AI coding agent, it reads, edits, and runs your code from the terminal, built on a provider-agnostic agent framework with first-class evals, memory, security hardening, and MCP tool integrations. Plug in Claude for top quality, or run it free on Gemini / Cerebras / Groq / Ollama.

[](LICENSE) [](CHANGELOG.md) [](https://www.python.org/downloads/) [](#-whats-under-the-hood) [](#-supported-providers) [](CONTRIBUTING.md)

> Runs free, no credit card. Point it at a free model (Gemini / Cerebras / Groq / OpenRouter) and go, or plug in Claude for top quality. Same agent, same UI, your choice of brain.

$ curl -sSL https://raw.githubusercontent.com/rohithkandula19/Ronin/main/install.sh | bash
$ ronin                                       # ONE agent: talk · code · generate media · query data
$ ronin code "fix the failing test"           # the coding agent
$ ronin code "explain @main.py and add tests" # @-mention files inline

> The binary is ronin. ro also works as a short alias.

🎬 Demo

Usage dashboard → gamified profile → the 31-game arcade, in one shot:

Runs free: configured on Cerebras's free tier, answering a real question for $0:

The animated panda mascot, the command surface, and live MCP wiring:

ronin image "a red panda samurai, neon, flat vector": free, no API key, generated and shown right in your terminal:

Regenerate the walkthrough anytime with vhs: brew install vhs && vhs docs/demo/demo.tape.

What is ronin?

One front door: type ronin and you get a single agent that reads, writes, and runs code (every edit and shell command gated behind a diff preview and your approval, reads run freely), generates images/video/speech, and queries your connected data, all in one conversation, in plain language. It's provider-agnostic: the same agent runs on Claude or on free open models.

It's also a reference implementation for building agents the right way. The CLI is a thin wrapper over seven independently-usable packages: agent patterns, evals, memory, hardening, and MCP integrations, backed by 3,355 tests that run offline in CI. (ronin code is the focused coding agent; ronin chat is the talk/media surface, both available when you want a single-purpose mode.)

🛠 ronin code · the coding agent (Claude-Code shaped)

ronin code "add a --json flag and update the tests"
ronin code "explain @main.py and fix the bug in @utils.py"   # @-mention files
ronin code --plan "refactor the auth module"                 # plan → approve → execute
ronin code --continue                                        # resume your last session

A coding agent that reads, edits, and runs your code: every write and shell command gated behind a diff preview and your approval (read operations run freely). It mirrors the Claude Code experience:

• Rounded input box + live dropdowns: type inside a bordered prompt with ghost placeholder text. / opens a command menu (30 commands with descriptions), @ opens a live file picker, ! runs a shell command inline, and # files a note straight into project memory. ↑/↓ history, vi-mode (/vim).
• Premium status line + mode chips: a live footer always shows what ronin is and what it's allowed to do — a FREE / PAID / LOCAL badge, provider/model, the current mode, your git branch (with * when dirty and ↑/↓ ahead/behind), and the context size. Real output, no theming required:

``text chip strip (input): [FREE] [cerebras:gpt-oss-120b] [normal] [main*] [write-gated] per-turn footer: ✻ FREE Forged for 1.3s · ↑11.4k ↓314 · cerebras gpt-oss-120b · main* ``

The input box carries an always-visible chip strip — cost badge, provider:model, mode, git branch, the write-gated / auto-accept safety state, and the active role if set. It's width-aware: in a narrow terminal it sheds the lowest-priority chips first (role, then branch) but never the badge, mode, or write-gate. The badge reads FREE on free tiers, PAID when a paid key is required, LOCAL for Ollama/offline, and UNKNOWN only when pricing genuinely can't be determined (a custom endpoint). It never crashes outside a git repo (the branch chip just drops).

• Role agents (/role): pick how ronin works — researcher (read-only explore), implementer (gated edits), reviewer (read-only diff review), tester (verify with tests), architect (design first), debugger (root-cause failures). Read-only roles are enforced (the agent only gets read-only tools), not just suggested; doer roles still flow through the approval gate. The active role shows in the chip strip, and ronin gently suggests a fitting role (e.g. /role debugger for "why is this failing?") without ever switching for you.

``text /role debugger why is the token refresh failing? → root-cause first, then fix (gated) /role reviewer review my changes → read-only findings, no edits /role researcher how does the router pick a model? → read-only explanation w/ file:line /role clear back to default behavior ``

• Shift+Tab modes: cycle normal → auto-accept → plan edit modes, shown live in the input chrome.
• Streaming Markdown + inline tool calls: replies stream as rendered Markdown; tool activity renders Claude-Code-style as ⏺ Read(file) with ⎿ result underneath; edits are shown as syntax-highlighted diffs you approve.
• @-file & @-URL mentions: drop @path to pull a file into context, or @https://… to pull a web page's readable text into context. Start a message with a folder path to cd into it.
• Plan mode (--plan) proposes the steps read-only, you approve, then it executes. Resume (--continue) picks up your last session.
• Live plan tracker: multi-step tasks show a checklist the agent keeps current as it works — ✓ done · ▶ active · ☐ pending · ⊘ blocked · ✗ failed. It updates only from the agent's real update_todos state (no faked progress), and shows nothing when there's no plan.
• Tools: read / write / edit / multi_edit / glob / search / run, plus web_search / fetch_url, read-only git (git_status / git_diff / git_log), semantic code intelligence (diagnostics / definition / references via LSP), a task subagent plus parallel_task (concurrent read-only fan-out) and isolated_task (parallel mutating sub-agents, each in its own git worktree so edits can't collide), and any MCP server's tools (ronin mcp add …).
• Integrations: give the agent new tools three ways, each one command: local MCP servers (24-server catalog: ronin mcp install github), remote/hosted MCP servers (ronin mcp add-remote …), or plugins (200 built-ins like weather/currency/dns/uuid + scaffold your own with ronin plugin new). See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md).
• Project memory: auto-loads RONIN.md / CLAUDE.md / AGENTS.md from the repo so it follows your conventions.
• 34 slash commands · steer across turns: /help, /login, /provider, /free, /role, /model, /models, /theme, /mcp, /agents, /compact, /context, /copy, /export, /resume, /diff, /undo, /commit, /pr, /doctor, /config, and more. /provider shows every provider with a free/paid + key-health view; /free switches to a $0 provider; /role picks a coding role; /theme restyles code blocks + diffs live. The chip strip + per-turn footer show the FREE/PAID badge, provider/model, mode, git branch, role, context, and time.

🧠 Supported providers

ronin works with any LLM, proprietary or open-source. Switch provider or model from inside a session, no restart: /login sets a provider + key (masked), /provider lists every provider with a free/paid + key-health view and switches between them, /free [on] jumps to a $0 provider, and /model swaps the model.

| Provider | Free? | Default model | Notes | |---|---|---|---| | Anthropic | - | claude-sonnet-4-6 | top quality; native SDK | | Gemini | ✅ free tier | gemini-2.5-flash | generous free RPM; key at aistudio.google.com | | Cerebras | ✅ free tier | gpt-oss-120b | very fast / high throughput | | Groq | ✅ free tier | openai/gpt-oss-20b | 30 req/min free | | OpenRouter | ✅ free models | qwen/qwen3-coder:free | one key, many models | | Ollama | ✅ local | llama3.1 | runs on your machine, no key | | OpenAI | - | gpt-4o-mini | - | | Custom | - | (you specify) | any OpenAI-compatible endpoint |

ronin                       # then, in-session:
/login gemini               # paste a free key at the masked prompt
/provider                   # see all providers · free/paid · which have keys
/free on                    # switch to a $0 provider you can run right now
/model gemini-2.5-flash  # or switch models without re-entering the key
/models                     # list what the current provider offers

ronin auto-retries free-tier rate limits (429) with backoff, and round-trips Gemini thinking-model signatures, so free providers work for real multi-step agent tasks.

🚀 Beyond Claude Code

Because ronin is provider-agnostic, it can do things a single-vendor agent structurally can't:

• 🧩 Multi-model consensus: ronin consensus "" -m anthropic,gemini,cerebras runs the same question on several models in parallel, then a judge model synthesizes one cross-checked answer (with a "where they agreed / diverged" note). More robust on hard design/review/decision questions than any single model. Read-only.
• 🧭 Multi-agent orchestrator · provider-agnostic sub-agents: ronin orchestrate "" -r researcher=anthropic,implementer=cerebras,reviewer=gemini,tester=groq decomposes a goal into subtasks, assigns each to a built-in specialist sub-agent (researcher, implementer, reviewer, tester) on its own vendor's model, runs the independent ones in parallel, and synthesizes the result. --write runs editing sub-agents in isolated git worktrees (no collisions); --offline keeps it $0 with zero egress. Complements consensus/dojo (same task, many models) by splitting different subtasks across models. See [docs/ORCHESTRATOR.md](docs/ORCHESTRATOR.md).
• 🪜 Role-handoff pipeline: ronin pipeline "" runs the roles in sequence with gated handoffs — architect → implementer → reviewer → tester → verifier by default — passing a structured artifact between stages, not just prose. The architect emits an ArchitectPlan (objective, files to change, steps, risks, acceptance criteria); the implementer an ImplementationReport; the reviewer a ReviewReport; tester/verifier a VerificationReport. Each is typed, serializable, and uses explicit unknowns — a stage never fabricates a field.
• Real diff evidence: the harness captures the actual unified diff (read-only git diff HEAD) — tracked changes and brand-new untracked files (via git diff --no-index, so nothing is ever staged) — with files, +/- counts, and a byte-budgeted excerpt, so the verifier and semantic check reason about real changes, not the implementer's self-report. Binary/oversized files are recorded as metadata only. --diff-context / --max-diff-bytes tune it; --no-diff-evidence disables it; it's in --json.
• Multi-suite verification, required or optional — pass --verify-cmd repeatedly, name suites with --verify-suite "unit:pytest -q", mark one optional with a trailing ? ("lint?:ruff check .") or via --required-suite / --optional-suite, or --auto-verify-all to detect several (tests/build required; lint/typecheck/format optional, classification shown before running). All gated; results aggregate into a suite table (name · required/optional · status · exit · duration). A required failure fails the run; an optional failure only warns (never fails, blocks, or passes on its own). --no-auto-verify disables single-command auto-detection.
• Artifact contract checks: a ContractCheckReport cross-checks the artifacts — changed files must overlap the architect's files_to_change, the verifier must cover every acceptance criterion, unresolved review blockers fail the run. With --semantic-contract, a read-only model pass judges whether the actual diff fulfils the plan (objective/acceptance alignment, scope-creep, unexpected changes) — advisory, and it never claims a pass when the diff is missing (→ unknown) or truncated (→ warning); a clear misalignment fails the run.
• Combined final verdict (safety-first precedence): a blocked stage → blocked; a failed required suite / failed contract / unmet criterion / blocking review / failed verifier / clearly-misaligned semantic → failed; passed only with real evidence (optional-suite warnings are advisory). A compact Final Verification truth table shows diff-evidence · untracked-evidence · suites (required/optional) · verify-result · git-snapshot · checkpoint-restore · acceptance · contract · semantic · review-blockers · verdict.
• Resume with git safety + restore any checkpoint (--save-state / --resume): checkpoints PipelineState after every stage (with a git snapshot — HEAD, branch, dirty/untracked, ignoring ronin's own .ronin/). On --resume it compares the saved tree to now and refuses an unsafe resume unless --force-resume. --list-checkpoints shows what's available (id · created · sha · files); --restore-latest-checkpoint, --restore-checkpoint-id , or --restore-checkpoint-interactive restore the tree to a checkpoint — always gated (a confirm before overwriting), re-checking the snapshot afterward and refusing if it still mismatches. It never resets/stashes or destroys local work silently. --no-restore-offer hides the offer; --rerun-completed re-runs finished stages.
• Safety: read-only roles (architect/reviewer/verifier) are enforced; without --write the whole run is a read-only proposal; every edit/command still hits the approval gate; a blocked/failed stage halts (the rest → skipped, artifacts preserved); exit is non-zero on a failed/blocked verdict.
• Gated finish (opt-in, never silent): --commit offers a commit only after a passing final verdict (a non-passing verdict requires an explicit y/N), always showing the diff summary first; --pr then offers a gated push + PR; --branch / --commit-message / --pr-title / --pr-body override the drafts. --dry-run describes the whole plan + what it would commit and changes nothing.
• --free/--offline keep it $0; --json/--out emit the full state including artifacts, contract, and verification. Complements orchestrate (parallel, multi-vendor) with a single-provider, step-by-step, safety-first flow.

``bash ronin pipeline "fix auth tests" --write --auto-verify-all # tests required, lint/typecheck optional ronin pipeline "fix auth" --write --verify-suite "unit:uv run pytest -q" --verify-suite "lint?:uv run ruff check ." ronin pipeline "fix frontend" --write --required-suite "test:pnpm test" --optional-suite "typecheck:pnpm typecheck" ronin pipeline "add retry logic" --write --semantic-contract --max-diff-bytes 50000 ronin pipeline "fix auth tests" --write --checkpoint --save-state .ronin/pipeline/auth.json ronin pipeline --resume .ronin/pipeline/auth.json --list-checkpoints ronin pipeline --resume .ronin/pipeline/auth.json --restore-latest-checkpoint # gated restore if the tree moved ``

• 🔁 Cross-provider failover: set failover in config and a turn that hits a rate-limit or outage on the primary **transparently continues on the next pr

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rohithkandula19
• Source: rohithkandula19/Ronin
• License: MIT
• Homepage: https://github.com/rohithkandula19/Ronin#readme

Install and usage instructions live in the source repository linked above.