Apollo

The CLI coding agent with deterministic memory. Powered by Midas. An Archic project.

Apollo is a terminal-based AI coding agent for developers who want to command their codebase from the shell. Describe what you need in natural language and Apollo can inspect the repo, plan the change, edit multiple files, run checks, show reviewable git-native diffs, and remember project context through Midas memory.

It is the execution layer of the Archic ecosystem: Midas remembers, Apollo acts. Your API keys stay in .env. Your code and Apollo state stay on your machine.

Landing page: apollo.archic.es · Archic: archic.es · CLI: @vornicx/[email protected]

npm install -g @vornicx/apollo-agent
cd your-project
apollo setup
apollo

How Apollo works

Apollo is a terminal-first coding agent. You talk to it normally and it decides whether the input is:

• Chat — questions, explanations, repo Q&A, brainstorming.
• Mission — concrete work such as editing files, adding tests, refactoring, auditing, or running checks.
• Command — explicit CLI actions such as status, doctor, diff, rollback, cloud, skills, or config.

When Apollo enters mission mode, it runs a controlled loop:

goal -> plan -> implement -> review -> proof -> checkpoint -> certificate

The important difference from a plain chat agent is that "done" is not just a response. Apollo can run tests, contract commands, regex checks, scope checks, and budget limits before it marks a mission complete. It writes checkpoints before applying patches, so you can inspect diffs and roll back.

Apollo has two memory layers, with Midas providing the deterministic memory highlighted on the Archic landing page:

• Project memory in APOLLO.md and .apollo/, used for workspace facts, missions, checkpoints, config, and procedural lessons.
• Midas memory when midas-mcp or midas-memory-mcp is installed. Apollo launches Midas directly, stores a local SQLite memory at .apollo/midas.sqlite3, recalls relevant context before chat/mission prompts, and auto-captures durable facts, decisions, preferences, constraints, and corrections. Midas is local-first and does not use an LLM at ingest.

Your keys stay local in .env. Your Apollo state stays in .apollo/ inside your workspace.

Why Apollo

| | Chat agents (e.g. Hermes-style) | Apollo | |---|-------------------------------|------------| | Unit of work | Conversation turn | Mission with phases | | Done means | Model said so | Contract passed (tests, regex, HTTP) | | Proof | — | Mission certificate + replay | | Where you work | One channel | CLI + web + Telegram (same mission) | | Keys | Often hosted | BYOK — OpenRouter, Anthropic, OpenAI, … | | Rollback | — | Checkpoints before every apply |

Apollo is built for developers who ship: refactors, tests, migrations, and repo Q&A — with guardrails, not vibes.

Quick start (60 seconds)

1. Install Apollo

Linux and macOS, when Node.js 22+ is already installed:

npm install -g @vornicx/apollo-agent
apollo --version

Windows PowerShell, when Node.js 22+ is already installed:

npm install -g @vornicx/apollo-agent
apollo --version

2. Set up your project

cd your-repo
apollo setup --yes    # fast: .apollo/, .env, templates
apollo doctor

Add at least one LLM key to .env (recommended: OPENROUTER_API_KEY).

3. Optional: enable Midas memory

Midas gives Apollo durable local memory across sessions:

uv tool install "midas-memory[mcp,local]"
# or: pipx install midas-memory-mcp

apollo memory status

Apollo will use Midas automatically when the command is available.

4. First mission (no key required)

apollo run "summarize what this project does" --mode plan

5. Ship something

apollo
# apollo> add a /health route and a minimal test

Apollo picks plan · review · auto · full-auto from goal complexity and risk. You stay in control in review mode (approve before files are written).

Autorouter training

Apollo's local autorouter is regenerated from deterministic local data:

npm run router:dataset
npm run router:train

The generated model lives at .apollo/router/model.json and should report eval.fieldAccuracy >= 0.80. Treat it as reproducible local state unless you explicitly decide to version it.

Install & update

Apollo requires Node.js 22+ and npm. The npm package installs the CLI command apollo.

Linux

Install Node.js 22+ with your preferred package manager, then install Apollo:

node --version
npm --version
npm install -g @vornicx/apollo-agent
apollo --version

If global npm installs need root on your distro, prefer a user-local Node manager such as nvm, fnm, or Volta instead of using sudo npm install -g.

macOS

With Homebrew:

brew install node@22
npm install -g @vornicx/apollo-agent
apollo --version

With nvm:

nvm install 22
nvm use 22
npm install -g @vornicx/apollo-agent
apollo --version

Windows

PowerShell with winget:

winget install OpenJS.NodeJS.LTS
npm install -g @vornicx/apollo-agent
apollo --version

PowerShell with an existing Node.js 22+ install:

npm install -g @vornicx/apollo-agent
apollo --version

Initialize a repo

cd your-repo
apollo setup
apollo doctor

Add at least one LLM key to .env (recommended: OPENROUTER_API_KEY).

Enable Midas memory

Apollo integrates directly with Midas, a local-first memory layer for agents. Install one of the Midas MCP commands and Apollo will auto-detect it:

uv tool install "midas-memory[mcp,local]"
# or:
pipx install midas-memory-mcp

Then check the connection:

apollo memory status

Default Apollo/Midas behavior:

• Uses midas-mcp or midas-memory-mcp if found on PATH.
• Stores memory in .apollo/midas.sqlite3 per workspace.
• Recalls relevant memory before chat and mission prompts.
• Captures durable chat and mission facts through Midas capture.
• Falls back to Apollo's local .apollo/memory.jsonl if Midas is unavailable.

Update CLI

apollo update

Or manually:

npm install -g @vornicx/apollo-agent@latest
apollo --version

Updating the CLI does not change your project files (.apollo/, .env, APOLLO.md).

New user journey

install → apollo setup → apollo doctor → plan mission → add API key → apollo shell / run
                ↓ optional
         apollo setup --full → npm run dev → cloud sync → Telegram pair

| Step | Command | What you get | |------|---------|----------------| | Bootstrap | apollo setup | .apollo/apollo.db, APOLLO.md, .env, example contract.json / scope.json / budget.json | | Verify | apollo doctor | Node 22+, SQLite, provider keys | | Ask | apollo or apollo chat "how does auth work?" | Project-aware Q&A | | Build | apollo run "add pagination to users API" | Planner → implementer → reviewer → apply + checkpoint | | Prove | (auto in strict mode) | Runs .apollo/contract.json commands → certificate | | Undo | apollo rollback <id> | Restore pre-mission files | | Cloud | apollo cloud push | Sync missions to Supabase-backed dashboard | | Mobile | Settings → pair Telegram | Start missions from your phone |

Full walkthrough: docs/GETTING-STARTED.md

What’s in the box (v1.0)

• CLI — conversational shell with /goal tenacity, missions, checkpoints, skills, memory export
• Midas memory — direct local MCP integration for durable, source-traceable memory across sessions
• Strict mode (apollo_strict) — contract verification, scope limits, budget caps, certificates
• Hermes-compat — apollo config set apolloMode hermes_compat for faster, fewer gates
• Web dashboard — mission planning UI, orchestration stream, gateway pairing (npm run dev)
• Cloud — queue, worker cron, apollo cloud push|pull|status
• Gateway — Telegram / Discord webhooks, pairing codes
• Apollo memory — APOLLO.md, .apollo/memory.jsonl, Midas recall/capture, procedural memory, resume/replan
• Skills marketplace — catalog install + sandbox test (CLI)
• Replay & audit — apollo replay, apollo audit (CLI)

Execution model: repo changes + proof contracts run in the CLI. The web app orchestrates phases, syncs metadata, and pairs gateways — it does not patch your local files.

Surface status and focus: docs/SURFACES.md

Roadmap detail: docs/ROADMAP.md · Deploy cloud: docs/CLOUD-DEPLOY.md

Commands you’ll use daily

| Command | Purpose | |---------|---------| | apollo | Shell — questions → chat, goals → missions | | apollo setup | Wizard (--quick, --full, --yes) | | apollo run "goal" | One-shot mission | | apollo goal "criteria" | Goal-lock until success contract passes | | apollo status / apollo diff / apollo rollback | Mission control | | apollo cloud push | Upload local missions to cloud | | apollo omni on | Enable omnipresent cross-device mode | | apollo omni autoapply off | Require review before outside-workspace writes | | apollo omni trust|ask|block <root> | Set trust policy per external root | | apollo memory status | Check Midas/local memory status | | apollo memory export | Export workspace memory | | apollo replay <id> | Inspect mission timeline | | apollo config | apolloMode, iterations, integrations | | apollo update | Upgrade global CLI |

API keys (BYOK)

| Key | Role | |-----|------| | OPENROUTER_API_KEY | Recommended — all models via one gateway | | GROQ_API_KEY | Fast routing / classification | | ANTHROPIC_API_KEY / OPENAI_API_KEY / … | Direct provider access | | SUPABASE_* | Web app + cloud sync (optional) | | TELEGRAM_BOT_TOKEN | Gateway (optional, production) |

Keys live in your project .env — never in Apollo’s servers.

Project layout Apollo creates

| Path | Purpose | |------|---------| | .apollo/apollo.db | Missions, chat, checkpoints (local) | | .apollo/midas.sqlite3 | Midas durable memory when Midas is installed | | .apollo/memory.jsonl | Apollo local memory export/fallback | | .apollo/config.json | Mode, integrations, budgets | | .apollo/examples/ | Starter contract, scope, budget | | .apollo/cloud.json.example | Cloud sync token template | | APOLLO.md | Project memory Apollo reads | | .apolloignore | Paths Apollo must not touch |

Copy examples when you want enforced proof:

cp .apollo/examples/contract.json .apollo/contract.json
cp .apollo/examples/scope.json .apollo/scope.json

Web dashboard

Hosted (production): https://apollo-agent.vornicx.workers.dev — sign in, missions, chat, BYOK keys, gateway pairing.

The npm package ships CLI only. To run the web app locally:

git clone https://github.com/vornicx/apollo-agent.git
cd apollo-agent
npm install
apollo setup --full
# Apply supabase/migrations in your Supabase project
npm run build
node node_modules/wrangler/bin/wrangler.js dev --config dist/apollo_agent/wrangler.json --port 8787

Open http://127.0.0.1:8787 after npm run dev (build + wrangler — reliable on Windows). For experimental Vite HMR: npm run dev:vite.

Deploy / ops: docs/LAUNCH-OPS.md · docs/CLOUD-DEPLOY.md

Safety

• By default, edits are confined to your project directory
• Optional omnipresent mode (apollo omni on) allows cross-device paths with scope/deny guardrails
• Checkpoints before patches; apollo rollback restores files
• .apolloignore for secrets and vendored paths
• Review mode prompts before writes on high-risk goals
• Mission certificates record git head, contract results, reviewer score

Requirements

• Node.js 22+
• npm (global install) or clone for web
• Terminal UTF-8 (Windows PowerShell, macOS, Linux)

Troubleshooting

Update CLI

apollo update
# or
npm install -g @vornicx/apollo-agent@latest
apollo --version

No API key

apollo run "analyze structure" --mode plan   # works offline
apollo setup                                 # add keys

Regenerate Supabase types (maintainers)

supabase login
npm run types:sync

Links

• npm: @vornicx/apollo-agent
• Repo: github.com/vornicx/apollo-agent
• Web: apollo-agent.vornicx.workers.dev
• Contributing: docs/CONTRIBUTING.md
• Launch ops: docs/LAUNCH-OPS.md
• North star: docs/APOLLO_VISION.md · Fusion: docs/APOLLO_FUSION.md · vs Hermes: docs/HERMES-COMPARISON.md

License

MIT — see LICENSE.