🖥️ 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.

📋 Table of Contents

• Why this exists
• How it works
• Safety model
• Install
• Usage
• Cross-platform support
• Project structure
• Limitations
• Roadmap
• 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:

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

📦 Install

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

Get a free Groq API key → console.groq.com

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

See Cross-platform support below for OS-specific setup.

🚀 Usage

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):

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.

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 · LinkedIn

Built as a hands-on exploration of agentic AI systems — LLM decision loops, tool use, and safety-first automation.