Metadata-Version: 2.4
Name: prometheus-cli
Version: 1.0.23
Summary: Free terminal AI coding agent. `pipx install prometheus-cli && prometheus` works out of the box, no credit card. 13-provider key pool with automatic failover, ~155K free requests/day, brand-neutral display.
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.28.1
Requires-Dist: h11>=0.16
Requires-Dist: textual>=0.79
Requires-Dist: rich>=13.7
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: platformdirs>=4.2
Provides-Extra: voice
Requires-Dist: sounddevice>=0.4.6; extra == "voice"
Requires-Dist: numpy>=1.26.4; extra == "voice"
Requires-Dist: faster-whisper>=1.1.1; extra == "voice"
Provides-Extra: escalate
Requires-Dist: anthropic>=0.87.0; extra == "escalate"
Provides-Extra: recipes
Requires-Dist: PyYAML>=6.0.2; extra == "recipes"
Provides-Extra: visual
Requires-Dist: playwright>=1.49; 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.25; extra == "test"
Provides-Extra: all
Requires-Dist: sounddevice>=0.4.6; extra == "all"
Requires-Dist: numpy>=1.26.4; extra == "all"
Requires-Dist: faster-whisper>=1.1.1; extra == "all"
Requires-Dist: anthropic>=0.87.0; extra == "all"
Requires-Dist: PyYAML>=6.0.2; extra == "all"
Requires-Dist: playwright>=1.49; extra == "all"
Dynamic: license-file

# Prometheus

[![PyPI version](https://img.shields.io/pypi/v/prometheus-cli.svg)](https://pypi.org/project/prometheus-cli/)
[![tests](https://img.shields.io/badge/tests-2%2C574%20passing-brightgreen.svg)](#verify-locally)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/prometheus-cli.svg)](https://pypi.org/project/prometheus-cli/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](#install)

> **The free, universal terminal AI coding agent.
> No credit card. Works on Windows, macOS, and Linux out of the box.**

```
   ____                          _   _      __  _______
  / __ \_______  ___ _  ___ ____/ /_| |    / / /_  __/ /
 / /_/ / __/ _ \/ _ \ |/ _ `/ -_) __/| |/|/ /   / / / /__
/_____/_/  \___/_//_/_|\_,_/\__/\__/ |__/|__/   /_/ /____/
```

Two commands and you have a real coding agent in your terminal:

```bash
pipx install prometheus-cli
prometheus
```

That's it. No API key prompt. No "add a credit card to start." No "log in with…". A clean install routes through a free-tier provider pool and answers immediately. Drop in your own free keys (no credit card, ~30 s each) for ~155 K requests/day at $0.

---

## Why Prometheus

| | **Prometheus** | Claude Code |
|---|---|---|
| **License** | MIT, open source | Anthropic proprietary |
| **Free without a credit card** | ✓ — 13-provider free pool with automatic failover | Requires Anthropic Console account |
| **Multi-provider routing** | ✓ — OpenRouter, Groq, Mistral, Cerebras, Cloudflare, NVIDIA NIM, Together AI, Pollinations + your own keys | Anthropic only |
| **Windows native** | ✓ — first-class; `CREATE_NEW_PROCESS_GROUP`, `CTRL_BREAK_EVENT`, PowerShell receipts | ✓ |
| **Computer Use** | ✓ — macOS bundled, Linux via X11, Windows via Win32 | ✓ |
| **Trust gradient (T0–T3 graduated autonomy)** | ✓ — auto-advance after 5 clean calls | Static permission modes |
| **Verifiable release** | ✓ — `prometheus --audit` runs 183 deterministic scenarios | ✗ |
| **Headless checkpoint + non-zero exit on failure** | ✓ — every `-p` run writes a checkpoint before each tool call | Partial |
| **Reproduce-Before-Patching guard** | ✓ — system prompt mandates repro on bug-fix prompts | ✗ |
| **Self-healing tool router** | ✓ — graph-based fallback; LLM only on full escalation | ✗ |
| **Local TUI** | Textual + Rich, themeable | iTerm-style |

The four columns Prometheus genuinely owns: **MIT license**, **multi-provider**, **free without a credit card**, and the **161 rounds of production-agent hardening** documented end-to-end in [`docs/`](docs/) and [`CHANGELOG.md`](CHANGELOG.md).

---

## Quickstart

```bash
pipx install prometheus-cli
prometheus
```

Type any request and hit Enter:

```
> read prometheus/agent/loop.py and explain the dispatch flow

⏺ Read(prometheus/agent/loop.py)
⎿ 1,716 lines

The agent loop is a single async generator. Per turn, it
classifies the role (CODER / PLANNER / FAST / VISION),
streams text deltas + tool_call_complete events, and runs
read-only tools in parallel before mutating ones serialise…
```

For headless / pipeline use:

```bash
prometheus -p "summarise this PDF in 5 bullets" < paper.pdf
```

Headless mode writes a checkpoint before every tool execution and exits non-zero on any failure — your CI sees the failure immediately, not three days later.

---

## Capability map (161 rounds, condensed)

### Foundations
- 9-step turn pipeline with a deterministic `/pipeline` visualiser
- 5-step tool-pool assembly: Base → Mode → Deny → MCP → Dedup
- 7 catalogued recovery paths: tool-call markup, rate-limit retry, cache-break, circuit breaker, discovery fallback, structured-output retry, provider-pool failover
- 6 compaction strategies with a deterministic budget governor
- 28 sentinel events across 5 lifecycle types

### Workflow
- `⏺ Tool(args)` receipts and `⎿ result` continuation everywhere — never raw JSON, never `<function calls>` markup
- TodoWrite tracker with progress summary line
- Plan mode (Shift+Tab cycles), `/architect`, `/decompose`, `/dream`, `/insights`
- Read-before-edit contract enforced on every Update
- Atomic writes through temp + fsync + rename, cross-platform advisory locking
- Stuck-loop detector + same-tool-same-args repeat counter

### Safety (the 11 hardenings shipped in rounds 160–161)
- **Reproduce-Before-Patching guard** — abstain when the bug doesn't reproduce
- **Permission survival across compaction** — auto-clear all session grants on every compact
- **Headless checkpoint + non-zero exit** — known-location resume file before every tool call
- **Trust gradient T0–T3** — auto-advance after 5 clean calls, hard-deny always wins
- **Wink misbehaviour detector** — spec drift / reasoning loops / tool failures
- **Self-healing tool router** — capability-graph fallback, LLM only on full escalation
- **Dual-state recovery hierarchy** — L1 refine → L2 backtrack → L3 escalate
- **Functional clustering verifier** — multi-candidate I/O clustering, confidence-gated
- **Spotify-style verification loop** — syntax + import + scope + tests before commit
- **CARGO confidence-aware router** — best free model per task category
- **SSR self-improvement pipeline** — bug injection + repair → Memory Vault patterns

### TUI
- Textual + Rich, themeable: dark / night / light / paper / tokyonight / catppuccin / gruvbox / nord
- Activity rail with live timer, parenthesized `Xm Ys` metrics, no negative tokens
- Compact mode by default, `/verbose` toggle, `/stats`, `/details last command`
- Vim mode (round-106), Bash mode (`!`), file mention (`@`), tab autocomplete
- `Ctrl+V` paste image to Vision tier, `/voice` (Ctrl+Space) hands-free dictation

### Provider pool
- 13 providers, automatic failover on rate limits, 5xx, transport errors, empty-200, AND health-aware cooldowns
- `/escalate` ladder: Premium → Premium+ → Premium Max with hard daily/turn USD caps
- Brand-neutral by default — vendor names appear only in `/provider` admin view
- `/byok` per-engine key management

### Operations
- `prometheus --doctor` self-test — Python, terminal, keys, optional deps, state dir
- `prometheus --audit` — 183 deterministic acceptance scenarios; the public release contract
- `/checkpoint`, `/rewind`, `/undo` for atomic-write rewind
- Tamper-evident audit log: hash-chained, JSONL, fsync per write
- SQLite-backed sessions; `/resume`, `/fork`, `/from-pr`, `/sessions`

### Extension
- Custom subagents — drop a `.prometheus/agents/<name>.md` file, model can spawn it via `task(subagent_type=<name>)`
- MCP servers — hash-pinned binaries, per-server consent (`/mcp`)
- Forge marketplace — install / update / disable / publish skills + plugins (`/forge`)
- Recipes — declarative YAML agent invocations (`prometheus --run @gallery/code-review`)
- Bundled skills: changelog, dep-upgrade, code-review, type-coverage, bug-triage

---

## Bring your own keys (optional, ~30 s each)

The zero-config Pollinations fallback handles light use. For ~155 K requests/day with 10× faster responses, plug in any combination of free-tier keys:

```bash
mkdir -p ~/.prometheus
cat > ~/.prometheus/.env <<'EOF'
PROMETHEUS_GROQ_KEYS=gsk_your_key_here
PROMETHEUS_API_KEYS=or-your_openrouter_key
EOF
prometheus
```

| Provider | Per-key/day | Get a key (no credit card) |
|---|---:|---|
| Groq | 14,400 | https://console.groq.com/keys |
| Mistral La Plateforme | ~33,000 | https://console.mistral.ai/api-keys |
| Cerebras | 2,000 | https://cloud.cerebras.ai |
| Cloudflare Workers AI | ~3,000 | https://dash.cloudflare.com/profile/api-tokens |
| NVIDIA NIM | ~1,000 | https://build.nvidia.com |
| OpenRouter | 50 / 1,000 | https://openrouter.ai/keys |
| Together AI | $25 free credit | https://api.together.xyz/settings/api-keys |
| Gemini | ~100 | https://aistudio.google.com/apikey |

Stack any combination. Run `/provider` inside the TUI any time to see live pool, cascade order, and failover state.

---

## Install

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

Optional extras:

```bash
pipx install "prometheus-cli[voice]"      # local /voice (faster-whisper)
pipx install "prometheus-cli[escalate]"   # /escalate with your Anthropic key
pipx install "prometheus-cli[voice,escalate]"
```

---

## Verify locally

```bash
prometheus --doctor      # quick self-check (Python, terminal, keys, dirs)
prometheus --audit       # full 183-scenario release acceptance suite
pytest -q                # all 2,574 regression tests
```

`pytest -q` is the contract. If it doesn't end with `2574 passed, 4 skipped, 0 failed`, the release is broken on your machine — please file an issue.

---

## Honest scope

Prometheus is **not** Claude. It is a deterministic infrastructure layer that wraps any underlying model — by default a free-tier multi-provider pool, optionally your own paid Anthropic key via `/escalate`. The 161-round build closes the gaps between independent CLIs and Claude-Code-class behaviour, but the underlying model still matters: free-tier models are slower and less accurate than Sonnet 4.6 on hard tasks. That's why the `/escalate` ladder exists.

What Prometheus does guarantee:

- Every tool call routed through the deterministic safety stack (Overseer hard-deny, trust gradient, Wink misbehaviour detector, scope judge)
- Recovery on failure — retry-then-backtrack-then-escalate, never blind retry loops
- Reproducible builds: `prometheus --audit` produces the same result your CI does
- Audit trail: tamper-evident, hash-chained, fsync-flushed JSONL

If those aren't true on your machine, that's a release bug and a P0 issue.

---

## Documentation

- [`docs/RECIPES.md`](docs/RECIPES.md) — declarative YAML agent workflows
- [`docs/CUSTOM_AGENTS.md`](docs/CUSTOM_AGENTS.md) — author your own subagents
- [`docs/SAFETY.md`](docs/SAFETY.md) — the safety architecture
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — common issues + fixes
- [`docs/PRESS_KIT.md`](docs/PRESS_KIT.md) — single-page summary for journalists
- [`CHANGELOG.md`](CHANGELOG.md) — full 161-round release log

---

## Privacy

See [`PRIVACY.md`](PRIVACY.md) for what travels upstream, what stays local, how to opt out of telemetry, and how to wipe state. Short version: tool calls and tool results travel to whichever model provider you've configured; nothing else leaves your machine without explicit consent.

## Security

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

## Contributing

Code, audits, plugins, skills, themes, and docs all welcome — start with [`CONTRIBUTING.md`](CONTRIBUTING.md).

## License

MIT — see [`LICENSE`](LICENSE).
