🔍 ArgusTerm

An OS-aware AI terminal copilot. ArgusTerm watches your shell for failed commands, harvests OS state, captures compiler stderr silently, analyzes blast radius, and uses Gemini 3.6 Flash to iteratively suggest and apply fixes.

---

✨ Key Features

Feature	Description
🩺 OS State Harvesting	Inspects active ports, top processes, git status, and directory context
💥 Blast-Radius Analysis	Categorizes command danger (LOW → CRITICAL) before execution
🧠 Iterative Auto-Retry	Diagnoses errors, applies fixes (sed, pip), and automatically reruns the original command until it passes
📸 Diagnostic Re-run	Silently recaptures stderr for deterministic tools (g++, python) to give AI full context
🎨 Rich TUI	Beautiful terminal panels, tables, and interactive prompts
🪝 Bulletproof Hooks	Generates an isolated python runner script to bypass shell environment pollution

---

🚀 Quickstart

1. Install

pip install argus-term

2. Set API Key

export GEMINI_API_KEY="your-key-here"

Get a key at https://aistudio.google.com/app/apikey.

3. Install Shell Hook

argus install-hook
source ~/.zshrc   # or ~/.bashrc

4. Run a Health Check

argus doctor

---

🛠️ Commands

argus fix "<command>" <exit_code>

Manually diagnose a failed command:

argus fix "git pussh origin main" 1

This will:

1. Harvest current OS state (ports, git, processes)
2. Analyze blast radius of the suggested fix
3. Call Gemini 3.6 Flash for diagnosis
4. Display a Rich TUI panel with the explanation
5. Prompt you to execute the fix immediately

argus doctor

Verify all dependencies and configuration:

argus doctor

argus install-hook

Append the shell hook to your rc file:

argus install-hook          # Auto-detects shell
argus install-hook --shell bash
argus install-hook --shell zsh

---

🪝 How Shell Hooks Work

After argus install-hook, your shell calls argus fix automatically after every failed command (exit code ≠ 0). The hook is non-blocking — it only fires when there's an error, and runs in the foreground for interactive diagnosis.

Zsh Hook (.zshrc)

# ArgusTerm hook — auto-appended
source ~/.config/argus/argus.zsh

Bash Hook (.bashrc)

# ArgusTerm hook — auto-appended
source ~/.config/argus/argus.bash

---

📐 Architecture

Shell Failure
     │
     ▼
argus fix "<cmd>" <exit_code>
     │
     ├──► OSHarvester.gather_context()     ← ports, git, processes, files
     │
     ├──► BlastRadiusAnalyzer.analyze()    ← danger level + affected resources
     │
     ├──► Diagnostic Re-run                ← captures stderr silently
     │
     └──► ModelRouter.diagnose()
              │
              ├── Tier 1: Rule Filter      ← typos, missing sudo (instant)
              └── Tier 2: Gemini 3.6 Flash ← structured JSON diagnosis + iterative retry loop

---

⚙️ Configuration

Environment Variable	Purpose	Default
GEMINI_API_KEY	Gemini API key (required)	—
ARGUS_MODEL	Override Gemini model	gemini-3.6-flash
ARGUS_MAX_FILES	Max files to list in context	30
ARGUS_SKIP_GEMINI	Skip cloud calls (rule-only mode)	false

---

📄 License

MIT © ArgusTerm Contributors