rtqcode

A terminal-based coding assistant that works like Claude Code, but runs locally via Ollama (or any OpenAI-compatible / Anthropic / Gemini / OpenRouter / Groq / xAI endpoint).

Setup

First, make sure you have Ollama running locally. Then install the dependencies:

pip install -r requirements.txt

(If it feels sluggish, double-check that Ollama is actually utilizing your GPU and not falling back to CPU).

Running it

Just run the batch file:

run.bat

How it works

The default setup uses two local models:

• rtqcode:7b: Handles actual coding, editing, and tool execution.
• rtqflash:3b: Handles breaking larger tasks down into step-by-step plans.

If you don't want to use local models, or just want to try a different size, you can swap them out or connect to external APIs (like OpenAI) by running /setup directly inside the CLI.

Tools

The agent has a tool loop (up to 25 iterations per prompt) and can call any of these:

Tool	What it does
read_file	Read a file's contents (numbered lines, skips binaries)
write_file	Write or overwrite a file
edit_file	Replace an exact unique substring in a file
delete_file	Delete a file or directory
list_directory	List files (recursive optional, respects .gitignore)
search_in_files	Case-insensitive substring search
grep	Fast regex search across files (glob filter, ignore-case, multiline)
glob	Find files matching a glob pattern
web_fetch	Fetch a URL and return stripped text
web_search	DuckDuckGo Lite search, returns result snippets
todo_write	Create or replace the session TODO list
notebook_edit	Replace a cell in a Jupyter .ipynb notebook
exit_plan_mode	Exit plan mode by submitting a plan for user approval
agent	Spawn a subagent for an isolated subtask
run_command	Run a shell command

Commands

Drop these into the prompt to manage your workspace and control the agent:

Command	What it does
/plan <task>	Asks the planner model to break down a task into a step-by-step TODO list
/plan-mode	Toggle plan mode (read-only exploration, then exit_plan_mode for approval)
/todos	Show the current session TODO list
/setup	Configure your API provider (Local Ollama vs. REST API) and models
/model	Quickly swap the active code/planner models
/git <cmd>	Run local git commands (/git status, /git diff, etc.)
/cd <path>	Change the current directory (supports autocomplete)
/ls [path]	List files in a directory
/run <cmd>	Run terminal commands directly
/read <file>	Print a file's contents to the screen
/clear	Wipe chat history, todos, and plan mode
/undo	Go back one turn
/rewind [n]	Rewind N turns (default 1)
/retry	Retry the last thing you asked
/resume	Resume a previous saved session
/compact	Summarize old turns into a compact context note
/cost	Show token estimates and turn count
/status	Show session info (cwd, models, plan mode, todos, history)
/add-dir <path>	Add an additional directory to the session scope
/memory	List loaded memory files
/agents	List available subagents
/permissions	Show active permission rules
/hooks	Show configured hooks
/output-style	Switch between default / terse / verbose
/debug	Turn on verbose logging to see what the agent is actually doing under the hood
/models	Show which models are currently loaded
/help	Print this list in the terminal
/exit	Quit out

Plan Mode

Toggle plan mode with /plan-mode. In plan mode the agent only has read-only tools (read_file, list_directory, grep, glob, search_in_files, web_fetch, web_search, todo_write, exit_plan_mode) — no writes, no mutating commands. The agent explores, drafts a plan, then calls exit_plan_mode to present it. You approve or discard; on approval, plan mode turns off and the agent executes the plan.

Memory Files

rtqcode loads memory markdown files hierarchically and injects them into the system prompt:

1. Global: ~/.rtqcode/CLAUDE.md
2. Project: .rtqcode.md in the current directory, plus the same file in every parent directory walking up to the filesystem root

Use /memory to see which files are currently loaded.

Subagents

Drop a .md file in ~/.rtqcode/agents/ or ./.rtqcode/agents/ to define a subagent. The filename (minus .md) is the subagent name; the first line becomes its description; the whole file is its system prompt.

The agent tool (agent) spawns a subagent with a read-only tool subset and an isolated conversation, runs it to completion, and returns its final summary. Use /agents to list configured subagents.

Skills

Create a .rtqskills/ folder. Toss in some markdown files (like .rtqskills/deployment_workflow.md). The agent will scoop them up and load them as usable context.

Permissions & Hooks

rtqcode reads settings (merged in order) from:

• ~/.rtqcode/settings.json (global)
• .rtqcode/settings.json (project, commit this)
• .rtqcode/settings.local.json (project, gitignore this)

{
  "permissions": {
    "allow": ["read_file", "list_directory", "grep", "glob", "run_command(git *)"],
    "deny":  ["delete_file", "run_command(rm -rf *)"],
    "ask":   ["write_file", "edit_file"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "prettier --write $(jq -r .tool_input.path)", "timeout": 30}]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "echo logged >> ~/.rtqcode/bash.log"}]
      }
    ],
    "Stop": [
      {"hooks": [{"type": "command", "command": "echo done >> ~/.rtqcode/stops.log"}]}
    ]
  }
}

• Permissions: allow runs silently, deny blocks, ask prompts. Rule syntax: Tool (any call) or Tool(key=value) (arg match).
• Hooks: PreToolUse / PostToolUse / Stop run shell commands with tool JSON on stdin. A hook can block the call by printing JSON like {"decision": "block", "reason": "..."}.

Use /permissions and /hooks to inspect the active configuration.

Sessions

Every agentic turn is auto-saved to ~/.rtqcode/sessions/<session-id>.json. Use /resume to pick a prior session and continue where you left off. /rewind drops the last N turns, /compact summarizes older turns into a short context note, /cost shows token estimates.

What it can actually do

• Read, write, and patch files directly on your disk
• Edit Jupyter notebooks cell-by-cell
• Traverse directories and regex-search code
• Execute shell commands natively
• Fetch URLs and search the web
• Spawn subagents for isolated research
• Track multi-step work with the TODO list
• Plan read-only, then execute after user approval
• Enforce permission rules and run hooks around tool calls
• Persist and resume sessions

Source

rtqcode/
├── main.py               # Entrypoint
├── run.bat               # Launcher
├── requirements.txt
└── agent/
    ├── core.py           # Main agent loop, slash commands, plan mode, dispatch
    ├── models.py         # Ollama + OpenAI + Anthropic provider hookups
    ├── tools.py          # Tool implementations + schemas
    ├── prompts.py        # System, plan-mode, and planner prompts
    ├── ui.py             # Terminal UI (sunset orange theme, panels, gradients)
    ├── session.py        # Session save/load, compaction
    ├── subagents.py      # Subagent runner + hierarchical memory loader
    └── permissions.py    # Permission rules + PreToolUse/PostToolUse/Stop hooks