# aio - AI Terminal Assistant

An intelligent terminal command assistant powered by LiteLLM and OpenRouter. Get instant help with shell commands, log analysis, and file operations directly in your terminal.

## Features

- 🤖 **Smart Command Generation**: Get exactly the commands you need, with explanations
- 📊 **Log Analysis**: Pipe logs, errors, or any text for instant analysis
- 🔄 **Interactive Mode**: Execute suggested commands with a single keypress
- 📁 **File Support**: Analyze files directly with `-f` flag
- 🎯 **Minimal & Focused**: Generates one command by default, up to 3 for complex tasks
- 🔒 **Output Truncation**: Automatically manages context to prevent token overflow

## Installation

```bash
# Install from PyPI
pip install aio-shell

# Or install from source
cd /path/to/aio
pip install -e .
```

## Configuration

Configure API keys according to your LLM provider. See [LiteLLM documentation](https://docs.litellm.ai/docs/providers) for provider-specific setup.

**Common examples:**

OpenAI:
```bash
export OPENAI_API_KEY="sk-..."
```

OpenRouter:
```bash
export OPENROUTER_API_KEY="sk-or-v1-..."
```

Anthropic:
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

Optionally set a default model:
```bash
export AIO_MODEL_NAME="openrouter/anthropic/claude-sonnet-4.5"
```

## Usage

### Basic Usage

```bash
# Interactive mode - generates commands for actionable tasks
aio "give me the biggest file in the current directory"

# With file input (stays interactive)
aio -f error.log "extract and count unique errors"

# Piped input (auto non-interactive) - provides direct analysis
cat error.log | aio "explain these errors to me"

# No question - auto-summarizes
aio -f config.yaml
```

**Key difference:** Piping automatically triggers non-interactive mode and exits after response. Use `-f` to maintain interactive session.

### Interactive Mode

**Safety:** Commands are NEVER auto-executed. You must type the number to confirm.

```bash
aio "find python files modified today"
# AI responds with numbered commands:
#   1: find . -name "*.py" -mtime -1

> 1  # Type number to execute
# Output shown to you and sent back to AI for analysis

> /reset  # Clear conversation history
```

**Exit:** Press `Ctrl+C` twice (within 2 seconds).

### Options

- `-m, --model MODEL`: Specify model (default: env AIO_MODEL_NAME or openrouter/anthropic/claude-sonnet-4.5)
- `-f, --file FILE`: Read input from file (preferred over piping - keeps interactive mode)
- `-n, --lines N`: Max preview lines for buffers (default: 50 for input, 256 for output)
- `-c, --chars N`: Max preview characters for buffers (default: 2000 for input, 4096 for output)
- `-e, --exec`: Force exec mode (one-shot, non-interactive)
- `-d, --dry-run`: Show API call parameters without executing

## Examples

### Tasks → Commands Generated

```bash
# System tasks - generates executable commands
aio "give me the biggest file in the current directory"
aio "find all python files modified today"
aio "show me disk usage by directory"

# File operations - generates processing commands
aio "find and compress all jpg files larger than 10MB from last week"
aio -f data.json "pretty print this json"

# Text processing - generates transformation commands
cat data.csv | aio "convert to JSON format"
aio -f error.log "extract and count unique errors"
```

### Analysis → Direct Answers

```bash
# Explains provided content
cat error.log | aio "explain these errors to me"
git diff | aio "review this change"
docker logs app | aio "why did this crash?"

# Summarizes when no question provided
aio -f /var/log/app.log
cat config.yaml | aio

# Conceptual questions
aio "what is a race condition?"
aio "why might my application be slow?"
```

## How It Works

1. **Input**: Text via stdin (piped), file (`-f`), or direct instruction
2. **Mode**: Piping auto-triggers non-interactive; `-f` stays interactive
3. **Smart Response**:
   - **Actionable tasks** (find, show, convert) → Generates bash commands
   - **Analysis requests** on provided content → Direct answers
   - **No question** → Summarizes content
4. **Execution**: You manually run commands by typing their number (interactive mode only)
5. **Truncation**: Inputs/outputs truncated for token efficiency (configurable via `-n`/`-c`)

## Buffer Management

- **Input**: Defaults to 50 lines / 2000 chars (adjust with `-n`/`-c`)
- **Output**: You see full output; AI gets truncated version (256 lines / 4096 chars)
- **Tip**: Use `-f` instead of piping to stay in interactive mode

## Command Format

```bash
# Explanation of what this does
command --with arguments
```

Commands include explanations and are executed exactly as shown when you type their number.

## Best Practices

- **Be specific**: "find large files" → "find files larger than 100MB in /var"
- **Use `-f` over piping**: Keeps interactive mode for follow-up questions
- **Action verbs for commands**: "show", "find", "convert" → generates commands
- **Analysis language for explanations**: "explain", "why", "summarize" → direct answers
- **Review before executing**: Commands require your confirmation

## Troubleshooting

**Commands not generated?** Use action verbs: "give me", "show me", "find", "convert"

**Output too long?** Adjust with `-n` and `-c` flags, or pipe through `head`/`tail`

**API errors?** Check your API key is set and has credits; try different model with `-m`

## License

MIT

## Contributing

Contributions welcome! Feel free to open issues or submit pull requests.
