optimus

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

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
• Architecture
• The cascade LLM provider
• Persistent global memory
• Comparison
• Referenced upstream repos
• Security
• License

Why optimus

Sub-skills

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.

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

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