RadSim

Radically simple by default — a coding agent that stays out of its own way.

RadSim (radsimcli on PyPI) is a coding agent that runs in your terminal. You configure a provider API key, type a task, and the agent edits files, runs commands, uses git, and reports back. The model never holds your code — it sits on your machine, calls a model over the network, and sends back tool results until the task is done.

It works on Python 3.10+, macOS, Linux, and Windows. The current version on this branch is 1.6.1.

Why RadSim exists

Most AI coding tools are tuned for impressive demos. The output runs once and then becomes a maintenance burden — clever one-liners, deep nesting, abstractions invented for problems that aren't there. RadSim was built around the opposite default: the simplest version of a thing that actually works. That rule applies in two places:

1. The code RadSim writes for you. The system prompt and built-in skills push the model toward flat control flow, descriptive names, single-purpose functions, and standard patterns that any other agent (or a junior developer) can read on the first pass. There is a slash command, /stress, that runs an adversarial review against those rules.

2. RadSim itself. The agent loop is short, the file layout is flat, the provider clients are thin wrappers, and the tool registry is a dictionary. When something breaks, you can find it.

It is also local-first. There is no server-side account, no project upload, no "cloud workspace." Your code is read from disk, sent to the model you chose, and the response goes through tool calls that run on your machine. If you revoke the API key, RadSim stops working — there's nowhere else for it to go.

How the agent loop works

1. You type a task — either as a single argument (radsim "fix the failing test") or interactively after radsim.
2. RadSim sends three things to your provider: the conversation so far, a system prompt, and the list of tool definitions the model is allowed to call.
3. The model replies with text, with tool calls, or both.
4. For each tool call, RadSim either runs it immediately (read-only operations) or asks you to confirm (anything that mutates state).
5. The tool result goes back to the model.
6. Steps 3–5 repeat until the model has nothing left to do or you stop the loop with Ctrl+C / /kill.

Two design choices fall out of this:

• The model never executes code directly. Everything that touches your machine goes through a named tool with a defined schema. That's what lets RadSim show you a diff before writing a file, or a command before running it.

• Confirmations are policy, not friction. The model can request a destructive action, but you decide whether it happens. Trust patterns are learned per action type so the prompts get less chatty over time without removing the guardrail.

Why OpenRouter is the default provider

RadSim supports openrouter, openai, and claude directly. OpenRouter is the recommended starting point because:

• One key, many models. The curated selector includes Kimi K3, Claude Fable 5, all six GPT-5.6 variants, GLM 5.2, and other current models.
• Your model choice persists. RadSim reuses the provider and model you most recently selected instead of resetting each new instance. GLM 5.2 is the OpenRouter first-run fallback when no preference exists.
• Live model catalogue. OpenRouter publishes the full list of available models with their context windows and capabilities. RadSim caches that under ~/.radsim/models_cache.json and falls back to a static list if the fetch fails.
• Reasoning controls match the model. RadSim reads each OpenRouter model's supported effort levels and sends the selected value as reasoning.effort. Models with one fixed level, such as Kimi K3, use that required level automatically.

If you already pay for Anthropic or OpenAI directly, those providers are first- class — there's no degraded path. The provider layer is the same code shape; OpenRouter is just the most flexible starting point.

Install

RadSim installs with pipx, which puts it in its own isolated environment. You never create or activate a virtualenv, and it avoids the externally-managed-environment error (PEP 668) that modern macOS and Linux raise when you pip install into the system Python.

Pick your platform, copy-paste the block, then restart your terminal so the updated PATH takes effect and run radsim.

Quick install (macOS & Linux, one line)

Auto-detects your distro, sets up pipx, and installs RadSim:

curl -fsSL https://raw.githubusercontent.com/MBemera/Radsim/main/install.sh | bash

Prefer to do it by hand? Use the per-platform blocks below.

macOS

# With Homebrew (recommended)
brew install pipx
pipx ensurepath
pipx install radsimcli

No Homebrew? Install pipx with pip instead:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
python3 -m pipx install radsimcli

Ubuntu / Debian / Kubuntu / Mint / Pop!_OS

# Ubuntu 22.04+ or Debian 12+
sudo apt update
sudo apt install pipx
pipx ensurepath
pipx install radsimcli

Older releases (Ubuntu 20.04, Debian 11) have no pipx package — use pip:

sudo apt update && sudo apt install python3-pip
python3 -m pip install --user pipx
python3 -m pipx ensurepath
python3 -m pipx install radsimcli

Fedora / RHEL / Rocky / Alma

# Fedora, and RHEL / Rocky / Alma 9+
sudo dnf install pipx
pipx ensurepath
pipx install radsimcli

On RHEL / Rocky / Alma 8 (no pipx package), use pip:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
python3 -m pipx install radsimcli

Arch / Manjaro

sudo pacman -S python-pipx
pipx ensurepath
pipx install radsimcli

openSUSE

sudo zypper install python3-pipx
pipx ensurepath
pipx install radsimcli

Alpine

sudo apk add pipx
pipx ensurepath
pipx install radsimcli

Windows (PowerShell)

Needs Python 3.10+ (install from python.org with "Add Python to PATH", or use the py launcher as shown):

py -3 -m pip install --user pipx
py -3 -m pipx ensurepath
py -3 -m pipx install radsimcli

Or let the bundled installer set it up for you:

.\install.ps1

Notes: py -3 -m radsim runs RadSim even before PATH is refreshed. Config and credentials live under %USERPROFILE%\.radsim. Scheduled jobs use Windows Task Scheduler; winget, Chocolatey, and Scoop are auto-detected for optional tool installs, but none is required.

Verify

Restart your terminal first, then:

radsim --version

From source

For reading the code or sending PRs:

git clone https://github.com/MBemera/Radsim.git
cd Radsim
pipx install -e ".[dev]"     # or: python3 -m pip install -e ".[dev]"

On Windows PowerShell:

git clone https://github.com/MBemera/Radsim.git
Set-Location .\Radsim
py -3 -m pip install -e ".[dev]"
py -3 -m pytest -q

Plain pip (alternative)

If your Python isn't externally managed (older distros, an activated venv, or Windows), you can skip pipx entirely:

python3 -m pip install --user radsimcli

First run

Run radsim with no arguments. The setup wizard asks for:

• Terms acceptance.
• A provider (openrouter, openai, or claude).
• A model from that provider's list.
• An API key, which is written to ~/.radsim/.env with chmod 600.

You can re-enter the wizard at any time with radsim --setup. Once configured:

# Interactive mode
radsim

# One-shot mode
radsim "Find the failing tests and explain the cause"
radsim "Add input validation to the API handler"

# Skip confirmation prompts (use deliberately)
radsim --yes "Format the project and fix lint errors"

Where RadSim looks for .env

In priority order, highest first:

1. RADSIM_ENV_FILE if it points at a real file.
2. A preferred_env_file saved as a memory preference.
3. .env in your current working directory.
4. The .env next to the installed RadSim source (used during development).
5. ~/.radsim/.env (the global config).

Earlier files win on conflicting keys. This means you can drop a .env in any project to override the global one without touching ~/.radsim.

Slash commands

Slash commands exist because there are workflows you'll reach for often enough that typing them as a prompt would be wasteful. They all work mid-session.

Command	What it does
/help, /commands	Show help, list slash commands.
/tools	List the tools the model can currently call.
/switch, /free	Change provider/model now (and persist to ~/.radsim/.env). /free jumps to the cheapest OpenRouter model.
/login, /logout	Save or remove provider credentials.
/config, /settings	Re-run the setup wizard or inspect agent settings.
/ratelimit	Cap how many tool calls the model can make per turn.
/clear, /new	Forget the current conversation; start fresh.
/memory	Inspect or edit persistent memory.
/skill	Manage your custom-instruction skill files.
/teach	Toggle teach mode (annotated diffs, slower pace).
/plan, /panning	Plan-then-execute and brain-dump processing workflows.
/background, /job	Start sub-agent jobs and scheduled jobs.
/mcp, /telegram	Connect to MCP servers; configure Telegram remote control.
/complexity, /stress, /archaeology	Score complexity, run adversarial review, find dead code.
/exit, /kill	Quit normally; emergency-stop the loop.

Tools, explained simply

The model gets 72 tools by default, grouped by what they let it do:

• Look at your code. read_file, list_directory, glob_files, grep_search, repo_map, plus symbol-level helpers like find_definition and find_references. None of these mutate anything; they don't ask for confirmation.

• Change your code. write_file, replace_in_file, multi_edit, apply_patch. Each one shows you a diff before running.

• Run things. run_shell_command, run_tests, lint_code, format_code, type_check. The general shell always requires a fresh confirmation; learned trust can auto-confirm safer, purpose-built test and analysis tools.

• Use git. Status, diff, log, branch, add, commit, checkout, stash. Reads are free; writes confirm.

• Manage dependencies. pip_install, npm_install, add_dependency, list_dependencies. Always confirms.

• Talk to the web. web_fetch for HTTP, plus a Playwright-driven browser (browser_open, browser_click, browser_type, browser_screenshot). Browser tools need python3 -m playwright install chromium first.

• Remember things across sessions. save_memory, load_memory, forget_memory. Memory is sanitized before write — anything that looks like an API key gets replaced with [REDACTED_SECRET].

• Stay organized. todo_read, todo_write, plan_task, delegate_task for in-session tracking and farming work out to a sub-agent.

• Heavier operations. run_docker, database_query, generate_tests, refactor_code, deploy. All confirm.

• Add more tools at runtime. add_tool lets the model register a new tool by name, schema, and Python body. The new tool is appended to radsim/tools/custom_tools.py and hot-loaded into the live registry — no restart needed. list_custom_tools and remove_tool manage the result.

If you ask "can you do X?" and the answer is no, the right follow-up is often "add a tool that does X" — that's a single add_tool call, not a code change.

MCP support is opt-in:

python3 -m pip install "radsimcli[mcp]"

Safety

RadSim's safety model is simple: anything that touches your machine confirms unless you've trained the trust system to allow it.

Confirmations cover file writes and deletes, shell commands, git mutations, dependency changes, code formatting, database queries, deploys, memory writes, scheduled jobs, custom-tool registration, and outbound Telegram messages.

A few hard rules don't bend even with --yes:

• General shell commands always require a fresh confirmation because a shell can read, write, execute project code, and access the network.
• API keys live in ~/.radsim/.env with chmod 600.
• The agent cannot write to .env, credentials files, or known private-key paths. It can read them when you ask.
• Anything you include in a prompt gets sent to the provider you chose. That's how the model works; pick a provider whose data policy matches your context.

You can disable the GitHub release check at startup with --skip-update-check.

Configuration files

Everything user-level lives under ~/.radsim:

Path	Purpose
~/.radsim/.env	Provider, model, and API keys.
~/.radsim/settings.json	Reasoning effort, rate limits, UI preferences.
~/.radsim/memory/	Persistent memory store.
~/.radsim/schedules.json	Scheduled jobs.
~/.radsim/mcp.json	MCP server config.
~/.radsim/models_cache.json	Cached OpenRouter model catalogue.

Architecture

For contributors. Files are flat under radsim/:

Path	Purpose
radsim/cli.py	CLI entry point and startup flow.
radsim/agent.py, agent_*.py	Main agent class and conversation/policy mixins.
radsim/api_client.py	Provider clients (OpenAI, Anthropic, OpenRouter).
radsim/config.py	Provider lists, defaults, pricing, settings, env loading.
radsim/tools/	Tool definitions and implementations.
radsim/commands*.py	Slash command registry and handlers.
radsim/safety.py	Path checks and confirmation prompts.
radsim/memory.py	Persistent memory plus secret sanitization.
radsim/mcp_client.py	Optional MCP integration.
radsim/telegram.py	Telegram bridge.
radsim/scheduler.py	Scheduled jobs.
tests/	Pytest suite.

Development

python3 -m pip install -e ".[dev]"
pytest
ruff check .

License

MIT. See LICENSE.