Imported from XeriChen/grok-switch (AGENTS.md). Install upstream with npx skills add XeriChen/grok-switch. Copyright stays with the author.

AGENTS.md — grok-switch

Instructions for coding agents working in this repository.

What this project is

grok-switch is a minimal CLI for Grok Build configuration profiles.

• In scope: switch between named profiles for ~/.grok/config.toml; extract and save common (stable) vs profile (endpoint/provider) settings; backup before write.
• Out of scope: local routing/proxy/failover, multi-tool managers (Claude/Codex/etc.), desktop UI, marketplace, usage dashboards.

Live config path (default): ~/.grok/config.toml.

Working rules

1. Read this file and docs/DEVELOPMENT_PLAN.md before implementing.
2. Prefer small, reviewable commits. Do not mix scaffolding with large feature dumps.
3. Do not invent scope. If a feature is not in the plan MVP, ask or open a plan update first.
4. Never commit secrets. API keys, full live config.toml with keys, or real profile dumps with keys must not enter git. Use placeholders in docs/tests.
5. Preserve user data. Any write to live config must: validate → backup → atomic write → update state. Refuse silent overwrite when common/live drift is detected (unless explicit --force).
6. Use the repository tooling: uv for Python, rg/fd/exa for search/list, gh for GitHub.
7. Language: user-facing CLI messages and primary docs may be Chinese; code identifiers English.

Repository layout

.
├── AGENTS.md                 # this file
├── README.md                 # human overview
├── docs/
│   └── DEVELOPMENT_PLAN.md   # phases, data model, non-goals
├── src/                      # Python implementation
├── tests/                    # pytest suite
└── profiles/                 # sanitized examples only (currently empty)

Runtime user data lives under ~/.grok-switch/ by default and must not be committed.

Implementation status

CLI MVP implemented. Core TOML extraction/merge/validation, backup and atomic write logic, state management, and Typer commands live under src/grok_switch/. The supported runtime is Python 3.14+. Run validation with uv run pytest.

Implementation constraints

• Keep parse/extract/merge/validate logic independent from the CLI layer.
• Prefer tomlkit (or equivalent) for round-trip edits when preserving structure matters.
• Preserve the live-write sequence: validate → backup → atomic write → state.
• Keep API keys, tokens, secrets, and passwords redacted in output.
• Keep the post-switch reminder to open a new Grok session.

Third-party reference (cc-switch)

• Local reference clone: temp/cc-switch/ (gitignored). Upstream: https://github.com/farion1231/cc-switch
• License: MIT — Copyright (c) 2025 Jason Young. Reuse and derivative work are allowed.
• Obligation: if you copy or adapt substantial portions of cc-switch into this repo, retain the copyright notice and MIT permission text (see docs/THIRD_PARTY.md).
• Prefer re-implementing against Grok’s config.toml rather than vendoring large chunks of cc-switch.
• Do not treat cc-switch as a runtime dependency or git submodule for the product.

Do not

• Add local HTTP proxy / request routing.
• Depend on or fork CC Switch as a runtime requirement.
• Store credentials in the git tree.
• Expand into managing non-Grok tools in MVP.
• Copy substantial third-party code without updating docs/THIRD_PARTY.md and required notices.