chezmoi-guard

cli-workbench

English | 简体中文

A terminal workbench for AI coding agents. Claude Code, Codex, Gemini CLI, Grok CLI and the like are command-line programs that read and write plain text, so the best place to run them is a terminal you control: tmux sessions per project, an editor one key away from the agent, ripgrep, fzf and jq for text, and every setting in a Git repository you can read, diff and fork. This repository is that environment, deployed with chezmoi.

  prefix + P  ->  pick a project  ->  one tmux session, one window per repository
 ┌───────────────────────────────────┐
 │  claude / codex / gemini / grok   │   the first installed agent starts here,
 │                                   │   in the project's directory
 ├───────────────────────────────────┤
 │  shell                            │
 └───────────────────────────────────┘
  prefix + e / prefix + g: Neovim in a popup, to browse code or review changes

What makes it a workbench, not just dotfiles

Agent-specific today: the workspace switcher starts any of the four agents; the shared instruction text reaches Claude Code, Codex and Gemini CLI (Grok CLI is not wired up: the location of its instruction file is not known); the status line (~/.claude/statusline.sh) and the mods (below) are for Claude Code only. Full agent settings files are deliberately not tracked. Codex's portable UI preferences are merged into its local configuration, see below. The agents themselves are not installed by this repository.

What this is: a personal-dotfiles repository laid out as a chezmoi source tree. You fork it, edit home/, and keep it as your own.

What this is not: a package manager, a one-click installer, a theme pack, or an agent framework. It does not install software and it does not manage secrets.

Requirements and scope

What it changes on your machine: exactly the files under home/ that chezmoi deploys (the table below), a zsh completion cache in ~/.cache/zsh/, and backups of the files it replaces in ~/.cli-workbench-backup/<timestamp>/ (chezmoi itself keeps none; see Safety model).

Quick start

brew install chezmoi
git clone https://github.com/dishangyijiao/cli-workbench.git ~/dev/cli-workbench   # or your fork; any location works

chezmoi init --source ~/dev/cli-workbench   # use this clone as the source, and install the backup hook (below)

chezmoi diff                       # read-only: what would change in $HOME
chezmoi apply ~/.tmux.conf         # apply ONE file first, then look at the result
chezmoi apply                      # then everything

Or let chezmoi do the clone: chezmoi init <your-github-user>/cli-workbench, then the same diff and apply.

What gets deployed (the layout follows chezmoi's naming: dot_ becomes ., executable_ sets the mode, private_ makes the directory mode 700):

Suggested order and the manual steps (Homebrew tools, tmux plugin manager) are in docs/bootstrap.md.

Defaults you may want to change first

These are opinions, not requirements. Edit the files in home/ and run chezmoi apply (or chezmoi edit --apply ~/.tmux.conf).

• tmux: prefix is Ctrl-a (not Ctrl-b); vi-style copy mode; mouse on; windows numbered from 1. Pane contents are not saved to disk by default (that would store anything printed in a pane, tokens included); see the comment next to @resurrect-capture-pane-contents to turn it on.
• zsh: 50,000-line shared history, case-insensitive completion, starship, zoxide, fzf and zsh-syntax-highlighting only if installed.
• Ghostty: Catppuccin Mocha and SauceCodePro Nerd Font Mono (install the font or change the line).

Make it yours

• Per-machine settings (extra PATH entries, a proxy, turning on the tmux chooser): copy templates/local.zsh.example to ~/.config/zsh/local.zsh. chezmoi does not manage it and it is loaded last.
• Secrets: templates/secrets.zsh.example to ~/.config/zsh/secrets.zsh, mode 600. Never commit it. The repository must never contain keys or tokens.
• Add another tool: chezmoi add ~/.config/<tool>/config copies the file into home/; commit it.
• Files a program rewrites (for example lazy-lock.json after :Lazy update): the copy in $HOME changes, the repository does not. chezmoi diff shows it; chezmoi re-add pulls it back into home/.
• Neovim: to use your own setup instead, delete home/dot_config/nvim from your fork.

Commands

chezmoi diff | status | verify   # what differs between home/ and $HOME (verify exits non-zero if anything does)
chezmoi doctor                   # chezmoi's own health check
tests/run.sh                     # the repository's tests, including an end-to-end run of this quick start in a throwaway HOME
scripts/privacy-scan [--all]     # secrets, personal paths and e-mail addresses in staged (or all tracked) files, or in commit metadata (--commits)
scripts/lint-shell               # shellcheck (warning level and above) over every bash/sh script in the repository

Safety model

• chezmoi diff and chezmoi apply --dry-run change nothing.
• Backup before every apply. chezmoi overwrites a differing file without keeping a copy. chezmoi init installs a hook (scripts/backup-before-apply) that copies every file the apply is about to replace, including files you edited after chezmoi wrote them, to ~/.cli-workbench-backup/<timestamp>/ first. Directory mode 700, symlinks kept as symlinks, a RESTORE note with one copy-paste command per file. If nothing would change, nothing is created. If the backup fails, the apply is refused. --dry-run has no side effects.
• The hook is part of the config chezmoi init writes. If you only create chezmoi.toml by hand, or run chezmoi apply --source ... without having run init, there is no backup.
• It only touches the targets in the table above, and it deletes nothing unless you ask for it (chezmoi destroy).
• scripts/privacy-scan guards what you commit; see "Safe to make public" above.

Agent instructions

Claude Code, Codex and Gemini CLI each read a plain-text instruction file from their home directory. Here they are generated from one source, home/.chezmoitemplates/agent-instructions.md, so the agents get the same facts about the machine and the same engineering principles: one source of truth with layers that only add differences, least privilege, files over conversation, the simplest thing that works, and evidence before "done" with a way back.

• Your own rules go in ~/.config/cli-workbench/agent-instructions.local.md. It is not tracked, so personal preferences never reach a public fork. It is appended after the shared text in all three files. Remove the file and the next chezmoi apply removes its text.
• Existing files: your current ~/.claude/CLAUDE.md (and the others) are replaced on apply and backed up first. Move their content into the local file beforehand if you want to keep it as it is.
• Edit the source, not the deployed file. Text that a tool appends to ~/.claude/CLAUDE.md is overwritten at the next apply. The generated files cannot be pulled back with chezmoi re-add.
• Not tracked as complete files, on purpose: settings.json, config.toml, auth.json, histories, sessions and databases. They hold machine paths, proxies and credentials, and the tools rewrite them. A test fails if such a file appears under home/.
• To publish your own principles, put them in the shared source in your fork, not in the untracked local file.

Portable Codex preferences

home/dot_codex/modify_private_config.toml merges five UI settings into ~/.codex/config.toml: the status line (model, directory, session name, five-hour and weekly remaining limits), status-line colors, and completion notifications using a terminal bell regardless of focus. With the existing tmux bell settings, Ghostty can mark the background tab with a bell.

On a new machine, install Codex separately and run the usual chezmoi init / chezmoi apply setup, then sign in to Codex. The configuration is created if absent. Existing model choices, local paths, notification commands, project trust, and other settings are preserved; credentials and sessions are not migrated. Restart an existing Codex CLI after applying (use codex resume --last to continue).

Edit the merge template to change these shared preferences. Changes to these five settings made inside Codex are replaced by the next apply. Do not use chezmoi add or re-add to copy the full local file into the repository. When values need changing, the TOML is reserialized, so comments and formatting are lost; matching files remain unchanged. The existing pre-apply backup hook keeps the original before replacement. Invalid TOML stops the merge without overwriting the file.

Claude Code mods

A mod is a Claude Code plugin whose behavior is a small TypeScript file that Claude Code calls when something happens: a tool is about to run, a reply is about to be drawn. This repository ships four, as a local marketplace (a folder Claude Code installs plugins from) in home/dot_claude/workbench-mods/:

Install once per machine (needs Claude Code 2.1.287 or later; chezmoi apply only deploys the files, it does not install anything):

chezmoi apply                                                   # deploys ~/.claude/workbench-mods
claude plugin marketplace add ~/.claude/workbench-mods
claude plugin install chezmoi-guard@cli-workbench --scope user
claude plugin install reply-polish@cli-workbench --scope user
claude plugin install agent-state@cli-workbench --scope user
claude plugin install md-open@cli-workbench --scope user

Then restart Claude Code, or run /reload-plugins in a running session.

• Change a mod: edit it under home/dot_claude/workbench-mods/, run chezmoi apply, then /reload-plugins. A marketplace that is a folder is read from the folder itself, so no version bump is needed. claude plugin disable <name> turns one off, claude plugin uninstall <name> removes it.
• Tests: tests/mods.test.sh always checks the layout of the marketplace. With Claude Code installed it also runs claude plugin validate and each mod's own tests (claude plugin test); without it that part is skipped.
• Trust: a mod sees every tool call and reply and runs with your permissions. Read the source before you install it; each mod is a few hundred lines.
• Stability: the mods API is early access and changes between releases. These mods were built and tested with Claude Code 2.1.289 (md-open with 2.1.295). Mods do not load under --safe-mode or --bare.
• Not tracked on purpose: the type declarations Claude Code writes into a mod's .claude-plugin/types/ when it loads the mod.

Keybindings

The keys you use most, on one page to print: docs/keybindings.md. A test keeps it in step with the config.

Workspace switcher (tmux)

Press prefix then P (Ctrl-a P) for a picker over ~/dev/projects. Every directory directly under a root is a workspace, opened as one tmux session: an AI agent on top, a shell under it. There is no editor pane; prefix e and prefix g open Neovim in a popup when you want to read code (see below). A directory that is not a repository but contains several (a multi-repo product) is one workspace with one window per repository. Choosing an existing workspace only switches to it. It needs tmux 3.2+ and fzf.

• Agent pane: the first installed of claude codex gemini grok is started in the project directory. If none is installed, the window has just a shell. WORKSPACE_SWITCH_AGENT="claude --continue" picks one (with arguments), none turns it off, WORKSPACE_SWITCH_AGENTS="aider claude" changes the candidates and their order. Set these with set-environment -g in home/dot_tmux.conf, next to WORKSPACE_ROOTS.
• Roots: uncomment WORKSPACE_ROOTS in home/dot_tmux.conf to scan other directories.
• Details are in the header of home/dot_tmux/scripts/executable_workspace-switch.sh.

Code popups (tmux)

Read code without leaving the agent's pane. Both keys open Neovim in a popup over the current pane, in that pane's directory; closing Neovim closes the popup and you are back where you were. They need tmux 3.2+.

• prefix then e: browse the project with the usual Neovim keys (<leader>ff find a file, <leader>fg search, <leader>e file tree). :qa closes it.
• A Markdown file opened there is shown rendered in place (headings, lists, tables, code blocks); <leader>mp switches the rendering off and on. The text is a centred column of about 80 characters, so it stays readable on a wide screen.
• prefix then g: review changes. A Telescope list of every file the branch changed since it left the default branch (origin/HEAD, else origin/main, main and so on): committed, uncommitted, deleted and untracked files, each marked, with a colored diff as the preview. Enter opens the file in a new tab beside its version at the fork point, in Neovim's own diff mode (a deleted file: its old version beside an empty side) (]c/[c jump between changes). Inside Neovim the same list is :Changes or <leader>gv. :qa closes the popup. Outside a Git repository it says so. No extra plugin is needed.
• The script is home/dot_tmux/scripts/executable_code-popup.sh; tmux passes it only the pane id, never a directory name.

Translate what you select (tmux)

Select some English text with the mouse (or v ... y in copy mode), then press prefix then t (Ctrl-a t). A popup shows a translation, so you do not leave the pane you are reading. One word gives a dictionary entry; anything longer gives its translation. Close the popup with q.

• Needs: tmux 3.2+ and translate-shell (brew install translate-shell; without it the popup says so).
• Privacy: the selected text is sent to the translation service (Google by default; if that fails, Bing is asked once). Do not use it on text you may not send out.
• Language: LOOKUP_LANG sets the target language (default zh-CN). Details are in the header of home/dot_tmux/scripts/executable_lookup.sh.

Idea inbox (tmux)

Write an idea down the moment you have it, without leaving the pane or interrupting the agent. Press prefix then a (Ctrl-a a), type one line, press Enter; the popup closes and you are back where you were. An empty line cancels. In a shell, idea some text does the same (or idea alone to be asked). It needs tmux 3.2+.

• Where: one line per idea in ~/.config/cli-workbench/inbox.md (private, mode 600, not in this repository), for all projects: - [ ] 2026-10-06 17:42 · ~/dev/projects/foo · the idea. The project is the repository's top directory, for a worktree the repository it belongs to; ? if the pane was gone.
• Safe to type anything: the text is stored as it is and never run. A failed write keeps the popup open and repeats the idea.
• Processing it: ask your agent to "process the inbox". The rules: copy the file to a timestamped backup (mode 600) first; change only the lines it handles, ticking - [ ] to - [x], never deleting; afterwards check that every line from before is still there; ask before anything leaves the machine, such as opening a GitHub issue.

Agent overview (tmux)

When several agents work at once, the question is which one needs you. Press prefix then O (Ctrl-a O) for a popup that lists every agent session, one row each: state, project, branch and how long it has been in that state. Waiting comes first (a permission prompt or a question; the longest wait on top), then working, then idle. Enter jumps to that pane (its session, window and pane); Esc closes the popup. With fzf it is a picker you can type into; without it, a numbered menu. Plain text, no colors. It needs tmux 3.2+ and jq.

• Where the rows come from: Claude Code. The agent-state mod (see "Claude Code mods") runs ~/.tmux/scripts/agent-state.sh: a turn starts, working; a permission prompt or an MCP question appears, waiting; a turn ends for any reason (an answer, an interrupt, an error), idle; a session starts, idle (a compaction does not count); a session ends, the record is removed. When a tool finishes, fails, is denied, or a dialog is answered while the pane still says waiting, it goes back to working. Without the mod the popup is empty.
• Files: one small file per pane, ${XDG_STATE_HOME:-~/.local/state}/cli-workbench/sessions/<tmux server>/<pane id>.json, with state, project, branch, since and session id. The server directory is the tmux server's pid and start time, so a pane id reused after a tmux restart never meets an old record. The last event wins; the file is replaced atomicall