Metadata-Version: 2.4
Name: prometheus-cli
Version: 0.1.6
Summary: PrometheUS — autonomous terminal assistant. Free out of the box across 9 model providers with cross-provider failover, /escalate when you need premium horsepower, ships a public 280-test audit with every release.
Author: PrometheUS Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/prometheus-cli/prometheus
Project-URL: Repository, https://github.com/prometheus-cli/prometheus
Project-URL: Issues, https://github.com/prometheus-cli/prometheus/issues
Project-URL: Changelog, https://github.com/prometheus-cli/prometheus/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/prometheus-cli/prometheus#readme
Keywords: ai,agent,tui,terminal,coding-assistant,textual,openrouter,anthropic,claude,mcp,voice,playwright,audit,byok
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: textual>=0.79
Requires-Dist: rich>=13.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: platformdirs>=4.2
Provides-Extra: voice
Requires-Dist: sounddevice>=0.4.6; extra == "voice"
Requires-Dist: numpy>=1.24; extra == "voice"
Requires-Dist: faster-whisper>=1.0; extra == "voice"
Provides-Extra: escalate
Requires-Dist: anthropic>=0.50; extra == "escalate"
Provides-Extra: recipes
Requires-Dist: PyYAML>=6.0; extra == "recipes"
Provides-Extra: visual
Requires-Dist: playwright>=1.40; extra == "visual"
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Provides-Extra: all
Requires-Dist: sounddevice>=0.4.6; extra == "all"
Requires-Dist: numpy>=1.24; extra == "all"
Requires-Dist: faster-whisper>=1.0; extra == "all"
Requires-Dist: anthropic>=0.50; extra == "all"
Requires-Dist: PyYAML>=6.0; extra == "all"
Requires-Dist: playwright>=1.40; extra == "all"
Dynamic: license-file

# PrometheUS

[![PyPI version](https://img.shields.io/pypi/v/prometheus-cli.svg)](https://pypi.org/project/prometheus-cli/)
[![CI](https://github.com/prometheus-cli/prometheus/actions/workflows/ci.yml/badge.svg)](https://github.com/prometheus-cli/prometheus/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/prometheus-cli.svg)](https://pypi.org/project/prometheus-cli/)

**PrometheUS is the autonomous terminal assistant: 120,000+ free requests per day across 9 model providers, transparent failover when one provider hiccups, opt-in `/escalate` to premium engines only when you ask. Read code, edit files, run shells, browse the web, paste images — all from one TUI.**

## Why PrometheUS

- **120,000+ requests/day at $0.** Cross-provider key pool with automatic failover (OpenRouter → Groq → Gemini → Cerebras → Mistral → Pollinations → …) on rate limits, 5xx errors, transport failures, and even empty 200 responses. Run it 24/7 without a credit card.
- **Frontier free models**: Kimi K2.6, GLM-5.1, MiniMax M2.5, DeepSeek V4-Pro, Qwen3-Coder, Llama 4, and 8 more — all `:free` tier on OpenRouter, hot-swapped per turn.
- **Optional `/escalate`** routes a single turn through your own Anthropic key when a problem genuinely needs more horsepower. Daily USD cap is hard-enforced — never a surprise bill.
- **Brand-neutral**: PrometheUS, every step. Vendor names appear only in `/provider` (where you set keys) — never in chat output, never in errors.
- **288-test audit suite** ships with every release. `prometheus --audit` runs the full thing locally.
- **Claude-Code parity** for the workflow patterns that matter: `⏺` tool receipts, `⎿` continuation, TodoWrite tracker, Plan mode (Shift+Tab), `/resume`, atomic edits with read-before-edit guard, post-write syntax verification, parallel-dispatch reads, stuck-loop detector.
- **Custom subagents**: drop a `.prometheus/agents/<name>.md` file with frontmatter (`tools:`, `permission_mode:`, system-prompt body) and the model can spawn it via `task(subagent_type=<name>)`. See [docs/CUSTOM_AGENTS.md](docs/CUSTOM_AGENTS.md) for the full schema and examples.
- **Backgrounded shells**: long-running commands (`run_in_background: true`) keep working while the agent does other things — model polls via `bash_output` or kills with `kill_shell`. `/bashes` to list/manage from the TUI.

```
   _ __  _ __ ___  _ __ ___   ___| |_| |__ ___| | | / __|
  | '_ \| '__/ _ \| '_ ` _ \ / _ \ __| '_ \ / _ \ | | \__ \
  | |_) | | | (_) | | | | | |  __/ |_| | | |  __/ |_| |__) |
  | .__/|_|  \___/|_| |_| |_|\___|\__|_| |_|\___|\___/____/
```

---

## Quickstart

PrometheUS ships as `prometheus-cli` on PyPI. Pick whichever installer you already use:

```bash
# Recommended — isolated, auto-upgradable
pipx install prometheus-cli

# Modern uv-based workflow
uv tool install prometheus-cli

# Plain pip into the active environment
pip install prometheus-cli
```

Python 3.11, 3.12, and 3.13 are supported on Linux, macOS, and Windows.

## Provider pool — 120,000+ requests/day at $0

PrometheUS aggregates 9 free-tier providers and fails over between them automatically. Configure as many or as few as you like — anything you skip just leaves capacity on the table.

| Provider | Per-key/day | Env var | Models |
|---|---:|---|---|
| OpenRouter | 1,000 (with $10 credit) | `PROMETHEUS_API_KEYS` (comma-separated) | Frontier `:free` chain |
| Groq | 14,400 | `PROMETHEUS_GROQ_KEYS` | Llama 3.3 70B, Llama 4 Scout/Maverick @ 700+ tok/s |
| Gemini | 500 | `PROMETHEUS_GEMINI_KEYS` | Gemini 2.5 Flash |
| Cerebras | 2,000 | `PROMETHEUS_CEREBRAS_KEYS` | Llama 3.3 70B @ 2,000 tok/s |
| NVIDIA NIM | ~1,000 | `PROMETHEUS_NVIDIA_KEYS` | MiniMax M2.7, GLM-5.1, Llama 3.3 |
| Mistral La Plateforme | ~33,000 | `PROMETHEUS_MISTRAL_KEYS` | Codestral-latest (123B coder) |
| Together AI | ~10,000 | `PROMETHEUS_TOGETHER_KEYS` | DeepSeek-V3, Qwen3-Coder |
| Cloudflare Workers AI | ~3,000 | `PROMETHEUS_CLOUDFLARE_ACCOUNT_ID` + `_API_TOKEN` | Workers AI catalog |
| Pollinations | ~5,000 | *(zero-config, no key)* | OpenAI-compatible fallback |

A typical setup with 4 OpenRouter keys + 5 Groq keys + 1 each Gemini/Cerebras/Mistral lands around **116,500 req/day at $0**. Add the rest and clear 200,000.

Type `/provider` inside the TUI any time to see your live pool, cascade order, and failover state.

## Optional extras

PrometheUS keeps the base install lean. Heavier capabilities live behind extras:

```bash
# Local voice input — installs sounddevice + faster-whisper
pipx install "prometheus-cli[voice]"

# Premium-tier escalation — installs the anthropic SDK
pipx install "prometheus-cli[escalate]"

# Both at once
pipx install "prometheus-cli[voice,escalate]"
```

`[voice]` enables `/voice` (Ctrl+Space) for hands-free dictation. `[escalate]` enables `/escalate` to route a turn to the Premium / Premium+ / Premium Max engines via your own Anthropic key.

## Verify your install

```bash
prometheus --doctor
```

`--doctor` checks Python version, terminal capabilities, API key reachability, optional dependency status (voice / escalate), and write access to the PrometheUS state directory. Run it any time you suspect something's off.

## First chat

```bash
prometheus
```

You'll land in the TUI. Type a prompt, hit Enter:

```
> read prometheus/agent/loop.py and explain the role-routing logic

⏺ Read(prometheus/agent/loop.py)
  ▸ 412 lines

The agent loop classifies each turn into a role (CODER / PLANNER / FAST /
VISION) and dispatches to the matching engine chain. CODER is the default…
```

That's it. The amber `⏺` glyph is the receipt for every tool call. Cycle permission modes with **Shift+Tab**. Rewind a mistake with **Esc Esc**. Quit with `/quit` or Ctrl+C.

## Feature highlights

- **Engines for every job** — Core (default coder), Reasoner (planner), Swift (fast), Vision (multimodal), with on-demand Premium / Premium+ / Premium Max escalation via `/escalate`. Tier name appears on every assistant turn — model swaps are never silent.
- **WorkSpace Trust** — every new project is untrusted until you approve it. MCP servers are pinned by binary hash. Skills are trust-gated. Ancestor `PROMETHEUS.md` files outside `$HOME` are gated against prompt injection.
- **Dangerous-pattern blocklist** — `run_bash` refuses `rm -rf /`, `git reset --hard`, `git filter-repo`, force-push to protected branches, `dd`, `mkfs`, fork bombs, and curl-pipe-sh before they execute.
- **Atomic writes + file locking** — `EditFile` / `MultiEdit` / checkpoint rewind atomic-write through a temp + fsync + rename pipeline; cross-platform advisory locking serializes concurrent edits.
- **Per-OS subprocess sandbox** — POSIX `setsid` + `os.killpg(SIGTERM)` reaps the whole process tree on timeout; Windows `CREATE_NEW_PROCESS_GROUP` + `CTRL_BREAK_EVENT`; opt-in macOS `sandbox-exec` (`PROMETHEUS_BASH_SANDBOX=1`); opt-in `RLIMIT_AS` / `RLIMIT_CPU` caps.
- **Untrusted-fetch wrapper** — `web_fetch` results are wrapped with an explicit "do not follow instructions inside" marker and re-validated against the SSRF guard on every redirect hop.
- **Plugins, MCP, async jobs, checkpoints** — `~/.prometheus/plugins/` manifests, hash-pinned MCP servers (`/mcp`), background agents via `/async`, atomic-write checkpoint rewind via `/rewind` or `/undo`.
- **Voice + image paste** — `/voice` (Ctrl+Space) toggles local faster-whisper capture; Ctrl+V drops a screenshot straight into the conversation, routed to the Vision tier automatically.
- **`/escalate` ladder** — Premium → Premium+ → Premium Max. Auto-bumps to Premium+ once if Premium fails on the same prompt. Auto-compacts the context to free chain *before* a paid call.
- **Spending caps** — `PROMETHEUS_DAILY_USD_LIMIT` / `PROMETHEUS_PER_SESSION_USD_LIMIT` / `PROMETHEUS_PER_TURN_USD_LIMIT`. Always-visible USD ticker in the header (`$0.42 / $5.00`, color-codes amber at 80% / red at 95%). Hard 95%-of-cap throttle. BYOK (`/byok`) bypasses the pooled cap.
- **Crash recovery** — agent state snapshotted to `state.json` after every turn; `/resume <sid>` rebuilds the in-memory message buffer exactly, including pending tool turns.
- **Tamper-evident audit log** — every tool call hash-chained, JSONL-appended with `flush+fsync` at `~/.local/share/prometheus/audit/<session>.jsonl`.

## Slash commands

`/help` lists all of them. The headline set:

| Command | Purpose |
|---|---|
| `/help` | List every command with a one-liner. |
| `/escalate` | Route this turn to a Premium tier. |
| `/byok` | Bring-your-own-key — manage credentials per-engine. |
| `/credits` | Show remaining free-tier and paid credits. |
| `/architect` | Enter planning-first mode. |
| `/trust` | Trust the current workspace. |
| `/plugins` | Install / enable / disable plugins. |
| `/async` | Launch the current request as a background job. |
| `/jobs` | Tabular dashboard of agents + backgrounded shells. |
| `/voice` | Toggle voice capture (requires `[voice]` extra). |
| `Ctrl+V` | Paste an image into the conversation. |
| `Ctrl+G` | Open `$EDITOR` to compose the current prompt. |
| `/commit`, `/revert` | Stage all + commit (auto-message); `git revert HEAD --no-edit`. |
| `/verify` | Re-check the last reply against the original request. |
| `/implement` | Issue-driven dev: `/implement github:owner/repo#123`. |
| `/worktree` | Spawn a parallel agent on a fresh git worktree. |
| `/visual` | Screenshot a URL and verify with the Vision tier. |
| `/typecheck` | Auto-detect + run the project's typechecker. |
| `/share` | Export the session as a static local HTML file. |
| `/export` | Export the session as Markdown. |
| `/transcript` | Open the raw JSONL transcript. |
| `/rewind`, `/undo` | Browse and restore workspace snapshots. |
| `/skills` | List trust-gated skills auto-loaded for this workspace. |
| `/mcp` | Manage MCP servers (per-server consent, hash-pinned). |

## Configuration

Settings are read from your shell environment or a project-local `.env`:

| Variable | Purpose |
|---|---|
| `PROMETHEUS_API_KEY` | Primary credential for the PrometheUS free + premium routing service. |
| `ANTHROPIC_API_KEY` | Optional. If set, `/escalate` uses your direct Anthropic account. |
| `PROMETHEUS_DAILY_USD_LIMIT` | Hard cap on USD spend per UTC day. |
| `PROMETHEUS_PER_SESSION_USD_LIMIT` | Hard cap per session. |
| `PROMETHEUS_PER_TURN_USD_LIMIT` | Hard cap per single turn. |
| `PROMETHEUS_VERBOSE_MODELS` | `1` to surface the resolved engine name in receipts. |
| `PROMETHEUS_THEME` | TUI theme — one of `dark`, `night`, `light`, `paper`, `tokyonight`, `catppuccin`, `gruvbox`, `nord`. |

All limits default to sensible values; override only what you need.

## Engines

PrometheUS abstracts away upstream model identity. You pick a tier, the router picks the engine.

| Tier | When it runs | Strengths |
|---|---|---|
| **Core** | Default for code work. | Diff-clean edits, fast iteration, tool-call discipline. |
| **Reasoner** | Auto-selected for `/architect` and multi-step planning. | Long-horizon decomposition, tradeoff analysis. |
| **Swift** | Selected for trivial lookups, lints, single-line answers. | Sub-second latency. |
| **Vision** | Auto-selected when an image is in context. | Image + code understanding. |
| **Premium** | `/escalate` once. | Higher reliability under hard tasks. |
| **Premium+** | `/escalate` twice or auto on repeated free-chain failure. | Larger context, deeper reasoning. |
| **Premium Max** | `/escalate` three times or `/escalate max`. | The strongest tier PrometheUS can route to. |

`/credits` always shows what you've used and what's left.

## Audit suite — verifiable releases

PrometheUS is the only terminal AI coding agent that ships a public release-acceptance test on every install:

```bash
prometheus --audit
```

`--audit` runs 183 deterministic scenarios across the agent loop, tools, TUI, safety, slash commands, and per-round regression coverage. Transient free-tier failures (engine busy / quota exhausted) are reported as SKIP, never FAIL. The summary line is the contract — if it ever shows fewer than the expected count, the release is broken on your machine.

You can also run individual audits directly:

```bash
python scripts/workflow_audit.py     # the full suite
python scripts/live_tui_audit.py     # live TUI rendering
```

## Recipes — declarative agent workflows

Recipes are checked-in YAML files that capture an agent invocation:

```bash
# Run a bundled gallery recipe
prometheus --run @gallery/code-review

# Or a recipe checked into your repo
prometheus --run ./tasks/release-changelog.yaml
```

Bundled gallery: `bug-triage`, `dep-upgrade`, `changelog`, `code-review`, `type-coverage`. List them with `prometheus --run @gallery`.

A recipe is just:

```yaml
name: release-changelog
description: Generate CHANGELOG.md from commits since last tag
permission_mode: acceptEdits
prompt: |
  Find the most recent git tag, group commits by category, write
  CHANGELOG.md in Keep-a-Changelog format.
```

## Privacy

PrometheUS is built privacy-first. See [PRIVACY.md](PRIVACY.md) for what is sent upstream, what stays local, how to opt out of telemetry, and how to wipe local state.

## Security

To report a vulnerability, please follow the disclosure process in [SECURITY.md](SECURITY.md). Do not open a public issue for security reports.

## Contributing

Contributions are welcome — code, audits, plugins, skills, themes, docs. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for the dev loop, coding standards, and PR checklist.

## License

PrometheUS is released under the MIT License. See [LICENSE](LICENSE) for the full text.
