A terminal coding agent that reads your codebase, writes code, runs tests, and iterates — all on your machine. Use DeepSeek, Sarvam AI, a local Ollama model, Groq, OpenAI, or any OpenAI-compatible provider.
By downloading you agree to the Ralph License and Terms of Use.
Ralph is an independent, open-source coding agent that is intentionally decoupled from any specific LLM provider.
Frontier coding agents like Claude Code, Cursor, and GitHub Copilot tightly bundle the agent layer with a specific model or cloud platform. Ralph separates those concerns. The agent — its agentic loop, tool set, session management, and safety guardrails — is a standalone piece of software. The LLM is a pluggable backend. You choose the model; Ralph does the work.
Ralph ships with DeepSeek as its default provider. DeepSeek V4 offers frontier-class coding performance at a fraction of the cost of OpenAI or Anthropic. It supports a context window of up to 1 million tokens, and Ralph supports configurable context length so you can tune how much of that window the agent uses for your workload. It is the recommended starting point for most users.
Sarvam AI is an Indian AI lab building large language models trained with Indian languages and context. Pair Ralph with Sarvam and you get a coding agent where the entire stack — from agent runtime to inference provider — runs without dependency on US-based infrastructure or data pipelines.
A few honest caveats: Sarvam’s coding capabilities are not yet at par with DeepSeek, Claude, or GPT-4o. For complex, large-scale refactoring or multi-file architectural changes, a frontier model will perform better. For small to medium coding tasks — writing functions, fixing bugs, adding tests, explaining code — Sarvam works well, and the data-sovereignty story is compelling.
Ralph works with any model served locally via Ollama. No API keys, no data leaving your machine. Useful for air-gapped environments, cost-sensitive workflows, or experimenting with open-weight models like Qwen2.5-Coder or CodeLlama.
Ralph Plus is an experimental build of Ralph that adds a persistent Brain — a semantic memory system backed by a local SQLite graph. As Ralph Plus works on your codebase, it builds a context graph of files, symbols, and past edits. It recalls decisions across sessions, gets faster the longer it works on a project, and uses that memory to guide future edits rather than rediscovering the codebase from scratch every time.
Ralph Plus is early-stage and opt-in. It is best suited for developers who work on the same codebase repeatedly and want an agent that genuinely learns the project over time.
Created and maintained by Anand Kumar Keshavan — linkedin.com/in/anand-kumar-keshavan-18829a1.
Choose your platform. One binary, no dependencies.
For Macs with M1, M2, M3, or M4 chips.
Option A — Homebrew (recommended)
brew tap akkeshavan/ralph
brew install ralph
Upgrade: brew upgrade ralph
Option B — Manual install
# Download curl -L -o ralph.tar.gz https://github.com/akkeshavan/ralph-releases/releases/latest/download/ralph-LATEST-aarch64-apple-darwin.tar.gz
tar xzf ralph.tar.gz
sudo mv ralph-*/ralph /usr/local/bin/ralph
rm -rf ralph.tar.gz ralph-*/
ralph --version
ralph --help
For Macs with Intel processors (2020 and earlier).
Option A — Homebrew (recommended)
brew tap akkeshavan/ralph
brew install ralph
Option B — Manual install
# Download curl -L -o ralph.tar.gz https://github.com/akkeshavan/ralph-releases/releases/latest/download/ralph-LATEST-x86_64-apple-darwin.tar.gz
tar xzf ralph.tar.gz
sudo mv ralph-*/ralph /usr/local/bin/ralph
rm -rf ralph.tar.gz ralph-*/
ralph --version
ralph --help
For standard 64-bit Linux (Ubuntu, Debian, Fedora, Arch, Alpine, etc.).
# Download (statically linked musl build) curl -L -o ralph.tar.gz https://github.com/akkeshavan/ralph-releases/releases/latest/download/ralph-LATEST-x86_64-unknown-linux-musl.tar.gz
tar xzf ralph.tar.gz
sudo mv ralph-*/ralph /usr/local/bin/ralph
rm -rf ralph.tar.gz ralph-*/
ralph --version
ralph --help
For ARM64 Linux — AWS Graviton, Raspberry Pi 5, Oracle Ampere, etc.
# Download (statically linked musl build) curl -L -o ralph.tar.gz https://github.com/akkeshavan/ralph-releases/releases/latest/download/ralph-LATEST-aarch64-unknown-linux-musl.tar.gz
tar xzf ralph.tar.gz
sudo mv ralph-*/ralph /usr/local/bin/ralph
rm -rf ralph.tar.gz ralph-*/
ralph --version
ralph --help
For Windows 10/11 x86-64. Run commands in PowerShell.
.zip for Windows x86-64.New-Item -ItemType Directory -Force -Path "C:\tools\ralph"
Copy-Item ralph.exe "C:\tools\ralph\"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\tools\ralph", "Machine")
ralph --version
ralph --help
brew uninstall ralph # Optionally remove the tap entirely: brew untap akkeshavan/ralph
sudo rm /usr/local/bin/ralph
Remove-Item "C:\tools\ralph\ralph.exe" # Then remove C:\tools\ralph from your PATH in System Environment Variables
Ralph uses DeepSeek by default. Set your API key in your shell profile or in a .env file in your project directory.
Get your key at platform.deepseek.com. You pay DeepSeek directly for usage — typically fractions of a cent per coding task.
Option 1 — Shell profile (global, all projects):
export DEEPSEEK_API_KEY="sk-..."
[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-...", "User")
Option 2 — .env file (per-project, team-friendly):
DEEPSEEK_API_KEY=sk-...
BRAVE_API_KEY=BSA... # optional
Ralph automatically loads .env from the project directory on startup. Shell exports always take precedence over .env. A global default can also be placed in ~/.ralph/.env.
Enables Ralph to search the web — useful for looking up current API docs, error messages, and library versions. Three providers are supported; pick whichever you have a key for.
Option A — Brave Search (free tier available, no SerpAPI account needed)
BRAVE_API_KEY=BSA...
# Ralph auto-selects Brave when BRAVE_API_KEY is set
Get a free key at brave.com/search/api.
Option B — SerpAPI / Google
SERP_API_KEY=... # Optionally pin provider explicitly: # RALPH_SEARCH_PROVIDER=serpapi
Option C — DuckDuckGo (reuses your SerpAPI key)
SERP_API_KEY=... RALPH_SEARCH_PROVIDER=duckduckgo
When both BRAVE_API_KEY and SERP_API_KEY are set, Ralph auto-selects Brave. Use RALPH_SEARCH_PROVIDER to override (brave, serpapi, or duckduckgo).
Ralph automatically compacts the conversation history when it approaches the model’s context limit, summarising old turns so the session can continue without losing track of the task. The default trigger is 40,000 tokens — a conservative value chosen to work reliably across all supported providers, including those with modest 32–128k context windows (Groq, Ollama, older OpenAI models).
DeepSeek V3 and V4 have a 1 million token context window and perform well with much larger contexts — typically up to 200k tokens before coherence starts to degrade. At the default 40k threshold, Ralph compacts long sessions far more often than necessary, discarding context that would have been genuinely useful to DeepSeek.
Recommended starting point for DeepSeek
[compaction] compact_at_tokens = 150000 # compact when session exceeds ~150k tokens compact_to_tokens = 80000 # target size after compaction keep_recent_turns = 15 # always keep the N most recent turns verbatim [guardrails] max_tokens_per_session = 600000 # raise the hard session ceiling (default: 200k)
[compaction] compact_at_tokens = 150000 compact_to_tokens = 80000
How to find your own sweet spot — there is no single right answer. A higher compact_at_tokens means more working memory per session and fewer compactions, but each API call becomes more expensive and slightly slower. Start with 150k, run a few multi-file tasks, and watch the [tokens] counter in the output. If compaction is still firing too early (or never firing), adjust in 25k increments. Keep compact_to_tokens at roughly half of compact_at_tokens so there is plenty of room for the summary and new turns after a compaction event.
The default 40k is intentionally safe for users who switch between providers. If you use a mix of DeepSeek and a smaller-context provider (e.g. a local Ollama model with 8k context), set the compaction config in a per-project .ralph.toml rather than globally.
Ralph works with DeepSeek (default), Sarvam AI, and any OpenAI-compatible provider — including local models. Add credentials to your .env file and pass --provider on the command line.
Ollama runs open-source models (Llama, Qwen, Mistral, Gemma, etc.) directly on your machine. Great for privacy-sensitive code or offline use.
ollama pull qwen2.5-coder:14b # or: llama3.1:8b, deepseek-coder-v2:16b, mistral:7b, gemma3:12b
.env fileOLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_MODEL=qwen2.5-coder:14b
# OLLAMA_CONTEXT_LENGTH=32768 # optional — set if auto-detection fails
ralph --provider local-ollama # or pass a task directly: ralph --provider local-ollama "fix the failing tests"
Ralph auto-detects the model context window via Ollama’s /api/show endpoint. If detection fails, set OLLAMA_CONTEXT_LENGTH in your .env. No OLLAMA_API_KEY needed unless your Ollama instance requires authentication.
Groq runs open-source models (Llama 3, Mixtral, Gemma) on custom LPU hardware with extremely low latency. Free tier available.
.env fileGROQ_API_KEY=gsk_...
GROQ_MODEL=llama-3.3-70b-versatile
# other options: llama-3.1-8b-instant, mixtral-8x7b-32768, gemma2-9b-it
ralph --provider groq "refactor the auth module"
Use OpenAI models (GPT-4o, GPT-4o-mini, o3-mini) with your existing OpenAI API key.
.env fileOPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
# other options: gpt-4o-mini, o3-mini
ralph --provider openai "add pagination to the API"
Together AI hosts a large catalogue of open-source models including Llama, Qwen, Mistral, and DeepSeek variants.
.env fileTOGETHER_API_KEY=... TOGETHER_MODEL=meta-llama/Llama-3-70b-chat-hf # other options: Qwen/Qwen2.5-Coder-32B-Instruct, deepseek-ai/DeepSeek-V3 # TOGETHER_CONTEXT_LENGTH=32768 # optional override
ralph --provider together "write unit tests for the payment module"
Sarvam AI provides sarvam-30b (default) and sarvam-105b (pro) — both with full native tool and function calling support. Get a key at dashboard.sarvam.ai.
.env fileSARVAM_API_KEY=... SARVAM_MODEL=sarvam-30b # use sarvam-105b for the larger, more capable model # SARVAM_CONTEXT_LENGTH=32768 # optional override
ralph --provider sarvam "add input validation to the signup endpoint" # or interactive: ralph --provider sarvam
Switch to the larger model by setting SARVAM_MODEL=sarvam-105b in your .env. The --pro flag has no effect with Sarvam — select the model via the env var instead.
Each project can have its own .env with different provider settings. Just cd into the project and run ralph --provider <name> — it picks up the right credentials automatically. Add .env to your .gitignore so keys are never committed.
# Default — DeepSeek (no flag needed) ralph "fix the bug" # Sarvam AI ralph --provider sarvam "fix the bug" # Local Ollama model (private, free) ralph --provider local-ollama "fix the bug" # Groq — very fast cloud inference ralph --provider groq "fix the bug"
Start Ralph in your project directory and describe what you want in plain language.
# Navigate to your project, then start Ralph cd /path/to/your/project ralph # Use the pro (reasoning) model ralph --pro # Resume the last session ralph --resume # Disable plan mode for this session ralph --no-plan
Once Ralph starts, type your task in plain language. Ralph reads your code, makes changes, runs commands, and iterates until the task is done.
# Type your task — no special syntax needed
> add input validation to the signup endpoint
> the auth tests are failing, fix them
> refactor the database module to use a connection pool
> explain how the rate limiter works
Use /h inside Ralph to see all commands, including checkpoints, session history, and skills.
Before making any changes, Ralph drafts a step-by-step plan and waits for your approval. Review, edit, or reject it — Ralph only acts once you say go.
Plan mode is on by default. To skip planning for a session:
ralph --no-plan
Toggle plan mode at any time from inside the REPL:
# Disable plan mode for this session > /plan off # Re-enable plan mode > /plan on
When plan mode is on, Ralph outputs a numbered task list and pauses. Type yes (or press Enter) to proceed, or describe changes to the plan before Ralph starts coding.
Spin up background subagents to work on independent subtasks in parallel. Each subagent runs in its own context with file-locking to prevent conflicts.
# Start Ralph with agents enabled ralph --agents
Enable agents mid-session or manage running tasks from the REPL:
# Enable agents for the current session > /agents on # List all running and completed subagent tasks > /tasks # Kill a specific task by ID > /kill <task-id> # Kill all running subagents > /kill all
When agents are enabled, Ralph can delegate independent subtasks to background workers via the delegate_task tool. Subagents run silently with a 25-turn limit. They share read access to the codebase but use file locking to prevent concurrent writes. Subagents cannot spawn further subagents, delete files, or run shell commands.
Give Ralph standing instructions for your project. Coding conventions, architecture notes, key context — all automatically loaded at the start of every session.
Create a RALPH.md (or .ralph/RALPH.md) in your project root. Ralph will load it automatically. For conventions that apply across all your projects, create ~/.ralph/RALPH.md.
# My Project ## Stack - Next.js 14, TypeScript, PostgreSQL - Use `pnpm` for package management (not npm or yarn) - Tests with Vitest; mocking with `vi.mock()` ## Conventions - Functional React components only; no class components - All API routes must validate input with Zod - Prefer named exports over default exports - Errors are wrapped with a custom `AppError` class ## Key files - `src/lib/db.ts` — database client and query helpers - `src/middleware/auth.ts` — JWT validation middleware
Ralph uses this as context for every task — so it won’t suggest npm when you use pnpm, and it already knows how errors are handled in your project.
Skills are reusable prompt templates stored as .md files. Invoke them with /skill-name at the Ralph prompt, optionally followed by a file or description.
Place a .md file in .ralph/skills/ (project) or ~/.ralph/skills/ (global). Then invoke it from Ralph’s prompt.
# Invoke a skill on specific files > /review-python src/auth.py > /review-ts-node src/api/users.ts # Or just invoke it — Ralph uses the current context > /review-rust
Use {{input}} as a placeholder for what you type after the skill name. If omitted, input is appended automatically.
# Security Review
Review {{input}} for security vulnerabilities. Focus on:
- Authentication and authorisation gaps
- Input validation and injection risks (SQL, XSS, path traversal)
- Secrets and sensitive data exposure in logs or responses
- Insecure defaults and missing security headers
Save as .ralph/skills/security.md, then use /security src/api/.
Ready-made code review skills for popular languages and frameworks. Download a file into .ralph/skills/ and start using it immediately.
Skills are plain Markdown files — open any downloaded file to see how they work and customise them for your project.
Every time Ralph modifies a file it quietly saves a snapshot. If something goes wrong you can roll back to any earlier state without touching your git history.
On session start Ralph creates an orphan branch named ralph/checkpoints/<hostname> and a linked git worktree at .ralph/checkpoint-worktree/. Every write, edit, and delete is mirrored there as a commit. This branch shares no history with your working branch — it never appears in git log and is never pushed (a pre-push hook blocks it automatically).
In addition, every destructive operation writes a timestamped .bak file under .ralph/backups/<path>/ (up to 10 revisions per file) for fast single-file recovery without git. The .ralph/ directory and the worktree are automatically added to .gitignore so none of this appears in your repository.
List recent checkpoints from the Ralph prompt:
/checkpointsRevert to a checkpoint by name or number. Ralph shows a preview of every file that will change and requires confirmation before doing anything:
/revert 3
/revert before-delete-190532To restore a single file from the latest checkpoint without rolling back the whole session:
/restore src/main.rs
/restore src/main.rs HEAD~2You can also inspect the checkpoint branch directly with standard git commands — the worktree is a normal git working directory:
git -C .ralph/checkpoint-worktree log --oneline
git -C .ralph/checkpoint-worktree show HEAD:src/main.rsgit_commitThere is an optional setting git_commit = true in the [checkpoints] section of RALPH.md or your config. Leave this off. When enabled, Ralph commits checkpoint snapshots directly onto your working branch after every file change. A single task that touches ten files can produce dozens of commits; a long session can produce hundreds. These commits clutter git log, make diffs unreadable, and are difficult to clean up retroactively.
The orphan-branch system described above already protects all your work without polluting your history. The git_commit option exists only for unusual setups where the worktree mechanism is unavailable.
If you prefer Ralph not to create the checkpoint branch or worktree at all, add this to your RALPH.md:
[checkpoints]
enabled = falsePer-file backups in .ralph/backups/ are still written when checkpoints are disabled, so you always have a fast single-file fallback.
Session integrity on stall exit — typing a follow-up prompt after Ralph stalled no longer produces an immediate HTTP 400 error. The stall exit was leaving an orphaned assistant tool_calls message in the active session; the next prompt would flush that corrupt state to disk and the API would reject the whole conversation. The session is now cleaned up before the stall exit so the conversation continues uninterrupted.
Parallel subagent orchestration — delegate independent subtasks to background workers running concurrently with file-locking. Use --agents to enable, /tasks to monitor, /kill <id> to stop.
Anti-stall & large-codebase handling — context-aware stall nudges (read-loop, edit-without-test, repeated-failure), repo map injected into the system prompt so the LLM can orient itself without reading every file, and a reasoning provider fallback triggered automatically after consecutive edit or test failures.
Security hardening — compound shell commands (&&, ||, ;, |) always require confirmation regardless of the base command, closing a safe-prefix injection bypass. Secret file guard now applied consistently across all read paths including load_files. GitHub token patterns added to secret detection.
Version check fix — Ralph and Ralph Plus now independently track their own release tags; the previous bug where Ralph displayed a Ralph Plus version as an available upgrade is resolved.
Session auto-repair — sessions interrupted mid-turn (crash, kill signal, or user cancel) are automatically healed on resume. Previously they would fail immediately with a cryptic HTTP 400 error and be permanently stuck.
Cancel without breaking the session — cancelling a tool action mid-turn no longer corrupts the message history. Remaining tool calls in the same turn receive a synthetic “cancelled” result so the conversation sequence stays valid for the next LLM call.
Compaction preserves system prompt — the system prompt is now always retained at position 0 after context compaction. Previously it could be silently dropped or misplaced in long sessions.
400 errors fast-fail — HTTP 400 Bad Request errors are immediately fatal instead of being retried three times. Eliminates the confusing “Turn 1” ×4 behaviour seen in logs when history was corrupt.
Hard-trim safety — the emergency context trim (fallback when LLM compaction fails) now correctly removes orphaned tool-result messages left behind after trimming, preventing a second class of 400 errors.
Image / vision support — drop image files (.png, .jpg, .gif, .webp) directly into the prompt. Ralph resizes, base64-encodes, and sends them to vision-capable providers. DeepSeek V4 Flash and Pro support this natively.
Loop stability — stall detection threshold reduced (20→5 turns), fuzzy edit fallback when exact match fails, command deduplication to break cycling loops, same-file edit loop detection.
Sarvam improvements — reasoning effort default raised to high; additional code-quality rules injected into the system prompt for Sarvam and all non-DeepSeek providers.
Provider identity fix — Ralph now correctly identifies itself by the active provider in all configurations.
Generic search provider abstraction — web search now supports Brave, SerpAPI (Google), and DuckDuckGo (via SerpAPI). Set BRAVE_API_KEY or SERP_API_KEY and Ralph auto-detects the right provider. Use RALPH_SEARCH_PROVIDER=brave|serpapi|duckduckgo to pin a specific one.
Sarvam AI support — use sarvam-30b or sarvam-105b with --provider sarvam.
Smart context window detection — Ralph now auto-detects the model’s context window for all providers. For Ollama it queries the native /api/show endpoint; for cloud providers it tries the /models API and falls back to sensible defaults. Override with <PROVIDER>_CONTEXT_LENGTH in your .env.
Three-layer file safety — all file writes are now atomic (temp → fsync → rename). Before every write or edit the original is backed up to .ralph/backups/. At the end of every completed task Ralph commits modified files to a dedicated ralph/checkpoints/<hostname> git branch in an isolated worktree — your working branch is never touched.
Delete protection — delete_file always requires explicit confirmation. A backup is taken before deletion.
OpenAI-compatible providers — added --provider flag supporting local-ollama, groq, openai, and together. Credentials loaded from .env file.
.env file support — Ralph now auto-loads .env from the project directory and ~/.ralph/.env as a global fallback.
Parallel subagents — delegate independent subtasks to background workers running concurrently with file-locking.
Plan mode on by default — Ralph drafts a step-by-step plan before making any changes.
Context compaction — long sessions are automatically summarised when approaching the model’s context window.
Session persistence — resume any previous session with ralph --resume.