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 2026-03-25T11-45-02.123Z-0000 --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 remove refuses: profile is referenced by a context

Cause: A saved context still maps that tool to the profile. Removing it would leave the context pointing at something that no longer exists, so aisw refuses before touching any credential.

Fix: Drop the mapping, or remove the context, then retry:

# If the context maps other tools too, drop just this tool's mapping
aisw context unset <context> --claude

# If this was the context's only mapping, unset would leave it empty,
# so remove the context instead
aisw context remove <context> --yes

aisw remove claude work --yes

A context must keep at least one mapping, so unset refuses when it would empty the context and tells you to use context remove.

The error names every blocking context. Nothing is deleted when the removal is refused - credentials and profile files are left intact.

---

aisw add refuses: key or account already exists

Cause: aisw will not store the same account under two names. For API keys it compares the key itself; for OAuth it compares the resolved account identity.

Fix: Use the profile it names, or supply a different account. To re-point an existing profile at new credentials, remove it first and re-add.

---

aisw add refuses: API key contains a control character

Cause: The key has an embedded newline, carriage return, or tab - usually from copy/paste, or from piping a file that ends in a newline.

Fix: Strip the trailing newline. printf does not add one:

printf '%s' "$ANTHROPIC_API_KEY" | aisw add claude work --api-key-stdin

Keys must be a single line, because a Gemini key is written into a .env file the CLI sources, where an embedded newline would define an unrelated variable.

---

aisw use --all exits non-zero

Cause: At least one tool that has a profile with that name failed to switch. Tools with no profile of that name are skipped and do not cause a failure.

Fix: The error lists each failing tool and its reason. Run aisw status to see which tools are affected, then fix or switch those individually.

---

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, gemini, or agy 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.