aweswitch: Agent Profile Switcher

A tiny local launcher for switching AI agent runtime profiles.

Start different agent sessions with different API endpoints, tokens, and models without rewriting global agent config.

English · 简体中文 · Webioinfo

Run different agent profiles side by side without breaking sessions that are already open.

aweswitch reads profiles from ~/.config/aweswitch/config.json, expands environment references, prepares provider-specific runtime arguments, and then starts the selected agent. Each launch gets its own API endpoint, token, and model through runtime arguments instead of mutating global agent settings.

It is intentionally small. The project is positioned as an agent profile switcher, but today it supports Claude Code profiles only. Codex and Hermes profile groups may appear in the config shape later, but they are not executable yet.

Powered by aweswitch

• aweshelf — Session bookmark manager for Claude Code and Codex. Bookmark, categorize, and restore sessions with aweswitch profiles.

aweswitch manages how you launch sessions; aweshelf manages how you remember them. Use aweswitch -c to auto-bookmark at launch, and aweshelf resume to restore with the same profile later.

Known issue: launching multiple aweswitch -c sessions at the same time in the same project may bookmark the wrong session. Sequential launches are safe. See CONTRIBUTING.md for why.

Install

Install from PyPI:

pip3 install aweswitch
aweswitch --help

Create the default config:

aweswitch config init

Then open the config and align it with your real Claude Code providers, models, and token variable names:

aweswitch config edit

Or add a new profile interactively:

aweswitch add

This prompts for profile name, base URL, auth token env var, model, and optional haiku/sonnet model overrides.

The default config shape groups profiles under their provider. This is a reference config you can adapt:

{
  "profiles": {
    "claude": {
      "cc-glm": {
        "env": {
          "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
          "ANTHROPIC_AUTH_TOKEN": "${GLM_ANTHROPIC_AUTH_TOKEN}",
          "ANTHROPIC_MODEL": "glm-5.1"
        }
      },
      "cc-gemini": {
        "env": {
          "ANTHROPIC_BASE_URL": "https://openclaw.chatgo.best",
          "ANTHROPIC_AUTH_TOKEN": "${GEMINI_ANTHROPIC_AUTH_TOKEN}",
          "ANTHROPIC_MODEL": "gemini-3.1-pro-preview"
        }
      },
      "cc-xiaomi": {
        "env": {
          "ANTHROPIC_BASE_URL": "https://token-plan-sgp.xiaomimimo.com/anthropic",
          "ANTHROPIC_AUTH_TOKEN": "${XIAOMI_ANTHROPIC_AUTH_TOKEN}",
          "ANTHROPIC_MODEL": "mimo-v2.5-pro"
        }
      }
    }
  }
}

Configure the token variables referenced by your profiles:

export GLM_ANTHROPIC_AUTH_TOKEN="..."
export GEMINI_ANTHROPIC_AUTH_TOKEN="..."
export XIAOMI_ANTHROPIC_AUTH_TOKEN="..."

Put long-lived variables in ~/.zshrc if you want them available in every shell.

Verify the configured profiles:

aweswitch list
aweswitch show cc-glm

Run a profile:

aweswitch cc-glm

Pass extra arguments through to Claude Code:

aweswitch cc-glm --dangerously-skip-permissions

Auto-bookmark sessions with aweshelf:

aweswitch cc-glm -c backend -t "Fix auth bug"

See aweshelf Integration for details.

Useful config commands:

aweswitch config path
aweswitch config show
aweswitch config edit

aweshelf Integration

aweshelf is a session bookmark manager for Claude Code and Codex CLI. It lets you save, tag, search, and resume past coding sessions.

aweswitch integrates with aweshelf so you can bookmark a session at launch time, without a separate step:

aweswitch cc-glm -c backend -t "Fix auth bug"

Options

Flag	Description
-c, --category	Category to tag the bookmark with (e.g. backend, research, infra).
-t, --title	Custom bookmark title. If omitted, aweshelf uses the session's first message.

Both options require aweshelf to be installed. If aweshelf is not found, they are ignored with a warning printed to stderr. Claude Code launches normally regardless.

Note: launching multiple aweswitch -c sessions simultaneously in the same project may result in incorrect bookmark assignment. Sequential launches are safe — as long as the previous session's JSONL file has been created before starting the next one (typically a few seconds). See CONTRIBUTING.md for details.

Install aweshelf

pip3 install aweshelf

What aweshelf does on its own

Even without aweswitch's -c/-t flags, aweshelf is useful independently:

aweshelf bookmark               # bookmark a session interactively
aweshelf bookmark --current     # bookmark the most recent session in this project
aweshelf list                   # list all bookmarks
aweshelf search "auth"          # full-text search across bookmarks
aweshelf resume BOOKMARK_ID     # resume a saved session
aweshelf browse                 # interactive TUI browser

See the aweshelf README for full documentation.

FAQ

Why aweswitch, and who is it for?

aweswitch is for people who use AI coding agents with more than one runtime endpoint, model, or token source and want a repeatable local command instead of editing settings by hand.

• One local config file at ~/.config/aweswitch/config.json
• Named agent profiles such as cc-glm, cc-gemini, or cc-xiaomi
• Side-by-side sessions where different terminals can launch different API/model combinations
• Runtime-only injection through provider-specific arguments
• No mutation of global agent config, so already-open agent sessions keep working with the settings they started with
• Token references through shell variables or ~/.claude/settings.json
• Readable JSON with provider grouping under profiles.claude

Where does aweswitch store profiles?

By default, profiles live in:

~/.config/aweswitch/config.json

You can override that path with AWESWITCH_CONFIG.

Does aweswitch modify Claude settings?

No. It reads your aweswitch config and launches Claude Code with runtime settings for that process only. Switching profiles does not rewrite the global API endpoint or model, so it does not disturb agent sessions that are already running.

Does aweswitch support Codex or Hermes?

Not yet. The config format groups profiles by provider so future support can fit naturally, but the executable provider set is currently Claude Code only.

Similar Tools

cc-switch

cc-switch is an adjacent Claude Code switching tool. It is useful reference material for the same problem space: making Claude Code provider/model switching easier from the command line.

The key difference is that aweswitch avoids global config mutation. Many switching tools work by changing the agent's shared API/model settings; that can make already-open agent sessions unreliable because the global API endpoint changed underneath them. aweswitch keeps profiles in its own JSON file and injects settings only when launching a new process, so each session keeps the API and model it started with.

aweswitch currently takes a smaller Python-package approach: local JSON profiles, runtime-only Claude Code --settings, secret redaction for inspection commands, and provider grouping that leaves room for future agent support.

Profile Rules

• Profiles are grouped under profiles.<provider>.<profileName>.
• claude is the only supported provider right now.
• Profile names must be unique across all provider groups.
• Claude profiles pass env through runtime --settings '{"env": ...}'.
• Set the Claude model with env.ANTHROPIC_MODEL.
• env values only apply to the launched process.
• ${VAR_NAME} values are expanded from the current shell environment.
• Claude token values can also expand from ~/.claude/settings.json when they are missing from the shell.
• show and config show redact keys matching token, key, secret, password, or auth.

Claude Model Overrides

For Claude profiles, ANTHROPIC_MODEL is the primary model setting.

ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_OPUS_MODEL are not configured by default.

If you want Claude Code to use a lighter model for lightweight or background tasks, add ANTHROPIC_DEFAULT_HAIKU_MODEL to the profile:

{
  "profiles": {
    "claude": {
      "cc-xiaomi": {
        "env": {
          "ANTHROPIC_BASE_URL": "https://token-plan-sgp.xiaomimimo.com/anthropic",
          "ANTHROPIC_AUTH_TOKEN": "${XIAOMI_ANTHROPIC_AUTH_TOKEN}",
          "ANTHROPIC_MODEL": "mimo-v2.5-pro",
          "ANTHROPIC_DEFAULT_HAIKU_MODEL": "mimo-v2.5"
        }
      }
    }
  }
}

This keeps the main model on mimo-v2.5-pro while allowing Claude Code to use mimo-v2.5 for lighter work.

Development

Run the test suite:

python3 tests/test_aweswitch.py

Run the syntax check:

python3 -m py_compile src/aweswitch/cli.py tests/test_aweswitch.py

Install the local checkout in editable mode:

pip3 install -e .

Build a local package:

pip3 install build
python3 -m build

Install a built wheel locally:

pip3 install dist/aweswitch-0.1.6-py3-none-any.whl

Project docs:

• Contributing
• Changelog