⚙️ Install contextd

Install the runtime-neutral CLI first, then add only the host adapters you use.

Works on Linux · macOS · Windows

Need source code too? Open it on GitHub

VIEN
Pre-check 📥 Download (no Git needed) 1. Clone (with Git) 2. Run installer 3. Setup project Common issues Update ← Onboarding
🪟 Windows / Bash 🔍 No commands 📂 knowledge_root error 🏢 Workspace not found 🔒 Permission error

📋 Before you start

Before you start, check these basics:

  • ✅ Release CLI path: curl or wget on Linux/macOS; PowerShell on Windows.
  • ✅ Source/developer path: Git and Python ≥ 3.10.
  • ⚪ Claude adapter path only: Claude Code plus a Bash shell:
    • Linux/macOS: available by default (your standard terminal)
    • Windows: install Git for Windows (includes Git Bash) or enable WSL

The CLI, source checkout, and Claude adapters are separate install surfaces. Pick only the paths you need.

📥 Path A: Install the runtime-neutral CLI

Run one command to install the latest prebuilt CLI binary from 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

These URLs always point to the latest published installer assets.

Important: these one-liners install the contextd binary only. They do not install Claude slash commands and do not provide a knowledge root. Verify with contextd --version, then use an existing team knowledge root or follow the source path below.

Need the bundled default workspace, packs, or Claude adapters? Download the source zip below or use the Git clone path.

⬇️ Download contextd-latest.zip

This link works when opening files locally or when hosting a directory that includes release/.

1

Extract the zip

Extract to any folder — for example ~/wiki on Linux/macOS or D:\tool\contextd on Windows.

mkdir -p ~/wiki && unzip contextd-latest.zip -d ~/wiki
# The zip contains root folder 'contextd' → unzip creates ~/wiki/contextd/
cd ~/wiki/contextd
# PowerShell
Expand-Archive -Path contextd-latest.zip -DestinationPath D:\tool
# Creates D:\tool\contextd\
cd D:\tool\contextd

# Or Git Bash
unzip contextd-latest.zip -d /d/tool

Or right-click the zip file and choose "Extract All..." in File Explorer.

2

Install the CLI from source and optionally add Claude adapters

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

# Optional: only for Claude Code slash commands and subagents
bash scripts/install-to-claude.sh --knowledge-root "$(pwd)"

The Python command installs the CLI. The Bash script is a separate, optional Claude adapter installer.

3

Setup codebase

Continue to Connect your first project. Use contextd init for the CLI path or /contextd-setup after installing Claude adapters.

⚠️ Future updates: you must download a new zip for each update — there is no git pull. We recommend Git clone if you update often.
💡 For maintainers: create a new zip with bash scripts/package-release.sh. Output is written to release/contextd-{version}.zip + release/contextd-latest.zip. It automatically excludes .git/, raw evidence, workspaces other than default/, and runs/cache/log files. See scripts/package-release.sh --help.

🔧 Path B: Source/developer install

Use this path when editing contextd, using the bundled default workspace, or installing host adapters.

1

Download the repository

Choose any base folder — for example ~/wiki on Linux/macOS or D:\tool\contextd on 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

In Git Bash, Windows path D:\tool\ is written as /d/tool/ (forward slash).

The source checkout contains the Python CLI, workspace knowledge, packs, schemas, docs, and host adapter installers. Python ≥ 3.10 is required for the CLI.

2

Install the CLI, then optional Claude adapters

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

# Optional and safe to run multiple times:
bash scripts/install-to-claude.sh --knowledge-root "$(pwd)"

The optional Bash command does 3 Claude-specific things:

  • Syncs slash commands + subagents to ~/.claude/commands/ and ~/.claude/agents/ — Claude Code reads these folders automatically
  • Creates ~/.contextd/config.json and points knowledge_root to your cloned repo
  • Safe to run again: rerun after each git pull to refresh commands

Verify installation

Check that the config path is correct:

cat ~/.contextd/config.json
# PowerShell
	type $env:USERPROFILE\.contextd\config.json

# Or Git Bash
cat ~/.contextd/config.json

You should see field "knowledge_root" with an absolute path to your cloned repo. Example:

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

If you installed Claude adapters, open Claude Code and run /contextd-setup. Autocomplete confirms that adapter installation succeeded.

Optional MCP setup: generate a client snippet with contextd connect --client codex --knowledge-root "$(pwd)" --workspace default. See docs/mcp.md for Claude, Cursor, and Codex examples.
3

Connect your first project

For the runtime-neutral CLI, go to the codebase and run:

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 "describe your first task" --preview

If you installed Claude adapters, the equivalent guided setup is:

/contextd-setup

The setup flow guides you step by step:

  • Automatically detects project name + tech stack from package.json / pom.xml / Cargo.toml / ...
  • Prompts you to choose an existing workspace — or create a new workspace via /new-workspace {name}
  • Step 4.5 (Manage packs): shows checkboxes for all available packs; auto-detects and pre-selects based on stack
  • Creates <codebase>/.contextd/config.json with complete config + per-codebase pack overrides
💡 You only run this once per project. After that, contextd just works — you can use slash commands normally (/use-contextd, /find, /tool-design, ...).

Next: open index.html and choose a persona path (PM / Engineer / Wiki Owner / Solo Builder).

🔧 Common issues

Windows without Bash

The Windows release installer needs no Bash. If you specifically want Claude adapters without Git Bash or WSL, use these PowerShell steps from a source checkout:

  1. Create the canonical global config directory: 
    New-Item -ItemType Directory -Force "$env:USERPROFILE\.contextd"
  2. Write the correct global config shape; replace the path and workspace as needed: 
    @'
{
  "knowledge_root": "D:\\tool\\contextd",
  "default_workspace": "default"
}
'@ | Set-Content "$env:USERPROFILE\.contextd\config.json" -Encoding utf8
  3. Copy the adapter folders: 
    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"

Recommended: install Git for Windows (free) to get Git Bash → installer runs with one simple command.

Commands do not appear in Claude Code

Error knowledge_root not found when running slash commands

/contextd-setup shows "workspace not found"

Permission error when running installer

🔄 Future updates

For a release binary, rerun the release installer. For a source checkout, pull changes and refresh the CLI; rerun the adapter installer only if you use Claude:

cd ~/contextd
git pull
python3 -m pip install -e .
bash scripts/install-to-claude.sh --knowledge-root "$(pwd)"   # optional Claude adapter refresh
💡 When should you update?
  • The contextd repo has new slash commands (e.g. newly shipped /tool-design)
  • New packs were added to packs/
  • Engine constraints / coding-rules were updated (new validator rules)

Your workspaces (workspaces/{your-ws}/) are data — they are not affected by engine updates.

← Back to Onboarding QUICKSTART.md (text) README.md GitHub Repository