Skip to content

Latest commit

 

History

History

shell

Folders and files

README.org

Shell configuration

Activation and load order

The tracked zsh startup files are active through these home-directory symlinks:

Live pathRepository source
~/.zshenvshell/.zshenv
~/.zprofileshell/.zprofile
~/.zshrcshell/.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.

Default Node runtime

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.

Codex account selection

.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.

Secrets boundary

.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.

Command shims

shims/ is prepended to PATH directly. The shims are not copied or linked into ~/bin:

ShimContract
claudeSelects the allowed Claude authentication route and strips unintended ambient Anthropic credentials.
codexRetains the current Homebrew runtime and reconciles Chrome’s account-local plugin before local session launches.
emacsclientFinds 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.
opRoutes 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.

Codex runtime retention

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 -v

Local 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.

History filtering

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