🔍 ArgusTerm

An OS-aware AI terminal copilot. ArgusTerm watches your shell for failed commands, harvests OS state, analyzes blast radius, and uses Gemini 2.5 Flash to suggest fixes — all before you can blink.

---

✨ 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
🧠 Two-Tier Diagnosis	Instant rule-based fixes for typos, cloud-escalated Gemini for complex errors
🎨 Rich TUI	Beautiful terminal panels, tables, and interactive prompts
🪝 Shell Hooks	Non-blocking Zsh/Bash hooks that trigger automatically on failure

---

🚀 Quickstart

1. Install

git clone https://github.com/argus-term/argus-term
cd argus-term
pip install -e .

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 2.5 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
     │
     └──► ModelRouter.diagnose()
              │
              ├── Tier 1: Rule Filter      ← typos, missing sudo (instant)
              └── Tier 2: Gemini 2.5 Flash ← structured JSON diagnosis

---

⚙️ Configuration

Environment Variable	Purpose	Default
GEMINI_API_KEY	Gemini API key (required)	—
ARGUS_MODEL	Override Gemini model	gemini-2.5-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