Cross-tool · Tested with aisw v0.3.10 · Desktop v0.2.1 · Updated July 16, 2026
Profiles vs. Contexts in aisw
A profile is one saved account for one tool, like a Claude Code work login. A context is a named group of profiles across tools, one profile for each supported agent you need, that you switch together with a single command. Use profiles when you only care about one tool at a time, and contexts when you regularly switch your whole coding-agent setup at once.
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-liveaisw add codex work --api-key "$OPENAI_API_KEY"aisw add gemini workEach of these is an independent profile. Switching one doesn’t touch the others:
aisw use claude workThis 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, including any combination of Claude Code, Codex CLI, Gemini CLI, and Antigravity CLI, in one command.
aisw context create client-acme \ --claude client-acme \ --codex client-acme \ --gemini client-acme \ --antigravity client-acme
aisw context use client-acmeThat one command switches every mapped tool to its client-acme profile 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 the tools that boundary needs, 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 statusShows both the active profile per tool and, if applicable, which context (if any) that combination currently matches.
Frequently asked questions
Do I have to use contexts, or can I just use profiles?
Contexts are optional. If you only use one coding agent, or you switch tools independently of each other, plain profiles are simpler and cover the whole use case.
Can a context include just one or two tools instead of all four?
Yes. A context maps whichever supported tools are relevant, so you can define one with only Claude Code and Codex CLI profiles, or include Gemini CLI and Antigravity CLI when the workflow needs them.
What happens if a profile inside a context gets removed?
aisw flags the context as incomplete and tells you which mapping is missing; it won't silently drop or ignore it.