Metadata-Version: 2.4
Name: tagent-cli
Version: 0.1.0
Summary: A plain-English terminal agent that plans and runs shell commands for you.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: groq>=0.11.0
Requires-Dist: python-dotenv>=1.0.0

# 🖥️ terminal-agent

**A plain-English terminal agent.** Tell it what you want done — it plans the shell commands, runs them, and adapts based on what happens. No more copy-pasting commands out of a chatbot.

<p align="left">
  <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white" alt="Python 3.10+">
  <img src="https://img.shields.io/badge/LLM-Groq%20%7C%20Llama%203.3-orange?style=flat" alt="Groq Llama 3.3">
  <img src="https://img.shields.io/badge/Platform-WSL%20%7C%20Linux%20%7C%20Windows-blue?style=flat" alt="Cross-platform">
  <img src="https://img.shields.io/badge/License-MIT-green?style=flat" alt="MIT License">
</p>

---

## 📋 Table of Contents

- [Why this exists](#-why-this-exists)
- [How it works](#-how-it-works)
- [Safety model](#-safety-model)
- [Install](#-install)
- [Usage](#-usage)
- [Cross-platform support](#-cross-platform-support)
- [Project structure](#-project-structure)
- [Limitations](#-limitations)
- [Roadmap](#-roadmap)
- [Author](#-author)

---

## 💡 Why this exists

Copy-pasting shell commands out of an LLM chat window into your terminal is slow, breaks your flow, and is easy to get wrong. `terminal-agent` closes that loop:

```
You: "set up docker"
         ↓
Agent proposes a command → you approve (if risky) → it runs → output feeds back
         ↓
Agent decides the next step, or says it's done
```

No copy-paste. No context-switching between a chat tab and your terminal.

## ⚙️ How it works

```
┌─────────────┐      ┌──────────────┐      ┌───────────────┐
│  Your task   │ ───▶ │  agent.py    │ ───▶ │  executor.py  │
│ (plain text) │      │  (asks LLM   │      │  (runs command │
└─────────────┘      │  for next    │      │  safely)       │
                      │  command)    │      └───────┬───────┘
                      └──────▲───────┘              │
                             │        output         │
                             └────────────────────────┘
                          (loops until task is done,
                           or 12-step safety cap is hit)
```

The agent never runs blind — every command passes through a safety classifier before execution.

## 🛡️ Safety model

Every command gets classified into one of three tiers before it runs:

| Tier | Behavior | Example commands |
|---|---|---|
| 🟢 **AUTO** | Runs immediately | `ls`, `cat`, `docker --version`, `dir` |
| 🟡 **CONFIRM** | Asks before running | `sudo`, `rm`, `chmod`, `del`, `git push --force` |
| 🔴 **BLOCKED** | Never runs — no override | `rm -rf /`, `format c:`, fork bombs |

A hard **12-step limit** per task also prevents runaway loops.

## 📦 Install

```bash
git clone https://github.com/AnuragBel/terminal-agent.git
cd terminal-agent
```

Get a free Groq API key → [console.groq.com](https://console.groq.com)

```bash
cp .env.example .env      # then paste your key into .env
```

See [Cross-platform support](#-cross-platform-support) below for OS-specific setup.

## 🚀 Usage

```bash
tagent "check disk usage and list the top 5 largest folders in home"
```

```
Task: check disk usage and list the top 5 largest folders in home

[AUTO] du -h --max-depth=1 ~ | sort -rh | head -5
  reason: list top 5 largest folders by size
/home/user/Downloads    4.2G
/home/user/Projects     1.8G
...

✓ Done — Found and listed the 5 largest folders in your home directory.
```

Auto-approve CONFIRM-tier steps (use with care):
```bash
tagent "install nodejs and check the version" --yes
```

## 🌐 Cross-platform support

The agent auto-detects the OS at runtime and adjusts its command vocabulary and safety patterns accordingly — one codebase, no manual flags needed.

| | WSL Ubuntu | Native Ubuntu | Native Windows |
|---|---|---|---|
| Create venv | `python3 -m venv venv` | `python3 -m venv venv` | `python -m venv venv` |
| Activate | `source venv/bin/activate` | `source venv/bin/activate` | `venv\Scripts\activate` |
| Install | `pip install -e .` | `pip install -e .` | `pip install -e .` |
| Env file | `cp .env.example .env` | `cp .env.example .env` | `copy .env.example .env` |
| Agent proposes | `df -h`, `ls` | `df -h`, `ls` | `dir`, `wmic` |

> Each environment needs its own `venv/` and `.env` — these aren't shared across OSes.

## 🗂️ Project structure

```
terminal-agent/
├── terminal_agent/
│   ├── __init__.py
│   ├── agent.py       # LLM decision loop + OS auto-detection
│   ├── executor.py     # 3-tier safety-gated command execution
│   └── cli.py          # tagent entry point
├── pyproject.toml       # pip-installable packaging
├── .env.example
└── README.md
```

## ⚠️ Limitations

- Requires an internet connection (cloud LLM via Groq — no local model support yet)
- CONFIRM/BLOCKED detection is pattern-based, not exhaustive — always read a command before approving it
- Tested primarily on WSL2 Ubuntu; native Windows and native Ubuntu support is newer and less battle-tested

## 🗺️ Roadmap

- [ ] `--dry-run` flag to preview the full plan before executing anything
- [ ] Docker sandbox mode for isolated execution
- [ ] Local model support via Ollama
- [ ] `--platform` override flag for edge cases (e.g. WSL running Windows-style commands)

## 👤 Author

**Anurag Belgudri** — Agentic AI Engineer Intern @ Entra Innovation
[GitHub](https://github.com/AnuragBel) · [LinkedIn](https://linkedin.com/in/anuragbelgudri)

---

<p align="center"><i>Built as a hands-on exploration of agentic AI systems — LLM decision loops, tool use, and safety-first automation.</i></p>
