- Create the project Bash
mkdir agentrun && cd agentrun mkdir agentrun # inner package directory Copy all the files above into the correct locations.
- 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.
- 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
Metadata
Release files for agentrunai 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentrunai-1.0.1.tar.gz | 29.2 kB | Without provenance | Details for agentrunai-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentrunai-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for agentrunai-1.0.1-py3-none-any.whl |
Total release size: 59.2 kB
Release files / agentrunai-1.0.1.tar.gz
| Download URL | agentrunai-1.0.1.tar.gz |
|---|---|
| Size | 29.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2f5ad963e348cd838e15b0b7a2d1101bb276afa9fadb7bc58a8447f0b322147c
|
|
BLAKE2b-256 checksum How to use checksums |
6c0b1cb64022fac3f07d03a01d50ef9c308f04d7c44ffd72bcdd6cde16482954
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.9
|
Release files / agentrunai-1.0.1-py3-none-any.whl
| Download URL | agentrunai-1.0.1-py3-none-any.whl |
|---|---|
| Size | 30.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2eae37857e4534d0c1c7556937b4305d654261fd4dfcb19aba746978f836e222
|
|
BLAKE2b-256 checksum How to use checksums |
2b31b930462a1449b09c77fd899b53c0052e2d847fb7a84a12be0d45bf5e6b4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.9
|
Security for agentrunai 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.