1. Create the project Bash

mkdir agentrun && cd agentrun mkdir agentrun # inner package directory Copy all the files above into the correct locations.

2. Install globally with pip Bash

From the project root (outer agentrun/ directory):

pip install -e . Or install without editable mode:

Bash

pip install . 3. Set your OpenAI API key Option A: Environment variable (add to your ~/.bashrc, ~/.zshrc, etc.):

Bash

export OPENAI_API_KEY="sk-your-key-here" Option B: Let AgentRun prompt you on first run — it saves to ~/.agentrun/config.json.

4. Use it from anywhere! Bash

Interactive mode — opens a REPL

agentrun

Single command mode

agentrun "create a python flask hello world app" agentrun "read main.py and fix the bug on line 42" agentrun "run the tests and fix any failures"

With options

agentrun -m gpt-4o-mini # use a different model agentrun -y "add logging to app.py" # auto-confirm all changes

Icon mode

default: unicode (compatible glyphs)

phosphor: real phosphor codepoints (requires a supporting font)

ascii: safest fallback

AGENTRUN_ICON_MODE=unicode agentrun AGENTRUN_ICON_MODE=phosphor agentrun AGENTRUN_ICON_MODE=ascii agentrun

Theme mode (clean defaults)

AGENTRUN_THEME=minimal agentrun AGENTRUN_THEME=vivid agentrun

Animation controls

AGENTRUN_ANIMATIONS=false disables all banner/spinner transitions

AGENTRUN_ANIMATION_SPEED controls timing multiplier (0.2 to 3.0)

AGENTRUN_ANIMATIONS=true AGENTRUN_ANIMATION_SPEED=1.0 agentrun AGENTRUN_ANIMATIONS=false agentrun

How It Works text

┌─────────────────────────────────────────────┐ │ YOU │ │ "Fix the bug in app.py line 23" │ └──────────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ AgentRun CLI │ │ • Interactive REPL with history │ │ • Slash commands (/help, /reset, /cd) │ │ • Single-command mode │ └──────────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ OpenAI GPT-4o API │ │ • Function/tool calling │ │ • Iterative reasoning loop │ │ • Context-aware code understanding │ └──────────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ Tools Layer │ │ ⊙ read_file ✚ write_file │ │ ≣ replace_in_file ⌬ insert_at_line │ │ ⊘ delete_lines ↵ run_command │ │ ⌨ list_files ⌕ search_in_files │ │ │ │ • Colored diff previews │ │ • User confirmation prompts │ │ • Automatic backups (.bak files) │ │ • Dangerous command blocking │ └─────────────────────────────────────────────┘ Key Features Feature Description Agentic Loop The AI can chain multiple tool calls — read a file, edit it, run tests, fix issues — all automatically Safe by Default Every file change and command shows a preview and asks for confirmation Backup Files Automatic .bak backups before any file modification Syntax Highlighting Rich terminal output with colored code, diffs, and panels Command History Arrow-key history saved across sessions at ~/.agentrun/history.txt Dangerous Command Blocking Blocks rm -rf /, mkfs, dd and other destructive patterns Multi-model Support Works with any OpenAI-compatible API (GPT-4o, GPT-4o-mini, local LLMs via compatible servers)

Token/Cost Optimization Feature Description Context Compaction Older turns are compressed into a rolling summary to reduce prompt size Repo-aware Retrieval Auto-selects relevant files/snippets for each request instead of loading broad context Read Cache Unchanged file reads are cached to avoid repeat disk reads and redundant payloads Tool Output Compression Large file/command payloads are truncated intelligently before model context insertion Model Routing Routes simple planning/tooling to fast model and escalates complex/error flows to quality model Token Budgets Configurable budget values for tuning behavior Persistent Project Memory Stores per-project preferences, recent files, and successful commands in ~/.agentrun/memory.json Parallel Read/Search Batch Executes independent read/list/search tool calls in parallel Targeted Retry Only transient API failures are retried with backoff

Routing and Budget Env Vars Bash

Optional model routing controls

export AGENTRUN_ROUTING_ENABLED=true export AGENTRUN_FAST_MODEL="openai/gpt-4o-mini" export AGENTRUN_QUALITY_MODEL="openai/gpt-4o"

Optional token budgets

export AGENTRUN_CONTEXT_BUDGET=256000 export AGENTRUN_TURN_BUDGET=256000