⚙️ Cài đặt contextd cho Claude Code

Làm một lần (~5 phút), sau đó dùng được cho mọi dự án

Chạy được trên: Linux · macOS · Windows

Cần xem source đầy đủ? Mở trên GitHub

VIEN
Pre-flight 📥 Download (không cần Git) 1. Clone (có Git) 2. Run installer 3. Setup codebase Khi gặp lỗi thường gặp Update ← Onboarding
🪟 Windows / Bash 🔍 Lệnh không hiện 📂 Lỗi wiki_root 🏢 Workspace not found 🔒 Lỗi quyền

📋 Kiểm tra trước khi cài

Trước khi bắt đầu, bạn cần 3 thứ sau:

  • ✅ Claude Code CLI hoặc IDE extension đã cài + login (verify: gõ claude --version trong terminal hoặc thấy icon Claude trong VS Code/JetBrains)
  • ✅ Bash shell:
    • Linux/macOS: có sẵn (terminal default)
    • Windows: cài Git for Windows (bao gồm Git Bash) hoặc enable WSL
  • ✅ Git (verify: git --version)
  • ⚪ Optional: Python ≥ 3.9 (chỉ cần khi dùng scripts/validate.py + trace tools)

Nếu KHÔNG có Bash trên Windows → xem phần Khi gặp lỗi thường gặp phần "Windows native (không Bash)".

📥 Cách dễ nhất: Cài one-command từ latest release

Bạn chỉ cần 1 lệnh để tải + giải nén + cài tự động từ bản phát hành mới nhất trên GitHub.

Linux / macOS one-liner 
curl -fsSL https://github.com/philngt/contextd/releases/latest/download/install.sh | sh
Windows PowerShell one-liner 
iwr https://github.com/philngt/contextd/releases/latest/download/install.ps1 -UseBasicParsing | iex

Các URL này luôn trỏ tới installer mới nhất đã publish.

Hoặc tải zip thủ công nếu cần, rồi chạy installer như cũ.

⬇️ Download contextd-latest.zip

Link này hoạt động khi bạn mở file trên máy hoặc host thư mục có chứa release/.

1

Giải nén zip

Giải nén vào thư mục tuỳ ý — vd ~/wiki trên Linux/macOS hoặc D:\tool\wiki-template trên Windows.

mkdir -p ~/wiki && unzip contextd-latest.zip -d ~/wiki
# Zip chứa folder gốc 'wiki-template' → unzip sẽ tạo ~/wiki/wiki-template/
cd ~/wiki/wiki-template
# PowerShell
Expand-Archive -Path contextd-latest.zip -DestinationPath D:\tool
# Tạo D:\tool\wiki-template\
cd D:\tool\wiki-template

# Hoặc Git Bash
unzip contextd-latest.zip -d /d/tool

Hoặc click chuột phải file zip → "Extract All..." trong File Explorer.

2

Chạy trình cài đặt

Giống Step 2 cách Git clone — file scripts/install-to-claude.sh đã có trong zip:

bash scripts/install-to-claude.sh

Verify giống cách Git: cat ~/.claude/wiki-global.json phải thấy "wiki_root" đúng path bạn vừa extract.

3

Setup codebase

Giống Step 3 bên dưới — gõ /contextd-setup trong codebase.

⚠️ Cập nhật sau này: phải download zip mới mỗi lần update — KHÔNG có git pull. Khuyên dùng dùng cách Git clone nếu bạn sẽ update thường xuyên.
💡 Cho quản trị: tạo zip mới bằng bash scripts/package-release.sh. Output ghi vào release/wiki-template-{version}.zip + release/contextd-latest.zip. Auto-exclude .git/, evidence raw, workspaces khác wiki/, runs/cache/log files. Xem scripts/package-release.sh --help.

🔧 Cách ổn định cho người dùng kỹ thuật: Git clone

Nếu bạn có Git và muốn cập nhật dễ hơn về sau, dùng cách này.

1

Tải repo về máy

Chọn 1 thư mục gốc tuỳ ý — vd ~/wiki trên Linux/macOS hoặc D:\tool\wiki-template trên Windows.

git clone https://github.com/philngt/contextd ~/contextd
cd ~/contextd
git clone https://github.com/philngt/contextd /d/tool/contextd
cd /d/tool/contextd

Trong Git Bash, Windows path D:\tool\ viết là /d/tool/ (forward slash).

Repo này KHÔNG cần build, KHÔNG cần install dependency — chỉ là markdown + bash scripts.

2

Chạy trình cài đặt

Chạy 1 lệnh sau (có thể chạy lại nhiều lần, vẫn an toàn):

bash scripts/install-to-claude.sh

Lệnh này sẽ tự làm 3 việc:

  • Sync slash commands + subagents vào ~/.claude/commands/ và ~/.claude/agents/ — Claude Code tự đọc folder này
  • Tạo ~/.claude/wiki-global.json với wiki_root trỏ về repo bạn vừa clone
  • An toàn khi chạy lại: chạy lại sau mỗi git pull để cập nhật slash mới

Kiểm tra cài đặt

Kiểm tra cấu hình đã đúng đường dẫn:

cat ~/.claude/wiki-global.json
# PowerShell
type $env:USERPROFILE\.claude\wiki-global.json

# Hoặc Git Bash
cat ~/.claude/wiki-global.json

Phải thấy field "wiki_root" với absolute path đúng repo bạn vừa clone. Vd:

{
  "wiki_root": "/home/user/wiki",
  "default_workspace": null,
  "obsidian": { ... }
}

Mở Claude Code, gõ /contextd-setup → nếu slash command hiện ra trong autocomplete = OK.

3

Kết nối vào dự án đầu tiên

Vào thư mục codebase bạn muốn dùng wiki, mở Claude Code (hoặc IDE extension) tại đó, gõ:

/contextd-setup

Hệ thống sẽ hướng dẫn bạn từng bước:

  • Tự nhận diện tên dự án + loại công nghệ từ package.json / pom.xml / Cargo.toml / ...
  • Hỏi chọn workspace có sẵn — hoặc tạo workspace mới qua /new-workspace {name}
  • Bước 4.5 (Manage packs): hiện checkbox UI cho mọi pack có sẵn; auto-detect và pre-tick theo stack
  • Tạo <codebase>/.claude/wiki.json với cấu hình hoàn chỉnh + packs override per-codebase
💡 Mỗi dự án chỉ cần chạy 1 lần. Sau đó wiki tự work — bạn chỉ gõ slash command bình thường (/use-contextd, /find, /tool-design, ...).

Tiếp theo: mở index.html để chọn đường đi theo persona (PM / Engineer / Wiki Owner / Solo Builder).

🔧 Khi gặp lỗi thường gặp

Windows không có Bash

Nếu bạn chưa có Git Bash hoặc WSL, làm thủ công 4 bước sau:

  1. Copy templates\wiki-global.json → %USERPROFILE%\.claude\wiki-global.json
  2. Mở file vừa copy bằng Notepad, sửa "wiki_root" thành absolute path tới repo. Nhớ dùng \\ thay cho \: 
    {
  "wiki_root": "D:\\tool\\wiki-template",
  ...
}
  3. Copy folder .claude\commands\ và .claude\agents\ sang %USERPROFILE%\.claude\: 
    xcopy /E /I /Y .claude\commands %USERPROFILE%\.claude\commands
xcopy /E /I /Y .claude\agents %USERPROFILE%\.claude\agents
  4. Verify: type %USERPROFILE%\.claude\wiki-global.json

Khuyên dùng: cài Git for Windows (free) để có Git Bash → installer chạy 1 lệnh đơn giản hơn nhiều.

Lệnh không hiện trong Claude Code

Lỗi wiki_root not found khi gõ slash

/contextd-setup báo "workspace not found"

Lỗi quyền khi chạy trình cài đặt

🔄 Cập nhật sau này

Sau mỗi git pull trên repo wiki-template, re-run installer để sync slash commands mới:

cd ~/wiki
git pull
bash scripts/install-to-claude.sh   # idempotent — cập nhật tất cả
💡 Khi nào cần cập nhật?
  • Wiki-template repo có slash command mới (vd /tool-design mới ship)
  • Có pack mới được thêm vào packs/
  • Engine constraints / coding-rules update (validator rules mới)

Workspaces của bạn (workspaces/{your-ws}/) là dữ liệu — KHÔNG bị ảnh hưởng bởi update engine.

← Quay về Onboarding QUICKSTART.md (text) README.md GitHub Repository