ReIN

Harness your code.

Quick Start · Architecture · Usage · 中文文档

ReIN is an open-source agentic coding runtime that implements a complete harness architecture — the control plane that orchestrates LLM calls, tool execution, hook lifecycle, permission control, and plugin systems.

It supports both Anthropic Claude (cloud) and local LLMs (Ollama, LM Studio, llama.cpp, vLLM) for fully offline operation.

Why ReIN?

Rein (n.) — a strap fastened to a bit, used to guide a horse. In software, the harness that guides an AI agent: intercepting, evaluating, executing, and extending every action it takes.

Most agentic coding tools are closed-source black boxes. ReIN opens up the full runtime:

• See exactly how LLM tool calls are orchestrated
• Hook into every lifecycle event (PreToolUse, PostToolUse, Stop, etc.)
• Control permissions at 5 layers (admin → user → project → command → hook)
• Extend with plugins (commands, agents, skills, hooks, MCP)
• Run offline with any local model — no API key needed

Quick Start

Prerequisites

• Python 3.11+
• An LLM backend (choose one):
  • Anthropic API key, or
  • Ollama / LM Studio / any OpenAI-compatible local server

Install

git clone https://github.com/BDeMo/ReIN.git
cd ReIN
pip install -r requirements.txt

Run

# Cloud mode (Anthropic Claude)
export ANTHROPIC_API_KEY=sk-ant-xxx
python -m rein direct

# Fully offline (Ollama)
ollama pull qwen2.5-coder:7b
python -m rein direct --local

# Custom local server (LM Studio / llama.cpp / vLLM)
python -m rein direct --local --local-url http://localhost:1234/v1 --local-model my-model

Architecture

rein/
├── core/
│   ├── harness.py          Core orchestrator — the heart of ReIN
│   ├── config.py           Multi-layer settings hierarchy
│   └── conversation.py     Session and message management
├── llm/
│   ├── provider.py         Abstract LLM interface
│   ├── anthropic_llm.py    Anthropic Claude (streaming + tool use)
│   └── local_llm.py        Local LLM (Ollama / LM Studio / llama.cpp / vLLM)
├── tools/
│   ├── registry.py         Tool registry and base class
│   ├── file_tools.py       Read / Write / Edit
│   ├── bash_tool.py        Bash with command filtering and security
│   └── search_tools.py     Grep / Glob
├── hooks/
│   ├── engine.py           Hook execution engine (command + prompt based)
│   └── types.py            9 lifecycle event types
├── permissions/
│   └── manager.py          5-layer permission model (allow / deny / ask)
├── plugins/
│   └── loader.py           Plugin discovery and loading
├── server/
│   └── app.py              FastAPI server with WebSocket streaming
├── client/
│   └── cli.py              Terminal client (direct + server modes)
└── main.py                 CLI entry point

Harness Pipeline

Every tool call passes through the full harness pipeline:

User Input
  → [UserPromptSubmit Hook]      Validate / preprocess
  → LLM streaming response       Generate text + tool calls
  → Tool call detected
    → [PreToolUse Hook]          Validate / modify / block
    → [Permission Check]         5-layer allow / deny / ask
    → Tool Execution             Run the tool
    → [PostToolUse Hook]         React / log / feedback
  → LLM continues                Feed result back
  → [Stop Hook]                  Validate task completion

Hook Events

Permission Layers

Layer 1  managed-settings.json       Enterprise admin (MDM deployable)
Layer 2  ~/.claude/settings.json     User global preferences
Layer 3  .claude/settings.json       Project-level settings
Layer 4  YAML frontmatter            Command / Agent tool whitelist
Layer 5  PreToolUse Hook             Runtime dynamic decisions

Usage

Direct Mode (simplest)

# Anthropic Claude
python -m rein direct

# Local LLM (Ollama)
python -m rein direct --local --local-model qwen2.5-coder:7b

# Custom system prompt
python -m rein direct --system-prompt "You are a Python expert."

Server + Client

# Terminal 1: server
python -m rein server --port 8765

# Terminal 2: client
python -m rein client --url ws://localhost:8765/ws/chat

# Local LLM server
python -m rein server --local --local-model llama3.1:8b

API

WebSocket Protocol

// Client → Server
{"type": "message", "content": "Read main.py", "system_prompt": "..."}

// Server → Client (streamed)
{"type": "text_delta",    "data": {"text": "I'll read..."}}
{"type": "tool_use",      "data": {"id": "...", "name": "Read", "input": {...}}}
{"type": "tool_result",   "data": {"tool_use_id": "...", "result": "..."}}
{"type": "usage",         "data": {"input_tokens": 150, "output_tokens": 80}}
{"type": "turn_complete", "data": {"stop_reason": "end_turn"}}

Local LLM

ReIN supports two tool-use modes:

Auto-detected from model name. Force native with --native-tools.

Compatible Servers

Recommended Models

Environment Variables

Dependencies

Acknowledgements

ReIN is inspired by and built upon ideas from:

• Anthropic — the Claude Code open-source plugin ecosystem and harness architecture
• Ollama — making local LLMs accessible to everyone
• FastAPI — elegant async Python web framework
• llama.cpp — efficient local model inference
• OpenAI — the tool-calling API convention adopted by local LLM servers

License

MIT