prometheus-cli 1.0.16

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.

Prometheus

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:

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/ and CHANGELOG.md.

---

Quickstart

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:

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:

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

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

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

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 — declarative YAML agent workflows
• docs/CUSTOM_AGENTS.md — author your own subagents
• docs/SAFETY.md — the safety architecture
• docs/TROUBLESHOOTING.md — common issues + fixes
• docs/PRESS_KIT.md — single-page summary for journalists
• CHANGELOG.md — full 161-round release log

---

Privacy

See 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. Do not open a public issue for security reports.

Contributing

Code, audits, plugins, skills, themes, and docs all welcome — start with CONTRIBUTING.md.

License

MIT — see LICENSE.