Metadata-Version: 2.4
Name: cairos-shell
Version: 0.5.0a3
Summary: Context-aware AI-assisted shell command planner and safety layer
Author: CAIROS Developer
License-Expression: MIT
Project-URL: Homepage, https://github.com/Saltybukket/cairos
Project-URL: Documentation, https://github.com/Saltybukket/cairos#readme
Project-URL: Repository, https://github.com/Saltybukket/cairos
Project-URL: Issues, https://github.com/Saltybukket/cairos/issues
Project-URL: Source, https://github.com/Saltybukket/cairos
Project-URL: Changelog, https://github.com/Saltybukket/cairos/blob/main/CHANGELOG.md
Keywords: cli,shell,terminal,assistant,ai,developer-tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Shells
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: httpx2; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: ml-router
Requires-Dist: scikit-learn>=1.4; extra == "ml-router"
Requires-Dist: joblib>=1.3; extra == "ml-router"
Provides-Extra: gui
Requires-Dist: fastapi; extra == "gui"
Requires-Dist: uvicorn; extra == "gui"
Requires-Dist: jinja2; extra == "gui"
Requires-Dist: python-multipart; extra == "gui"
Dynamic: license-file

# 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:

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

Use from any project:

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

Optional AI quickstart:

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

Windows users should run:

```powershell
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:

```bash
pipx install cairos-shell
```

## Development Install

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

## Everyday Use

```bash
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:

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

For editable development installs:

```bash
python -m pip install -e ".[gui]"
```

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 never displays raw API keys.

## 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:

```bash
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](docs/SHELL_NAVIGATION.md) for `cd` workflows.

## Update

```bash
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](docs/AI_PROVIDERS.md).

```bash
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:

```bash
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.

## 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](docs/QUICKSTART.md)
- [User Guide](docs/USER_GUIDE.md)
- [AI Setup](docs/AI_SETUP.md)
- [AI Providers](docs/AI_PROVIDERS.md)
- [Local Web GUI](docs/GUI.md)
- [Windows Guide](docs/WINDOWS.md)
- [Shell Navigation](docs/SHELL_NAVIGATION.md)
- [Request Router](docs/ROUTER.md)
- [AI Troubleshooting](docs/TROUBLESHOOTING_AI.md)
- [Updating](docs/UPDATING.md)
- [Safety](docs/SAFETY.md)
- [Release Guide](docs/RELEASE.md)
- [Developer Guide](docs/DEVELOPER.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Changelog](CHANGELOG.md)
