almightygpt

The convention and tooling for multi-AI development. One AI writes. A different AI reviews. The decision trail lives in git.

AlmightyGPT drops a Worker / Reviewer convention into any repo, then runs real cross-AI code reviews (OpenAI, Anthropic, Google) and saves the review artifact in git as your durable decision trail.

npx almightygpt init

Full documentation, design notes, and roadmap: https://github.com/roxjayanath/almightygpt

Install

npm install -g almightygpt
# or one-shot, no global install:
npx almightygpt init

Requires Node.js 18+.

Quick start

# 1. Initialize the Convention Pack in any repo
cd ~/your-project
almightygpt init --stack node-ts   # or next-js / python-django / python-fastapi / rails / go

# 2. Set at least one provider API key. Two ways — pick one:
#    a) guided (v0.8.0+, stored in OS keychain):
almightygpt auth                            # interactive
almightygpt auth anthropic                  # one provider directly

#    b) classic env vars (still supported; env wins over keychain):
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=...

# 3. Run a review
almightygpt review --diff --reviewer codex --topic auth-refactor

# 4. Or run the headline two-role flow (one AI writes, a different AI reviews)
almightygpt review --diff \
  --worker claude --reviewer codex \
  --topic auth-refactor

# 5. Record your decision
almightygpt decide latest --status approved --note "Reviewer caught the missing null check"

The review lands at docs/codex-reviews/<topic>.md, committed to git as your audit trail. Machine metadata (cost, tokens, raw outputs) lands at .almightygpt/runs/<id>/.

Commands

| Command | What | | --- | --- | | almightygpt auth [<provider>] | Guided API key setup → OS keychain (v0.8.0+) | | almightygpt auth status [--validate] | Show which providers are configured and from where | | almightygpt auth remove <provider> | Delete a key from the OS keychain | | almightygpt init [--stack <name>] [--backup\|--force] | Install the Convention Pack | | almightygpt review --diff [range] [--worker X] --reviewer Y --topic Z | Run a review (Stage 2 — deep cross-AI) | | almightygpt precommit [--strict] | Quick last-mile review of uncommitted changes (Stage 3 — Gemini Flash by default) | | almightygpt runs list [--limit N] | List recent runs | | almightygpt runs latest | Show the most recent run | | almightygpt decide <id\|latest> --status <s> --note "..." | Record a human decision |

All commands accept --json for machine-readable output. The review command streams JSON events one per line, suitable for tooling (the VS Code extension uses this directly).

Six supported stack templates

node-ts, next-js, python-django, python-fastapi, rails, go — each ships with a stack-tuned CLAUDE.md for the Worker AI, an .almightyignore covering that stack's typical secret-bearing paths, and a config with sensible context.include / context.exclude globs.

Five real provider adapters + Mock (v0.12.0+)

Three direct + two meta-providers (covering 100+ models in total).

| Provider | Default model | Auth | When to pick | | --- | --- | --- | --- | | OpenAI | gpt-4o | OPENAI_API_KEY | Reviewer (structured output, JSON) | | Anthropic | claude-sonnet-4-6 | ANTHROPIC_API_KEY | Worker (planning, multi-file reasoning) | | Google / Gemini | gemini-2.5-flash | GOOGLE_API_KEY or GEMINI_API_KEY | Quick reviewer (cheap precommit, ~$0.003/call) | | OpenRouter | deepseek/deepseek-chat | OPENROUTER_API_KEY | 100+ models (DeepSeek, Mistral, Codestral, Llama, Qwen, Grok, …) via one key | | Ollama (local) | llama3.3:70b | no key | Regulated / air-gapped / privacy-first — runs entirely on your machine | | Mock | n/a | none | Tests without API keys |

OpenAI and Anthropic adapters have prompt caching enabled — 50% off cached input tokens on OpenAI, 90% off on Anthropic. Kicks in automatically on the second run in the same 5-minute window.

The 3-stage canonical default flow uses Anthropic → OpenAI → Google. Mix and match per project — see docs/use/providers.md for picker logic + cost numbers + example mixed configurations.

VS Code extension

The official UI wrapper for this CLI: https://marketplace.visualstudio.com/items?itemName=almightygpt.almightygpt-vscode

Six commands under the AlmightyGPT: palette category, a Runs tree view in the activity bar, real-time progress driven by this CLI's JSON event stream. The extension never owns orchestration — all review work happens here in the CLI.

Cursor / VSCodium / code-server / Theia users: https://open-vsx.org/extension/almightygpt/almightygpt-vscode

Runtime behavior — what this package actually does

For users and security teams evaluating AlmightyGPT, here's exactly what the CLI does at runtime. Every behavior is intentional and required for the product to work; none is hidden.

Network access (provider calls only)

The CLI makes outbound HTTPS requests only to the AI provider whose adapter is invoked, and only when you explicitly run a review command that uses that adapter:

• api.openai.com — via the official openai SDK, when OPENAI_API_KEY is set and an OpenAI adapter (e.g. codex) is invoked
• api.anthropic.com — via the official @anthropic-ai/sdk, when ANTHROPIC_API_KEY is set and a Claude adapter is invoked
• generativelanguage.googleapis.com — via the official @google/generative-ai SDK, when GOOGLE_API_KEY (or GEMINI_API_KEY) is set and a Gemini adapter is invoked

No other network access. No telemetry, no analytics beaconing, no auto-update calls, no anonymous usage stats, no error-reporting service. The CLI doesn't even check for its own newer versions.

Shell access (git only)

The CLI spawns git as a child process via execa for the following read-only operations:

• git status --short -- <file> — per-target safety check before any Markdown write
• git diff --no-color [range] — collect the diff to review
• git rev-parse --abbrev-ref HEAD / git rev-parse HEAD — record branch and commit hash into run.json

All git invocations pass arguments as an argv array, never as a shell string. The CLI never executes arbitrary user-supplied commands. It never calls sh -c, eval, or exec with concatenated input.

Environment-variable access (read-only)

The CLI reads these env vars at run time:

• OPENAI_API_KEY (for the OpenAI adapter)
• ANTHROPIC_API_KEY (for the Anthropic adapter)
• GOOGLE_API_KEY (for the Gemini adapter)
• GEMINI_API_KEY (alias for the Gemini adapter)

API keys are passed directly into each provider's official SDK and used as the Authorization: Bearer <key> header for that provider's API. The CLI never writes env vars, never stores keys to disk, never logs their values, and never sends them anywhere except the matching provider.

Filesystem access

• Reads (from your workspace): .gitignore, .almightyignore, .almightygpt/config.yaml, .almightygpt/rules.md, AGENTS.md, your configured agent memory files (CLAUDE.md, CODEX_AGENT.md, GEMINI_AGENT.md), and the file contents covered by the collected git diff.
• Writes (only to two paths, both configured in .almightygpt/config.yaml):
  • docs/<reviewer>-reviews/<topic>.md — the human review artifact (subject to a refuse-overwrite policy: never overwrites an existing review file without --force)
  • .almightygpt/runs/<id>/ — machine-readable run metadata
• Per-target git safety check runs before every Markdown write. Dirty target files are refused unless --force is passed.

Secret redaction (defense in depth)

Before any diff is sent to a provider, the CLI:

1. Filters out ignored files per-file by parsing the unified diff into per-file sections and dropping any file matching .gitignore, .almightyignore, or config.context.exclude. Ignored files never reach the provider — they're not just redacted, they're omitted entirely.
2. Redacts nine secret patterns in what remains: OpenAI / Anthropic keys, GitHub PATs, AWS access keys, Slack tokens, JWTs, PEM private key blocks, bearer tokens in headers, generic assignment-style secrets (api_key="...", password=...).

Both steps are logged in context-manifest.json for every run.

What the CLI does NOT do

• Send your code anywhere other than the AI provider you explicitly configured and invoked
• Phone home with telemetry, analytics, or error reports
• Auto-update itself or check for newer versions
• Store API keys in any file
• Execute arbitrary user-supplied shell commands
• Eval remote content
• Run install/postinstall scripts (none in the runtime dependency tree)

Runtime dependencies (12 total: 10 third-party + 2 our own)

almightygpt
├── @almightygpt/core
│   ├── @anthropic-ai/sdk    Anthropic's official Claude SDK
│   ├── @google/generative-ai Google's official Gemini SDK
│   ├── openai                OpenAI's official SDK
│   ├── execa                 spawn `git` as child process
│   ├── ignore                parse .gitignore / .almightyignore syntax
│   ├── yaml                  parse .almightygpt/config.yaml
│   ├── zod                   validate config schema
│   └── p-limit               limit parallel adapter calls
├── @almightygpt/templates    (no runtime dependencies)
├── chalk                     terminal colors
└── commander                 CLI argument parser

All pure JavaScript. No native binaries. No install scripts. npm audit reports zero vulnerabilities. Verify on Socket: https://socket.dev/npm/package/almightygpt

License

MIT. See LICENSE.

Links

• GitHub: https://github.com/roxjayanath/almightygpt
• Issues: https://github.com/roxjayanath/almightygpt/issues
• VS Code extension: https://marketplace.visualstudio.com/items?itemName=almightygpt.almightygpt-vscode
• Open VSX extension: https://open-vsx.org/extension/almightygpt/almightygpt-vscode