convez.ai
MCP Server
tlrmchlsmth

claudectx

tlrmchlsmth/claudectx

Ver no GitHub
InicialPluginScore · de 0 a 100

kubectx for AI coding agents — switch paired Claude Code + Codex CLI contexts (settings, tokens, skills, MCP servers) and translate config between them

Instalação

$npx convez-ai tlrmchlsmth/claudectx

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
1
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

claudectx

CI

kubectx for your AI coding agents. Keep independent, named profiles for Claude Code and Codex CLI — settings, auth tokens, skills, instructions, MCP servers — and switch each tool on its own axis. Translate configuration between the two tools.

Why per-tool? Identities don't pair up. You might have three Claudes (work via Vertex, personal Max plan, a work API key) and two Codexes (personal, work API key). Each tool switches independently:

$ claudectx create claude vertex
$ claudectx claude vertex
Switched claude to "vertex" (keychain ✓)
$ claudectx codex work          # codex switches without touching claude
Switched codex to "work"
$ claudectx
claude: vertex
codex:  work
$ claudectx claude -            # per-tool previous

Install

go install github.com/tlrmchlsmth/claudectx@latest   # or: just install

Then adopt your existing state:

claudectx init

init moves ~/.claude and ~/.codex into per-tool default profiles under ~/.claudectx/profiles/ and symlinks them back. Nothing is deleted; ~/.claude.json is backed up to ~/.claudectx/backups/ first. If either path is already a symlink you manage yourself (e.g. into dotfiles), claudectx refuses to touch it and tells you why.

Terminal-scoped profiles

Global switching changes every terminal at once (it's a symlink). To pin just one terminal's tool to a profile, use env pinning — both tools natively honor CLAUDE_CONFIG_DIR / CODEX_HOME:

eval "$(claudectx env codex work)"   # this terminal's codex now uses "work"
claudectx shell --claude vertex --codex work   # or: a pinned subshell
eval "$(claudectx env --unset)"      # follow the global profiles again

Add eval "$(claudectx shell-init)" to your shell rc for the short form:

cx claude work    # pin this terminal's claude
cx codex personal # pin this terminal's codex
cx off            # unpin both
cx                # status

claudectx current and the status view are pin-aware. One caveat: the macOS Keychain is per-user, not per-terminal, so pinned terminals share whichever Claude login is globally active — pinning isolates settings, skills, MCP servers, and history, not the OAuth token. (Codex auth.json is per-profile even when pinned.) Avoid running global switches while a pinned terminal actively uses the same profile — both write the same .claude.json.

Tab completion

claudectx completion <bash|zsh|fish> prints a completion script that completes subcommands, tool names, flags, and live profile names:

# bash (~/.bashrc) or zsh (~/.zshrc, after compinit):
eval "$(claudectx completion bash)"
eval "$(claudectx completion zsh)"

# fish:
claudectx completion fish > ~/.config/fish/completions/claudectx.fish

The zsh script also works as a static file: save it as _claudectx anywhere in your $fpath.

How it works

~/.claude  -> ~/.claudectx/profiles/claude/<current>/home   (symlink)
~/.codex   -> ~/.claudectx/profiles/codex/<current>/home    (symlink)
~/.claude.json <- copy-swapped on claude switches with the profile's
                  home/.claude.json (not symlinked: Claude Code rewrites it
                  with rename(2), which would destroy a symlink)

Each axis has its own current/previous in ~/.claudectx/state.json. The profile's claude.json copy lives at profiles/claude/<name>/home/.claude.json — exactly where Claude Code itself writes it under CLAUDE_CONFIG_DIR, so global mode and terminal pinning share one canonical file.

A claude switch runs five journaled steps (stash keychain → capture claude.json → repoint link → install claude.json → restore keychain). A codex switch is a single atomic link repoint — auth.json lives inside the dir and travels by itself.

Crash recovery

Every multi-step operation writes a journal entry to ~/.claudectx/state.json before each step. If a switch or migration dies halfway — power loss, ^C, a failing security call — the next claudectx command of any kind notices the journal and rolls the operation forward to its target before doing anything else. Steps are ordered so this is always safe: outgoing state is captured before anything moves, the symlink repoint is the atomic commit point, and the installing steps are pure replays. Recovery reconciles by looking at where the links actually point, not by trusting what the journal says happened, so even a crash during recovery converges. claudectx doctor shows any pending journal.

Tokens

Each profile carries its own logins:

  • Codex: auth.json (a ChatGPT login or your OPENAI_API_KEY) lives inside the symlinked dir — travels with the profile automatically. Use codex login --with-api-key so the key lands on disk; a key set only via the OPENAI_API_KEY shell variable is not profile-scoped.
  • Claude Code (macOS): the OAuth token lives in the Keychain. On switch, claudectx stashes it into the outgoing profile (profiles/claude/<name>/secrets/, mode 0600) and restores the incoming profile's token. A profile with no stored login gets the keychain item deleted, so tokens never leak between profiles; just run claude and log in once.
  • Claude Code (Linux): ~/.claude/.credentials.json travels with the dir.
  • Claude via Vertex or an Anthropic API key: configure the env block of the profile's settings.json (CLAUDE_CODE_USE_VERTEX, ANTHROPIC_API_KEY, …) — it's a file in the profile, so it travels.

Disable keychain handling with CLAUDECTX_NO_KEYCHAIN=1. No credential — the Keychain stash, Claude's .credentials.json, or Codex's auth.json — is ever copied by create --from; clones start logged out so each profile holds its own key. Tokens are also never printed and never passed as command-line arguments.

Commands

CommandWhat it does
claudectxstatus: both tools' current profiles
claudectx claude <name> / claudectx codex <name>switch that tool (--force skips the running-process check)
claudectx claude - / claudectx codex -that tool's previous profile
claudectx claude / claudectx codexlist that tool's profiles
claudectx list [--json]both tools' profiles
claudectx current [claude|codex]both currents, or one bare name (scriptable)
claudectx show <tool> [name] [--json]settings, skills, MCP servers, token presence
claudectx create <tool> <name> [--from [<p>]]new empty profile; --from clones one (never its credentials)
claudectx delete <tool> <name>confirm, then move to backups/ (never rm -rf)
claudectx rename <tool> <old> <new> [--force]rename (relinks if active)
eval "$(claudectx env <tool> <name>)" / claudectx shell …pin one terminal
claudectx translate <direction>convert config between the tools (below)
claudectx migrateupgrade a v1 paired-context install (below)
claudectx doctor [--fix]verify symlinks, perms, state consistency
claudectx completion <bash|zsh|fish>print a tab-completion script

Translation

claudectx translate claude-to-codex --dry-run
claudectx translate codex-to-claude --claude vertex --codex work --only mcp,skills

Directions: claude-to-codex, codex-to-claude. Source and target profiles default to each tool's current (--claude/--codex to pick others) and the run prints a report of everything translated, skipped, or lost:

ArtifactClaudeCodexFidelity
InstructionsCLAUDE.mdAGENTS.md@file imports are inlined (Codex has no imports; --no-inline-imports to keep verbatim)
Skillsskills/*/SKILL.mdskills/*/SKILL.mdsame Agent Skills standard — copied; Claude-only frontmatter (allowed-tools, …) kept with a warning
MCP serversmcpServers in ~/.claude.json[mcp_servers.*] in config.tomlstdio servers map 1:1; http/sse reported with a paste-ready snippet
Permissionspermissions.defaultModeapproval_policy + sandbox_modemode maps; allow/deny rule lists have no Codex equivalent (reported as lost with counts)
Modelsmodelmodelnever translated across vendors

Existing destination files are merged, not clobbered: config.toml edits are spliced around your comments and re-validated before writing; settings.json / claude.json merges only touch the relevant keys. Conflicts skip unless --force. A symlinked CLAUDE.md/AGENTS.md destination is never overwritten.

Migrating from v1

claudectx ≤0.1.x paired both tools into one context. claudectx migrate converts that layout to per-tool profiles:

  • each context's claude/codex halves become profiles/claude/<name> and profiles/codex/<name> (empty halves are skipped),
  • keychain stashes move with the claude profile,
  • both axes stay on whatever the live links pointed at (exact semantic preservation), and previous carries over per axis where it exists,
  • the v1 state.json and all leftovers are kept under ~/.claudectx/backups/ until you delete them.

The migration is journaled like every other operation: if it's interrupted, the next claudectx command rolls it forward. It's safe to run while the tools are running (moves are atomic renames; open files keep working). Terminals pinned with claudectx env before migrating must re-run the eval. The one hard requirement: a v1 install with an interrupted v1 operation must be recovered with v0.1.x first.

Environment variables

VariableDefaultPurpose
CLAUDECTX_HOME~/.claudectxstate root
CLAUDECTX_CLAUDE_DIR$CLAUDE_CONFIG_DIR or ~/.claudemanaged Claude dir
CLAUDECTX_CODEX_DIR$CODEX_HOME or ~/.codexmanaged Codex dir
CLAUDECTX_CLAUDE_JSON~/.claude.jsoncopy-swapped Claude state file
CLAUDECTX_NO_KEYCHAINunsetdisable macOS Keychain handling

Architecture

graph TD
    main["main.go"] --> cli["internal/cli<br/>per-tool dispatch + commands"]

    cli --> adopt["internal/adopt<br/>init: take over ~/.claude + ~/.codex"]
    cli --> switcher["internal/switcher<br/>journaled per-axis switch + recovery"]
    cli --> migratepkg["internal/migrate<br/>v1 contexts -> v2 profiles"]
    cli --> doctor["internal/doctor<br/>health checks, --fix"]
    cli --> translate["internal/translate<br/>instructions / skills / mcp / settings"]

    adopt --> linker["internal/linker<br/>symlink classify + atomic repoint"]
    switcher --> linker
    migratepkg --> linker
    doctor --> linker

    adopt --> store["internal/store<br/>state.json (two axes), journal, profile CRUD"]
    switcher --> store
    migratepkg --> store
    doctor --> store

    switcher --> keychain["internal/keychain<br/>macOS security CLI behind an interface"]
    cli --> procs["internal/procs<br/>detect running claude/codex"]

    translate --> tomlx["internal/tomlx<br/>TOML emit + comment-preserving splice"]
    translate --> frontmatter["internal/frontmatter<br/>SKILL.md frontmatter"]
    translate --> reportpkg["internal/report<br/>actions + lossiness notes"]

    store --> paths["internal/paths<br/>all path/env resolution"]
    store --> toolpkg["internal/tool<br/>the claude/codex axis type"]
    linker --> paths

Layering rules: paths is the only package that reads environment variables; everything receives a Paths value, which is what makes the whole tree testable under a temp dir. tool is the leaf axis type every layer shares. linker and store are the primitives; switcher (journaled, per-axis), adopt, and migrate compose them; cli only parses arguments and formats output. translate is a pure planner: each translator returns Actions with attached LossNotes, and nothing touches disk until the plan is applied — which is why --dry-run output is exactly what a real run does.

PackageOne-liner
cliper-tool dispatch (claude/codex subcommands), command implementations, exit codes
toolthe axis type (claude | codex) shared by every layer
pathsresolves every location from env, detects per-axis terminal pinning
storetwo-axis state.json, crash journal, profile CRUD, name validation
linkerclassifies live paths (real dir / managed link / foreign link / dangling) and atomically repoints symlinks
switcherclaude: 5-step journaled switch (keychain + claude.json swap); codex: atomic link repoint
adoptinit: moves existing real dirs into per-tool default profiles; refuses foreign symlinks
migratejournaled v1→v2 layout upgrade; live axes first to minimize the relink window
keychainBackend interface over the macOS security CLI (secret via stdin, never argv) with Null/Fake implementations
procsscans ps for running claude/codex so switch/rename can warn first
doctorread-only health checks (links vs state per axis, perms, stale journal, v1 layout) with an auto---fix subset
translatethe four translators; plan-then-apply with per-artifact lossiness reporting
tomlxminimal TOML emitter + textual section splice that preserves user comments, re-validated before write
frontmattertolerant SKILL.md frontmatter parse that round-trips byte-faithfully
reportshared Action/LossNote model and terminal rendering
fsxCopyTree (symlink-preserving) shared by adopt/create/skills
testenvtest fixture builder: realistic ~/.claude/~/.codex trees and a full v1 installation under t.TempDir()

Development

just test     # go test ./...
just lint     # go vet
just build    # bin/claudectx

Everything is testable against a throwaway root: the env vars above redirect every path, and the keychain sits behind an interface with a fake.

License

Apache-2.0

Ver o original no GitHub

Bom para

Relacionados