Install Guide
Prerequisites
You need Python 3.10 or later. The installer handles everything else.
Verify Python is installed:
python3 --version # macOS / Linux
py --version # Windows
Should print Python 3.10.x or higher.
Installation model
Each platform installs to a self-contained directory. Source files are
copied (not symlinked) into the per-platform target. The clone you
start from is purely a source-bundle — once the install finishes, you can
delete the clone.
git clone https://github.com/MobiusQuant/OpenMobius-skill /tmp/openmobius-src
cd /tmp/openmobius-src
python install.py --platform claude-code # → ~/.claude/skills/OpenMobius-skill/
rm -rf /tmp/openmobius-src # ✓ safe to delete
The target dir owns its own .venv and _index. Removing the target
(python install.py --uninstall) is a complete uninstall for that platform.
User-global caches (the open-source nomic embedding model and Playwright
chromium) stay in your OS's standard cache locations — shared across
platforms by design, so installing N platforms does not re-download them
N times.
One-line install
| OS | Command |
|---|
| macOS / Linux | bash install.sh or python3 install.py |
| Windows (PowerShell) | .\install.ps1 or python install.py |
| Windows (cmd / Git Bash) | python install.py |
The installer is idempotent — re-running skips already-done steps. First run takes 5–10 min (downloads). Subsequent runs are <30 s.
Pick your platform:
| Agent | Flag | Install path |
|---|
| Claude Code (default) | --platform claude-code (or omit) | ~/.claude/skills/OpenMobius-skill/ |
| Codex | --platform codex | ~/.codex/skills/OpenMobius-skill/ |
| OpenClaw | --platform openclaw | ~/.openclaw/skills/OpenMobius-skill/ |
| Hermes | --platform hermes | ~/.hermes/skills/market-data/OpenMobius-skill/ |
Other options:
--platform auto — Detect installed agents by scanning ~/.<agent> dirs.--target-dir <path> — Override the default install path.--platform all — Install to all four platforms in one go (each gets its own self-contained copy).
Installing on multiple agents
python install.py --platform all
Each platform gets its own complete install (its own .venv, its own
_index). The shared caches (nomic ~274MB, Playwright chromium ~280MB)
are downloaded once and shared via your OS's user-global cache, so
installing all four platforms doesn't quadruple the download.
What the installer does (9 steps)
| # | Step | First run | Subsequent |
|---|
| 0 | Stage source files → target dir (copy) | <1 s | overwrites |
| 1 | Check Python ≥ 3.10 | <1 s | <1 s |
| 2 | Create <target>/.venv/ | ~5 s | skip if exists |
| 3 | pip install -r requirements.txt into <target>/.venv/ | ~3 min | seconds (pip wheel cache) |
| 4 | Playwright chromium (~280 MB, user-global cache) | ~1 min | skip if cached |
| 5 | CJK font check (warn only) | <1 s | <1 s |
| 6 | Pre-warm nomic-embed model (~274 MB, user-global cache) | ~30 s | skip if cached |
| 7 | Build vector index from precomputed embeddings (964 cards) | ~2 s | skip if exists |
| 8 | Generate <target>/SKILL.md (platform frontmatter + shared body) | <1 s | overwrites |
| 9 | Run kb_doctor health check | ~5 s | ~5 s |
Common options
python install.py # default: auto, non-interactive, resume
python install.py --strict # CI: fail fast, no retry
python install.py -i # interactive: prompt y/n each step
python install.py --no-register # don't symlink to ~/.claude/skills/
python install.py --skip-fonts # skip CJK font check
python install.py --skip-chromium # skip Playwright install
python install.py --skip-doctor # skip final health check
python install.py --no-resume # re-run every step (don't skip cached)
Combined example — re-build everything from scratch:
rm -rf .venv knowledge_base/_index
python install.py --no-resume
Windows specifics
os.symlink typically requires admin on Windows. The installer falls back to a directory junction (mklink /J) which works without admin.- Junction target ↔ source behaves transparently for Claude Code.
- Playwright cache lives at
%LOCALAPPDATA%\ms-playwright\ (not ~/.cache/).
Manual install (if installer fails)
If install.py fails partway, you can resume by re-running it (--resume is default). For full manual setup:
# 1. venv
python3 -m venv .venv
# 2. dependencies
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt
# 3. CJK fonts (Linux only; macOS/Windows usually bundled)
sudo apt install fonts-noto-cjk # Debian/Ubuntu
# sudo dnf install google-noto-cjk-fonts (Fedora)
# sudo pacman -S noto-fonts-cjk (Arch)
# 4. Playwright chromium
.venv/bin/python -m playwright install chromium
# 5. Pre-warm embedding model
.venv/bin/python -c "from sentence_transformers import SentenceTransformer; \
SentenceTransformer('nomic-ai/nomic-embed-text-v1.5', trust_remote_code=True)"
# 6. Build vector index
.venv/bin/python scripts/build_index.py
# 7. Register with Claude Code (symlink)
mkdir -p ~/.claude/skills
ln -sf "$(pwd)" ~/.claude/skills/OpenMobius-skill
# 8. Verify
.venv/bin/python scripts/kb_doctor.py
Smoke test (post-install)
cd ~/.claude/skills/OpenMobius-skill
# Test concept retrieval
.venv/bin/python scripts/kb_retrieve.py "what is FVG" --top-k 3
# Test Mobius API resolve
.venv/bin/python scripts/kb_klines.py resolve "比特币"
# Test full chart pipeline
.venv/bin/python scripts/kb_klines.py chart --query BTC --interval 1h --limit 100 --output /tmp/t.json
.venv/bin/python scripts/kb_klines.py render --input /tmp/t.json --output /tmp/t.png --width 1200 --height 700
ls -l /tmp/t.png
All four commands should succeed.
Uninstall
The installer handles uninstall too — same install.py, different flag.
# Soft uninstall: remove only the platform registration (~/.claude/skills/...)
python install.py --uninstall # current platform (default claude-code)
python install.py --uninstall --platform codex # specific platform
python install.py --uninstall --platform all # all 4 platforms at once
# Full uninstall: also remove local build artifacts (.venv + vector index)
python install.py --uninstall --full
# Full purge: also remove global caches (chromium ~280MB + nomic model ~274MB)
# WARNING: these caches may be shared by other projects on your machine!
python install.py --uninstall --purge --yes-i-know
# Combine: full + purge on all platforms
python install.py --uninstall --platform all --full --purge --yes-i-know
Cleanup levels:
| Flag | Removes |
|---|
| (default) | ~/.<platform>/skills/OpenMobius-skill/ registration only |
--full | + .venv/ + knowledge_base/_index/ |
--purge --yes-i-know | + Playwright browser cache chromium* (~/.cache/ms-playwright Linux · ~/Library/Caches/ms-playwright macOS · %LOCALAPPDATA%\ms-playwright Windows) + ~/.cache/huggingface/hub/models--nomic-* |
Not removed (you delete manually if you want):
- The cloned repo at
<your-clone-dir> — just rm -rf it
Updating
# Full update: git pull + reinstall deps + regenerate SKILL.md
python install.py --update
# Update without pulling (you've already pulled manually)
python install.py --update --no-pull
# Update all installed platforms
python install.py --update --platform all
# Force rebuild vector index (after knowledge_base/concepts or cases changed)
python install.py --update --rebuild-index
--update runs:
git pull (unless --no-pull)install.py in resume mode (skip already-done steps; auto-install new deps)- Regenerate
SKILL.md at target (frontmatter from platforms/<name>.yaml + body from SKILL.body.md)
- (optional)
build_index.py --force if --rebuild-index
- Run
kb_doctor.py to verify everything works
You can also rebuild the index alone, without a full update:
.venv/bin/python scripts/build_index.py --force
Troubleshooting
| Symptom | Fix |
|---|
Python 3.x is too old | Install Python 3.10+ (see Prerequisites) |
pip install hangs | Try --strict to see real errors; check network/proxy |
playwright install chromium fails | Set PLAYWRIGHT_BROWSERS_PATH to a writable location |
| Index build OOM (low-RAM machine) | Use OPENAI_API_KEY to switch to OpenAI embedding (smaller footprint) |
| Chinese labels render as boxes | Install fonts-noto-cjk (Linux); macOS/Windows usually bundled |
| Symlink fails on Windows | Installer auto-falls-back to junction; no admin needed |
| Skill not invoked in Claude Code | Check ~/.claude/skills/OpenMobius-skill exists; restart Claude Code |
When in doubt: python scripts/kb_doctor.py reports exactly what's broken.