# realiti4/claude-swap architecture

> Architecture diagram of the GitHub repository realiti4/claude-swap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/realiti4/claude-swap
- Repository: https://github.com/realiti4/claude-swap

## Overview

claude-swap manages multiple Claude Code accounts: users add accounts, inspect usage, switch manually or automatically, and can launch isolated parallel sessions. The CLI is the primary command surface; a Textual dashboard and menubar provide additional interfaces. Account switching combines stored account data with OAuth credentials and usage measurements, while autoswitch evaluates policy and asks the switcher to change accounts. Session mode launches Claude Code with a per-account configuration. The README documents these capabilities; several implementation links below rely on source-index references rather than sampled call sites.

Main entry points: [`src/claude_swap/switcher.py`](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/switcher.py) (Account switcher), [`src/claude_swap/cli.py`](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/cli.py) (CLI commands), [`src/claude_swap/autoswitch.py`](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/autoswitch.py) (Auto-switch policy), [`src/claude_swap/tui/app.py`](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/tui/app.py) (Textual dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_tui["Textual dashboard<br/>[app.py]"]
  node_menubar["Menubar<br/>[menubar.py]"]
end

subgraph group_accounts["Accounts and switching"]
  node_switcher["Account switcher<br/>[switcher.py]"]
  node_oauth["OAuth and usage API<br/>[oauth.py]"]
  node_account_data["Account models<br/>[models.py]"]
  node_transfer["Account transfer<br/>[transfer.py]"]
end

subgraph group_automation["Usage automation"]
  node_usage[("Usage cache<br/>[usage_store.py]")]
  node_autoswitch["Auto-switch policy<br/>[autoswitch.py]"]
  node_poll["Polling policy<br/>[poll_policy.py]"]
  node_snapshot["Dashboard snapshots<br/>[snapshot_source.py]"]
end

subgraph group_sessions["Parallel sessions"]
  node_session["Session launcher<br/>[session.py]"]
  node_spawn["Process launch<br/>[spawn.py]"]
end

subgraph group_support["Preferences and integrations"]
  node_settings[("Settings<br/>[settings.py]")]
  node_paths["Storage paths<br/>[paths.py]"]
  node_keychain["macOS Keychain<br/>[macos_keychain.py]"]
  node_launch_agent["Background agent<br/>[launch_agent.py]"]
  node_update["Update checker<br/>[update_check.py]"]
end

node_user(("User"))

node_user -->|"runs commands"| node_cli
node_user -->|"opens dashboard"| node_tui
node_cli -->|"dispatches account actions"| node_switcher
node_cli -->|"starts auto mode"| node_autoswitch
node_cli -->|"launches account session"| node_session
node_cli -->|"invokes transfer"| node_transfer
node_cli -->|"opens TUI"| node_tui
node_cli -->|"controls menubar"| node_menubar
node_cli -->|"manages agent"| node_launch_agent
node_cli -->|"checks upgrades"| node_update
node_switcher -->|"refreshes credentials"| node_oauth
node_switcher -->|"accesses credentials"| node_keychain
node_switcher -->|"uses account records"| node_account_data
node_switcher -->|"reads usage state"| node_usage
node_autoswitch -->|"selects and switches"| node_switcher
node_autoswitch -->|"tracks polling state"| node_usage
node_autoswitch -->|"uses poll policy"| node_poll
node_usage -->|"fetches measurements"| node_oauth
node_tui -->|"refreshes snapshots"| node_snapshot
node_tui -->|"performs account actions"| node_switcher
node_tui -->|"runs auto view"| node_autoswitch
node_snapshot -->|"collects account state"| node_switcher
node_snapshot -->|"reads cached usage"| node_usage
node_session -->|"reads stored account"| node_switcher
node_session -->|"launches Claude Code"| node_spawn
node_session -->|"handles credentials"| node_keychain
node_cli -->|"configures preferences"| node_settings
node_switcher -->|"uses storage locations"| node_paths
node_settings -->|"resolves settings file"| node_paths
node_menubar -->|"offers auto controls"| node_autoswitch
node_menubar -->|"switches accounts"| node_switcher
node_launch_agent -->|"checks update status"| node_update

click node_cli "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/cli.py"
click node_tui "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/tui/app.py"
click node_menubar "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/menubar.py"
click node_switcher "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/switcher.py"
click node_oauth "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/oauth.py"
click node_account_data "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/models.py"
click node_transfer "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/transfer.py"
click node_usage "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/usage_store.py"
click node_autoswitch "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/autoswitch.py"
click node_poll "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/poll_policy.py"
click node_snapshot "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/snapshot_source.py"
click node_session "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/session.py"
click node_spawn "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/spawn.py"
click node_settings "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/settings.py"
click node_paths "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/paths.py"
click node_keychain "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/macos_keychain.py"
click node_launch_agent "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/launch_agent.py"
click node_update "https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/update_check.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_tui,node_menubar,node_user toneBlue
class node_switcher,node_oauth,node_account_data,node_transfer toneAmber
class node_usage,node_autoswitch,node_poll,node_snapshot toneMint
class node_session,node_spawn toneRose
class node_settings,node_paths,node_keychain,node_launch_agent,node_update toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/cli.py): `src/claude_swap/cli.py`
- [Textual dashboard](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/tui/app.py): `src/claude_swap/tui/app.py`
- [Menubar](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/menubar.py): `src/claude_swap/menubar.py`

### Accounts and switching

- [Account switcher](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/switcher.py): `src/claude_swap/switcher.py`
- [OAuth and usage API](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/oauth.py): `src/claude_swap/oauth.py`
- [Account models](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/models.py): `src/claude_swap/models.py`
- [Account transfer](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/transfer.py): `src/claude_swap/transfer.py`

### Usage automation

- [Usage cache](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/usage_store.py): `src/claude_swap/usage_store.py`
- [Auto-switch policy](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/autoswitch.py): `src/claude_swap/autoswitch.py`
- [Polling policy](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/poll_policy.py): `src/claude_swap/poll_policy.py`
- [Dashboard snapshots](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/snapshot_source.py): `src/claude_swap/snapshot_source.py`

### Parallel sessions

- [Session launcher](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/session.py): `src/claude_swap/session.py`
- [Process launch](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/spawn.py): `src/claude_swap/spawn.py`

### Preferences and integrations

- [Settings](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/settings.py): `src/claude_swap/settings.py`
- [Storage paths](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/paths.py): `src/claude_swap/paths.py`
- [macOS Keychain](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/macos_keychain.py): `src/claude_swap/macos_keychain.py`
- [Background agent](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/launch_agent.py): `src/claude_swap/launch_agent.py`
- [Update checker](https://github.com/realiti4/claude-swap/blob/main/src/claude_swap/update_check.py): `src/claude_swap/update_check.py`

### Other components

- **User**

## Connections

- User → CLI commands: runs commands (evidence: `README.md`)
- User → Textual dashboard: opens dashboard (evidence: `README.md`)
- CLI commands → Account switcher: dispatches account actions (evidence: `src/claude_swap/cli.py`)
- CLI commands → Auto-switch policy: starts auto mode (evidence: `src/claude_swap/cli.py`)
- CLI commands → Session launcher: launches account session (evidence: `README.md`)
- CLI commands → Account transfer: invokes transfer (evidence: `src/claude_swap/cli.py`)
- CLI commands → Textual dashboard: opens TUI (evidence: `src/claude_swap/cli.py`)
- CLI commands → Menubar: controls menubar (evidence: `src/claude_swap/cli.py`)
- CLI commands → Background agent: manages agent (evidence: `src/claude_swap/cli.py`)
- CLI commands → Update checker: checks upgrades (evidence: `src/claude_swap/cli.py`)
- Account switcher → OAuth and usage API: refreshes credentials (evidence: `src/claude_swap/switcher.py`)
- Account switcher → macOS Keychain: accesses credentials (evidence: `src/claude_swap/switcher.py`)
- Account switcher → Account models: uses account records (evidence: `src/claude_swap/switcher.py`)
- Account switcher → Usage cache: reads usage state (evidence: `src/claude_swap/switcher.py`)
- Auto-switch policy → Account switcher: selects and switches (evidence: `src/claude_swap/autoswitch.py`)
- Auto-switch policy → Usage cache: tracks polling state (evidence: `src/claude_swap/autoswitch.py`)
- Auto-switch policy → Polling policy: uses poll policy (evidence: `src/claude_swap/autoswitch.py`)
- Usage cache → OAuth and usage API: fetches measurements (evidence: `src/claude_swap/usage_store.py`)
- Textual dashboard → Dashboard snapshots: refreshes snapshots (evidence: `src/claude_swap/tui/app.py`)
- Textual dashboard → Account switcher: performs account actions (evidence: `src/claude_swap/tui/app.py`)
- Textual dashboard → Auto-switch policy: runs auto view (evidence: `src/claude_swap/tui/app.py`)
- Dashboard snapshots → Account switcher: collects account state (evidence: `src/claude_swap/snapshot_source.py`)
- Dashboard snapshots → Usage cache: reads cached usage (evidence: `src/claude_swap/snapshot_source.py`)
- Session launcher → Account switcher: reads stored account (evidence: `src/claude_swap/session.py`)
- Session launcher → Process launch: launches Claude Code (evidence: `README.md`)
- Session launcher → macOS Keychain: handles credentials (evidence: `src/claude_swap/session.py`)
- CLI commands → Settings: configures preferences (evidence: `src/claude_swap/cli.py`)
- Account switcher → Storage paths: uses storage locations (evidence: `src/claude_swap/switcher.py`)
- Settings → Storage paths: resolves settings file (evidence: `src/claude_swap/settings.py`)
- Menubar → Auto-switch policy: offers auto controls (evidence: `src/claude_swap/menubar.py`)
- Menubar → Account switcher: switches accounts (evidence: `src/claude_swap/menubar.py`)
- Background agent → Update checker: checks update status (evidence: `src/claude_swap/launch_agent.py`)