ccctx

ccctx is a small Go CLI for saving, listing, switching, and temporarily executing with multiple Claude Code and pi Anthropic OAuth sessions on one machine.

The project is built to be maintained by LLM coding agents as a first-class workflow. Human-readable docs, llms.txt, Claude Code plugin metadata, and portable Agent Skills are all kept in-repo so future agents can understand the codebase, change it safely, and verify their work without reverse-engineering the project from scratch.

LLM-First Maintenance Contract

Every change should make the repository easier for LLMs to use, review, and update.

Before changing code, agents should read llms.txt, then choose the project skill that matches the task:

• ccctx-work: implement features, fixes, tests, and docs.
• ccctx-review: review diffs, pull requests, or release candidates.
• ccctx-update: update maintenance files, docs, CI, plugin metadata, and release prep.

Claude Code can load these skills directly from this checkout:

claude --plugin-dir .

Then invoke:

/ccctx-work implement a focused bug fix
/ccctx-review review the current diff
/ccctx-update refresh documentation and maintenance files

See docs/skills.md and docs/llm-maintenance.md.

What It Does

ccctx works like a kubectx-style selector for Claude Code and pi Anthropic OAuth sessions:

ccctx           # list saved sessions
ccctx work      # switch to the work session
claude          # runs with the work Claude auth session
pi              # runs with the work pi Anthropic auth session
ccctx personal  # switch both clients to the personal session

If Claude Code is already logged in but that account has not been saved yet, ccctx shows it as current (unsaved).

Install

go install github.com/mauromedda/ccctx/cmd/ccctx@latest

From this checkout:

go install ./cmd/ccctx

Quick Workflow

1. Log in to Claude Code with the first account.

2. Save the active authentication:

   ccctx save work

3. Log both clients in with another account.

4. Save it:

   ccctx save personal

5. Configure each saved Claude subscription for pi with a long-lived setup token:

   ccctx setup-pi work
   ccctx setup-pi personal

6. Switch any time:

   ccctx work
   claude
   pi

setup-pi switches to the requested profile, runs the interactive claude setup-token flow, and stores the generated token as that profile's pi Anthropic credential. It requires a recent Claude Code installation and never places the token in command arguments or prints it through ccctx.

Commands

ccctx                 List saved sessions
ccctx save NAME       Save current Claude Code and pi auth as NAME
ccctx save -f NAME    Overwrite an existing saved session
ccctx NAME            Switch Claude Code and pi to session NAME
ccctx use NAME        Switch Claude Code and pi to session NAME
ccctx setup-pi NAME   Generate Claude setup-token and configure pi for NAME
ccctx exec NAME --    Run a command with session NAME for this process only
ccctx current         Print the active saved session
ccctx delete NAME     Delete a saved session
ccctx rename OLD NEW  Rename a saved session

Per-Instance Sessions

Use exec when one Claude Code process should use a saved session without changing the global active session:

ccctx exec work -- claude
ccctx exec personal -- claude -p "summarize this repo"

exec starts the command with a temporary HOME, isolated Claude configuration, and an isolated PI_CODING_AGENT_DIR. Your normal ~/.claude.json and ~/.pi/agent/auth.json are not overwritten. When the command exits, refreshed Claude and pi Anthropic auth state is copied back into that saved profile.

Storage

Profiles are stored under ~/.ccctx/profiles. Each profile contains private snapshots of Claude Code state and, when configured, the anthropic credential from pi's ~/.pi/agent/auth.json.

On each switch, ccctx first saves the active profile's current Claude Code and pi Anthropic authentication. This preserves token refreshes written since the last switch. Only pi's anthropic entry is switched; credentials for OpenAI and other pi providers remain unchanged.

Environment overrides:

CCCTX_HOME=/path/to/store
CCCTX_CLAUDE_CONFIG=/path/to/.claude.json
CCCTX_PI_AUTH=/path/to/pi/auth.json

Without CCCTX_PI_AUTH, ccctx honors PI_CODING_AGENT_DIR and otherwise uses ~/.pi/agent/auth.json. Profiles created before pi support leave pi auth unchanged until they are refreshed with ccctx save -f NAME.

Repository Map

cmd/ccctx/              CLI entry point
internal/ccctx/         application logic and behavior tests
docs/                   architecture, development, skill, and LLM maintenance docs
skills/                 portable Agent Skills for review, update, and work
.claude-plugin/         Claude Code plugin manifest
.github/                CI, issue templates, and PR template
llms.txt                compact agent entrypoint

Development

Run the local verification path before changing behavior:

make check
go build -o bin/ccctx ./cmd/ccctx
claude plugin validate . --strict

Useful docs:

• llms.txt: first file for LLM agents.
• CONTRIBUTING.md: contributor workflow.
• docs/architecture.md: package, storage, credential, and exec-mode design.
• docs/development.md: local development commands.
• docs/skills.md: Claude Code and portable Agent Skill usage.
• docs/llm-maintenance.md: maintenance direction for future agents.

Security

Do not print, log, commit, or paste OAuth tokens, .credentials.json, full .claude.json or pi auth.json files, Keychain exports, or ~/.ccctx profile snapshots.

Use temporary directories and synthetic Claude configs in tests and bug reports. See SECURITY.md.

License

MIT. See LICENSE.