cchost 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,70 @@ All notable changes to `cchost` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] - 2026-11-07
+
+### Added
+
+- **`cchost` command.** The CLI now installs as both `cchost` (primary) and
+  `cc` (legacy alias). `cc` is the system C compiler on macOS and Linux, so
+  docs, help, and new scripts use `cchost`; the alias stays for backwards
+  compatibility.
+- **Inherited-auth warning.** `cchost use` now warns when `ANTHROPIC_API_KEY`,
+  `ANTHROPIC_AUTH_TOKEN`, or `CLAUDE_CODE_OAUTH_TOKEN` is set in the shell for a
+  subscription profile, because those variables can silently override the
+  profile's login. It does not strip them.
+- **Endpoint environment isolation.** Endpoint profiles now drop inherited
+  `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, and
+  `ANTHROPIC_BASE_URL` values the profile does not set itself, with a short
+  notice listing what was removed.
+- **macOS login visibility.** `cchost list` reports an inferred Keychain login
+  as `true` instead of `false`, exposes `credentialSource` in `--json`, and
+  `cchost doctor` explains that Keychain entries are namespaced by the profile's
+  exact `CLAUDE_CONFIG_DIR` path.
+- **See what a profile shares.** `cchost list <profile>` prints each of the 7
+  resources as `shared`, `private`, `empty`, `missing`, or `foreign-link`;
+  `--json` adds a `resources` object.
+- **`--dry-run`** on `cchost link`, `unlink`, and `copy` prints what would
+  change without touching the filesystem.
+- **`cchost help sharing`**: a task-oriented guide to what is shared and how to
+  make a resource private, share it again, or copy into a profile.
+
+### Changed
+
+- All README examples, help text, and error hints now use `cchost`.
+- `cchost doctor` no longer reports `/usr/bin/cc` or a real C compiler
+  (clang, gcc, ccache) as cchost; a `cc` entry counts only when it resolves to
+  cchost, and the two shims from one install still count as one entry.
+- README now separates **credential** isolation from the default shared pool.
+  `projects/` (full session transcripts) and `settings.json` / `mcp.json`
+  (code-executing config) are shared across profiles by default, and are
+  documented as a privacy/security trade-off rather than as isolated state.
+
+### Fixed
+
+- `cchost link` reports a symlink that points outside `~/.claude/` as
+  `foreign-link` instead of claiming it is already linked.
+- `cchost doctor --fix` prints and uses the post-fix results; `--json --fix`
+  is supported again and emits one post-fix JSON report (fix logs go to stderr).
+- `cchost doctor` no longer warns that macOS subscription profiles may share
+  one Keychain login; it explains that entries are namespaced by the exact
+  profile path (renaming or moving a profile requires a new login), and stays
+  silent when no profile uses a Keychain login.
+- `cchost help migrate` prints command-specific help.
+- `.cc-env.json` is created user-only; optional non-string fields are ignored
+  instead of making the profile unusable.
+- Help banner shows the version again, and `NO_COLOR` follows no-color.org
+  (a non-empty value disables color; `NO_COLOR=""` leaves it enabled).
+
+### Known limitations
+
+- **macOS Keychain entries are keyed by the exact profile path.** Claude Code
+  (verified with 2.1.319) stores each profile's OAuth token under a service
+  name derived from the `CLAUDE_CONFIG_DIR` string, so renaming, moving, or copying a profile — or
+  accessing it through a different path spelling or symlinked home — requires a
+  fresh login. `cchost list` infers the login from `.claude.json`; it does not
+  read the Keychain secret or verify that the token is still live.
+
 ## [0.4.4] - 2026-06-19
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # cchost
 
-> **nvm, but for your Claude Code accounts.** Works on Windows, Linux, and macOS.
+> **nvm, but for your Claude Code accounts.** Works on Windows, Linux, and macOS — see [Platform notes](#platform-notes) for macOS credential-storage caveats.
 
 [![npm version](https://img.shields.io/npm/v/cchost.svg)](https://www.npmjs.com/package/cchost)
 [![CI](https://github.com/allenhack638/cchost/actions/workflows/ci.yml/badge.svg)](https://github.com/allenhack638/cchost/actions/workflows/ci.yml)
@@ -9,13 +9,13 @@
 [![platforms](https://img.shields.io/badge/platforms-windows%20%7C%20linux%20%7C%20macos-blue)](#install)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/allenhack638/cchost/master/docs/demo.png" alt="cchost CLI — cc list showing masked emails and shared resource counts" width="100%">
+  <img src="https://raw.githubusercontent.com/allenhack638/cchost/master/docs/demo.png" alt="cchost CLI — cchost list showing masked emails and shared resource counts" width="100%">
 </p>
 
 `cchost` is a multi-account profile manager for [Claude Code](https://code.claude.com).
 
-- **Isolated profiles** — each profile is a complete `CLAUDE_CONFIG_DIR` with its own credentials, session history, and settings. Switch with `cc use <name>`.
-- **Shared pool** — `skills/`, `agents/`, `commands/`, `projects/`, and shared config files (`mcp.json`, `settings.json`, `CLAUDE.md`) link across all profiles by default. Credentials never do.
+- **Isolated credentials** — each profile is a complete `CLAUDE_CONFIG_DIR` with its own login, endpoint, and credential files. Credentials are never copied between profiles (on macOS, see [Platform notes](#platform-notes) for Keychain caveats). Switch with `cchost use <name>`.
+- **Shared tooling and history by default** — `skills/`, `agents/`, `commands/`, `projects/`, and the config files (`mcp.json`, `settings.json`, `CLAUDE.md`) link across all profiles. That includes session transcripts and code-executing config; see [Sharing model](#sharing-model) before using profiles for separated trust boundaries.
 - **Custom endpoints** — route a profile through any Anthropic-compatible API (Moonshot, OpenRouter, self-hosted vLLM, corporate proxies) instead of Anthropic OAuth.
 - **Zero runtime dependencies** — single Node CLI on your `PATH`. Identical behavior across PowerShell, cmd, bash, zsh, and fish.
 
@@ -27,32 +27,36 @@ npm install -g cchost
 
 Requires Node.js 18+ and Claude Code 2.1.140+ (`npm install -g @anthropic-ai/claude-code`).
 
+`cchost` is the primary command. The same binary is also installed as `cc` for
+backwards compatibility, but `cc` is the standard C compiler on macOS and
+Linux — prefer `cchost` in scripts, build files, and daily use.
+
 ## Quickstart
 
 ```bash
-cc add work             # create a profile
-cc use work             # launch Claude under it (prompts for login on first run)
-cc use work --resume    # resume the last conversation
-cc list                 # see all profiles
-cc remove old-profile   # delete a profile
+cchost add work             # create a profile
+cchost use work             # launch Claude under it (prompts for login on first run)
+cchost use work --resume    # resume the last conversation
+cchost list                 # see all profiles
+cchost remove old-profile   # delete a profile
 ```
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `cc add <profile>` | Create a subscription profile. Logs in via Anthropic OAuth on first `cc use`. Auto-shares all 7 resources with `~/.claude/`. |
-| `cc add <profile> --custom [...]` | Create or edit a custom-endpoint profile. Interactive wizard, or `--base-url=URL --token=TOKEN [--model=…]`. See [Custom endpoints](#custom-endpoints). |
-| `cc use <profile> [...args]` | Launch Claude under that profile. Extra args are forwarded to `claude`. |
-| `cc list [<profile>] [--json] [--reveal]` | List all profiles or show one in detail. Emails and tokens are masked by default; `--reveal` prints them in full. |
-| `cc copy default <profile> [--force]` | Seed an unlinked profile resource from `~/.claude/`. No-op for fully-shared profiles. |
-| `cc link <profile> [--projects\|--tools\|--config]` | Link a profile's resources to `~/.claude/`. Defaults to all 7 when no flag is passed. |
-| `cc unlink <profile> [--projects\|--tools\|--config]` | Break the link and make those resources private to the profile. Non-destructive. |
-| `cc remove <profile> [--force]` | Delete a profile. Requires typing the profile name. `--force` required when private resources exist. |
-| `cc doctor [--fix [--force]] [--json]` | Diagnose environment, storage, and platform issues. `--fix` applies safe auto-fixes; `--force` is required for destructive ones. |
-| `cc help [command]` | Print usage. |
-
-Sample `cc list` output:
+| `cchost add <profile>` | Create a subscription profile. Logs in via Anthropic OAuth on first `cchost use`. Auto-shares all 7 resources with `~/.claude/`. |
+| `cchost add <profile> --custom [...]` | Create or edit a custom-endpoint profile. Interactive wizard, or `--base-url=URL --token=TOKEN [--model=…]`. See [Custom endpoints](#custom-endpoints). |
+| `cchost use <profile> [...args]` | Launch Claude under that profile. Extra args are forwarded to `claude`. |
+| `cchost list [<profile>] [--json] [--reveal]` | List all profiles, or show one in detail including the state of each of its 7 resources. Emails and tokens are masked by default; `--reveal` prints them in full. |
+| `cchost copy default <profile> [--force] [--dry-run]` | Seed an unlinked profile resource from `~/.claude/`. No-op for fully-shared profiles. |
+| `cchost link <profile> [--projects\|--tools\|--config] [--dry-run]` | Link a profile's resources to `~/.claude/`. Defaults to all 7 when no flag is passed. |
+| `cchost unlink <profile> [--projects\|--tools\|--config] [--dry-run]` | Break the link and make those resources private to the profile. Non-destructive. |
+| `cchost remove <profile> [--force]` | Delete a profile. Requires typing the profile name. `--force` required when private resources exist. |
+| `cchost doctor [--fix [--force]] [--json]` | Diagnose environment, storage, and platform issues. `--fix` applies safe auto-fixes; `--force` is required for destructive ones. |
+| `cchost help [command]` | Print usage. `cchost help sharing` is a task guide to linking, unlinking, and copying. |
+
+Sample `cchost list` output:
 
 ```
 Profile   LoggedIn  Email                  Shared  Endpoint
@@ -61,11 +65,11 @@ personal  true      p************.com      7/7     subscription
 work      true      w************.com      7/7     subscription
 ```
 
-The `Shared` column counts how many of the 7 shareable resources are linked into `~/.claude/`. `7/7` is the default; lower numbers mean one or more resources have been `cc unlink`ed and now hold private content.
+The `Shared` column counts how many of the 7 shareable resources are linked into `~/.claude/`. `7/7` is the default; lower numbers mean one or more resources have been `cchost unlink`ed and now hold private content.
 
 ## Sharing model
 
-Anything that authenticates a profile stays per-profile; everything else is shared.
+On Windows and Linux, anything that authenticates a profile stays per-profile and everything else is shared. On macOS, OAuth credentials live in the login Keychain rather than the profile directory — see [Platform notes](#platform-notes).
 
 | Resource | Shared by default | Flag group |
 | --- | :---: | --- |
@@ -75,21 +79,28 @@ Anything that authenticates a profile stays per-profile; everything else is shar
 | `.credentials.json`, `.claude.json`, `.cc-env.json` | never | — |
 | `sessions/`, `plugins/` | never | — |
 
-Sharing uses POSIX symlinks on Linux/macOS and directory junctions on Windows (no admin or Developer Mode required). File resources fall back to a hard link on Windows when symlink creation would require elevation. Note that `mcp.json` and `settings.json` can execute arbitrary code through MCP servers and hooks — if a profile needs an isolated copy of either, run `cc unlink <profile> --config`.
+Sharing uses POSIX symlinks on Linux/macOS and directory junctions on Windows (no admin or Developer Mode required). File resources fall back to a hard link on Windows when symlink creation would require elevation. Note that `mcp.json` and `settings.json` can execute arbitrary code through MCP servers and hooks — if a profile needs an isolated copy of either, run `cchost unlink <profile> --config`.
+
+> **Privacy note:** the defaults above are convenient, not isolated. `projects/`
+> contains full conversation transcripts, and `settings.json` / `mcp.json` can
+> execute hooks and MCP servers. For a work/personal split, unlink the resources
+> that must not cross over before first use, or use a separate OS account.
 
-To break sharing for a single profile:
+To see exactly what a profile shares, run `cchost list <profile>` — it prints each resource as `shared`, `private`, `empty`, `missing`, or `foreign-link`. `cchost help sharing` walks through the common tasks.
+
+To break sharing for a single profile (add `--dry-run` to any of these to preview first):
 
 ```bash
-cc unlink work --tools     # private skills/agents/commands
-cc unlink work --projects  # private projects/
-cc unlink work --config    # private mcp.json/settings.json/CLAUDE.md
-cc unlink work             # all 7 private
-cc link work --tools       # re-share
+cchost unlink work --tools     # private skills/agents/commands
+cchost unlink work --projects  # private projects/
+cchost unlink work --config    # private mcp.json/settings.json/CLAUDE.md
+cchost unlink work             # all 7 private
+cchost link work --tools       # re-share
 ```
 
-`cc unlink` is non-destructive — pool content is copied into the profile before the link is broken. `cc link` refuses to overwrite existing private content; remove or relocate the private resource manually, then re-run.
+`cchost unlink` is non-destructive — pool content is copied into the profile before the link is broken. `cchost link` refuses to overwrite existing private content; remove or relocate the private resource manually, then re-run.
 
-Use `cc copy default <profile>` to seed an unlinked resource from the current `~/.claude/`. For fully-shared profiles this is a no-op.
+Use `cchost copy default <profile>` to seed an unlinked resource from the current `~/.claude/`. For fully-shared profiles this is a no-op.
 
 ## Custom endpoints
 
@@ -97,43 +108,77 @@ A profile can route through any Anthropic-compatible API — Moonshot/Kimi, Open
 
 > **Billing:** custom-endpoint profiles bill through the **third-party provider**, not your Anthropic subscription.
 
+Inherited Anthropic auth/endpoint variables (`ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_BASE_URL`) are removed for endpoint profiles when the profile doesn't set them, so a shell-level key cannot override the endpoint.
+
 ```bash
-cc add kimi --custom --base-url=https://api.moonshot.ai/anthropic \
+cchost add kimi --custom --base-url=https://api.moonshot.ai/anthropic \
                      --token=sk-your-key \
                      --model=kimi-k2.5
-cc use kimi
+cchost use kimi
 ```
 
-Run `cc add <profile> --custom` with no value flags for an interactive wizard — it prompts for every field and never echoes the token. Re-running on an existing custom-endpoint profile enters **edit mode**: the wizard prefills current values, and with flags only the flags you pass are changed.
+Run `cchost add <profile> --custom` with no value flags for an interactive wizard — it prompts for every field and never echoes the token. Re-running on an existing custom-endpoint profile enters **edit mode**: the wizard prefills current values, and with flags only the flags you pass are changed.
 
 ```bash
-cc add kimi --custom --model=kimi-k3      # change just the model
-cc add kimi --custom --token=sk-rotated   # rotate the API key
+cchost add kimi --custom --model=kimi-k3      # change just the model
+cchost add kimi --custom --token=sk-rotated   # rotate the API key
 ```
 
-Subscription and custom-endpoint profiles are mutually exclusive: a profile is either one or the other for its entire lifetime. To switch, remove the profile with `cc remove` and recreate it.
+Subscription and custom-endpoint profiles are mutually exclusive: a profile is either one or the other for its entire lifetime. To switch, remove the profile with `cchost remove` and recreate it.
 
-Inspect with `cc list <profile>` (token masked) or `cc list <profile> --reveal` (full). The endpoint URL should not include `/v1` — Claude Code appends `/v1/messages` itself. Most providers serve a single model; `--model` applies to every tier (`opus`/`sonnet`/`haiku`/`subagent`), or override per-tier with `--opus=`, `--sonnet=`, etc.
+Inspect with `cchost list <profile>` (token masked) or `cchost list <profile> --reveal` (full). The endpoint URL should not include `/v1` — Claude Code appends `/v1/messages` itself. Most providers serve a single model; `--model` applies to every tier (`opus`/`sonnet`/`haiku`/`subagent`), or override per-tier with `--opus=`, `--sonnet=`, etc.
 
-On launch, `cc use` prints a one-line endpoint banner to stderr:
+On launch, `cchost use` prints a one-line endpoint banner to stderr:
 
 ```
 [cchost] Profile 'kimi' → api.moonshot.ai (custom endpoint billing applies)
 ```
 
+## Platform notes
+
+### macOS
+
+Claude Code stores OAuth credentials in the login **Keychain**, not in
+`<profile>/.credentials.json`. Claude Code namespaces the Keychain entry by
+the exact `CLAUDE_CONFIG_DIR` path (verified with Claude Code 2.1.319):
+
+```
+Claude Code-credentials-<first 8 hex of sha256(path)>
+```
+
+So each profile gets its own Keychain entry. Two consequences:
+
+- `cchost list` infers the login from `.claude.json`; it does not read the
+  Keychain secret. Treat `LoggedIn` as a login hint, not proof of a live token.
+- The entry is keyed by the exact path string. Renaming, moving, or copying a
+  profile — or addressing it through a different path spelling or symlinked
+  home — changes the key and looks like a logout. Run `claude` under the new
+  path to log in again.
+
+If you need guaranteed account separation on macOS, **custom-endpoint profiles**
+(each has its own token in `.cc-env.json`) or separate macOS user accounts are
+still the most explicit option.
+
+### Windows and Linux
+
+Credentials are file-based (`.credentials.json` in the profile directory), so
+the `LoggedIn` column reflects the profile's own credential file.
+
 ## Security
 
-`~/.claude-profiles/<profile>/` holds real OAuth credentials and API keys. Treat it like `~/.ssh`: don't commit it, don't share it, don't sync it to public cloud storage. The shipped `.gitignore` excludes profile directories. `cc copy` and `cc link` never touch credential files (`.credentials.json`, `.claude.json`, `.cc-env.json`); each profile keeps its own auth state.
+`~/.claude-profiles/<profile>/` holds real OAuth credentials and API keys. Treat it like `~/.ssh`: don't commit it, don't share it, don't sync it to public cloud storage. The shipped `.gitignore` excludes profile directories. `cchost copy` and `cchost link` never touch credential files (`.credentials.json`, `.claude.json`, `.cc-env.json`); each profile keeps its own auth state. On macOS, OAuth tokens are stored in the login Keychain instead — see [Platform notes](#platform-notes).
 
 ## Troubleshooting
 
-Run `cc doctor` first — it checks Node, Claude Code version, profile integrity, symlinks, and the shared pool.
+Run `cchost doctor` first — it checks Node, Claude Code version, profile integrity, symlinks, and the shared pool.
 
 **`Claude Code does not appear to be installed`** — install with `npm install -g @anthropic-ai/claude-code` and verify `claude --version` runs in a fresh terminal.
 
 **`warning: Claude Code <version> is older than 2.1.140`** — earlier versions on Windows read `.claude.json` from `%USERPROFILE%` regardless of `CLAUDE_CONFIG_DIR`, breaking isolation. Run `claude update`.
 
-**`Profile "<name>" does not exist`** — `cc use` does not auto-create profiles. Run `cc add <name>` first.
+**`warning: ANTHROPIC_API_KEY ... may override the subscription login`** — a globally exported API key takes precedence over a profile's OAuth login. Unset it in that shell (`unset ANTHROPIC_API_KEY`, and the same for `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN`) or use a custom-endpoint profile.
+
+**`Profile "<name>" does not exist`** — `cchost use` does not auto-create profiles. Run `cchost add <name>` first.
 
 **Profile name rejected** — names must not contain path separators, whitespace, `..`, leading dots, or DOS reserved names (`CON`, `PRN`, `COM1`…). Use letters, digits, dashes, and underscores.
 

package/lib/banner.js

@@ -14,9 +14,11 @@ function renderBanner() {
   try {
     version = require('../package.json').version;
   } catch {
+    // Not fatal — help still works if package.json is unreadable.
   }
   const tagline = 'Multi-profile launcher for Claude Code';
-  return BANNER + '         ' + '\n\n';
+  const label = version ? `cchost ${version} — ${tagline}` : `cchost — ${tagline}`;
+  return BANNER + '  ' + label + '\n\n';
 }
 
 module.exports = { renderBanner, BANNER };