aisw Profiles, Contexts, and Workspace Rules

aisw splits account management into three decisions: which account a tool uses (profile), which accounts belong together (context), and which accounts a repository requires (workspace rule). Each layer is optional on top of the one before it, and keeping them separate is what stops a one-tool switch from quietly changing every other tool.

Profile: one account for one tool

A profile is the smallest unit aisw manages: one saved Claude Code, Codex CLI, Gemini CLI or Antigravity CLI account. Name it after the boundary that matters to you, not after the login session.

aisw add claude work --from-live
aisw add codex work --api-key "$OPENAI_API_KEY"
aisw add gemini work

Profile names are scoped per tool, so work can exist for Claude Code, Codex CLI and Gemini CLI at the same time. aisw list groups them by tool and marks which one is active:

$ aisw list
Profiles
────────────

Claude Code
  ○ personal [api-key]
  ○ work [api-key]
  ○ work-api-key [api-key]

Codex CLI
  ○ personal [api-key]
  ○ work [api-key]

Gemini CLI
  ○ personal [api-key]
  ○ work [api-key]

aisw use switches exactly one tool:

aisw use claude work

Codex CLI and Gemini CLI stay on whatever they were using. That independence is the point of a profile, and also its limit: if a work session needs three tools on work accounts, you have three switches to remember. The tool-specific guides cover this layer in depth, starting with switching Claude Code accounts.

Context: a named set of profiles that switch together

A context maps at most one profile per tool under a single name. The profile names don’t have to match across tools; map whichever profiles belong to the setup.

aisw context create work --claude work --codex work --gemini work
aisw context create personal --claude personal --codex personal --gemini personal

Context names follow the same rule as profile names: letters, digits, hyphens and underscores, up to 32 characters. aisw context list shows each mapping, with - for a tool the context leaves alone:

$ aisw context list
Contexts
────────────

  Name          : personal
  claude        : personal
  codex         : personal
  gemini        : personal
  agy           : -

  Name          : work
  claude        : work
  codex         : work
  gemini        : work
  agy           : -

aisw context use switches every mapped tool in one step:

$ aisw context use work
Activated context
─────────────────

  Context       : work

Effects
  Claude Code -> work (isolated)
  Codex CLI -> work (isolated)
  Gemini CLI -> work

Next
  Run 'aisw status --context' to verify the active mapping.

The switch is all or nothing. aisw snapshots the live credentials of every mapped tool first, and if any one switch fails it restores the snapshots, so you never end up half on work and half on personal. Claude Code and Codex CLI default to isolated state, which points CLAUDE_CONFIG_DIR and CODEX_HOME at the profile’s own directory; pass --state-mode shared to keep the tools’ standard config directories instead.

If your profiles share one name in every tool, aisw use --all --profile work does the same multi-tool switch without a saved context. A context is worth creating once the names differ, once some tools should stay out of the switch, or once a workspace rule needs something to point at. The guide to switching all four tools compares the two.

Check which context is active

aisw does not record “the current context” as a separate setting. aisw status --context derives it by comparing each tool’s active profile against every saved context:

$ aisw status --context
Status
────────────

  Context       : exact
  Active context: work
  Matches       : work
  claude        : work
  codex         : work
  gemini        : work
  Unmanaged     : agy=none

Unmanaged lists tools the context doesn’t map, with whatever profile they’re on. Plain aisw status leaves the context block out; you need the --context flag.

Because the context is derived, switching a single tool afterwards is allowed and visible. After aisw use codex personal, Claude Code and Gemini CLI still match work but Codex CLI matches personal, so the status changes from exact to drift and names every context that partly matches:

$ aisw status --context
Status
────────────

  Context       : drift
  Drift         : personal, work

The other two states are none, when no saved context matches any active profile, and ambiguous, when two contexts have identical mappings and both match. Running aisw context use work again clears drift.

Contexts protect their profiles

A context can’t be left pointing at a profile that no longer exists. Removing a mapped profile is refused, and --force doesn’t override it:

$ aisw remove codex work --yes --force
Error: cannot remove codex profile 'work' because it is referenced by contexts: work.
  Update or remove those contexts first, for example: aisw context unset work --codex

Renaming is safe: aisw rename updates every context that maps the old name. To change a mapping, use aisw context set work --codex work-api-key; to drop a tool from a context, aisw context unset work --codex.

Workspace rule: the context a repository requires

A workspace rule adds a location boundary. It binds a repository, a directory, or a git remote pattern to the context that location expects, and the shell hook checks that binding every time you launch claude, codex, gemini or agy there.

cd ~/code/work-api
aisw workspace bind . --context work
aisw workspace guard --mode strict

Inside a git repository, bind . writes .git/info/aisw.json, which is never committed. --git-remote 'github.com/acme/*' covers every clone of an organisation, and --default sets the fallback context for anything unbound. In warn mode, the default, the hook prints a warning and lets the agent start; in strict mode it blocks the launch and prints the command that fixes it.

A workspace rule is policy, not credentials. It names a context, the context names profiles, and the profiles hold the auth. Removing a binding deletes no credentials, and editing the context’s mappings doesn’t rewrite the binding. Rules also never switch accounts for you: they catch the mistake before the agent touches the code, and you run aisw context use to fix it. Resolution order, remote patterns and the hook setup are in preventing the wrong account in a repository and the workspace guardrails reference.

Which layers you need

You can stop at any layer:

• One tool, or tools that change independently: profiles only. Your Claude Code account changes per client while your Codex CLI account doesn’t, so aisw use claude <profile> is all you run.
• Several tools that should move together: add contexts. A personal context and a work context replace three or four separate switches with one, and aisw status --context tells you at a glance whether you’ve drifted.
• Repositories that must never run under the wrong account: add workspace rules on top of contexts. This matters most for client code, where a personal account in a client repository is more than a confusing status line. The client accounts guide walks through one context per client.

Everything stays local. aisw writes to the credential locations and keyrings the upstream tools already read, and doesn’t proxy prompts or require a cloud account. After any switch, aisw status --context shows what is active and which context it matches.