The tracked zsh startup files are active through these home-directory symlinks:
| Live path | Repository source |
|---|---|
~/.zshenv | shell/.zshenv |
~/.zprofile | shell/.zprofile |
~/.zshrc | shell/.zshrc |
.zshenv runs for every zsh process. It establishes the base PATH, common
environment variables, the shim path, and functions that must survive agent
shell snapshots. On an interactive login shell, macOS then runs
/etc/zprofile and path_helper, after which .zprofile loads Homebrew and
restores shim precedence. Finally, .zshrc loads interactive tools, aliases,
lazy language runtimes, and the history guard.
.zshrc optionally sources ~/.zshrc.local near the end, before its final
restoration of shim precedence. That file is ignored because it is a
machine-local override. At the time this README was written, the home path was
a dangling symlink to the absent shell/.zshrc.local; the guard in .zshrc
therefore skips it.
Shell startup uses Homebrew’s node instead of a hard-coded nvm Node 20 path.
The machine-local ~/.nvm/alias/default is system, so lazy-loading nvm
preserves that choice. Explicit project-specific nvm use remains available;
old installed runtimes are not deleted. The translation-server launcher
selects the newest installed Node 22 LTS explicitly: its legacy dependencies
still require util.isRegExp, removed in Node 23. It never falls back to Node 20.
.zshenv points CODEX_HOME at the account named in
~/.codex-current-account, which the Emacs account command writes. Without
this, a terminal codex used whichever identity ~/.codex was last logged in
to, while Emacs used the selected account. The two accounts have separate
quotas and billing, so the split stayed invisible until one of them reached a
usage limit. Each ~/.codex-<account> directory has its own authentication.
Account settings and plugin state are independent writable copies; shared
skills and history retain their configured links. An explicit CODEX_HOME
always wins, and an empty, unknown, or absent account name leaves the variable
unset so Codex falls back to ~/.codex.
.zshenv first sources the external ~/.zvars file and then
$DOTFILES/shell/.zshenv-secrets. The latter is tracked with the git-crypt
filter declared in shell/.gitattributes. It is read directly from the
repository; there is no separate ~/.zshenv-secrets symlink. Its contents must
never appear in public documentation, logs, diffs, or command output.
shims/ is prepended to PATH directly. The shims are not copied or linked
into ~/bin:
| Shim | Contract |
|---|---|
claude | Selects the allowed Claude authentication route and strips unintended ambient Anthropic credentials. |
codex | Retains the current Homebrew runtime and reconciles Chrome’s account-local plugin before local session launches. |
emacsclient | Finds the real Darwin temporary-directory socket when a caller overrides $TMPDIR. In Claude Code and Codex sessions, runs the first --eval expression with prompts and the debugger disabled and within EMACSCLIENT_EVAL_LIMIT seconds (default 120; 0 disables), so an agent’s evaluation cannot park the Emacs server. A non-string result whose printed form exceeds EMACSCLIENT_EVAL_MAX_PRINT characters (default 4000) comes back as an error, since the server’s unbounded pretty-printing of it can hang Emacs. |
op | Routes read-only Automations-vault work to op-automations and supported desktop-vault work to op-desktop. |
The dotfiles_prefer_shims function moves this directory back to the front
after Homebrew, nvm, pyenv, or a captured agent environment changes PATH.
.zshenv also defines an op function because functions survive agent shell
snapshots that may put Homebrew ahead of the shim directory.
The Codex shim calls bin/codex-runtime. It resolves Homebrew’s explicit
/opt/homebrew/bin/codex or /usr/local/bin/codex link and copies the complete
package, including its code-mode host and resources, to
~/.local/share/codex-runtimes/<content-hash>. Published copies are read-only
and never replaced. Each new invocation selects the currently installed package;
existing sessions retain their own executable paths through Homebrew upgrades
and cleanup. Embedded executable signatures retain exactly the original bytes.
The launcher checks all package contents, rejects incomplete or concurrently changing copies, and publishes completed copies atomically. Its lock covers only publication and verification, not the running session. It fails explicitly if the source package is unavailable or a retained copy is damaged; it never silently starts an older version. Directly invoking Homebrew’s absolute Codex path bypasses this protection. Existing sessions started before the shim also need restarting once.
Retained versions are not automatically deleted because an older session may still need its signed executable or helper. Each current package uses about 300 MB; safe process-aware retention cleanup is separate work. Focused tests:
python3 -m unittest tests.test_codex_runtime -vLocal session entry points also get process config overrides that replace the
desktop app’s Chrome plugin and node_repl server with a pinned Playwright MCP
server in extension mode; see codex/README.org. Maintenance commands, remote
sessions and direct calls to another Codex executable are outside this launch
boundary.
zsh-history-security.zsh installs a zshaddhistory hook. When an
interactive command contains a high-confidence credential pattern, the command
still executes, but the hook returns 1 so zsh omits it from persistent history
and prints a warning. This reduces accidental persistence; it is not a secret
scanner for arbitrary output or files.
The focused regression tests run with:
python3 -m unittest tests.test_zsh_history_secret_guard -v