Your agent, your rules.

Install · Middleware · Tools · Recipes · Roadmap · Docs

Most agent frameworks lock you in. ra doesn't — every decision the agent makes flows through hooks you control, tools you define, and configs you commit. No hidden prompts, no black-box loops, no vendor lock-in.

One config file is the difference between a coding agent, a code reviewer, a research loop, and a multi-agent orchestrator:

ra "Fix the failing tests and open a PR"
git diff | ra "Review this diff for security issues"
cat error.log | ra "Explain what went wrong"
ra --config recipes/code-review-agent "Review the last 3 PRs"
ra --config recipes/multi-agent "Refactor the auth module, test it, and update the docs"

Set a budget and walk away — ra runs until the job is done or the budget runs out, whichever comes first.

agent:
  maxTokenBudget: 500_000   # hard cap on total token spend
  maxDuration: 600_000      # max wall-clock time in ms
  thinking: adaptive        # scales reasoning effort automatically

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

Works with Anthropic, OpenAI, Google, Ollama, Bedrock, Azure, OpenRouter, and LiteLLM — switch with --provider. Bring your own API key, or use your existing Anthropic or OpenAI / Codex subscription. All providers →

Intercept any step in the loop — read the full context, mutate it, or stop it entirely.

// middleware/audit.ts — log every tool call
export default async (ctx) => {
  const { name, arguments: args } = ctx.toolCall
  ctx.logger.info('tool', { name, args })
}

Wire them to hooks in config:

agent:
  middleware:
    afterToolExecution:
      - ./middleware/audit.ts

Available hooks: beforeLoopBegin, beforeModelCall, onStreamChunk, afterModelResponse, beforeToolExecution, afterToolExecution, afterLoopIteration, afterLoopComplete, onError.

Built-in: Read, Write, Edit, Bash, Glob, Grep, WebFetch, Agent (parallel sub-agents), and more — enable, disable, or configure each one independently. Permissions use a simple regex allow/deny system — no custom DSL, just patterns you already know:

permissions:
  rules:
    - tool: Bash
      command:
        allow: ["^git ", "^bun "]
        deny: ["--force", "--no-verify"]
    - tool: Write
      path:
        deny: ["\\.env", "secrets"]

Custom tools — export a function, register it in config, and the model picks it up. Works with TypeScript, shell scripts, and any scripting language — see the docs.

Each recipe is a complete agent — config, middleware, tools, and skills — committed to your repo with the same observability and control as everything else.

ra --config recipes/oh-my-ra "Refactor the auth module and write tests"

Config lives in your repo — no hidden prompts, no default system prompt. One engineer defines the agent, commits it, everyone runs the exact same thing.

# ra.config.yml
agent:
  provider: anthropic
  model: claude-sonnet-4-6
  thinking: adaptive
  maxTokenBudget: 500_000
  skillDirs: [./skills]
  middleware:
    - ./middleware/token-budget.ts
    - ./middleware/audit-log.ts
  memory:
    enabled: true

Layered overrides: defaults → config file → env vars → CLI flags. YAML, JSON, or TOML.

ra isn't just a CLI. Pick the interface that fits your workflow:

Every model call, tool execution, and decision is captured automatically — structured JSONL logs, trace spans, and a built-in web inspector that shows the full picture: iterations, token spend, tool calls, and the complete message history.

ra --inspector

• Core agent loop with streaming
• Multi-provider support (Anthropic, OpenAI, Google, Ollama, Bedrock, Azure, OpenRouter, LiteLLM)
• Middleware hooks at every step of the loop
• Built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebFetch, Agent)
• Custom tools (TypeScript, shell, any scripting language)
• Regex-based permission system
• Skills and on-demand skill loading
• Token budgets and duration limits
• Adaptive thinking
• Session memory
• Multiple interfaces (REPL, CLI, HTTP, MCP, Cron)
• Built-in inspector / observability
• Recipes system
• Anthropic and Codex subscription support
• Self-improving agent
• Teams of agents
• Multi-agent orchestration via config
• Smarter compaction

Full reference at chinmaymk.github.io/ra — tools, skills, middleware, providers, configuration, and deployment guides.

MIT

ra — Your agent, your rules.