Troubleshooting

Common issues and fixes when using Shared Agents.

sa: command not found

source ~/.bashrc
# or
"${SHARED_AGENTS_HOME:-$HOME/.shared-agents}/scripts/sa" help

Re-run sa install if bashrc was not updated.

Shared Agents not installed

sa bootstrap
# or from dev checkout:
./sa install --home "$HOME/.shared-agents"

Tool shows not_configured in sa check

The AI tool is installed but adapters are missing:

sa install
sa check

Install a new IDE/CLI later? Run sa install again.

Stale skills, rules, or learnings

sa sync
sa status

Confirm session hooks are configured (sa check). Cursor: ~/.cursor/hooks.json · Claude Code: ~/.claude/settings.json.

Cursor rule symlink blocked

A rule exists as a regular file instead of a symlink:

sa doctor
sa doctor --fix

Backups land in $SHARED_AGENTS_HOME/.doctor-backups/.

Team layout warnings

sa team verify
sa team migrate --dry-run   # if legacy learnings/ at home root

See Team setup and Migrate team data.

Wizard cancelled / half-finished install

rm -rf ~/.shared-agents
sa bootstrap

Or fix manually with sa install after cleaning partial state.

Pending learnings not visible to teammates

1. sa pending push — commit + push team repo
2. Teammate runs sa sync
3. Human runs sa review to promote to approved/

Agents only read approved learnings.

Wrong path for learning drafts

Always resolve before writing:

sa pending path 2026-06-02-my-slug

See Canonical paths.

Dev checkout vs runtime home

Do not assume the Cursor workspace is $SHARED_AGENTS_HOME.

Still stuck?

• sa help — live command list
• sa status — what needs attention
• CLI reference
• GitHub issues