Plugin Distribution

Sequant is available as a Claude Code plugin — install it directly from Claude Code without npm, and get skills, hooks, and MCP tools with zero configuration.

Prerequisites

1. Claude Code — claude.ai/code
2. GitHub CLI — gh auth status (authenticated)
3. Git — any recent version
4. Node.js 22.13+ — node --version (for MCP server via npx)

Setup

Install the plugin

In Claude Code:

/plugin marketplace add sequant-io/sequant
/plugin install sequant@sequant

This loads:

• 17 workflow skills (/assess, /spec, /exec, /qa, /fullsolve, etc.)
• Pre/post-tool hooks (security guardrails, timing, smart tests)
• MCP server (sequant_status, sequant_run, sequant_logs)

Configure your project

/sequant:setup

The setup skill:

• Checks prerequisites (git, gh, node)
• Creates .sequant/settings.json with defaults
• Detects your package manager and dev server URL
• Creates ../worktrees/feature/ directory
• Copies the constitution template to .claude/memory/
• Creates .sequant-manifest.json with stack info

What You Can Do

After setup, all sequant workflows are available:

/assess 123        # Analyze issue, get recommended workflow
/fullsolve 123     # End-to-end: spec → exec → qa → PR
/spec 123          # Plan implementation
/exec 123          # Implement in isolated worktree
/qa 123            # Code review and AC validation

MCP tools are also available for programmatic access:

sequant_status     # Check issue progress
sequant_run        # Execute workflow phases
sequant_logs       # Review past run results

What to Expect

• Plugin install: Instant — skills and hooks load immediately
• /sequant:setup: ~10 seconds — creates config and detects stack
• MCP server: Starts automatically via npx -y sequant@<version> serve (stdio transport), pinned to the plugin’s release version (#793)
• First /fullsolve: 10–30 minutes depending on issue complexity

Plugin vs npm

Capability	Plugin	npm
Skills (17 slash commands)	Yes	Yes (via sequant init)
Hooks (guardrails, timing)	Yes	Yes (via sequant init, unless the plugin ships them — see below)
MCP tools	Yes (auto)	Yes (via .mcp.json)
CLI (sequant run, sequant doctor)	No	Yes
CI/headless mode	No	Yes
TypeScript library exports	No	Yes

Plugin is for interactive Claude Code users. npm is for power users, CI pipelines, and programmatic access.

One hook channel per checkout

A checkout gets sequant’s hooks from one channel: the repo (.claude/hooks/*.sh, registered in .claude/settings.json) or the plugin (hooks/hooks.json). Claude Code runs both when both are present, so every tool call runs the guard twice.

• sequant init checks the enabled plugins first. If one ships a hooks/hooks.json that registers pre-tool.sh, init writes no .claude/hooks/ and no .claude/settings.json, records "hooks": "plugin" in .sequant-manifest.json, and prints one line saying so. sequant update and sequant sync then leave the hooks absent, and do not report them as drift. init --agent opencode and init --agent codex always write the repo hooks, because their wrappers run .claude/hooks/pre-tool.sh.
• sequant doctor runs a Hook channels check. It reads the project’s .claude/settings.json and the enabledPlugins maps in ~/.claude/settings.json, .claude/settings.json and .claude/settings.local.json. It resolves each enabled plugin through ~/.claude/plugins/installed_plugins.json and checks whether its install path has a hooks/hooks.json that registers pre-tool.sh. It does not go by the plugin’s name. The check fails when both channels are active, names both files, and gives the two fixes:
  • Disable the plugin in this checkout: set "sequant@sequant": false (or your plugin’s id) under enabledPlugins in .claude/settings.local.json.
  • Or remove the repo copy: delete .claude/hooks/ and the hooks entries in .claude/settings.json, then add "hooks": "plugin" to .sequant-manifest.json.

Keeping the plugin up to date

Plugins do not auto-update. Claude Code pins an install to the version (commit SHA) you installed it at and never moves it on its own — even as new releases ship. An install can silently run months-old skills and hooks while newer versions are available.

To pick up a new release, update the installed plugin and restart Claude Code:

claude plugin update sequant@sequant

Note the distinction from refreshing the marketplace listing:

Command	What it does
claude plugin update sequant@sequant	Updates the installed plugin to the latest marketplace version (restart Claude Code after).
/plugin marketplace update sequant-io/sequant	Refreshes only the local marketplace listing — it does not touch any installed plugin.

Staleness warning

pre-tool.sh compares the running plugin’s version against the local marketplace clone and prints a single warn-only line to stderr when the install falls behind:

sequant plugin v<installed> is stale (marketplace has v<latest>) — run: claude plugin update sequant@sequant, then restart Claude Code

The check is zero-network (grep/sed/awk only), never blocks the tool call, and is rate-limited to once per day via a stamp file. It only fires for real plugin-cache installs (paths under plugins/cache/) — repo-local dev copies never warn. See Plugin Updates & Versioning for the full versioning and auto-update opt-in details.

Configuration

After /sequant:setup, edit .sequant/settings.json to customize:

Setting	Description	Default
run.timeout	Max phase duration (seconds)	1800
run.qualityLoop	Auto-iterate on QA failures	false
run.maxIterations	Max quality loop iterations	3
run.smartTests	Auto-run tests after edits	true
run.pmRun	Package manager run command	auto-detected
run.devUrl	Dev server URL for /test	auto-detected
agents.parallel	Parallel sub-agent execution	false
agents.model	Sub-agent model (currently inert — see anthropics/claude-code#43869; kept for forward compatibility)	"haiku"

MCP Server Details

The plugin bundles an MCP server that starts automatically. The bundled .mcp.json pins sequant to the plugin’s release version (#793) — the build step stamps the concrete version in place of @latest, so an npx reconnect never re-resolves @latest (which was surfacing as -32000 after releases). You pick up a new version when you update the plugin:

{
  "sequant": {
    "command": "npx",
    "args": ["-y", "sequant@2.9.0", "serve"]
  }
}

Tools: sequant_status, sequant_run, sequant_logs Resources: sequant://state, sequant://config Transport: stdio (default, most compatible)

Log Storage

Hook logs are stored in the first location available:

1. Plugin users: ${CLAUDE_PLUGIN_DATA}/logs/ (persistent across updates)
2. npm/CI users: ${HOME}/.sequant/logs/ (persistent; one sink shared by the main repo and every worktree)
3. Last resort (no HOME): ${TMPDIR:-/tmp}/ — session-scoped, and macOS purges it

Log files: claude-timing.log, claude-hook.log, claude-quality.log, claude-tests.log

pre-tool.sh and post-tool.sh resolve this location with an identical block and share claude-timing.log (START from pre, END from post) and claude-quality.log. Changing the location in one hook without the other splits every START/END pair across two files (#763).

The log directory deliberately lives outside the repo: creating it inside one would make git status --porcelain non-empty, which silently defeats the pre-tool no-changes guard that reads exactly that output.

Troubleshooting

MCP tools not available after install

Symptoms: Skills work but sequant_status / sequant_run don’t appear.

Solution: Verify Node.js 22.13+ is installed (node --version). The MCP server requires npx which ships with Node.js. Restart Claude Code after installing Node.

/sequant:setup says “gh auth: not authenticated”

Symptoms: Prerequisites check fails on GitHub CLI.

Solution: Run gh auth login in your terminal, then re-run /sequant:setup.

Settings not being picked up

Symptoms: Changed .sequant/settings.json but behavior doesn’t change.

Solution: Verify the file is valid JSON (cat .sequant/settings.json | jq .). Settings are read fresh on each skill invocation — no restart needed.

Plugin install says “not found”

Symptoms: Installing with the GitHub owner/repo (sequant-io/sequant) directly after the @ fails with Plugin "sequant" not found in marketplace "sequant-io/sequant".

Solution: The part after @ is a marketplace name, not a GitHub repo — ours is named sequant, not sequant-io/sequant. Add the marketplace first, then install from it by name:

/plugin marketplace add sequant-io/sequant
/plugin install sequant@sequant

---

Generated for Issue #476 on 2026-03-27