ra

ra is a small, hackable agent. Nothing hidden behind abstractions you can't reach. It doesn't ship with a system prompt. Every part of the loop is exposed via config and can be extended by writing scripts or plain TypeScript. Middleware hooks let you intercept every step — model calls, tool execution, streaming, all of it.

It comes with built-in tools for filesystem, shell, network, and user interaction. Connect to MCP servers for additional tools. Persistent sessions via JSONL. An FTS5 memory backed by SQLite. It talks to Anthropic, OpenAI, Google, Ollama, Bedrock, and Azure. Switch providers with ease.

It speaks MCP both ways — use external MCP servers, or expose ra itself as an MCP server so you can use it from Cursor, Claude Desktop, or anything else that speaks the protocol.

It gives you real control over context. Deterministic discovery for common formats (CLAUDE.md, AGENTS.md, README.md), pattern resolution, prompt caching, compaction, token tracking. A skill system that can pull skills from GitHub repos or npm packages.

It runs as a CLI, REPL, HTTP server, or MCP server. No runtime dependencies. Structured logs and traces per session, so you can actually see what your agent is doing.

All of this is configurable via a layered config system — env vars, config files (JSON, YAML, TOML), or CLI flags. Each layer overrides the last.

Install

curl -fsSL https://raw.githubusercontent.com/chinmaymk/ra/main/install.sh | bash

Quick start

export RA_ANTHROPIC_API_KEY="sk-..."

ra "Summarize the key points of this file" --file report.pdf   # one-shot
ra                                                              # interactive REPL
cat error.log | ra "Explain this error"                         # pipe stdin
git diff | ra --skill code-review "Review these changes"        # pipe + skill
ra --http                                                       # streaming HTTP API
ra --mcp-stdio                                                  # MCP server for Cursor / Claude Desktop

The config is the agent

Drop a ra.config.yml in a repo and that directory becomes a project-specific assistant. Set env vars for a different persona. Pass --skill to inject a role at runtime. Run --mcp-stdio to expose it as a tool for Cursor or Claude Desktop. Same binary, different agent — every time.

# ra.config.yml
provider: anthropic
model: claude-sonnet-4-6
maxIterations: 50
thinking: medium

skills:
  - code-review

middleware:
  beforeModelCall:
    - "./middleware/budget.ts"

mcp:
  client:
    - name: github
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]

Use cases

CI caught a flaky test

ra --skill debugger --file test-output.log "Why is this test failing?"

Reads the logs, explains the root cause, and exits. Pipe the output to Slack or a PR comment.

You're building a feature

ra
› /attach src/auth.ts
› How should I add rate limiting to this endpoint?

Attach files, ask follow-ups, keep context. Resume the session tomorrow with /resume.

Your product needs AI

ra --http --http-port 3000

POST a message, get SSE chunks back. No framework — just Bun.serve() under the hood.

Your editor needs a specialist

ra --mcp-stdio --skill code-review

Now Cursor or Claude Desktop has a dedicated code reviewer that uses your project's style guide, your skills, your system prompt.

What's in the box

Feature	Description
The Agent Loop	Model → tools → repeat, with streaming, middleware hooks at every step, and configurable iteration limits
Context Control	Smart compaction, token tracking, prompt caching, extended thinking, context discovery, pattern resolution
CLI	One-shot prompts, piping, chaining, scriptable
REPL	Interactive sessions with history, slash commands, file attachments
HTTP API	Sync and streaming chat, session management
MCP	Client (pull tools from MCP servers) and server (expose ra as a tool)
Built-in Tools	Filesystem, shell, network, and user interaction tools
Skills	Reusable instruction bundles — roles, behaviors, scripts, and reference docs
Middleware	Hooks at every loop stage — intercept, modify, or stop the loop
Sessions	Persist conversations as JSONL, resume from any interface, auto-prune
Memory	Persistent SQLite memory with FTS — save, search, forget across conversations
Configuration	Layered: defaults → file → env → CLI. The config is the agent