Metadata-Version: 2.5
Name: argus-term
Version: 0.1.2
Summary: An OS-aware AI terminal copilot powered by Gemini 3.6 Flash.
Project-URL: Homepage, https://github.com/argus-term/argus-term
Project-URL: Repository, https://github.com/argus-term/argus-term
Author: ArgusTerm Contributors
License: MIT
Keywords: ai,copilot,devtools,gemini,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: google-genai>=1.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# 🔍 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.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![Powered by Gemini](https://img.shields.io/badge/powered%20by-Gemini%203.6%20Flash-4285f4.svg)](https://ai.google.dev)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## ✨ 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

```bash
pip install argus-term
```

### 2. Set API Key

```bash
export GEMINI_API_KEY="your-key-here"
```
Get a key at [https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey).

### 3. Install Shell Hook

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

### 4. Run a Health Check

```bash
argus doctor
```

---

## 🛠️ Commands

### `argus fix "<command>" <exit_code>`

Manually diagnose a failed command:

```bash
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:

```bash
argus doctor
```

### `argus install-hook`

Append the shell hook to your rc file:

```bash
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`)

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

### Bash Hook (`.bashrc`)

```bash
# 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
