Metadata-Version: 2.4
Name: altergo
Version: 0.40.0
Summary: Don't break flow. Switch accounts. — N-account session manager for Claude Code, Gemini CLI, Codex, and Copilot
Author: thepixelabs
License-Expression: MIT
Project-URL: Homepage, https://altergo.pixelabs.net
Project-URL: Repository, https://github.com/thepixelabs/altergo
Project-URL: Issues, https://github.com/thepixelabs/altergo/issues
Keywords: claude,claude-code,gemini,gemini-cli,codex,github-copilot,multi-account,session-manager,ai-coding-assistant,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/logo-light.svg">
    <img alt="altergo" src="docs/logo-dark.svg" width="420">
  </picture>
</p>

<p align="center">
  <strong>Don't break flow. Switch accounts.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/altergo/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/altergo"></a>
  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10+-blue.svg">
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
  <a href="https://github.com/thepixelabs/altergo/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/thepixelabs/altergo/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/thepixelabs/altergo/actions/workflows/release.yml"><img alt="CD" src="https://github.com/thepixelabs/altergo/actions/workflows/release.yml/badge.svg"></a>
</p>

<p align="center">
  Personal account, Pro subscription, side project — as many as you need.<br>
  <code>altergo personal</code> and you are in. Isolates credentials. Shares everything else.
</p>

---

## <img src="docs/icons/why.svg" width="22" align="center"> Why altergo

You're mid-session and your AI hits a limit — or you need a different model for the next task. `altergo pro` swaps credentials in place. Same project, same history, no ramp-up. You just keep working.

**When altergo matters:**

- **Rate-limited. Not stopped.** You hit the wall mid-thought. Another account is ready. Switch credentials and drop back into the same session — no lost context, no starting over.
- **Thinker, then sprinter.** One account for deep architecture (extended reasoning, heavy models). Another for rapid execution (fast models, high throughput). Flip between them like gear ratios — same codebase, different operating mode.
- **Clients, credentials, firewalls.** Consultant with three engagements? OSS contributor with a personal account and a project account? Each gets isolated credentials. Shared history stays local. Nothing leaks sideways.
- **Work vs. personal.** Your employer provisions a managed AI account. You also have a personal one for side projects. Keep them cleanly separated on one machine without touching either.

altergo runs each account in its own isolated HOME, so credentials never mix. Session history, settings, and tool configs are shared across all accounts via symlinks — pick up any conversation from any account, instantly.

### Isolated by account. Shared where it matters.

**Each account keeps its own:**

- `~/.claude/.credentials.json` — OAuth tokens and session cookies live per account. Nothing leaks sideways.
- `~/.claude.json` — per account (holds your `oauthAccount` identity), but `mcpServers` is bidirectionally synced so `claude mcp add` registrations propagate automatically.

**Every account shares:**

- your sessions and projects
- your skills, commands, and agents
- your CLAUDE.md and keybindings
- your plans, tasks, file history, and shell snapshots
- your settings.json

Shared entries are real symlinks to the same underlying file or directory — when you edit your CLAUDE.md under one account, every other account sees the change instantly. Same inode, no sync step.

No daemon. No sync service. No config files to wrangle. One Python file.

### Before and after

<table>
<tr>
<th width="50%">Before altergo</th>
<th width="50%">With altergo</th>
</tr>
<tr>
<td>

- Hit a limit mid-session → terminal dead end, context lost, start over
- Separate terminals per account, or swap credential files by hand
- Each account has its own session history — "where was I?" requires hunting
- Tool configs (AWS, gcloud, kubectl) randomly break as you jump around
- No visual indicator of which account is active until something breaks

</td>
<td>

- Hit a limit → `altergo pro` → same session, different credentials, keep going
- One terminal. One command. Right credentials, instantly.
- Session history shared across **all** accounts — `altergo --resume` picks from everywhere
- AWS, gcloud, Docker, kubectl stay shared by default — nothing breaks
- Each account isolated at `HOME`, wires never cross

</td>
</tr>
</table>

---

## <img src="docs/icons/install.svg" width="22" align="center"> Install

**pip** (recommended — always up to date from PyPI)

```bash
pip install altergo
```

**pipx** (isolated environment)

```bash
pipx install altergo
```

**curl** (single-file, no pip required)

```bash
curl -fsSL \
  https://raw.githubusercontent.com/thepixelabs/altergo/main/altergo.py \
  -o ~/.local/bin/altergo
chmod +x ~/.local/bin/altergo
```

**Requirements:** Python 3.10+, one or more supported AI CLI tools installed (Claude Code, Gemini CLI, Codex, or GitHub Copilot), macOS or Linux.

---

## <img src="docs/icons/quickstart.svg" width="22" align="center"> Quick start

```bash
# Name your accounts — run once per login you have
altergo --config personal
altergo --config pro

# Launch your configured AI assistant as that account
altergo personal

# Open the interactive session picker across all accounts
altergo --resume
```

That is the full workflow. The first time you run `altergo personal`, your configured provider authenticates under that account's isolated credentials. Every session you create is visible from every account — switch accounts, not worlds. Your history follows you everywhere.

### What to try next

- `altergo --search "docker build"` — full-text search across every session from every account
- `altergo --resume` — interactive picker; press `/` to search, `f` to filter by provider, `s` to change sort
- `altergo work --add-provider codex` — one identity, many tools: your `work` account can run claude AND codex AND gemini, switched by `altergo work codex` etc.
- `altergo --settings` — enable **tmux sessions** so your AI keeps running when SSH drops
- `altergo native` — launch your provider against your real `$HOME` (bypass isolation when you need it)
- `altergo --rename old new` — rename an account without losing credentials or history

---

## <img src="docs/icons/features.svg" width="22" align="center"> Features

| Feature | What it means |
|---|---|
| **Named accounts** | `personal`, `pro`, `sideproject`, or any name. One per AI account you use. Each gets its own isolated provider credentials. |
| **One command to switch** | `altergo pro` launches your configured AI assistant with the right credentials. No flags, no config editing. |
| **Credential isolation** | Each account's provider credentials are isolated. AWS, GCP, Docker, kubectl, and GitHub CLI stay shared by default. |
| **Shared skills, commands, agents** | User-authored Claude Code skills, slash commands, and agent definitions live under your primary home. Every account picks them up through the same symlinks. |
| **MCP sync** | `claude mcp add` registrations propagate across all accounts automatically. OAuth identity stays isolated. |
| **Configurable sharing** | `altergo --settings` opens a multi-page TUI — configure appearance (theme, launch animation), behavior (greeting/goodbye messages, tmux persistence, update checks), and which CLI tool credentials are shared. |
| **Interactive session picker** | Full-screen TUI with arrow keys, `j`/`k` vim bindings, full-text search (`/`), provider filter (`f`), sort (`s`), goto (`g`), and a preview of each session's final message. |
| **Full-text conversation search** | `altergo --search "query"` searches across every session from every account. |
| **tmux session persistence** | Opt in via settings — wraps every session in a tmux window so it survives SSH disconnects and can be reattached. |
| **Native passthrough** | `altergo native` launches your provider against your real `$HOME` — handy for quick one-offs without isolation. |
| **Zero dependencies** | Ships as a single Python file. Standard library only. |
| **Cross-platform** | macOS and Linux wherever Python 3.10+ is available. |

---

## <img src="docs/icons/commands.svg" width="22" align="center"> Command reference

| Command | What it does |
|---|---|
| `altergo <name>` | Launch the configured AI assistant as the named account (e.g. `altergo personal`) |
| `altergo <name> <provider>` | Launch a specific provider under the named account, overriding that account's default (e.g. `altergo personal gemini`) |
| `altergo` | Launch the default account's AI assistant (backwards compatible) |
| `altergo native` | Launch your configured provider against your real `$HOME` — no isolation, no symlinks |
| `altergo native <provider>` | Same as above, but force a specific provider (e.g. `altergo native gemini`) |
| `altergo --recall` | Open the interactive TUI session picker (all accounts, all providers); account is resolved from the selected session |
| `altergo --resume` | Pass `--resume` through to the provider's own native resume UI |
| `altergo --resume <id>` | Resume a specific session by ID directly |
| `altergo --search <query>` | Full-text search across every session from every account |
| `altergo --config <name>` | Create or reconfigure a named account, wire symlinks automatically |
| `altergo <name> --add-provider <id>` | Add another provider to an existing account (reconciles any orphan data) |
| `altergo <name> --remove-provider <id>` | Remove a provider from an account (session data in MAIN_HOME untouched) |
| `altergo <name> --default-provider <id>` | Set which provider plain `altergo <name>` launches |
| `altergo --rename <old> <new>` | Rename an existing account (credentials and history preserved) |
| `altergo --teardown` | Remove symlinks (account directory and credentials untouched) |
| `altergo --teardown --name <n>` | Remove a specific named account's symlinks |
| `altergo --settings` | Multi-page settings TUI: appearance, behavior, and credentials |
| `altergo <name> shell` | Interactive shell inside the named account HOME |
| `altergo <name> -- <cmd>` | Run one command with HOME set to the named account directory |
| `altergo --version` | Show version number |
| `altergo --help` | Show help text |

### Keyboard shortcuts (interactive picker)

| Key | Action |
|---|---|
| `↑` / `k` | Move up |
| `↓` / `j` | Move down |
| `PgUp` / `PgDn` | Page scroll |
| `Tab` / `Shift+Tab` | Next / previous page |
| `g` / `G` | Jump to top / bottom |
| `/` | Full-text search within sessions |
| `f` | Filter by provider |
| `s` | Cycle sort order |
| `Enter` | Resume session |
| `q` / `Esc` | Quit |

### Keyboard shortcuts (settings TUI)

| Key | Action |
|---|---|
| `←` / `→` / `h` / `l` / `Tab` | Switch pages |
| `↑` / `↓` / `j` / `k` | Navigate within page |
| `Space` | Toggle setting |
| `s` | Save and exit |
| `q` / `Esc` | Cancel |

---

## <img src="docs/icons/howitworks.svg" width="22" align="center"> How it works

altergo sets `HOME=~/.altergo/accounts/<name>` for the provider process. Each account's token lives in its isolated provider directory (e.g. `.claude/.credentials.json` for Claude Code, `.gemini/oauth_creds.json` for Gemini CLI). Everything else is shared via symlinks back to the primary provider directory.

```
~/.claude/                        Your primary Claude Code account (untouched)
    ├── .credentials.json
    ├── projects/
    └── ...

~/.altergo/
    └── accounts/
        ├── default/              Default alt account  (Claude Code provider shown)
        │   └── .claude/
        │       ├── .credentials.json   ← isolated per account
        │       ├── projects/        ──→ symlink to ~/.claude/projects/
        │       ├── settings.json    ──→ symlink to ~/.claude/settings.json
        │       └── CLAUDE.md        ──→ symlink to ~/.claude/CLAUDE.md
        └── pro/                  Named account (altergo --config pro)
            └── .claude/
                ├── .credentials.json   ← isolated per account
                ├── projects/        ──→ symlink to ~/.claude/projects/
                └── ...
```

**What gets symlinked — shared across all accounts (Claude Code provider):** `projects/`, `tasks/`, `session-env/`, `file-history/`, `shell-snapshots/`, `agents/`, `commands/`, `skills/`, `plans/`, `cache/`, `settings.json`, `CLAUDE.md`, `keybindings.json`.

The "why": user-authored content (skills, commands, agents, CLAUDE.md), persistent preferences (settings.json, keybindings.json), and project state (projects, tasks, plans, session history) all belong to *you*, not to a specific OAuth identity. Sharing them means one edit is visible from every account — same inode, no sync step.

**What stays separate per account:** provider credentials (`.credentials.json` for Claude Code; `oauth_creds.json` for Gemini CLI; `auth.json` for Codex; `config.json` for Copilot) and the isolated machinery behind them (`.claude.json`, `plugins/`, `paste-cache/`).

### MCP servers: sync, not symlink

Claude Code stores both `mcpServers` and `oauthAccount` inside `~/.claude.json`. Symlinking that file would leak your OAuth identity across accounts; *not* sharing it would strand every `claude mcp add` in whichever account happened to run it. altergo splits the difference: on every `altergo --config` and every Claude launch it **bidirectionally merges** the `mcpServers` section between your primary `~/.claude.json` and the account's `.claude.json`, then atomically writes both files back. `oauthAccount` is never touched. Register an MCP server once; every account sees it.

**CLI tool credentials** are shared or isolated per tool, configurable via `altergo --settings`. Shared by default: `.aws`, `.config/gcloud`, `.azure`, `.docker`, `.kube`, `.terraform.d`, `.config/gh`. Isolated by default: `.ssh`, `.gitconfig`, `.gnupg`, `.npmrc`, `.config/glab`.

### Running other tools in account context

Some tools (`gh`, `git`, SSH) read credentials from your home directory. Use `altergo <name> shell` or `altergo <name> -- <cmd>` to run them inside a specific account's HOME:

```bash
# Authenticate gh inside a specific account's environment
altergo pro shell
gh auth login
exit

# Or run a single command directly
altergo pro -- gh auth login
altergo pro -- gh auth status
```

Credentials set this way persist in `~/.altergo/accounts/pro/` and are available every time you run `altergo pro`. The same pattern works for the default account with `altergo shell` or `altergo -- <cmd>`.

### macOS Keychain note

When using Claude Code, tokens may be stored in the system Keychain rather than a flat file. When you authenticate inside `altergo pro`, the token is stored under a separate Keychain entry keyed to that account's email. The `.credentials.json` file may appear empty — this is expected. Auth still works correctly.

---

## <img src="docs/icons/migrate.svg" width="22" align="center"> Migrating older installs

- **From v0.4.x:** auto-migration existed through v0.35.2 and was removed in v0.35.3. If you are still on a pre-v0.5.0 layout today, see [docs/migration.md](docs/migration.md#archived-migration-notes-v04x--v050) for the archived steps — or open an issue for manual guidance.
- **Syntax change in v0.34.0:** `altergo --config --name <n>` is now `altergo --config <name>`. The old form was removed; update any aliases.
- **From claude100-resume:** credentials and aliases are not picked up automatically. See [docs/migration.md](docs/migration.md) for step-by-step instructions.

---

## <img src="docs/icons/howitworks.svg" width="22" align="center"> Next steps

- [docs/how-it-works.md](docs/how-it-works.md) — the mechanics and design tradeoffs, in depth
- [docs/settings.md](docs/settings.md) — every setting, what it toggles, and where it is stored
- [docs/migration.md](docs/migration.md) — upgrade notes, syntax changes, and archived migrations

Three power-user features new users miss:

- `altergo --search "<query>"` — full-text search across every session, every account
- **tmux session persistence** — toggle it in `altergo --settings` → Behavior so SSH drops never kill a session again
- `altergo native` — launch your provider against your real `$HOME` when you want isolation out of the way

---

## <img src="docs/icons/legal.svg" width="22" align="center"> Contributing & License

See [CONTRIBUTING.md](CONTRIBUTING.md) · [MIT License](LICENSE)

---

> altergo is an independent open-source project by [Pixelabs](https://pixelabs.net) · not affiliated with Anthropic, Google, OpenAI, or GitHub
>
> altergo depends on the internal directory structure of each supported provider. Any provider may change their structure without notice — if altergo breaks after an update, please [open an issue](https://github.com/thepixelabs/altergo/issues). Back up your provider data directories before first use. Full terms in [DISCLAIMER.md](DISCLAIMER.md).
