Profiles, Contexts, and Workspace Rules: the Three Layers of AI Account Management

1. A profile answers: which account does this tool use?

A profile is the smallest useful unit. It represents one saved Claude Code, Codex CLI, Gemini CLI, or Antigravity CLI account. Name profiles after the boundary that matters to you, not after a temporary login session.

aisw add claude work --from-live
aisw add claude personal
aisw use claude work

Use profiles when you are changing one coding agent independently. They are also the clearest way to see which identities are available in AI Switcher Desktop. A profile switch changes the selected tool; it does not silently change every other tool.

2. A context answers: which complete setup is active?

A context groups one profile per tool under a single name. This is the right abstraction for a client engagement or a work setup where Claude Code, Codex CLI, Gemini CLI, and Antigravity CLI should move together. The profile names can differ across tools.

aisw context create client-acme \
  --claude acme-claude \
  --codex acme-codex \
  --gemini acme-gemini
aisw context use client-acme

Contexts prevent a common operational mistake: switching one provider and forgetting the others. They make the transition explicit and keep a named client setup repeatable from the terminal or the desktop app.

3. A workspace rule answers: what is allowed in this repository?

A workspace rule adds a location boundary. Bind a repository to the context it expects, then let the shell hook warn or block when the active accounts do not match.

aisw workspace bind . --context client-acme
aisw workspace guard --mode strict

This matters when the cost of a mistake is more than a confusing status line. A client repository may need the client account, while a personal repository must never start an agent under it. Strict mode makes that policy enforceable before the coding agent launches.

How the layers work together

Think of the model as account, setup, and location. Profiles store the identities you switch. Contexts compose the identities that belong together. Workspace rules protect the repositories that need one of those setups. You can stop at any layer: a solo developer may only need profiles, a consultant may need contexts, and a team with sensitive client boundaries should add workspace rules.

The model is deliberately local. AI Switcher uses the credential locations and keyrings already used by the upstream tools. It does not proxy prompts or require a cloud account. Use aisw status after a change and aisw verify when you need to compare recorded state with live provider state.

For implementation details, see the guide to profiles versus contexts, then read how to prevent the wrong account in a repository.