CAIROS

CAIROS - Context-Aware Intelligent Runtime Operating Shell

CAIROS is a context-aware console assistant that lives inside your normal shell. It is useful offline through deterministic templates, and can use AI as a fallback when configured.

Package/distribution name: cairos-shell
Terminal command: cairos
GitHub repo: Saltybukket/cairos

Quickstart

Install from GitHub:

pipx install git+https://github.com/Saltybukket/cairos.git
cairos quicksetup

Use from any project:

cd ~/projects/my_repo
cairos doctor
cairos context
cairos check if repo is ready to commit

Optional AI quickstart:

export OPENROUTER_API_KEY="your-key"
cairos config ai use-openrouter-free
cairos config ai test

Windows users should run:

py -m pip install --user pipx
py -m pipx ensurepath
pipx install git+https://github.com/Saltybukket/cairos.git
cairos quicksetup

PyPI-Ready Install

There is no PyPI release yet. The repository is prepared for PyPI Trusted Publishing; after the first release is published, installation will be:

pipx install cairos-shell

Development Install

git clone https://github.com/Saltybukket/cairos.git
cd cairos
pipx install --editable .
cairos install-info

Everyday Use

cairos
cairos templates
cairos gui --check
cairos gui
cairos templates system
cairos plan create cpp mini project engine with class Player and main
cairos plan list wsl distros
cairos plan open project in vscode
cairos run create folder docs

Direct cairos <task> prints a plan. Use cairos run <task> to execute after confirmation.

Optional Local Web GUI

Install the optional GUI dependencies, then launch a localhost-only dashboard:

pipx inject cairos-shell fastapi uvicorn jinja2 python-multipart
cairos gui --check
cairos gui

For editable development installs:

python -m pip install -e ".[gui,dev]"

The GUI shows config paths, AI profiles, provider setup, fallback settings, doctor output, and update/backup guidance. It binds locally, uses a temporary session token for state-changing POST requests, and hides raw API keys unless you explicitly use a reveal action.

Templates vs AI

Simple, clear commands use offline deterministic templates. Longer fuzzy requests are scored for confidence; low-confidence templates step back so AI fallback can handle the request when configured. Every template or AI plan is still safety-scanned before display or execution.

Debug routing decisions with:

cairos plan --debug-route <task>

CAIROS cannot permanently change the parent shell directory from a child process. Use cairos find-dir <name> or a shell wrapper from Shell Navigation for cd workflows.

Update

cairos update
cairos backup-config

GitHub installs are updated with the command printed by cairos update. Config, history and AI profiles live outside the package install and are preserved across package upgrades.

AI Profiles

Save multiple providers/models and switch quickly. Full provider setup lives in AI Providers.

cairos config ai use-openrouter-free
cairos config ai profiles
cairos config ai switch

Automatic profile fallback is enabled by default. If the active profile is rate-limited, out of credits, temporarily unavailable, missing a visible key, or points at an unavailable model, CAIROS tries another saved profile and prints a notice before the plan:

cairos config ai fallback status
cairos config ai fallback disable
cairos config ai fallback enable
cairos config ai fallback order openrouter-free gemini-flash groq-llama

CAIROS stores environment variable names, never raw API keys.

Generate shell-specific key setup commands:

cairos config ai key commands OPENROUTER_API_KEY --shell bash
cairos config ai key commands OPENROUTER_API_KEY --shell powershell
cairos config ai key status OPENROUTER_API_KEY

Reveal commands print secrets only when explicitly requested:

cairos config ai key reveal OPENROUTER_API_KEY

Key Locations

Global config lives in ~/.config/cairos/config.json on Linux/macOS/WSL and %APPDATA%\cairos\config.json on Windows. History lives in ~/.local/state/cairos/history.jsonl or %LOCALAPPDATA%\cairos\history.jsonl. Optional project-local rules live in .cairos/rules.json.

Documentation

• Quickstart
• User Guide
• AI Setup
• AI Providers
• Local Web GUI
• Windows Guide
• Shell Navigation
• Request Router
• AI Troubleshooting
• Updating
• Safety
• Release Guide
• Developer Guide
• Troubleshooting
• Changelog