prometheus-cli 0.1.12

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.

PrometheUS

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

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

# 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

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

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:

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:

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:

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

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

Contributing

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

License

PrometheUS is released under the MIT License. See LICENSE for the full text.