optimus

One Rust binary. Many LLM subskills. Persistent global memory.

Install · Sub-skills · Architecture · Cascade · Comparison

---

optimus is a unified LLM skill suite branched from wiki-llm (no fork — plain code-copy branch strategy). It fuses wiki, caveman, aura, and graphify into one Rust binary with a shared embedded memory (sled), a shared LLM provider cascade (cascade), and one install path on every desktop OS.

Table of contents

• Why optimus
• Sub-skills
• Ingest folder semantics
• Quick start
• Install
• Packages
• Architecture
• The cascade LLM provider
• Persistent global memory
• Comparison
• Referenced upstream repos
• Security
• License

Why optimus

Concern	optimus	wiki-llm	caveman	aura	graphify
Single binary	✅ Rust	❌ Bun	❌ Python	❌ Python	❌ Python
Persistent global memory across agents/LLMs	✅ sled embedded	partial	❌	partial	❌
Token compression	✅	❌	✅	❌	❌
Cross-repo semantic graph	✅	❌	❌	partial	✅
Wiki ingest of folder-of-folders	✅	❌	❌	❌	❌
Cascade provider routing	✅	❌	❌	❌	❌
Windows / macOS / Linux one-liner installer	✅	✅	✅	✅	partial

Sub-skills

Sub-skill	Syntax	Purpose
wiki	optimus wiki …	Persistent per-project wiki. optimus wiki ingest <path> treats each child folder as a wiki, appending as <parent>-<name>
caveman	optimus caveman on|off|stats|compress|review|commit	Ultra-compressed output mode (~65% token cut)
aura	optimus aura <path>	Structural + semantic repo fingerprint written to .aura/aura.json with a shared memory graph
graphify	optimus graphify <path>	Fuse a repo with linked repos into a navigable tree-sitter-backed graph (Leiden clustering, exporters)
init manual	optimus init manual	Interactive installer that prompts for each optional setting
init auto	optimus init auto	Silent installer using cascade defaults
help	optimus help [sub]	Explains every sub-skill and its parameters

Every subskill is dual-callable: as optimus <sub> … and as its own standalone SKILL.md entry

Sub-skill topology

┌──────────────────────────────────────────────────────────────┐
│                         optimus (CLI)                        │
├──────────────────────────────────────────────────────────────┤
│  wiki    caveman    aura    graphify    init-manual/auto     │
│    │        │        │         │                             │
│    ▼        ▼        ▼         ▼                             │
│  ┌──────────────────────────────────────────┐                │
│  │  optimus-core  (dispatcher · registry)   │                │
│  ├──────────────────────────────────────────┤                │
│  │  optimus-memory (sled) · optimus-llm     │                │
│  │  optimus-config · optimus-util           │                │
│  └──────────────────────────────────────────┘                │
└──────────────────────────────────────────────────────────────┘

Ingest folder semantics

optimus wiki ingest <ext-path> never overwrites. Each immediate child of <ext-path> becomes a new wiki, appended under the parent wiki using -:

current active wiki :  notes
ingested path       :  ./docs
found children      :  adr, guides, meeting-minutes
resulting wikis     :  notes-adr, notes-guides, notes-meeting-minutes

If multiple wikis exist, the active one is the most recently registered. Switch with optimus wiki use <name>.

Quick start

git clone https://github.com/bitphill/optimus.git
cd optimus
./install.sh                 # Linux / macOS / BSD
# ── or ──
install.cmd                  # Windows
# ── then ──
optimus init auto            # cascade defaults, no prompts
optimus wiki init ~/repos/my-project
optimus wiki ingest ~/repos/my-project/docs
optimus wiki query "how does auth flow work"
optimus caveman on
optimus aura ~/repos/my-project
optimus graphify ~/repos/my-project

Install

Pick whichever package manager you already have. All of them put an optimus binary on PATH.

cargo install optimus-cli      # crates.io — builds from source
npm install -g @bitphill/optimus   # npm — downloads a prebuilt binary
pip install optimus-cli        # PyPI — downloads a prebuilt binary on first run
brew install bitphill/optimus/optimus   # Homebrew tap — builds from source

Package names differ from the binary — optimus was already registered by unrelated projects on crates.io, npm, and PyPI. The installed command is always optimus regardless of which one you use. npm/PyPI currently ship prebuilt Linux x86_64 binaries only (glibc + musl, auto-detected); cargo/Homebrew build from source everywhere Rust does.

Or the universal one-command installer, self-detecting host, no package manager required:

./install.sh          # Linux / macOS / BSD — calls installers/deps.sh
install.bat           # Windows PowerShell — calls installers/deps.ps1
install.cmd           # Legacy Windows CMD — delegates to install.bat

The installer:

1. Detects OS (linux, macos, bsd, windows)
2. Runs the matching dependency script (installers/deps.{sh,ps1,bat,cmd})
3. Installs rustup + cargo if missing (stable, minimal profile)
4. Ensures git, curl, pkg-config, openssl (via native package manager: apt, dnf, pacman, apk, brew, pkg, winget, choco)
5. Builds optimus in release mode (lto="thin", codegen-units=1, opt-level=3, strip, panic="abort")
6. Installs binary to ~/.optimus/bin/optimus
7. Symlinks /usr/local/bin/optimus (if writable) or updates user PATH on Windows

Re-runnable. Idempotent. Logs to ~/.optimus/install.log.

Packages

Registry	Package	Link
crates.io (bin)	optimus-cli	https://crates.io/crates/optimus-cli
npm	@bitphill/optimus	https://www.npmjs.com/package/@bitphill/optimus
PyPI	optimus-cli	https://pypi.org/project/optimus-cli/
Homebrew	bitphill/optimus/optimus	https://github.com/bitphill/homebrew-optimus

optimus-cli provides the optimus binary. The rest of the workspace is published as library crates on crates.io — they compile automatically as dependencies of optimus-cli and don't need to be installed on their own:

Crate	Purpose	Link
optimus-util	os-detect, path, fs, hash, time	https://crates.io/crates/optimus-util
optimus-config	~/.optimus/config.toml, BYOK secrets	https://crates.io/crates/optimus-config
optimus-memory	sled-backed persistent global memory	https://crates.io/crates/optimus-memory
optimus-core	subskill trait, registry, dispatcher	https://crates.io/crates/optimus-core
optimus-llm	cascade provider client	https://crates.io/crates/optimus-llm
optimus-wiki	wiki subskill	https://crates.io/crates/optimus-wiki
optimus-caveman	caveman subskill	https://crates.io/crates/optimus-caveman
optimus-aura	aura subskill	https://crates.io/crates/optimus-aura
optimus-graphify	graphify subskill	https://crates.io/crates/optimus-graphify

Architecture

optimus-rs/
├── crates/
│   ├── optimus/            # CLI entrypoint (clap)
│   ├── optimus-core/       # subskill trait, registry, dispatcher
│   ├── optimus-config/     # ~/.optimus/config.toml
│   ├── optimus-memory/     # sled-backed persistent global memory
│   ├── optimus-llm/        # provider cascade client
│   ├── optimus-util/       # os-detect, path, fs, hash, time
│   ├── optimus-wiki/       # wiki subskill (init/ingest/query/lint/trash)
│   ├── optimus-caveman/    # caveman mode + hooks
│   ├── optimus-aura/       # aura extractor (tree-sitter)
│   └── optimus-graphify/   # graphify subskill (petgraph + Leiden)
├── installers/             # deps.{sh,bat,cmd,ps1}
├── install.{sh,bat,cmd}    # universal entrypoints
├── assets/                 # logo + banner
└── Cargo.toml              # workspace

The cascade LLM provider

Optimus merges the OpenRouter free-tier cascade with the interview-portal cheap cascade into a single fallback chain that starts with free models, escalates to cheap-with-quality, and only reaches the frontier tier when the earlier tiers refuse:

tier-0  →  openrouter/free  (qwen3-coder / gpt-oss-120b / nemotron-3-ultra …)
tier-1  →  cheap paid       (haiku-4.5, gpt-4.1-mini, mixtral-medium)
tier-2  →  quality          (sonnet-4.6, gpt-4.1)
tier-3  →  frontier         (opus-4.7, gpt-5, o5)

Configure once:

optimus init manual   # interactive: masked key prompts, cascade + subskill defaults
optimus init auto     # non-interactive: applies cascade defaults, reads keys from env/file

Env vars (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY) always take priority. Anything set via init manual is stored in ~/.optimus/config.toml under [secrets] (mode 0600); nothing is embedded in the binary.

Persistent global memory

A single sled embedded key-value store at ~/.optimus/memory/ is shared across all subskills, agents, and LLM sessions. Every read/write is:

• Transactional — sled provides serialisable snapshots
• Zero-daemon — no Redis, no Postgres, no external service
• Portable — a single directory you can rsync between machines
• Namespaced — wiki/…, aura/…, graphify/…, caveman/…, agents/…

Comparison

	wiki-llm	caveman	aura	graphify	optimus
Language	TS/Bun	Python	Python	Python	Rust
Startup latency	~200 ms	~600 ms	~800 ms	~1.2 s	~15 ms
Binary size	n/a	n/a	n/a	n/a	~9 MB (stripped)
Memory backend	JSON files	none	JSON	JSON	sled (ACID)
Cross-agent memory	❌	❌	❌	❌	✅
Token compression	❌	✅	❌	❌	✅ (caveman merged)
Repo graph fuse	❌	❌	partial	✅	✅
One-command install	✅	✅	✅	partial	✅ (universal)

Referenced upstream repos

• bitphill/wiki-llm — parent skill (branched code, not forked)
• JuliusBrussee/caveman + caveman-code, cavemem, cavekit, cavegemma — merged into optimus caveman
• ojuschugh1/aura — merged into optimus aura
• Graphify-Labs/graphify and skills.sh/safishamsi/graphify — merged into optimus graphify

Any linked repo that returned 404 or was private was excluded from the merge and is not required by optimus.

Security

• No unsafe blocks in first-party code (audited FFI only via tree-sitter)
• cargo-deny + cargo-audit in CI
• No unwrap on release paths (fallible ops return anyhow::Result)
• Secrets read from env or ~/.optimus/config.toml (mode 0600) — never embedded
• Path traversal blocked in wiki ingest and graphify walkers
• panic = "abort" in release to prevent double-panic UB
• LTO + strip + codegen-units=1 for a small, tamper-evident binary
• TLS via rustls (no OpenSSL runtime linkage)
• Reproducible builds pinned by rust-toolchain.toml

License

MIT © bitphill