Troubleshooting Guide

Common issues and solutions when using Sequant.

Worktree Issues

”Branch already exists” error

Problem: Creating a new feature worktree fails with “branch already exists”.

Solutions:

1. Check if worktree already exists:

   git worktree list

2. If worktree exists but is stale, remove it:

   # Remove the worktree directory
   rm -rf ../worktrees/feature/<issue-number>-*
   
   # Prune worktree references
   git worktree prune

3. If branch exists without worktree, delete the branch:

   git branch -D feature/<issue-number>-*

Orphaned worktrees after failed runs

Problem: Failed /exec or /fullsolve leaves behind orphaned worktrees.

Solutions:

1. List all worktrees to find orphans:

   git worktree list
   ls ../worktrees/feature/

2. Clean up using the cleanup script:

   ./scripts/cleanup-worktree.sh 'feature/<issue-number>-*'
   # Quote the glob — the script resolves the pattern itself, and zsh aborts
   # on an unmatched unquoted glob before the script ever runs.
   # Local worktree + branch are always removed. The remote branch is deleted
   # only when the PR is merged — an unmerged PR's remote branch is left intact
   # so GitHub doesn't close the PR unmerged.
   # Add --yes to skip the prompt in automation; --delete-remote (or --force,
   # which also implies --yes) to drop an unmerged PR's remote branch anyway.
   # See: cleanup-worktree.sh --help

3. Or clean manually:

   rm -rf ../worktrees/feature/<issue-number>-*
   git worktree prune
   git branch -D feature/<issue-number>-*

Worktree not found during /qa or /exec

Problem: Skills report “worktree not found” even though work was started.

Solutions:

1. Verify the worktree path:

   ls ../worktrees/feature/ | grep <issue-number>

2. If path exists but skill can’t find it, specify explicitly:

   cd ../worktrees/feature/<issue-number>-*/
   # Then run skill from within the worktree

3. If worktree was accidentally deleted, recreate it:

   ./scripts/new-feature.sh <issue-number>

Commits landed on main instead of feature branch

Problem: After running /exec or /fullsolve, commits ended up on main instead of the feature branch. This can happen when sub-agents or shell context resets silently switch the working directory back to the main repo root.

Prevention: Both /exec and /fullsolve now include branch verification gates that block commits on main/master. If you see the error “On main — do NOT commit here”, navigate to the correct worktree before continuing.

Recovery if it already happened:

1. Check which commits need to move:

   git log --oneline main ^origin/main

2. Switch to the feature branch and cherry-pick:

   git checkout feature/<issue-number>-*
   git cherry-pick <commit-hash>

3. Remove the commits from main:

   git checkout main
   git reset --soft origin/main
   git stash  # save any uncommitted changes

---

Project Type Support

Using Sequant with non-Node.js projects

Context: Sequant is optimized for Node.js/TypeScript projects, but the core worktree workflow works with any git repository.

What works universally:

• /spec - Issue planning and AC extraction
• /exec - Implementation in isolated worktree
• /qa - Code review (adapts to project type)
• /fullsolve - Complete workflow orchestration
• Git worktree isolation

Node.js specific features:

• npm test / npm run build verification
• Hook-based test running (detects npm/yarn/pnpm/bun)
• Prettier formatting for JS/TS files

For non-Node.js projects:

1. Skills will attempt to detect your build/test commands
2. You may see warnings about missing package.json - these are safe to ignore
3. Customize test commands in your constitution:

   ## Project-Specific Notes
   - Build: `cargo build` (Rust) / `go build` (Go) / `pytest` (Python)
   - Test: `cargo test` / `go test ./...` / `pytest`

Stack guides available:

• Rust
• Python
• Go

---

Installation Issues (npm)

sequant: command not found

Problem: After installing, the sequant command isn’t recognized.

Solutions:

1. Ensure global npm bin is in your PATH:

   npm config get prefix
   # Add [prefix]/bin to your PATH

2. Use npx instead:

   npx sequant init

3. Reinstall globally:

   npm install -g sequant       # npm
   pnpm add -g sequant          # pnpm
   yarn global add sequant      # yarn
   bun add -g sequant           # bun

Stray $HOME/node_modules/sequant install

Problem: On startup the CLI prints:

!  Sequant is running from /Users/<you>/node_modules/sequant — this pollutes
   resolution for every subdirectory of your home directory.

   If accidental (usually is — one stray `npm install sequant` from ~ does it):
       remove /Users/<you>/node_modules
       remove $HOME/package.json and $HOME/package-lock.json

   If intentional: use `npm install -g sequant` or the Claude Code plugin.

Cause: A npm install sequant was run from $HOME at some point. Node’s module resolution walks up the directory tree, so every subdirectory of home now resolves to that stale copy before reaching the npx cache. The result: npx sequant from any project silently runs the home-stray version instead of the latest.

Solutions:

1. If you didn’t intend to install sequant in $HOME:

   rm -rf "$HOME/node_modules"
   rm -f "$HOME/package.json" "$HOME/package-lock.json"

   Re-run npx sequant@latest <command> — resolution now falls through to the npx cache.

2. If you genuinely want sequant available everywhere, install it the right way:

   npm install -g sequant

   Or use the Claude Code plugin, which doesn’t rely on Node’s node_modules walk-up at all.

The warning only fires when the resolved install path is exactly $HOME/node_modules/sequant. Legitimate project-local installs (<project>/node_modules/sequant), global installs, and npx cache paths are not flagged.

Permission errors during install

Problem: EACCES permission denied errors.

Solutions:

1. Use a Node version manager (recommended):

   # Using nvm
   nvm install --lts
   nvm use --lts
   npm install -g sequant

2. Fix npm permissions:

   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   # Add ~/.npm-global/bin to PATH

Initialization Issues

Stack not detected

Problem: sequant init doesn’t detect your project stack.

Solutions:

1. Specify the stack manually:

   sequant init --stack nextjs

2. Ensure detection files exist:

   • Next.js: next.config.js or next in package.json
   • Rust: Cargo.toml
   • Python: pyproject.toml or requirements.txt
   • Go: go.mod

Already initialized error

Problem: Error saying Sequant is already initialized.

Solutions:

1. Use force flag to reinitialize:

   sequant init --force

2. Or remove existing config:

   rm -rf .claude .sequant-manifest.json
   sequant init

Skill Execution Issues

Skills not recognized

Problem: /spec or other skills aren’t recognized in Claude Code.

Solutions:

1. Verify skills are installed:

   ls .claude/skills/

2. Run doctor to check installation:

   sequant doctor

3. Restart Claude Code to reload skills.

Run fails with “Skills pre-flight failed”

Problem: sequant run exits immediately with ✖ Skills pre-flight failed: missing .claude/skills/ directory (or a list of missing skills).

Cause: .claude/skills/ is a hard runtime dependency of sequant run — phase agents load skills from the project directory only, so user-scope or plugin installs cannot substitute for it. The directory is easy to lose in consumer projects because it is untracked by default (an untracked-file cleanup deletes it silently).

Solutions:

1. Reinstall the skills:

   sequant sync --only skills

2. Commit .claude/skills/ to your repository so a fresh checkout keeps working:

   git add .claude/skills && git commit -m "chore: track sequant skills"

Note: The pre-flight only applies to drivers that resolve skills (the default claude-code driver). Aider runs are unaffected.

When the message names the main checkout (the main checkout at … is missing .claude/skills/spec/SKILL.md): spec runs in your main checkout, not a worktree, so its skill must be present there. Committing the skills will not help if they are already committed. Update the checkout (git pull on the base branch) or run sequant sync --only skills in it, then re-run. No worktree was created, so there is nothing to clean up.

Phases behave like an older sequant after sync

Symptoms: You ran sequant sync (or update), but sequant run phases still follow the old skill text. For example, exec opens the PR itself, or QA has no follow-up ledger. sequant run, doctor, sync and update print N tracked files under .claude/skills/ have uncommitted changes; ... phases will use the committed skills (<version>).

Cause: sequant run checks each phase worktree out from git, so phases load the skills committed at HEAD, not the files on disk in your main checkout. A sync that was never committed never reaches a run. The Skills are outdated (X → Y) line reads the version file on disk, so before v2.20 it could name a version the phases weren’t using (#1354).

Solution: Commit the sync, then run again:

git add .claude/skills .sequant-manifest.json
git commit -m "chore(sequant): sync skills"

If an issue’s worktree already exists, merge your base branch into its branch too (git -C <worktree> merge origin/<base>). A reused worktree keeps the skills from the commit it was cut from, and sequant run merges the base in only after the phases, before it updates the PR.

Spec fails with “spec produced no SEQUANT_SPEC marker”

Problem: The spec phase ran to completion, but the run records it as failed with spec produced no SEQUANT_SPEC marker … the /spec skill likely did not load.

Cause: The /spec skill ends by emitting a <!-- SEQUANT_SPEC: {...} --> marker, and sequant run reads it to pick the next phases. If the agent could not load the skill, it writes a plan by hand from the phase prompt and emits no marker. Sequant used to record that as success.

Solution: Check that .claude/skills/spec/SKILL.md exists in the checkout named in the error. That is your main checkout, which may be behind origin/<base> (the run warns about this before spec starts). Run git pull there, or sequant sync --only skills, then re-run.

Permission denied on hooks

Problem: Hook scripts fail with permission errors.

Solutions:

1. Make hooks executable:

   chmod +x .claude/hooks/*.sh

2. Run doctor with fix:

   sequant doctor --fix

Run Command Issues

claude command not found

Problem: npx sequant run fails because claude CLI isn’t available.

Solutions:

1. Install Claude Code CLI:

   # Follow Claude Code installation instructions

2. Verify installation:

   claude --version

3. Use dry-run to test without execution:

   npx sequant run 123 --dry-run

Timeout errors

Problem: Phases timeout before completing.

Solutions:

1. Increase timeout:

   npx sequant run 123 --timeout 3600  # 1 hour

2. Or set via environment:

   PHASE_TIMEOUT=3600 npx sequant run 123

GitHub CLI not authenticated

Problem: Skills fail when trying to access GitHub issues.

Solutions:

1. Authenticate GitHub CLI:

   gh auth login

2. Verify authentication:

   gh auth status

Claude Code process exited with code 1

Problem: sequant run fails with “Claude Code process exited with code 1” during a phase.

Causes:

• Outdated sequant version in local node_modules
• MCP server configuration issues
• Invalid project settings in .claude/settings.json

Solutions:

1. Update sequant to latest version:

   npx sequant@latest run 123
   # or update your local install with your package manager
   # npm update sequant / pnpm update sequant / bun update sequant
   # yarn 2+: yarn up sequant / yarn 1: yarn upgrade sequant

2. Try running without MCP servers to isolate the issue:

   npx sequant run 123 --no-mcp

3. Run with verbose mode to see detailed error output:

   npx sequant run 123 -v

4. Check for invalid hook scripts in .claude/hooks/:

   # Test hooks manually
   echo '{}' | .claude/hooks/pre-tool.sh

5. Verify Claude Code CLI works standalone:

   claude --version
   claude -p "Say hello" --print

MCP Server Issues

MCP server dies with CONNECTION_CLOSED — a local sequant shadows the pin

Problem: /mcp reports:

Failed to reconnect to plugin:sequant:sequant: CONNECTION_CLOSED

Cause: The plugin launches the server with npx -y sequant@<pin> serve, and npx resolves packages by walking up from the launch cwd looking for a node_modules/sequant before it ever considers the pinned spec. If the open project has any sequant in its own node_modules — commonly a stale "sequant": "^1.x" devDependency nobody imports — npx silently runs that local copy instead of the pin. A pre-serve version prints unknown command 'serve' and exits, so the MCP handshake never completes and Claude Code reports only the generic CONNECTION_CLOSED. No --prefix or other npx flag defeats this; only the working directory does.

Diagnosis: From the project root, compare what actually runs against the pinned version:

cd <project> && npx -y sequant@<pin> --version
# Prints the shadowed local version, not <pin>, if this is the cause

sequant doctor also flags this: a Local sequant shadow warning names the shadowing path and both versions.

Fix: Remove or upgrade the shadowing local copy:

npm uninstall sequant   # if it's not actually used by the project
# or
npm install sequant@latest   # to match the plugin's pin

The plugin itself (v2.16.0+) ships scripts/mcp-launch.mjs inline in .mcp.json (no file path, no ${...} placeholder) and spawns npx from an isolated temp directory precisely so this shadowing can’t happen for plugin-managed connections — this failure mode is now specific to older plugin versions or manually-configured .mcp.json/client configs that still invoke npx directly from the project directory. Since #1089, sequant init writes the same inline launcher into project and client configs, and sequant update / sequant sync migrate an existing npx -y sequant@<pin> serve entry to it — run sequant update in the affected project. See MCP Server → How the plugin avoids shadowing for how the launcher separates “where npx resolves packages from” (an isolated temp dir) from “which project sequant operates on” (SEQUANT_PROJECT_DIR).

MCP server won’t (re)connect — Failed to reconnect: -32000

Problem: Claude Code fails to start or reconnect the sequant MCP server, most often reported through /plugin or /mcp as Failed to reconnect to sequant: -32000. The -32000 is a generic JSON-RPC transport error — it means the server process never came up, not that sequant itself crashed.

Most common cause — a corrupted npx cache slot. The .mcp.json launches the server with npx -y sequant@<version> serve. Any time npx has to (re)install that package, a half-written or interrupted cache can turn into a hard failure. This is most likely with an sequant@latest config (the pre-#793 default, and still what an un-updated install carries), because @latest forces npx to re-resolve and reinstall whenever the published latest changes — so the reconnect right after a sequant release is exactly when it bites. Sequant now pins a concrete version by default (see MCP Server → Version pinning), which removes that per-release reinstall; run sequant update (or update the plugin) to move an old @latest config onto a pin. The underlying error is an npm bug — an atomic-rename collision with a leftover temp directory:

npm error code ENOTEMPTY
npm error syscall rename
npm error ENOTEMPTY: directory not empty, rename
  '.../_npx/<hash>/node_modules/sequant' -> '.../_npx/<hash>/node_modules/.sequant-XXXXXXXX'

Because this happens inside npx, before sequant serve runs, sequant cannot detect or self-heal it — the fix is to clear the stale cache entry.

Solutions:

1. Confirm it’s the npx cache (not a sequant bug) by running the exact launch command by hand and reading the real error:

   npx -y sequant@latest serve
   # A healthy start prints: "Sequant MCP server started (stdio)"
   # A cache problem prints the ENOTEMPTY rename error above

2. Remove the leftover temp directory (surgical — only touches the stale staging dir):

   rm -rf ~/.npm/_npx/*/node_modules/.sequant-*

3. If that isn’t enough, clear npx’s cached copy of sequant more broadly, then let it reinstall:

   npm cache clean --force
   npx -y sequant@latest serve   # re-download; expect the "started (stdio)" line

4. Reconnect in Claude Code (re-run /plugin or /mcp, or restart the session).

If it recurs on every release: you’re almost certainly still on an sequant@latest config. The durable fix is to pin the version so reconnects stop reinstalling: run sequant update (it rewrites .mcp.json to sequant@<installed version>), or update the Claude Code plugin (its bundled config is pinned to the release). Multiple Node prefixes on PATH (e.g. fnm/nvm and Homebrew) also make npx cache corruption more likely, because different node versions share and race on the same ~/.npm/_npx cache — standardizing on one node manager helps. As a last resort you can point the MCP entry at a locally-installed binary (sequant serve instead of npx -y sequant@<version> serve) if you have a global install — but do not commit that form to .mcp.json, since other contributors rely on the npx fallback. See #793.

Update Issues

Conflicts during update

Problem: sequant update shows conflicts with local changes.

Solutions:

1. Review the diff:

   sequant update --dry-run

2. Force update (overwrites local changes to package files):

   sequant update --force

3. Move skill customizations into an overrides file (not a full SKILL.md copy — Claude Code never loads .claude/.local/skills/<name>/SKILL.md). Put only the behavior you changed into overrides.md, then restore the managed skill:

   mkdir -p .claude/.local/skills/spec
   # Write your deltas into .claude/.local/skills/spec/overrides.md, then:
   sequant update --force   # restore the managed spec/SKILL.md

   The overlay directive in spec/SKILL.md makes overrides.md authoritative at invocation. See modifying an existing skill in the Customization Guide.

<path> is a directory; move it aside

Problem: sequant init, sync or update reports one or more destinations under Skipped — a directory sits where a template file goes: and those files are never written. sync --dry-run and update --dry-run report the same list.

Cause: A directory occupies the path a template file installs to — e.g. a .claude/settings.json/ directory instead of the file. Sequant will not delete a directory to make room for a file, so it skips the destination and names it (#1122). Before 2.18.0 the writer aborted there with a raw EISDIR and left the rest of the tree unwritten.

Solution: Move or remove the directory, then re-run the command:

mv .claude/settings.json .claude/settings.json.bak
sequant sync

Every other destination is written normally in the meantime — the run is not aborted, only that path is skipped.

update crashes or exits in CI / scripts

Problem: sequant update is interactive by default. When run without a terminal (a pipe, a non-interactive shell) — or in a detected CI environment, even one that allocates a pseudo-TTY — it has no way to answer its Apply updates? prompt.

Solution: Pass --yes (-y) to apply updates non-interactively:

sequant update --yes

Without --yes in a non-interactive or CI shell, update now exits with a clear message naming the reason and a non-zero status (instead of a raw ExitPromptError stack trace or a hung job), so scripts can detect the misuse. To preview what would change without applying — and without prompting — run sequant update --dry-run, which is safe in any shell. It exits non-zero when updates are pending (and 0 when nothing is to apply), so CI can gate on it directly without parsing stdout — parity with sync --dry-run. For a fast, CI-safe content-drift check that never prompts, use sequant sync.

Build/Test Issues

Tests fail during /exec

Problem: The execution phase fails because tests don’t pass.

Solutions:

1. Run tests manually first:

   npm test  # or your test command

2. Fix failing tests before running the workflow.

3. Skip verification (not recommended):

   SKIP_VERIFICATION=true npx sequant run 123

Lint errors blocking commit

Problem: The workflow can’t commit due to lint errors.

Solutions:

1. Run lint manually:

   npm run lint  # or your lint command

2. Fix lint errors before running the workflow.

3. Check your lint configuration is correct for your stack.

Windows Issues

”bash: command not found” or scripts don’t work

Problem: Shell scripts (hooks, new-feature.sh) fail because bash isn’t available.

Solution: Install WSL (Windows Subsystem for Linux):

1. Open PowerShell as Administrator
2. Run: wsl --install
3. Restart your computer
4. Open Ubuntu from Start menu and complete setup
5. Run Sequant commands from within WSL

Then install Node.js, Git and the GitHub CLI inside WSL and run every sequant command from the WSL shell.

Line ending issues (CRLF vs LF)

Problem: Git shows all files as modified, or scripts fail with “bad interpreter” errors.

Solution: Configure Git to use LF line endings:

# Set global config
git config --global core.autocrlf input

# Fix existing repo
git rm --cached -r .
git reset --hard

If using VSCode, add to .vscode/settings.json:

{
  "files.eol": "\n"
}

Path issues between Windows and WSL

Problem: Paths like C:\Users\... don’t work in WSL, or vice versa.

Solutions:

1. Access Windows files from WSL:

   cd /mnt/c/Users/YourName/Projects

2. Access WSL files from Windows:

   \\wsl$\Ubuntu\home\username

3. Best practice: Keep your projects in the WSL filesystem (~/projects/) for better performance.

npm/node not found in WSL

Problem: Node.js works in Windows but not in WSL.

Solution: Install Node.js inside WSL (it’s a separate environment):

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts

# Or using NodeSource
# See: https://github.com/nodesource/distributions

Git Issues

GPG signing failed

Problem: Commits fail with “gpg failed to sign the data” or “No pinentry”.

Solutions:

1. Commit without GPG signing (if allowed):

   git commit --no-gpg-sign -m "message"

2. Fix GPG agent:

   gpgconf --kill gpg-agent
   gpg-agent --daemon

3. Configure Git to skip signing:

   git config --global commit.gpgsign false

4. Fix pinentry (macOS):

   brew install pinentry-mac
   echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf
   gpgconf --kill gpg-agent

Common Error Messages

”Sequant is not initialized”

Run sequant init in your project directory.

”No valid issue numbers provided”

Provide at least one issue number:

npx sequant run 123

“Manifest not found”

The .sequant-manifest.json file is missing. Reinitialize:

sequant init --force

opencode Issues

opencode is an experimental driver (--agent opencode). It works and reads the same skill tree Claude Code does, but its promotion gate (#997) is deferred, so it has no reference page and no support commitment. Three limitations measured in the 2026-09 dogfood:

• sequant init --agent opencode must also run in the main checkout. The spec phase executes there, and the hook-shim check aborts the run when .opencode/ is missing from it.
• A failed spec dispatches the quality loop instead of stopping.
• No /spec plan comment is posted to the issue.

Claude Code remains the supported default.

Codex Issues

The Codex driver (--agent codex) is experimental; see Codex Agent Backend for setup.

Codex phases run without sequant’s guard hooks

Problem: A codex phase runs but never hits pre-tool.sh — a git push --force or a commit on main goes through unchallenged, and nothing in the phase output mentions hooks.

Cause: Codex loads project-layer hooks only once the project is marked trusted in your user config (~/.codex/config.toml). sequant init --agent codex writes the project-side .codex/config.toml, but cannot write your user config. Without the trust entry Codex skips the hooks silently.

Solution: Add the block init printed to ~/.codex/config.toml:

[projects."/absolute/path/to/your/project"]
trust_level = "trusted"

Commit .codex/ and .agents/ so worktree phases inherit the same hook wrapper and skills (#1072).

Codex does not find sequant’s skills ($spec, $exec unknown)

Problem: The phase prompt invokes a skill and Codex reports it unknown, or lists skills namespaced as <repo-dir>:<name>.

Cause: .agents/skills is missing, is a copy rather than a symlink, or is an absolute symlink into another checkout.

Solution: Re-run sequant init --agent codex; it creates .agents/skills as a relative symlink to ../.claude/skills. On Windows the symlink needs elevated privileges or Developer Mode, and init warns when it cannot create it. Check with ls -l .agents/skills (expect -> ../.claude/skills) and sequant doctor.

Codex phase edits files but “made no commits”, or cannot reach GitHub

Problem: On sequant < 2.16, a codex phase produced correct edits and ended with no commit (Unable to create '…/index.lock': Operation not permitted), or never posted a /spec comment and the orchestrator logged Could not parse spec recommendation.

Cause: Codex’s workspace-write sandbox excludes .git/ and disables network access by default.

Solution: Upgrade to 2.16 or later. CodexDriver now passes the repo’s git dir as a writable root (#1076) and enables network access under workspace-write (#1079). If you have set run.codex.networkAccess: false, phases are sealed off deliberately and cannot read issues, post comments or push; that is the trade-off that setting makes.

Codex phase fails with “You’ve hit your usage limit”

Problem: A codex phase ends with turn.failed and a usage-limit message, and the run stops rather than retrying.

Cause: Your Codex plan’s quota is exhausted. Since 2.17 the driver types this failure (#1087): a reset within seven days is reported as a rate limit with the reset time, anything later or unparseable as a billing failure, so the quality loop does not re-run into the same wall.

Solution: Run with --auto-wait <minutes> to have sequant resume when the window reopens, or wait for the reset time printed in the error and re-run. A billing failure means the reset is too far out to wait for; check your plan at the Codex side.

doctor reports codex unavailable or unauthenticated

Problem: sequant doctor says codex is missing, below 0.154.0, or not authenticated.

Solution: npm i -g @openai/codex and confirm codex --version; then either export CODEX_API_KEY or run codex login. doctor bounds each probe with a timeout (#1075), so a hung codex binary reports as unavailable rather than freezing the command; if that is what you see, run codex --version by hand.

Getting Help

1. Run diagnostics:

   sequant doctor

2. Check status:

   sequant status

3. View help:

   sequant --help
   sequant run --help

4. File an issue: GitHub Issues

See Also

• Customization Guide
• Stack Guides