🖥️ 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 fixfeeds 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, orANTHROPIC_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:
- Ollama (local, default model
qwen2.5:0.5b) — used if Ollama is running. - 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 examplesTESTING.md— testing guidePUBLISHING_GUIDE.md/QUICK_PUBLISH.md— releasing to PyPIIMPLEMENTATION.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.
Metadata
Release files for alan-terminal-ai 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| alan_terminal_ai-0.4.0.tar.gz | 54.0 kB | Without provenance | Details for alan_terminal_ai-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| alan_terminal_ai-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for alan_terminal_ai-0.4.0-py3-none-any.whl |
Total release size: 117.1 kB
Release files / alan_terminal_ai-0.4.0.tar.gz
| Download URL | alan_terminal_ai-0.4.0.tar.gz |
|---|---|
| Size | 54.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c227430bc6c8e11b092daeadb3422713deda1373a0ecfff83c5f7118b87efbd
|
|
BLAKE2b-256 checksum How to use checksums |
da7e16e8d82708164eed4567bc992ad32f4a6d6429f01d523cc6133e03dd1050
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / alan_terminal_ai-0.4.0-py3-none-any.whl
| Download URL | alan_terminal_ai-0.4.0-py3-none-any.whl |
|---|---|
| Size | 63.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f93e96484421a46204505d7bbea98d5bde3783577c09bdb6429d61140ddf170
|
|
BLAKE2b-256 checksum How to use checksums |
0b15cc0df6ef823f22cfbf92433615009225d7095fd36d596cdb83e7aecb6a4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for alan-terminal-ai 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.