🖥️ Alan – AI Terminal Command Assistant

Alan turns natural-language requests into safe, executable shell commands. It runs locally against Ollama by default and falls back to cloud LLM providers (OpenRouter, OpenAI, Anthropic) when an API key is configured.

alan please list all Python files

🚀 Features

• Natural language → shell commands (e.g. alan please list directory files → ls)
• Fix failed commands — alan fix feeds the last failed command and its error output to the LLM and proposes a corrected command
• Multiple LLM backends — local Ollama first, with OpenRouter / OpenAI / Anthropic fallback
• Safety checks — refuses dangerous commands (e.g. rm -rf /) and confirms before executing
• Smart command tracking — learns from accepted/rejected suggestions and scores confidence
• Command statistics via alan stats
• Cross-platform — detects macOS, Linux (apt/yum/dnf/pacman/zypper), and Windows
• Clipboard support via alan copy
• Additional modules included in the package: MCP server, speech-to-text / wake-word, daemon mode, and plugins

📦 Requirements

• Python 3.8+
• For local inference: Ollama installed and running, with at least one model pulled (default qwen2.5:0.5b):

  brew install ollama        # or see https://ollama.ai for other platforms
  ollama serve
  ollama pull qwen2.5:0.5b
  

• OR a cloud provider API key (no Ollama required): set one of OPENROUTER_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY.

Core Python dependencies (rich, colorama, pydantic, schedule, requests) are installed automatically by pip.

📥 Install (users)

pip install alan-terminal-ai

Optional provider/feature extras:

pip install "alan-terminal-ai[openrouter]"   # OpenRouter
pip install "alan-terminal-ai[openai]"       # OpenAI
pip install "alan-terminal-ai[anthropic]"    # Anthropic
pip install "alan-terminal-ai[mcp]"          # MCP server
pip install "alan-terminal-ai[stt]"          # speech-to-text + wake word
pip install "alan-terminal-ai[all]"          # everything optional

Verify the install:

alan --version
alan status        # shows which LLM backend is active

🛠️ Development setup (contributors)

If you want to work on Alan itself:

# 1. Clone
git clone https://github.com/ankit0305/alan-terminal-ai.git
cd alan-terminal-ai

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. Editable install with dev tools
pip install -e ".[dev]"

# 4. (Recommended) install git hooks
pre-commit install

Running tests

pytest

Tests live in tests/. The default pytest config (in pyproject.toml) runs with coverage enabled.

Linting & formatting

The repo is configured for black, isort, flake8, and mypy (line length 100):

black .
isort .
flake8
mypy alanterminalai

These also run automatically via pre-commit if you installed the hooks.

💡 Usage

alan please [your request]

Examples

alan please list all Python files
alan please find files modified today
alan please count lines in all py files
alan please show disk usage
alan please check running processes

For each request Alan suggests a command, runs safety checks, shows confidence based on your history, and asks for confirmation before executing.

📜 Commands

alan please [request]   # Get and run a command suggestion
alan fix                # Fix the last failed command Alan executed
alan fix [command]      # Run a command; if it fails, suggest a fix
alan copy               # Copy the last command/output to clipboard
alan stats              # Show command tracking statistics
alan status             # Show available and active LLM backends
alan --help             # Show help
alan --version          # Show version

Fixing failed commands

When a command executed through Alan fails, run alan fix to get a corrected version — Alan sends the failed command, its exit code, and its error output to the LLM and proposes a fix (with the usual safety check and confirmation).

You can also hand it any failing command directly:

alan fix gti status     # runs it, sees "command not found: gti",
                        # suggests: git status

The last run is recorded in ~/.alan/last_run.json, and each executed fix becomes the new "last command", so you can run alan fix repeatedly to iterate until it works.

🔀 LLM backend selection

Alan tries backends in this order:

1. Ollama (local, default model qwen2.5:0.5b) — used if Ollama is running.
2. Cloud fallback — if Ollama is unavailable, Alan uses the first configured cloud provider. Set one of:

   export OPENROUTER_API_KEY=...
   export OPENAI_API_KEY=...
   export ANTHROPIC_API_KEY=...
   

Run alan status to see which backends are available and which one is active.

🧠 Smart Learning & Tracking

Alan tracks command preferences to improve future suggestions:

• Acceptance/rejection tracking — learns which commands you accept or reject
• Confidence scoring — shows confidence levels based on your history
• Similar command suggestions — surfaces previously accepted similar commands
• Usage statistics — most-used command types and success rates

View your statistics with alan stats. History is stored in ~/.alan/command_history.json.

🧩 Configuration

Create ~/.alan_config.json to customize behavior:

{
  "tracking": {
    "enabled": true,
    "show_confidence": true,
    "show_similar_commands": true
  },
  "display": {
    "show_system_info": true,
    "use_emojis": true,
    "verbose_output": false
  },
  "safety": {
    "enable_safety_checks": true,
    "prompt_for_dangerous_commands": true
  }
}

⚠️ Safety

Alan will:

• Reject known-dangerous commands (e.g. rm -rf /)
• Display the suggested command first
• Ask for confirmation before running anything

You can review and modify the command before it runs.

📚 Documentation

Additional documentation lives in the docs/ folder:

• TERMINAL_USAGE_EXAMPLES.md — real-world CLI usage examples
• TESTING.md — testing guide
• PUBLISHING_GUIDE.md / QUICK_PUBLISH.md — releasing to PyPI
• IMPLEMENTATION.md — feature implementation notes

🤝 Contributing

Contributions are welcome. Fork the repo, create a feature branch, run the tests and linters (pytest, pre-commit run --all-files), and open a pull request against main.

• Issues: https://github.com/ankit0305/alan-terminal-ai/issues
• Repository: https://github.com/ankit0305/alan-terminal-ai

📄 License

See LICENSE.