⚙️ Cài đặt contextd

Cài runtime-neutral CLI trước, sau đó chỉ thêm adapter cho host bạn thực sự dùng.

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

  • ✅ Đường release CLI: curl hoặc wget trên Linux/macOS; PowerShell trên Windows.
  • ✅ Đường source/developer: Git và Python ≥ 3.10.
  • ⚪ Chỉ đường Claude adapter: Claude Code cùng Bash shell:
    • Linux/macOS: có sẵn (terminal default)
    • Windows: cài Git for Windows (bao gồm Git Bash) hoặc enable WSL

CLI, source checkout và Claude adapters là ba bề mặt cài đặt riêng. Chỉ chọn những đường bạn cần.

📥 Đường A: Cài runtime-neutral CLI

Chạy một lệnh để cài CLI binary dựng sẵn mới nhất từ GitHub Releases.

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.

Lưu ý: các one-liner này chỉ cài binary contextd. Chúng không cài Claude slash commands và không cung cấp knowledge root. Verify bằng contextd --version, sau đó dùng knowledge root của team hoặc theo đường source bên dưới.

Cần default workspace, packs hoặc Claude adapters đi kèm? Tải source zip bên dưới hoặc dùng đường Git clone.

⬇️ 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\contextd trên Windows.

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

# 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

Cài CLI từ source và thêm Claude adapters nếu cần

python3 -m pip install -e .
contextd --version

# Optional: chỉ dành cho Claude Code slash commands và subagents
bash scripts/install-to-claude.sh --knowledge-root "$(pwd)"

Lệnh Python cài CLI. Bash script là installer Claude adapter riêng và không bắt buộc.

3

Setup codebase

Tiếp tục tới Kết nối project đầu tiên. Dùng contextd init cho CLI hoặc /contextd-setup sau khi cài Claude adapters.

⚠️ 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/contextd-{version}.zip + release/contextd-latest.zip. Auto-exclude .git/, evidence raw, workspaces khác default/, runs/cache/log files. Xem scripts/package-release.sh --help.

🔧 Đường B: Source/developer install

Dùng đường này khi sửa contextd, cần default workspace đi kèm hoặc muốn cài host adapters.

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\contextd 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).

Source checkout chứa Python CLI, workspace knowledge, packs, schemas, docs và host adapter installers. CLI yêu cầu Python ≥ 3.10.

2

Cài CLI, sau đó cài Claude adapters nếu cần

python3 -m pip install -e .
contextd --version

# Optional và an toàn khi chạy lại nhiều lần:
bash scripts/install-to-claude.sh --knowledge-root "$(pwd)"

Lệnh Bash optional làm 3 việc riêng cho Claude:

  • Sync slash commands + subagents vào ~/.claude/commands/ và ~/.claude/agents/ — Claude Code tự đọc folder này
  • Tạo ~/.contextd/config.json với knowledge_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 ~/.contextd/config.json
# PowerShell
	type $env:USERPROFILE\.contextd\config.json

# Hoặc Git Bash
cat ~/.contextd/config.json

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

{
  "knowledge_root": "/home/user/contextd",
  "default_workspace": null
}

Nếu đã cài Claude adapters, mở Claude Code và gõ /contextd-setup. Autocomplete xuất hiện nghĩa là adapter đã được cài.

Setup MCP tuỳ chọn: sinh snippet cho client bằng contextd connect --client codex --knowledge-root "$(pwd)" --workspace default. Xem docs/mcp.md cho ví dụ Claude, Cursor, và Codex.
3

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

Với runtime-neutral CLI, vào codebase và chạy:

cd /path/to/your-codebase
contextd init --knowledge-root /path/to/contextd-or-team-knowledge-root --workspace default
contextd check
contextd synapse --preview --text
contextd context "mô tả task đầu tiên" --preview

Nếu đã cài Claude adapters, setup có hướng dẫn tương đương là:

/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>/.contextd/config.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 đó contextd 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

Windows release installer không cần Bash. Nếu bạn muốn cài riêng Claude adapters mà không có Git Bash hoặc WSL, dùng PowerShell từ source checkout:

  1. Tạo thư mục global config chuẩn: 
    New-Item -ItemType Directory -Force "$env:USERPROFILE\.contextd"
  2. Ghi đúng global config shape; thay path và workspace khi cần: 
    @'
{
  "knowledge_root": "D:\\tool\\contextd",
  "default_workspace": "default"
}
'@ | Set-Content "$env:USERPROFILE\.contextd\config.json" -Encoding utf8
  3. Copy các folder adapter: 
    New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude"
Copy-Item -Recurse -Force .claude\commands "$env:USERPROFILE\.claude\commands"
Copy-Item -Recurse -Force .claude\agents "$env:USERPROFILE\.claude\agents"
  4. Verify: Get-Content "$env:USERPROFILE\.contextd\config.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 knowledge_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

Với release binary, chạy lại release installer. Với source checkout, pull rồi refresh CLI; chỉ chạy lại adapter installer nếu bạn dùng Claude:

cd ~/contextd
git pull
python3 -m pip install -e .
bash scripts/install-to-claude.sh --knowledge-root "$(pwd)"   # optional refresh Claude adapter
💡 Khi nào cần cập nhật?
  • Repo contextd 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