Claude Code Installation Guide

Install Citadel as a Claude Code plugin, verify the marketplace, write project hooks, and run setup from the target repo.

Sources: Claude Code's current plugin docs support marketplace discovery, local paths, GitHub sources, install scopes, and non-interactive claude plugin marketplace / claude plugin install commands. See Discover and install plugins, Create and distribute marketplaces, and Plugins reference.

Fast Path: Local Project Install

From the project where you want Citadel enabled:

git clone https://github.com/SethGammon/Citadel.git ~/Citadel
cd /path/to/your-project
node ~/Citadel/scripts/claude-install.js --install --scope local
claude

Then in Claude Code:

/do setup --express
/do --list
/do review path/to/file

Local scope is the safest default for trying Citadel: it installs the plugin for you in this repository only and avoids committing project-wide Claude settings.

What The Installer Does

scripts/claude-install.js --install --scope local wraps the manual Claude Code setup:

• validates .claude-plugin/marketplace.json and .claude-plugin/plugin.json
• runs claude plugin marketplace add <Citadel> --scope local
• runs claude plugin install citadel@citadel-local --scope local
• runs scripts/install-hooks.js <project> so .claude/settings.json gets resolved absolute hook paths
• prints the next Claude Code commands to run

Useful variants:

node ~/Citadel/scripts/claude-install.js --dry-run --json
node ~/Citadel/scripts/claude-install.js --add-marketplace --scope user
node ~/Citadel/scripts/claude-install.js --install-plugin --scope project
node ~/Citadel/scripts/install.js --runtime claude --install --scope local
npm run claude:install -- --install --scope local

Manual Install

Inside Claude Code:

/plugin marketplace add /path/to/Citadel
/plugin install citadel@citadel-local --scope local

Or from the shell:

claude plugin marketplace add /path/to/Citadel --scope local
claude plugin install citadel@citadel-local --scope local
node /path/to/Citadel/scripts/install-hooks.js /path/to/your-project

For a one-session trial without registering a marketplace:

cd /path/to/your-project
claude --plugin-dir /path/to/Citadel

GitHub Marketplace Install

If you want Claude Code to fetch Citadel from GitHub instead of a local clone:

claude plugin marketplace add SethGammon/Citadel --scope local
claude plugin install citadel@citadel-local --scope local

You still need to run /do setup --express in the target project so Citadel can detect the stack, initialize state, and refresh hooks.

Verify

Expected project files after the installer and /do setup:

CLAUDE.md
AGENTS.md
.claude/settings.json
.claude/harness.json
.planning/
.citadel/

Fast checks:

claude plugin validate /path/to/Citadel
node /path/to/Citadel/scripts/test-installers.js

In Claude Code:

/do --list
/do review path/to/file

Troubleshooting

Hooks are not firing

Re-run the installer from the target project:

node /path/to/Citadel/scripts/claude-install.js --install --scope local

Or install only hooks:

node /path/to/Citadel/scripts/install-hooks.js /path/to/your-project

Claude says the plugin is not found

Refresh the marketplace and install again:

claude plugin marketplace update citadel-local
claude plugin install citadel@citadel-local --scope local

If the local clone moved, run:

claude plugin marketplace remove citadel-local
claude plugin marketplace add /new/path/to/Citadel --scope local

Setup runs in the wrong project

Start Claude Code from the actual target project root. Setup detects stack files such as package.json, tsconfig.json, Cargo.toml, and similar project markers.

You want a team-shared install

Use --scope project only when you intentionally want Claude Code plugin settings shared through the repository:

node /path/to/Citadel/scripts/claude-install.js --install --scope project

Review the settings diff before committing.