Skip to content

Troubleshooting

Jump to bottom
thitichaya edited this page Jun 12, 2026 · 5 revisions

Troubleshooting

Run the doctor first:

bash ~/.helix/tc-fe-prep/scripts/helix-doctor.sh
HELIX_DOCTOR_FIX=1 bash ~/.helix/tc-fe-prep/scripts/helix-doctor.sh

/helix not found (Claude Code)

Cause: Session started before install, plugin cache not refreshed, or legacy helix@local enabled.

Fix:

  1. Re-run install: curl -sL https://raw.githubusercontent.com/Thitic9203/helix/main/scripts/install.sh | bash
  2. Sync plugin: bash ~/.helix/tc-fe-prep/scripts/claude-plugin-sync.sh
  3. Start a new Claude Code session.
  4. Confirm skills exist: ls ~/.claude/skills/ | grep helix
  5. Use helix@helix only — do not enable helix@local.

Skill helix not listed (Cursor / Copilot / Gemini / etc.)

Cause: Global skills folder missing or not linked.

Fix:

bash ~/.helix/tc-fe-prep/scripts/link-skills.sh

Reload the IDE or agent session. See Supported-AI-Agents for expected paths.

Auto-update not running

Cause: HELIX_AUTO_UPDATE=0, offline, or interval not elapsed (default 4h).

Fix:

HELIX_FORCE_UPDATE=1 HELIX_AUTO_UPDATE_VERBOSE=1 bash ~/.helix/tc-fe-prep/scripts/helix-auto-update.sh

Check log: ~/.helix/auto-update.log

Copilot team repo does not see Helix

Fix: From repo root:

HELIX_LINK_WORKSPACE=$PWD ~/.helix/tc-fe-prep/scripts/link-skills.sh

Commit .github/skills/ symlinks if your team shares the repo.

Changes after update do not appear

Cause: Broken symlinks, stale Cursor cache, or editing a copy instead of ~/.helix/tc-fe-prep.

Fix:

cd ~/.helix/tc-fe-prep && git pull
ls -la ~/.cursor/skills/helix  # should point into tc-fe-prep
bash ~/.helix/tc-fe-prep/scripts/link-skills.sh

Cursor: Reload Window after pull.

Install script fails (network / curl)

Fix: Manual clone:

git clone https://github.com/Thitic9203/helix.git ~/.helix/tc-fe-prep
cd ~/.helix/tc-fe-prep && ./scripts/setup.sh

Workflow stops — missing Jira / browser / Playwright

Helix skills stop and report when a required tool is unavailable. Provide Jira access, log in via browser for UI steps, or run Playwright from the project that has tests installed.

Workspace guides (optional): references/*-guide.md in your application repo.

Jira comment looks wrong after TC prep

Cause: Literal <br> in cells, truncated table, or missing rows.

Helix runs post-publish review on the live Jira comment before reporting done. If you see issues:

More help

Home

Clone this wiki locally