> ## Documentation Index > Fetch the complete documentation index at: https://vietbui.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Linux Machine Setup Guide > Authoritative step-by-step guide for bootstrapping the full AI workflow on a fresh Linux machine after cloning this repo. Written for AI agents (Claude, Code… # Linux Machine Setup Guide Authoritative step-by-step guide for bootstrapping the full AI workflow on a fresh Linux machine after cloning this repo. Written for AI agents (Claude, Codex, Gemini) to execute directly. Run steps in order — ordering constraints are load-bearing. **Full AI stack covered:** Claude Code · opencode · pi · headroom · Gemini CLI · wiki toolchain (qmd + LightRAG) *** ## TL;DR — AI Agent Quickstart ```bash theme={null} # 1. System deps sudo apt-get update && sudo apt-get install -y git curl zsh jq stow build-essential ca-certificates # 2. nvm + node >= 18 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash source ~/.nvm/nvm.sh && nvm install --lts && nvm use --lts # 3. ollama (local models) curl -fsSL https://ollama.com/install.sh | sh # 4. Clone repos — llm-wiki FIRST (dotfiles symlinks point here) mkdir -p ~/repos git clone git@github.com:vietbui1999ru/llm-wiki.git ~/repos/llm-wiki git clone git@github.com:vietbui1999ru/dotfiles.git ~/dotfiles # 5. Stow all dotfiles modules cd ~/dotfiles && stow claude opencode gemini codex # 6. Install Claude Code npm install -g @anthropic-ai/claude-code # 7. Install pi (council voice B / AFK loop worker) npm install -g @earendil-works/pi-coding-agent # 8. Install opencode (curl script — no brew needed on Linux) curl -fsSL https://opencode.ai/install | bash # 9. Install Gemini CLI npm install -g @google/gemini-cli # 10. Install wiki toolchain (uv + wiki-chat/index/mcp + git hook + ollama models) cd ~/repos/llm-wiki && bash claude-setup/scripts/install.sh # 11. Install headroom (context compression) — requires uv from step 10 uv tool install headroom-ai # 12. Set environment variables (edit values, then reload) cat >> ~/.zshrc << 'EOF' export ANTHROPIC_API_KEY="sk-ant-..." export GITHUB_TOKEN="ghp_..." # optional: council Voice B (GitHub Models) export PATH="$HOME/.local/bin:$PATH" source ~/repos/llm-wiki/templates/env-model-routing.sh # opencode model routing EOF source ~/.zshrc # 13. First claude run — downloads all plugins; qmd CLI becomes available after this claude --version # 14. Build wiki LightRAG index (one-time; ~30-60 min; costs ~$0.50 via Claude Haiku) wiki-index --full ``` *** ## Prerequisites ### System packages ```bash theme={null} sudo apt-get update && sudo apt-get install -y \ git curl zsh jq stow build-essential ca-certificates ``` | Tool | Why | | ------ | ----------------------------- | | `git` | Clone repos, git hooks | | `jq` | Status line, hook scripts | | `stow` | Dotfiles symlink management | | `zsh` | Shell (hooks use zsh shebang) | | `curl` | nvm, ollama, brew installers | ### Node.js (via nvm) ```bash theme={null} curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash source ~/.bashrc # or ~/.zshrc nvm install --lts && nvm use --lts node --version # must be >= 18 ``` ### ollama (local models) ```bash theme={null} curl -fsSL https://ollama.com/install.sh | sh ollama serve & # start daemon before install.sh runs ``` Models pulled by `install.sh`: * `nomic-embed-text` — embeddings for qmd and LightRAG * `qwen2.5:3b` — local LLM fallback for wiki-mcp synthesis *** ## Step 1: Clone repositories **Order matters.** Dotfiles commits symlinks with absolute paths pointing to `~/repos/llm-wiki`. Clone llm-wiki first or stow creates broken symlinks in `~/.claude/rules/`. ```bash theme={null} mkdir -p ~/repos # llm-wiki FIRST git clone git@github.com:vietbui1999ru/llm-wiki.git ~/repos/llm-wiki # dotfiles second git clone git@github.com:vietbui1999ru/dotfiles.git ~/dotfiles ``` If already inside the cloned repo: skip the first clone. *** ## Step 2: Stow dotfiles Each dotfiles module maps to a different AI tool's config directory: ```bash theme={null} cd ~/dotfiles stow claude # → ~/.claude/ (Claude Code config, rules, hooks, settings) stow opencode # → ~/.config/opencode/ (opencode.json + plugins) stow gemini # → ~/.gemini/ (GEMINI.md, settings.json, commands/) stow codex # → ~/.codex/ (Codex config) ``` **Verify Claude:** ```bash theme={null} ls -la ~/.claude/rules/applied-ai.md # should be a symlink → llm-wiki/claude-setup/rules/ cat ~/.claude/CLAUDE.md | head -3 # "Global Claude Configuration" ``` **Verify opencode:** ```bash theme={null} cat ~/.config/opencode/opencode.json | head -5 # should show $schema line ``` *** ## Step 3: Set environment variables Add to `~/.zshrc`: ```bash theme={null} export ANTHROPIC_API_KEY="sk-ant-..." # required: Claude Code + wiki-index + wiki-mcp export GITHUB_TOKEN="ghp_..." # optional: council Voice B via GitHub Models export PATH="$HOME/.local/bin:$PATH" # wiki-chat, wiki-index, wiki-mcp # opencode model routing (sets OPENCODE_MODEL_PRIMARY, _WORKER, _MINI, _COUNCIL, etc.) source ~/repos/llm-wiki/templates/env-model-routing.sh ``` Reload: `source ~/.zshrc` Key uses by tool: | Key | Required by | | ---------------------------------- | -------------------------------------------------------------- | | `ANTHROPIC_API_KEY` | Claude Code, wiki-index (Haiku extraction), wiki-mcp synthesis | | `GITHUB_TOKEN` (models:read scope) | Pi council voice (openai/gpt-5.4 via GitHub Models endpoint) | *** ## Step 4: Install AI tools ### Claude Code ```bash theme={null} npm install -g @anthropic-ai/claude-code claude --version ``` ### Pi (council Voice B + AFK loop worker) ```bash theme={null} npm install -g @earendil-works/pi-coding-agent pi --version ``` Pi is used as a stateless subprocess in the council workflow: ```bash theme={null} pi -p "Peer review: [decision]. Flag concerns." \ --model openai-codex/gpt-5.3-codex \ --no-session --no-extensions --no-skills ``` ### opencode ```bash theme={null} curl -fsSL https://opencode.ai/install | bash # or: npm install -g opencode-ai opencode --version ``` opencode is used for: TUI sessions with open models, council Voice C, warm-server pattern for headless API calls. ### Gemini CLI ```bash theme={null} npm install -g @google/gemini-cli gemini --version # should show 0.4x.x ``` Gemini CLI is configured via `~/.gemini/` (stowed in Step 2). On first use, authenticate: ```bash theme={null} gemini auth login ``` ### Wiki toolchain (uv + wiki-chat/index/mcp + git hook + ollama models) ```bash theme={null} cd ~/repos/llm-wiki bash claude-setup/scripts/install.sh ``` What it does: 1. Installs `uv` (Python package manager via curl) 2. Copies `wiki-chat`, `wiki-index`, `wiki-mcp` → `~/.local/bin/` 3. Installs post-commit git hook (auto-runs qmd indexing after wiki commits) 4. Pulls ollama models: `nomic-embed-text`, `qwen2.5:3b` Exits 1 if `ollama` not found — start `ollama serve` first. ### headroom (context compression) Requires `uv` from step above: ```bash theme={null} uv tool install headroom-ai headroom --version ``` Usage patterns: ```bash theme={null} headroom wrap claude # wraps Claude Code — transparent compression headroom wrap opencode # wraps opencode headroom proxy --port 8787 # zero-code proxy; point ANTHROPIC_BASE_URL at it ``` See [Headroom](/entities/headroom) for deployment modes and CCR details. *** ## Step 5: First Claude Code run — plugin installation ```bash theme={null} claude --version ``` This triggers download of all enabled plugins from `~/.claude/settings.json`: | Plugin | Purpose | | ------------------------------------- | -------------------------------------------- | | `superpowers@claude-plugins-official` | Skills (brainstorming, debugging, tdd, etc.) | | `qmd@qmd` | Wiki search MCP + `qmd` CLI binary | | `caveman@caveman` | Compressed output style | | `context7@claude-plugins-official` | Live library doc fetching | | `code-review@claude-plugins-official` | PR review skills | | `feature-dev@claude-plugins-official` | Guided feature development | | `ralph-loop@claude-plugins-official` | Long-running autonomous agent loops | Plugin cache: `~/.claude/plugins/cache/` — downloaded fresh, not in dotfiles. **The `qmd` CLI comes from the plugin**, not npm. After this step, `qmd` is in PATH. *** ## Step 6: Build wiki LightRAG index (one-time) ```bash theme={null} wiki-index --full ``` **Cost warning:** Uses Claude Haiku by default when `ANTHROPIC_API_KEY` is set. \~200 wiki pages costs \~$0.30–$0.80 *(claimed, unverified)*. To use local ollama instead (free, slower): ```bash theme={null} unset ANTHROPIC_API_KEY && wiki-index --full && export ANTHROPIC_API_KEY="sk-ant-..." ``` **Time:** 30–60 min with Haiku; 2–4 hours with local qwen2.5:3b. **Progress:** ```bash theme={null} tail -f ~/repos/llm-wiki/.lightrag/last-index.log ``` After this, the post-commit hook handles incremental updates automatically. *** ## Step 7: Verify ```bash theme={null} # Claude Code + plugins claude --version qmd query "agent orchestration" --limit 3 # Wiki binaries wiki-index --status wiki-chat --help # opencode opencode --version cat ~/.config/opencode/opencode.json | jq '.mcp | keys' # should include: "context7", "qmd", "wiki-rag" # Pi pi --version # headroom headroom --version # Gemini CLI gemini --version # Hooks ls ~/.claude/hooks/ # should include: context-threshold-check.sh, enforce-agent-whitelist.sh, # enforce-bash-safety.sh, judge-reminder.sh, lint-autofix.sh, etc. ``` *** ## Gotchas and ordering constraints | Constraint | Why | | ---------------------------------------------- | --------------------------------------------------------------- | | Clone llm-wiki before `stow` | dotfiles rule symlinks use absolute path `~/repos/llm-wiki/...` | | `ollama serve` before `install.sh` | install.sh pulls models — needs daemon running | | `claude --version` before `qmd` CLI | qmd binary comes from Claude Code plugin, not npm | | `uv` (install.sh) before `headroom-ai` | `uv tool install` requires uv | | `ANTHROPIC_API_KEY` before `wiki-index --full` | falls back to local model without it | | `$HOME/.local/bin` in PATH before `wiki-*` | install.sh copies binaries there | *** ## File ownership map ``` ~/.claude/ ← stow claude ~/.claude/CLAUDE.md ← real file in dotfiles ~/.claude/settings.json ← real file in dotfiles ~/.claude/rules/ ← mix: real files + symlinks → llm-wiki/claude-setup/rules/ ~/.claude/hooks/ ← real files in dotfiles ~/.claude/plugins/cache/ ← downloaded on first claude run (not in dotfiles) ~/.config/opencode/opencode.json ← stow opencode (paths fixed by sed in Step 3+7) ~/.config/opencode/plugins/ ← stow opencode ~/.gemini/GEMINI.md ← stow gemini ~/.gemini/settings.json ← stow gemini ~/.gemini/commands/ ← stow gemini ~/.codex/ ← stow codex ~/.local/bin/wiki-chat ← install.sh ~/.local/bin/wiki-index ← install.sh ~/.local/bin/wiki-mcp ← install.sh ~/repos/llm-wiki/.git/hooks/post-commit ← install.sh ~/repos/llm-wiki/.lightrag/ ← wiki-index --full ``` *** ## Related pages * [Headroom](/entities/headroom) — context compression modes (proxy, wrap, library, MCP) * [Pi Agent (pi-mono)](/entities/pi-agent) — pi CLI, council workflow, pueue delegation * [OpenCode](/entities/opencode) — opencode TUI, headless API, warm-server pattern * [Lean Agentic Coding Workflow](/syntheses/lean-agentic-workflow) — how these tools compose in practice * [Council Pattern](/concepts/council-pattern) — when/how to invoke multi-vendor review