askshell-ai 0.3.0
用自然语言操控你的终端 - 让 AI 帮你生成并执行 Shell 命令
License: MIT
Requires Python: >=3.7
Keywords: shell, ai, cli, terminal, natural-language

# Ask-Shell

<p align="center">
  <img src="ask-shell-logo.jpg" alt="Ask-Shell Logo" width="600"/>
  <br/>
  <sub>Logo generated by Google Gemini</sub>
</p>

<p align="center">
  <strong><em>🤖 Your AI Task Automation Agent - Not Just Command Generator!</em></strong>
</p>

<p align="center">
  <strong>Describe complex tasks in plain language, and let AI execute them step-by-step until completion</strong>
</p>

<p align="center">
  <em>Multi-step execution • Auto-retry on failure • Real-time thinking display</em>
</p>

[![PyPI version](https://img.shields.io/pypi/v/askshell-ai.svg)](https://pypi.org/project/askshell-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://fssqawj.github.io/ask-shell/)

---

<p align="center">
  📖 <strong><a href="https://fssqawj.github.io/ask-shell/">Complete Documentation</a></strong> | 
  <a href="https://fssqawj.github.io/ask-shell/getting-started/quick-start/">Quick Start</a> | 
  <a href="https://fssqawj.github.io/ask-shell/user-guide/examples/">Examples</a> | 
  <a href="https://fssqawj.github.io/ask-shell/api/agent/">API Reference</a>
</p>

---

<div align="center">

### 🌟 What Makes Ask-Shell Special?

**Not Just a Command Generator - A True Task Automation Agent!**

<table>
<tr>
<td align="center">🔄</td>
<td><strong>Executes multi-step tasks</strong><br/>from start to finish</td>
<td align="center">🧠</td>
<td><strong>Learns from failures</strong><br/>and automatically retries</td>
</tr>
<tr>
<td align="center">💭</td>
<td><strong>Shows its thinking</strong><br/>in real-time for transparency</td>
<td align="center">✅</td>
<td><strong>Doesn't stop</strong><br/>until your task is complete</td>
</tr>
</table>

</div>

---

[中文](README_zh.md) | English

Ask-Shell is an **AI-powered task automation agent** that goes beyond simple command generation. Unlike tools that only translate queries into commands, Ask-Shell **executes multi-step tasks**, **learns from failures**, and **adapts its strategy** until completion.

## 🎯 Why Ask-Shell?

| Other Tools | Ask-Shell |
|------------|-----------|
| Generate ONE command → Done | Execute MULTIPLE steps → Analyze → Adjust → Complete |
| "Here's your command, run it yourself" | "I'll keep working until it's done" |
| Fails? You figure it out | Fails? AI analyzes, retries, finds alternatives |

**Example**: `"Organize my project files"`
```
Other tools: ls -la  # Just one command, you do the rest

Ask-Shell:  Step 1: Analyze directory structure
            Step 2: Create organized folders
            Step 3: Move files to appropriate locations
            Step 4: Verify organization
            ✓ Task complete!
```

## 🎬 Demo

![browser-demo](https://github.com/user-attachments/assets/717ce22f-084a-4081-8ad0-ae23f7daf0ff)

<p align="center"><em>Demo 1: Using ask-shell to control terminal with natural language</em></p>

![ask-shell-demo](https://github.com/user-attachments/assets/8721876f-92dc-4762-a03d-64d845546de0)

<p align="center"><em>Demo 2: Using ask-shell to control terminal with natural language</em></p>

Ask-Shell provides a beautiful terminal interface with real-time feedback:

- 💭 **Real-time Thinking Process** - See AI's thought process
- ⚙️ **Command Execution Animation** - Dynamic loading effects during command execution
- ✨ **Syntax Highlighting** - Generated commands with syntax highlighting
- 📊 **Structured Output** - Clear panels and icon displays
- 🎯 **Interactive Confirmation** - Dangerous operations with clear warning indicators

## 🚀 Quick Start

### Installation

#### Method 1: Development Mode (Recommended)

```bash
# Clone the repository
git clone https://github.com/fssqawj/ask-shell.git
cd ask-shell

# Install in development mode (can use ask-shell or ask command directly)
pip install -e .
```

#### Method 2: Install from PyPI

```bash
pip install askshell-ai
```

#### Method 3: Install Dependencies Only

```bash
pip install -r requirements.txt
```

### Configure API Key

1. Copy the environment variable template:
```bash
cp .env.example .env
```

2. Edit the `.env` file and fill in your OpenAI API Key:
```bash
OPENAI_API_KEY=your-api-key-here
```

## 💡 Usage

### After Installation (Recommended)

If you installed with `pip install -e .` or `pip install askshell-ai`, you can use commands directly:

```bash
# Use ask-shell command
ask-shell "list all Python files in current directory"

# Or use the shorter ask command
ask "list all Python files in current directory"

# Interactive mode
ask -i

# Demo mode (no API Key required)
ask -d "create a test folder"

# Auto execution mode (no confirmation needed for each command)
ask -a "count lines of code in current directory"

# Specify working directory
ask -w /path/to/dir "your task"
```

### Direct Run (Without Installation)

```bash
# Single task execution
python ask_shell/cli.py "list all Python files in current directory"

# Interactive mode
python ask_shell/cli.py -i

# Demo mode (no API Key required)
python ask_shell/cli.py -d "create a test folder"

# Auto execution mode
python ask_shell/cli.py -a "count lines of code in current directory"

# Specify working directory
python ask_shell/cli.py -w /path/to/dir "your task"
```

### Examples

The following examples work with both `ask` command and `python ask_shell/cli.py`:

#### **Simple Tasks** (Like other tools)
```bash
# File operations
ask "find all files larger than 1MB"
ask "list all running Python processes"
```

#### **Complex Multi-Step Tasks** (Where Ask-Shell shines!)
```bash
# Project organization - Multiple steps executed automatically
ask "organize this project: create docs, tests, and src folders, then move files accordingly"

# Environment setup - Handles errors and retries
ask "set up a Python virtual environment and install dependencies from requirements.txt"

# Git workflow - Complete task automation
ask "commit all changes with meaningful message, then push to origin"

# System maintenance - Intelligent execution
ask "find and compress all log files older than 7 days"

# Development tasks - Multi-step coordination
ask "find all TODO comments in Python files and create a summary file"
```

#### **Browser & System Operations**
```bash
# Browser operations
ask "open GitHub in default browser"
ask "open Google and search for Python tutorial"

# System information
ask "check system memory usage"
ask "show disk usage for all mounted drives"
```

#### **More Examples**
```bash
# Text processing with verification
ask "count total lines of all .py files"
ask "search for lines containing 'error' in all .txt files"

# Backup operations
ask "create a timestamped backup of this directory"
```

**💡 Pro Tip**: The more complex your task, the more Ask-Shell's advantages shine compared to simple command generators!

### Interactive Mode

```bash
ask -i
# or
python ask_shell/cli.py -i
```

In interactive mode, you can continuously input tasks:
```
Ask-Shell > list files in current directory
Ask-Shell > create a test file
Ask-Shell > exit  # Exit
```

## 📁 Project Structure

```
ask-shell/
├── ask_shell/           # Core code
│   ├── agent.py        # Task automation agent with intelligent loop
│   ├── executor/       # Command executor with safety checks
│   ├── llm/            # LLM client with context management
│   ├── models/         # Data models
│   └── ui/             # Beautiful terminal interface
├── requirements.txt    # Dependencies
└── .env.example        # Environment variable template
```

## 🆚 Comparison with Other Tools

| Feature | Shell-GPT | Aichat | Warp AI | **Ask-Shell** |
|---------|-----------|--------|---------|---------------|
| **Multi-step task execution** | ❌ | ❌ | ⚠️ Limited | ✅ **Full support** |
| **Auto-retry on failure** | ❌ | ❌ | ❌ | ✅ **Yes** |
| **Task context awareness** | ❌ | Partial | Partial | ✅ **Full context** |
| **Real-time thinking display** | ❌ | ❌ | ⚠️ Basic | ✅ **Streaming** |
| **Execution loop** | ❌ Single-shot | ❌ Chat only | ⚠️ Limited | ✅ **Until completion** |
| **Error analysis** | ❌ Manual | ❌ Manual | ⚠️ Basic | ✅ **Automatic** |
| **Dangerous operation detection** | ⚠️ Basic | ⚠️ Basic | ✅ Yes | ✅ **Dual-layer** |
| **Browser automation** | ❌ | ❌ | ❌ | ✅ **Built-in** |
| **File generation** | ❌ | ❌ | ❌ | ✅ **PPT, Images, etc.** |
| **Open source** | ✅ Python | ✅ Rust | ❌ Closed | ✅ **Python** |
| **Easy to extend** | ⚠️ | ⚠️ | ❌ | ✅ **Plugin-ready** |

### What Makes Ask-Shell Different?

**Shell-GPT / sgpt**: Great for quick command translation, but stops after generating one command.  
**Aichat**: Powerful chat interface with many features, but not task-focused.  
**Warp Terminal**: Modern terminal with AI features, but closed-source and requires full terminal replacement.  
**Ask-Shell**: ✨ **Focused on autonomous task completion** - keeps executing until your task is actually done.

### Advanced Capabilities

**Browser Automation**: Built-in Playwright integration for web automation tasks.
**File Generation**: Generate PPTs, images, and other files directly from natural language.
**Extensible Skills**: Plugin-ready architecture for adding new capabilities.

## ⚙️ Configuration Options

### Environment Variables

You can configure the following options in the `.env` file:

```bash
# OpenAI API Key (required)
OPENAI_API_KEY=your-api-key-here

# Custom API URL (optional, for compatible APIs)
OPENAI_API_BASE=https://api.openai.com/v1

# Model name (optional, default: gpt-4)
MODEL_NAME=gpt-4
```

### Command Line Arguments

- `task` - Task description to execute
- `-i, --interactive` - Interactive mode
- `-a, --auto` - Auto execution mode (no confirmation needed)
- `-d, --demo` - Demo mode (no API Key required)
- `-w, --workdir` - Specify working directory

## 🔒 Safety Features

Ask-Shell takes safety seriously with multiple protection layers:

### 🛡️ Dual-Layer Protection

1. **AI-Powered Detection** - GPT-4 analyzes commands for potential dangers
   - Understands context and intent
   - Explains WHY a command is dangerous
   - Catches subtle risks that pattern matching misses

2. **Built-in Blacklist** - Hardcoded protection against catastrophic commands
   - `rm -rf /` and variants
   - Direct disk operations
   - System file modifications
   - Fork bombs and malicious patterns

### ✋ User Control

3. **Interactive Confirmation** - You always have the final say
   - Clear danger warnings with explanations
   - Edit commands before execution
   - Skip commands you don't trust
   - Quit anytime

4. **Transparency** - Know exactly what's happening
   - See AI's reasoning process
   - Review commands before execution
   - Understand potential risks

**Safety Philosophy**: "Trust, but verify" - Give AI autonomy, but keep humans in control of critical decisions.

## 🛠️ Tech Stack

- **Python 3.7+** - Easy to understand and extend
- **OpenAI API** - GPT-4 model (extensible to other LLMs)
- **Rich** - Beautiful terminal output with streaming support
- **python-dotenv** - Environment variable management

### Architecture Highlights

- **Agent Loop Pattern**: Continuous task execution with feedback integration
- **Context Management**: Full conversation history with result tracking
- **Modular Design**: Easy to add new LLM providers, executors, or UI components
- **Safety-First**: Dual-layer protection (AI + blacklist)

## 🗺️ Roadmap

- [ ] Support for multiple LLM providers (Claude, Gemini, Ollama)
- [ ] Task history and replay functionality
- [ ] Plugin system for custom commands
- [ ] Task templates library
- [ ] Web UI interface
- [ ] Team collaboration features

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Issues and Pull Requests are welcome!