Skip to main content

Troubleshooting

Common problems and the direct fix. For full command syntax, see the CLI Reference.

Agent not installed

stak run and stak try launch each agent's own CLI on your PATH — Codex's codex, Claude Code's CLI, or Cursor's Agent CLI (agent). STAK does not install these for you. If a run fails with the agent not found, install that agent's CLI first and confirm it resolves on your PATH before retrying.

STAK login

Commands that talk to STAK Cloud require a signed-in session — notably stak memory recover and stak memory protect. stak memory backup works locally without signing in (uploading to Cloud is a bonus when you are signed in, not a requirement), and stak memory restore is purely local and never needs sign-in. If a command reports you're not signed in, run:

stak login

If sign-in itself fails, check your network connection and retry; STAK does not cache or fall back to stale credentials.

Missing Skills

If an agent doesn't see Skills you expect, first confirm they're actually part of your desired Environment:

stak status
stak diff

If a Skill is missing from main itself, re-add it with stak use. If it's in main but not showing up for a specific agent, re-run stak run <agent> to reconcile Skills into that agent's directory again.

Project mapping

Mapping a Project to a local directory is refused when that directory already belongs to a different repository or a different logical Project — this is intentional, not a bug. See Memory & Projects for why a directory is only ever a machine-specific binding. Review recovered Projects and pick an unambiguous destination directory:

stak project
stak project map my-app ~/code/my-app

Recovery

stak memory restore never overwrites an existing target — a differing existing target is reported as a conflict and left untouched, never merged over. Resolve the conflict manually (move or remove the conflicting local file) and re-run restore.

stak memory restore

Cursor login

As of 0.1.1, isolated trials (stak try … -- cursor) automatically detect and reuse a normal Cursor agent login session — if you're already signed in to Cursor that way, no extra setup is needed inside the trial. Setting CURSOR_API_KEY or CURSOR_AUTH_TOKEN remains available as an optional alternative for environments without an interactive agent login session, but it is not required.

Also as of 0.1.1, resolving the Cursor Agent CLI on Windows — including Cursor's shims — is handled automatically by stak run cursor and stak try … -- cursor; you do not need to point STAK at the shim manually.

Common OS issues

Skill projection and try isolation both depend on each agent's own config directory conventions (for example CODEX_HOME, CLAUDE_CONFIG_DIR, and CURSOR_CONFIG_DIR — see Agents). If an agent behaves differently than expected on your machine, confirm that agent's CLI runs correctly outside STAK first — most environment issues are in the underlying agent install, not STAK's reconciliation.