Troubleshooting

Quick diagnostics

Run these first when something is wrong:

aisw doctor
aisw status --json
aisw verify --json
aisw repair --json --dry-run

doctor checks binary detection, ~/.aisw/ permissions, shell hook status, and keyring availability. status --json shows the full state of every tool including live-match status and any credential warnings. verify --json combines both into a pass/warn/fail verdict with remediation hints. repair --json --dry-run previews safe local fixes for missing aisw state or broad permissions.

---

Tool reported as not installed

Symptom: aisw status shows a tool as missing, or aisw use <tool> fails with “tool not installed”.

Check:

which claude
which codex
which gemini

Fix:

• Install the missing tool (see the vendor’s installation instructions).
• Ensure the binary is on your PATH.
• Refresh shell binary cache: hash -r (bash), rehash (zsh).
• If the binary is in a non-standard location, add it to PATH before running aisw.

---

Shell hook not active

Symptom: aisw use applies credentials but environment variables are not updated in the current shell session.

Check:

echo "$AISW_SHELL_HOOK"
# Should print: 1

Fix:

Reload your shell config:

source ~/.zshrc    # zsh
source ~/.bashrc   # bash

If the hook is not installed, add it:

aisw shell-hook zsh >> ~/.zshrc && source ~/.zshrc
aisw shell-hook bash >> ~/.bashrc && source ~/.bashrc

Note: aisw use always writes live credential files regardless of whether the shell hook is active. The hook is only required for shell-level environment variable exports (CLAUDE_CONFIG_DIR, CODEX_HOME).

---

Live credentials do not match active profile

Symptom: aisw status shows “live mismatch” for a tool.

Causes:

• You authenticated directly in the tool (not through aisw) after the last aisw use.
• Another process changed the tool’s credential files.
• The profile was stored but never activated with aisw use.

Fix:

Re-apply the profile:

aisw use claude work

Or capture the current live account as a new profile:

aisw add claude current --from-live --set-active

For Codex ChatGPT-managed auth, prefer re-applying the isolated profile and re-authenticating inside that profile-owned CODEX_HOME if needed. Imported --from-live Codex sessions are bootstrap-only.

For Claude OAuth, a mismatch after trying isolated mode usually means the installed Claude build is still using its shared live Keychain credential. Re-apply with shared mode instead:

aisw use claude work --state-mode shared

---

OAuth flow fails or times out

Symptom: aisw add <tool> <name> (interactive OAuth) exits with a timeout or credential-not-found error.

Causes and fixes:

Browser did not open or login was not completed:

• Complete the browser-based login before the timeout.
• If the browser did not open, check that a default browser is configured.

Tool stores credentials in an unexpected location:

• Run aisw doctor to check for known detection issues.
• File a GitHub issue with the tool version and platform.

For Codex - login succeeds but later refreshes log you out or switch accounts:

• Use isolated mode only for ChatGPT-managed Codex profiles.
• If the profile came from aisw add codex <name> --from-live, re-login directly into that profile instead of treating the imported session as durable.

For Gemini - scratch directory error:

• This should not occur in normal usage. If it does, check that /tmp is writable.

For Claude - credentials captured but profile creation fails:

• Check available disk space under ~/.aisw/.
• Check permissions on ~/.aisw/profiles/.

For Claude - isolated mode is rejected:

• This is expected when Claude OAuth is backed by the legacy shared live Keychain credential.
• CLAUDE_CONFIG_DIR isolates config/history, not the upstream Keychain auth owner.
• Use aisw use claude <name> --state-mode shared, or switch that workflow to API key / long-lived token auth if you need repeatable per-profile isolation semantics.

---

Keyring not available (Linux)

Symptom: aisw reports that the system keyring is unavailable, or keyring-backed operations fail on Linux.

Cause: The Secret Service daemon (GNOME Keyring or KWallet) is not running, which is common on headless servers and minimal desktop environments.

Fix (headless/CI):

Use --api-key or --from-env for profiles on Linux servers:

aisw --non-interactive add codex ci --api-key "$OPENAI_API_KEY"

aisw automatically falls back to 0600 file-backed storage when the keyring is not available. Run aisw doctor to confirm which backend is active.

Fix (desktop):

Start the keyring daemon:

# GNOME
gnome-keyring-daemon --start

# Or ensure the keyring unlocks at login via your desktop environment settings

---

Permission errors

Symptom: Read or write failures under ~/.aisw/ or tool config directories.

Check:

ls -ld ~/.aisw ~/.aisw/profiles
find ~/.aisw -type f -maxdepth 3 | xargs ls -l

Fix:

• Confirm your user owns the files: ls -la ~/.aisw/
• Fix ownership if needed: chown -R $(whoami) ~/.aisw/
• Fix permissions: chmod -R u=rwX,go= ~/.aisw/
• Re-run aisw doctor to verify.

---

Backup restore did not switch the active profile

Expected behavior: aisw backup restore restores profile files into storage only. It does not activate the profile.

Fix: After restoring, explicitly activate the profile:

aisw backup restore 20260325T114502Z-claude-work --yes
aisw use claude work

---

Non-interactive mode fails in CI

Symptom: aisw exits with a prompt-related error in a CI environment.

Cause: The command requires user input (OAuth flow, overwrite confirmation) but --non-interactive is set.

Fix:

For API key profiles:

aisw --non-interactive add claude ci --api-key "$ANTHROPIC_API_KEY"

For removals and restores:

aisw --non-interactive remove codex ci --yes
aisw --non-interactive backup restore <id> --yes

Interactive OAuth is not available in --non-interactive mode by design. Use API keys or --from-env for CI.

---

aisw use gemini ... --state-mode shared fails

Cause: Gemini does not support shared state mode. Its auth credentials and local state are coupled under ~/.gemini/, making shared mode unsafe to implement.

Fix: Remove --state-mode when using Gemini. Gemini profiles are always isolated.

---

aisw use codex ... --state-mode shared fails for ChatGPT auth

Cause: Codex refreshes ChatGPT-managed auth in place. Refresh tokens and related session state are not safely shareable across multiple live owners, so aisw blocks shared-mode switching for those profiles. This is an expected upstream limitation, not an aisw corruption bug.

Fix:

aisw use codex work --state-mode isolated

If the profile was imported with aisw add codex work --from-live, treat it as a bootstrap session and re-login directly inside that isolated profile for the durable path.

Common symptoms of the upstream limitation:

• “refresh token already used”
• Codex suddenly appears logged out
• Codex refreshes into another account after you copied or reused state

If a desktop app, remote sidecar, or long-lived shell already had the old account state loaded, restart that connection after changing accounts so it re-reads the active profile.

---

Config lock timeout

Symptom: aisw reports a lock timeout error.

Cause: Another aisw command is running concurrently and holds the exclusive config lock.

Fix:

• Wait for the other command to complete.
• If no aisw process is running, a stale lock may remain. Check for lock files under ~/.aisw/ and remove any that have a modification time older than a minute.

---

Workspace guard blocked an agent launch

Symptom: Running claude, codex, or gemini fails with “workspace guard refused to launch”.

Cause: The shell hook is active, the current directory has a workspace binding, and the active context does not match the expected one.

Fix (switch to the right context):

aisw workspace status          # see what is expected and what is active
aisw context use client-acme   # switch to the expected context
claude                         # now launches normally

Fix (if the mismatch is intentional):

Change guard mode to warn so the agent launches with a warning instead of blocking:

aisw workspace guard --mode warn

Fix (if no workspace binding should apply here):

Remove the binding:

# Remove the repo-local binding for the current repo
aisw workspace unbind .

# Remove a user-level path rule
aisw workspace unbind ~/clients/acme-api

# Remove a user-level remote rule
aisw workspace unbind --git-remote "github.com/acme/*"

# Clear the default fallback context
aisw workspace unbind --default

Check what rule matched and why:

aisw workspace status --json
aisw workspace doctor --json

---

Still blocked?

Run these and include the output when opening an issue:

aisw doctor --json
aisw status --json
aisw list --json

Open an issue at: github.com/burakdede/aisw/issues

Include the command you ran, the exact error output, your OS and shell, and the diagnostic output above.