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 embeddings)
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 OPENCODE_GO_API_KEY_LIGHTRAG="..."  # required for wiki-index/wiki-chat/wiki-mcp (OpenCode Go)
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; needs OPENCODE_GO_API_KEY_LIGHTRAG; can hit OpenCode Go usage limits)
wiki-index --full --yes

---

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

curl -fsSL https://ollama.com/install.sh | sh
ollama serve &     # start daemon before install.sh runs

Model pulled by install.sh:

• nomic-embed-text — embeddings for qmd and LightRAG

No local LLM is pulled: LightRAG extraction and synthesis use OpenCode Go. A self-hosted llama.cpp server is planned for the LLM (LLAMACPP_BASE_URL slot reserved, not wired yet) and later for embeddings, which stay on ollama until then (OpenCode has no embeddings endpoint).

---

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
export OPENCODE_GO_API_KEY_LIGHTRAG="..." # required: wiki-index + wiki-chat + wiki-mcp backend (OpenCode Go)
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
OPENCODE_GO_API_KEY_LIGHTRAG	wiki-index extraction, wiki-chat and wiki-mcp synthesis (OpenCode Go, OpenAI-compatible; unset → no backend, error)
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 the ollama embedding model: nomic-embed-text

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 --test          # verify the OpenCode Go key first
wiki-index --full --yes

Usage warning: Requires OPENCODE_GO_API_KEY_LIGHTRAG; without it wiki-index exits with an error before touching the index. A full build runs several LLM calls per page and can exhaust the plan’s 5-hour usage limit (limits), hence --yes.

Time: not measured with OpenCode Go.

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
OPENCODE_GO_API_KEY_LIGHTRAG before wiki-index --full	no local fallback: wiki-index exits with an error 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