Profiles vs. Contexts: What's the Difference in aisw?

These are the two core building blocks in aisw, and picking the right one for a given task saves a lot of confusion later.

Profile: one account, one tool

A profile is the smallest unit aisw manages — a single saved account for a single tool.

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

Each of these is an independent profile. Switching one doesn’t touch the others:

aisw use claude work

This only changes the active Claude Code account. Codex CLI and Gemini CLI stay wherever they were.

Context: a named group of profiles across tools

A context maps one profile per tool under a single name, so you can switch your entire setup — Claude Code, Codex CLI, and Gemini CLI together — in one command instead of three.

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

aisw context use client-acme

That one command switches all three tools to their client-acme profiles at once.

When to use which

Use plain profiles if you only work with one coding agent, or you switch tools independently — say, your Claude Code account changes per client but your Codex CLI account doesn’t.

Use contexts if you regularly move between full setups — for example, a personal context and one context per client, each bundling all three tools — and want a single switch instead of remembering to update each tool separately. This is also what workspace guardrails bind repositories to, so a context is usually the right unit if you’re also enforcing per-repo account correctness.

Verify the result

aisw status

Shows both the active profile per tool and, if applicable, which context (if any) that combination currently matches.