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

# 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 [e-mail]:vietbui1999ru/llm-wiki.git ~/repos/llm-wiki
git clone [e-mail]: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

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)

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)

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/.

mkdir -p ~/repos

# llm-wiki FIRST
git clone [e-mail]:vietbui1999ru/llm-wiki.git ~/repos/llm-wiki

# dotfiles second
git clone [e-mail]: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:

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:

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:

cat ~/.config/opencode/opencode.json | head -5   # should show $schema line

---

Step 3: Set environment variables

Add to ~/.zshrc:

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

npm install -g @anthropic-ai/claude-code
claude --version

Pi (council Voice B + AFK loop worker)

npm install -g @earendil-works/pi-coding-agent
pi --version

Pi is used as a stateless subprocess in the council workflow:

pi -p "Peer review: [decision]. Flag concerns." \
   --model openai-codex/gpt-5.3-codex \
   --no-session --no-extensions --no-skills

opencode

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

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:

gemini auth login

Wiki toolchain (uv + wiki-chat/index/mcp + git hook + ollama models)

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:

uv tool install headroom-ai
headroom --version

Usage patterns:

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 for deployment modes and CCR details.

---

Step 5: First Claude Code run — plugin installation

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)

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):

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:

tail -f ~/repos/llm-wiki/.lightrag/last-index.log

After this, the post-commit hook handles incremental updates automatically.

---

Step 7: Verify

# 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 — context compression modes (proxy, wrap, library, MCP)
• Pi Agent (pi-mono) — pi CLI, council workflow, pueue delegation
• OpenCode — opencode TUI, headless API, warm-server pattern
• Lean Agentic Coding Workflow — how these tools compose in practice
• Council Pattern — when/how to invoke multi-vendor review