Getting started

One install per OS, one agent profile add, and the Codex and Claude CLIs talk to GitHub Copilot. This page is the install-to-uninstall lifecycle of copilot-env itself; the commands you run every day are on the usage page.

Install

# macOS / Linux
curl -fsSL https://github.com/Vivswan/copilot-env/releases/latest/download/install.sh | bash

# Windows (runs from any shell -- cmd, PowerShell, or the Run dialog)
powershell -c "irm https://github.com/Vivswan/copilot-env/releases/latest/download/install.ps1 | iex"

This downloads one self-contained agent binary for your platform into ~/.copilot-env, then wires your shell (shell integration). Next: restart your shell and run agent profile add (below).

• Install from a release, not main. main is for development and can run ahead of the released installer flow.
• Replaceable: re-run the installer any time to move to the selected release.
• Optional: agent shell --clis installs or updates the Claude/Copilot/Codex CLIs through their vendors' installers and turns the cl / co / cx launchers on (agent config set shell.launchers false turns them off again).
• Windows needs only PowerShell: Windows PowerShell 5.1 or pwsh 7; the installer uses curl.exe when PATH has it and PowerShell's own web cmdlets otherwise.

Specific version: replace latest with an exact release tag, or pass --version.

curl -fsSL https://github.com/Vivswan/copilot-env/releases/download/vX.X.X/install.sh | bash

powershell -c "irm https://github.com/Vivswan/copilot-env/releases/download/vX.X.X/install.ps1 | iex"

Install flags

macOS / Linux	Windows	Effect
--dir DIR	-InstallDir DIR	Install target (default ~/.copilot-env; overrides COPILOT_ENV_DIR)
--version TAG	-Version TAG	Install an exact release tag instead of the default
--no-shell-integration	-NoShellIntegration	Skip the shell wiring pass: no block is added to your rc / $PROFILE. A reinstall over an older release still runs its migrations, which may rewrite or remove a copilot-env block already in ~/.bashrc, ~/.zshrc, or $PROFILE
--yes	-Yes	Reload your shell at the end without asking
--no	-No	Don't reload your shell at the end, and don't ask (the offer is also skipped when non-interactive, under CI, or with COPILOT_ENV_NO_EXEC_SHELL set)
	-AllHosts	Wire the CurrentUserAllHosts PowerShell profile instead of the current host's

The first agent profile add

agent profile add sets up both Codex and Claude and prints the next steps. When no credential is stored it runs the agent profile auth picker first (providers), --proxy included. Headless runs store a token beforehand with agent profile auth --provider gh-env or agent profile auth --set <token>.

With no mode flag, add probes whether that credential can use Direct and falls back to the proxy when it cannot, or when the two agents' probes disagree. The probe runs through the installed agent CLIs when they exist, and against the Copilot endpoint when they do not. --direct and --proxy skip the probe and force one mode for both agents.

Mode	What the CLIs talk to	What runs locally
Direct	GitHub Copilot's own endpoints, with your GitHub credential	no daemon; Claude Code's WebSearch is replaced by the MCP tool (web search)
Proxy	a local @jeffreycao/copilot-api daemon that copilot-env fetches on first use	agent start / agent stop, or the managed lifecycle

agent profile sync --codex or --claude re-renders one agent's files from the recorded mode, with no probe (commands).

What a wiring pass writes

Every file copilot-env leaves outside its own homes (~/.copilot-env, ~/.local/share/copilot-env), in both directions: what creates or rewrites it, and what removes it. Every command prints the files it touched.

File	Created or rewritten by	Removed by	Holds
~/.codex/config.toml	the writers listed below the table	agent profile <name> del strips that profile's provider; agent uninstall strips the copilot-env wiring in every known Codex home	the copilot-env model provider for the default and each profile, and the model_catalog_json reference
~/.codex/<name>.config.toml	agent profile <name> add / sync, agent sync, cx --profile, agent settings --import, agent profile <name> settings --import; the 4.0.9 migration, through agent update, moves each [profiles.<name>] table copilot-env wrote into it, your own keys in the file winning except model_provider, which becomes the selector either way	agent profile <name> del and agent uninstall drop the selector, and the file when nothing else remains in it	the named profile's Codex selector: the top-level model_provider that codex --profile <name> layers over config.toml (profiles)
~/.codex/config.toml.copilot-env-mobile.bak	agent codex-mobile	the same command, on a clean finish	a backup of the Codex config for the pairing
~/.codex/.env, in every known Codex home	the 4.0.0 migration, through agent update	never	rewritten without the COPILOT_ENV_GH_TOKEN line an older release baked in
~/.codex/hosts/<hostname>/: .tmp/, log/, tmp/, config.toml, .personality_migration and history.jsonl (seeded from the shared root, or empty), symlinks into the shared root	every default Codex wiring pass while codex.host is on	the next default Codex wiring pass after codex.host is set to false; agent uninstall	the per-host CODEX_HOME farm (Linux/macOS)
the shared ~/.codex root while codex.host is on: existing host state dirs (sessions/, skills/, memories/, the other Codex state dirs) merged in; empty .codex-global-state.json, AGENTS.md, session_index.jsonl, version.json seeded when missing	the same farm build	never	the state every host shares
~/.claude/settings.json	agent profile add / sync, agent profile launch (cl) when the default is proxy or unwired, agent settings --import, agent profile settings --import, agent profile mcp --remove (drops the deny), the 4.0.0 migration (inlines the helper)	agent uninstall strips the wiring; it and agent profile mcp --remove remove the file when nothing else is in it	Claude Code's base URL, the credential helper or the static key, and the WebSearch deny on direct wiring
~/.claude/settings-<name>.json	agent profile <name> add / sync, agent sync, cl --profile / cx --profile, agent settings --import, agent profile <name> settings --import, the 4.0.0 migration	agent profile <name> del, agent uninstall	the named profile's Claude wiring
~/.claude/copilot-token[-<name>].sh and copilot-proxy-token[-<name>].sh (.cmd on Windows)	nothing since 3.5.6	the 4.0.0 migration, through agent update, after inlining the helper into the settings file	the helper files 3.5.6 wrote
~/.claude.json	direct Claude wiring while claude.wire-mcp is on (agent profile add, agent profile sync, agent settings --import, agent profile settings --import)	proxy wiring (agent profile add, agent profile sync, cl rewiring a proxy default, agent settings --import, agent profile settings --import), direct wiring with claude.wire-mcp off, agent profile mcp --remove, agent uninstall	the copilot-env MCP server registration (web search)
Claude Desktop: Claude-3p/configLibrary/<uuid>.json per entry and Claude-3p/configLibrary/_meta.json; Claude-3p/claude_desktop_config.json; Claude/developer_settings.json and Claude-3p/developer_settings.json	every Claude wiring pass (agent profile [<name>] add / sync, agent sync, cl when the default is proxy or unwired, cl --profile / cx --profile, agent settings --import, agent profile [<name>] settings --import) while claude.desktop is on and the app is installed; the 5.0.2 migration runs a pass	owned entries, by the triggers listed below the table; the three app files are never removed	the gateway entries and the two settings that make the app boot into them
~/.bashrc / ~/.zshrc; on Windows <Documents>/WindowsPowerShell/Microsoft.PowerShell_profile.ps1 and <Documents>/PowerShell/Microsoft.PowerShell_profile.ps1 (profile.ps1 with --all-hosts)	the installer, agent shell; the 4.0.0 migration re-fences the block	agent shell --remove, agent uninstall	the shell integration block
the path you pass to agent settings --export [file] or agent profile [<name>] settings --export [file]	agent settings --export, agent profile [<name>] settings --export	never	the settings bundle (stdout without a path)
the vendors' own installs: ~/.local/bin/claude (a link into ~/.local/share/claude/versions/), copilot, and codex (a link into ~/.codex/packages/standalone/), with ~/.local/share/claude/, ~/.local/state/claude/, and ~/.cache/claude/ (or the XDG_* homes you set), the install record in ~/.claude.json (under CLAUDE_CONFIG_DIR if set), and ~/.codex/packages/standalone/ (Windows: %USERPROFILE%\.local\bin\claude.exe with %USERPROFILE%\.local\share\claude\, %LOCALAPPDATA%\Programs\OpenAI\Codex\bin\ as a junction into %USERPROFILE%\.codex\packages\standalone\ holding codex.exe and rg.exe, and the Copilot CLI's winget package under %LOCALAPPDATA%\Microsoft\WinGet\Packages\ with its WinGet\Links\copilot.exe link); the Codex and Copilot installers may add ~/.local/bin to your shell profile, the Codex Windows installer and winget edit the User PATH, winget records the package under Apps & features, keeps its own state under %LOCALAPPDATA%\Packages\Microsoft.DesktopAppInstaller_8wekyb3d8bbwe\, deploys its source package under %ProgramFiles%\WindowsApps\ when a source refresh is due, and where the host lacks PowerShell 7 winget installs it as an MSIX package under %ProgramFiles%\WindowsApps\ with a pwsh.exe alias under %LOCALAPPDATA%\Microsoft\WindowsApps\	agent shell --clis (each vendor's installer; see installing the CLIs)	never (agent uninstall leaves the CLIs alone)	the claude / copilot / codex CLIs

The ~/.codex/config.toml writers, in full:

• The Codex wiring passes: agent profile [<name>] add / sync, agent sync, agent profile launch (cl / cx) when the default is proxy or unwired, cx --profile, agent settings --import, agent profile [<name>] settings --import.
• A default-profile launch (cl / cx on a proxy default, or a direct cx, never cx --profile <name>) keeps the catalog line in step with codex.model-catalog.
• agent codex-mobile strips the provider and restores it.
• The 4.0.0 migration rewrites old wiring.
• The 4.0.9 migration moves the [profiles.<name>] tables copilot-env wrote out of the file. Foreign ones are reported, never moved.

What removes a Claude Desktop entry, in full:

• A default wiring pass (agent profile add / sync, agent sync, agent settings --import) and the 5.0.2 migration remove owned entries that are orphaned or unlisted and rewrite _meta.json.
• With claude.desktop off, wiring a named profile (agent profile <name> add / sync, cl --profile / cx --profile) removes that profile's entry, and a default wiring pass removes every profile entry.
• agent profile <name> del removes its entry whatever the key says.
• agent uninstall removes every owned entry.

~/.codex stands for $CODEX_HOME when set, and for the active per-host home while codex.host is on, except the farm itself, which always sits under the real ~/.codex/hosts; ~/.claude and ~/.claude.json follow $CLAUDE_CONFIG_DIR when set. Claude-3p and Claude sit in ~/Library/Application Support/ on macOS, in %LOCALAPPDATA% and %APPDATA% on Windows, and in $XDG_CONFIG_HOME (default ~/.config) on Linux.

Updating

agent update fetches the newest release's binary, checks its SHA256 against checksums.txt, then verifies both files against the release's Sigstore build-provenance attestation. Only then does it swap the binary in place.

The attestation must be signed by a GitHub Actions workflow of the repository owner's GitHub account (any repository, any ref), and both files must be among the attested bytes.

• That check is on by default. agent update --no-verify skips it once, agent config set update.verify-provenance false turns it off.
• The release lookup is anonymous: no GH_TOKEN / GITHUB_TOKEN from the shell and no stored Copilot credential is sent, so a token for another account cannot turn the lookup into a 401. GitHub's anonymous limit (60 requests an hour per IP) covers one lookup per --check or autoupdate cooldown; when nothing resolves (no eligible release, a refusal, or no network) agent update --check says so and exits 2.
• Your config, credentials, and profiles live outside the install directory and are untouched.
• agent config set update.auto true self-updates daily, with the cooldown from update.cooldown.

Verifying a download by hand

The installer checks the binary's SHA256 against the release's checksums.txt before it puts it anywhere. That proves the download is intact, not who built it: the installer comes from the same release, so a first install trusts it on first use.

Every release also carries a build-provenance attestation, attestation.json. The GitHub CLI checks it with the closest equivalent of the policy agent update enforces, for the binary AND checksums.txt:

for f in copilot-env-<target> checksums.txt; do
  gh attestation verify "$f" --owner Vivswan --bundle attestation.json \
    --cert-identity-regex '^https://github\.com/Vivswan/[^/]+/\.github/workflows/[^@]+@refs/.+$'
done

• --owner and --cert-identity-regex allow any workflow of any repository under the repository owner's GitHub account, at any ref: the fleet's publish leg signs releases from another repository and a tag. The repository is pinned by the download URL, not the certificate.
• --owner also requires the calling repository to be the repository owner's; agent update checks only the signing workflow's identity.

Uninstall

agent uninstall removes everything copilot-env manages: daemons, profiles, agent wiring, shell integration, credentials, data, and the install itself. It leaves the agent CLIs (claude / copilot / codex) alone. Its flags are in the command list.