Admins

Describes Xaden v0.2.3, released 2026-10-13.

Prerequisites

Optional: assistant add-ons

The add-ons in the table above are third-party; the scaffold installs none of them, and your project’s AGENTS.md takes precedence over each. Install commands, sources, licenses and the risks to know before installing are in the Optional tools section “Assistant plugins”.

Install

Xaden runs from one folder on your machine and gives you one command, xaden. Install it once; every other command in these docs uses it. First get the files (clone or zip), then run the installer.

Get the files

Clone with git (recommended, because git pull updates Xaden later):

git clone https://github.com/flo1o1/xaden.git ~/.xaden

• git clone ...: downloads Xaden into the hidden folder .xaden in your home directory.

Or download the release as a zip (no git history; you update by downloading a newer release):

curl -fsSL -o xaden.zip https://github.com/flo1o1/xaden/archive/refs/tags/v0.2.3.zip
unzip -q xaden.zip -d ~/tools

• curl ...: downloads the archive of release v0.2.3 into the current folder and stops with an error if the download fails.
• unzip ...: extracts it into ~/tools/xaden-0.2.3. If unzip is missing, install it with your package manager.

Xaden publishes no checksums or signatures. Download only from the address above over HTTPS and read the scripts you are about to run: they are plain shell.

Install the command

~/.xaden/scripts/install.sh

• ~/.xaden/scripts/install.sh: creates one link, ~/.local/bin/xaden, that points into the Xaden folder. It changes nothing else and never replaces a different file of that name. Keep the folder where it is, because the link points into it.

If you downloaded the zip, run the installer from that folder instead: ~/tools/xaden-0.2.3/scripts/install.sh.

If ~/.local/bin is not on your PATH, the installer says so. Add this line to your shell profile (~/.bashrc for bash, ~/.zshrc for zsh) and open a new terminal:

export PATH="$HOME/.local/bin:$PATH"

• export PATH=...: puts ~/.local/bin in front of the folders your shell searches for commands, so it finds xaden.

Check the result:

xaden version

• xaden version: prints the installed Xaden version, 0.2.3 for this release.

Update Xaden

If you cloned it:

git -C ~/.xaden pull

• git -C ~/.xaden pull: fetches the newest Xaden into the folder. The xaden command keeps working. To stay on a fixed release instead of the newest code, run git -C ~/.xaden tag -l to list the releases and git -C ~/.xaden checkout v0.2.3 (use the release you want) to switch; switch back with git -C ~/.xaden checkout main before the next pull.

If you downloaded the zip, get the new release and extract it next to the old one. Then move the command over:

~/tools/xaden-OLD/scripts/install.sh --uninstall
~/tools/xaden-NEW/scripts/install.sh
rm -r ~/tools/xaden-OLD

• ~/tools/xaden-OLD/scripts/install.sh --uninstall: removes the xaden link, but only if it points into the old folder. Replace OLD with the old version, for example 0.2.2.
• ~/tools/xaden-NEW/scripts/install.sh: links xaden to the new folder. Replace NEW with the new version.
• rm -r ~/tools/xaden-OLD: deletes the old folder once the new link works.

Linux

git, bash, awk, sed, tar, grep and cksum are normally preinstalled. Install a missing one with your distribution’s package manager.

macOS

bash 3.2, the version macOS ships, is supported. If git is missing, running it once offers to install Apple’s command line tools. The default shell is zsh, so the PATH line goes into ~/.zshrc.

Windows

Untested: nobody has run these steps on Windows yet, so expect to adapt them. WSL is recommended: open a WSL shell and follow the Linux steps, keeping Xaden and your projects in the Linux file system (your WSL home directory) rather than under /mnt/c. Git Bash is also possible but untested. Native PowerShell is not supported, because the scripts are bash.

The xaden command

scripts/install.sh links xaden into ~/.local/bin (or the directory you pass) so you can use Xaden from any directory. It writes nothing else; git pull in the checkout updates the command, and scripts/install.sh --uninstall removes the link. If the directory is not on your PATH, the script prints the line to add to your shell profile. Keep the checkout where it is: the link points into it. Every command in these docs assumes the command is installed.

Project commands run that project’s scripts, just as typing them would: use them only in projects you trust.

Optional tools

Extra checks that make code more robust where they fit. None is required. xaden check (full run) prints a TIP: line for each one that fits this project and is not adopted yet; tips never change the result. Once adopted, the check runs it and its findings fail the run like any other check. Ask the user before installing anything.

Quality checks

Starting configurations (adjust paths to the project):

# pyproject.toml
[tool.vulture]
paths = ["src", "tests"]
min_confidence = 80

{ "threshold": 5, "ignore": ["**/node_modules/**", "**/.venv/**"] }

The second block is .jscpd.json: the run fails when more than 5 % of the code is duplicated. Lower the threshold as duplication goes down; raising it needs the user’s approval. False positives of vulture go into a whitelist file (vulture --make-whitelist) listed in paths.

When to use which test technique: docs/clean-code.md → Tests.

Assistant plugins (Claude Code)

Public plugins that add depth to reviews. They are optional, and this project’s AGENTS.md takes precedence over them. Install from the named sources only.

Before installing one, read its notes:

• Ponytail: its hooks need node on your PATH. Other tools (Codex, Copilot CLI, Cursor): follow the project’s INSTALL.md; tools that only read a rules file can use its AGENTS.md. Do not replace this project’s AGENTS.md with it. Sources: DietrichGebert/ponytail on GitHub, @dietrichgebert/ponytail on npm.
• Caveman: its hooks need node on your PATH; other tools follow its INSTALL.md. It switches back to full sentences for security warnings and irreversible actions. Keep project files in normal prose: do not run its /caveman-compress on AGENTS.md, CLAUDE.md, requirements or guides, and do not commit the always-on rule files /caveman-init writes.
• Token Optimizer: run /token-optimizer once after installing to set up its hooks. License: PolyForm Noncommercial 1.0.0 plus a written small-business permission (fewer than 5 people and under $20k monthly revenue, counted for the whole company); other commercial use needs a paid license, so check that your use qualifies. It keeps full tool output on disk in your home directory (private file permissions; credentials removed by pattern only), so never print secrets in a session.
• Output compression (Caveman, Token Optimizer): compressed output is a summary. A completion report must quote failing lines from the full output (rerun the check or expand the archived result). Use one output-compression plugin at a time.
• claude-mem: other tools install with npx claude-mem install --ide <tool>. It installs Bun and uv if missing, runs a local worker service and stores sessions in ~/.claude-mem, so never print secrets in a session (use its <private> tags for sensitive text). Its installer offers a hosted memory service (the claude-mem observer, sign-in required) that receives session content: choose your Anthropic plan or your own model key when code must not leave your assistant’s provider, or set CLAUDE_MEM_ONLINE_OPTIN=false. Its memories are context: requirements and rules are still looked up in the files.
• obsidian-skills: Codex, OpenCode and others follow its README. Use Obsidian syntax in prompts/ only; AGENTS.md, requirements and guides stay plain Markdown, because other assistants and the check scripts read them. Web pages its defuddle part extracts are untrusted content.
• impeccable: other tools install with npx impeccable install. It runs a binary engine that is downloaded once to ~/.impeccable/bin/. Both routes add an assistant hook that checks UI files after each edit; the project install writes it into the project’s tool folders (.claude/ and others), so committing them gives it to every contributor. Skip it with npx impeccable install --no-hooks. Starting a new design always asks impeccable.style for design options and by default records which one was chosen (anonymous; no project files or code). Opt out per machine with DO_NOT_TRACK=1, or for everyone with "telemetry": false in .impeccable/config.json. Its findings are suggestions; this project’s checks decide.

Not recommended: frameworks that bring their own complete workflow (for example Superpowers, with its own brainstorm, plan, TDD and review phases). They duplicate the workflow in AGENTS.md and prompts/, and two workflows give the assistant conflicting instructions.

Update a project

Pull the newest Xaden (git pull in its folder), then run this inside your project:

xaden update
xaden update --apply

• xaden update: dry run, lists what would change
• xaden update --apply: stages the changes; review them with git diff --cached

Only scaffold-managed files (scripts, prompts, presets, rules, commands, Claude Code permissions in .claude/settings.json) are updated; code, requirements, guides, README and changelog are never touched. Merge any *.scaffold-new files it reports (your local edits are never overwritten), then commit chore(scaffold): update to vX.Y.Z. Each project records its scaffold version in .scaffold/.

Projects that still keep requirements in one docs/requirements/REQUIREMENTS.md table run scripts/migrate-requirements.sh after updating: it converts every row into a requirement file (job stories left as TODO to rewrite) and the checks then accept the new format.