Install guide

Install Adams

You need Python 3.9+, Node 18+ and git. LibreOffice is optional, for pptx and docx checks.

Claude Code plugin

Two commands inside Claude Code, then start a new session. The skill appears as adams:adams, and /plugin lists what is installed.

Claude Code
/plugin marketplace add UpgradIQ/adams
/plugin install adams@adams

Paste into Claude Code, not your terminal.

Or from a terminal:

zsh
claude plugin marketplace add UpgradIQ/adams
claude plugin install adams@adams

Optional: adams-extras

Three modules most projects never need live in a second plugin from the same marketplace: innovation-builder, seo-architect and obsidian-vault-memory. It has its own skill, adams-extras:adams-extras, and no hooks. It uses the core plugin's rules and adams check, so install Adams first.

Claude Code
/plugin install adams-extras@adams

Paste into Claude Code, not your terminal.

Or from a terminal:

zsh
claude plugin install adams-extras@adams

A clone install does not link them. Point your tool at plugins/adams-extras in the clone, then restart the session.

Any terminal

Works in any shell and sets up Claude Code and Copilot CLI together. Preview with --dry-run first. Use one method, not both: if the plugin is enabled, adams install skips the skill link and hooks.

zsh
git clone https://github.com/UpgradIQ/adams.git ~/adams
~/adams/bin/adams install --dry-run
~/adams/bin/adams install
export PATH="$HOME/.local/bin:$PATH"
adams sync
adams doctor

Copilot CLI

The clone install links the skill into ~/.copilot/skills/adams. adams sync writes the Copilot instructions file, since Copilot has no prompt hook.

zsh
adams install
adams sync

Check your setup

adams doctor prints the installed version, what is missing and how to fix it. If your app does not load marketplace plugins, --link links the skill and registers the hooks anyway.

zsh
adams doctor
adams install --link

Ship loop

Optional, for work split into tasks that agents run in parallel, one pull request each. /ship commits this session's files by name, opens the PR and merges it once the fast checks pass. It needs the GitHub CLI (gh, signed in), and nothing runs until you call it.

Claude Code
/ship

Paste into Claude Code, not your terminal.

Or from a terminal:

zsh
adams ship all

Settings live in .adams/ship.json, every key optional: base, auto_merge, skip_checks, tracker, prompts_file, deps_field, risk and max_wait_minutes. High-risk PRs wait for your yes. It never force-pushes and never passes --admin.

  • adams ship PR: merge one PR
  • adams next: tasks ready to start
  • adams watch: your open PRs
  • adams track set: set a task status

Staying up to date

Claude Code does not auto-update third-party marketplaces by default. Turn it on once in /plugin inside Claude Code, under Marketplaces, then choose adams. A clone updates itself: a session-start hook runs at most once a day, follows release tags only and touches only a clean clone.

zsh
claude plugin marketplace update adams
claude plugin update adams@adams
adams update
adams update --check

The first two update a plugin install, then restart the session. adams update moves a clone now. --check only asks. Set ADAMS_AUTO_UPDATE=0 to opt out of the daily check.

Opting out

The gates block the first code edit until decisions are recorded, and block done and git commit until tests ran green. Set a switch in the environment before you start Claude Code.

zsh
export ADAMS_GATES=0     # every gate, leak guard
export ADAMS_VERIFY=0    # verification only
export ADAMS_STOP=0      # text, ledger, live check
export ADAMS_AGENT_BOX=0 # subagent time box
export ADAMS_NO_NOTIFY=1 # no desktop notices
adams schedule uninstall # stop clean and hygiene jobs
adams uninstall

Every deny message ends with its override. A small task satisfies the align gate with adams decide --small. adams uninstall removes exactly what install added.

What it touches

Read this before you install. There is no telemetry, and ADAMS_AUTO_INSTALL=0 forbids dependency installs.

  • Symlinks: skill, /ship and adams.
  • On a clone install, hook entries in ~/.claude/settings.json, which is backed up first.
  • Pinned layout tools on first use.
  • Only if you run adams schedule install: four user LaunchAgents for clean and hygiene.
  • No network calls from hooks except the daily release check on clone installs.