context-gauge
Context fill as a bar on the prompt hint line, with a /clear nudge as context grows
newbandspinner
Context fill as a bar on the prompt hint line, with a /clear nudge as context grows
A collection of neovim, tmux, and zsh configurations for macOS. Built for DevOps workflows with Terraform, Python, YAML, and JSON.
Clone the dotfiles repository to your home directory as ~/.dotfiles.
git clone https://github.com/puffin/dotfiles.git ~/.dotfiles
cd ~/.dotfilesRun install/backup.sh to back up any existing symlinked files to ~/dotfiles-backup. The installation scripts will not overwrite existing files.
Install XCode CLI tools and Homebrew first:
xcode-select --installFollow instructions at https://brew.sh/ to install Homebrew, then:
./install.shThis will:
*.symlink files to your home directory (e.g. zshrc.symlink becomes ~/.zshrc)config directory contents to ~/.config/Brewfileinstall/osx.sh, including remapping Caps Lock to Control on every keyboard (via hidutil, persisted with a LaunchAgent)./uninstall.shReverses the above: removes the symlinks (only if they still point at this repo), reverts the shell change, uninstalls exactly the packages/casks/taps listed in Brewfile, clears zinit/fzf/tf-helper/nvim/tmux-plugin caches, and deletes the specific macOS defaults keys install/osx.sh set. It prompts for confirmation before doing anything, since most of it is destructive, and it deliberately leaves ~/.ssh, ~/.gnupg (besides the generated gpg-agent.conf), and any nvim/tmux session history alone, since those can hold data of your own. Note claude-code is itself a Brewfile cask, so it gets uninstalled too.
To support italic fonts in tmux:
tic -x resources/xterm-256color-italic.terminfo
tic -x resources/tmux.terminfoZSH is configured in zshrc.symlink. Key features:
EDITOR set to nvim~/.localrc for machine-specific config (API keys, etc.)RPROMPT+ New files added! Existing files modified? Untracked files>> Files renamed✘ Tracked file deleted$ Stashed files= Unmerged files⇡ Branch ahead of remote⇣ Branch behind remote⇕ Branches diverged✔ Working directory cleanNeovim is configured entirely in Lua with the following structure:
~/.config/nvim/
├── init.lua -- Entry point
└── lua/user/
├── options.lua -- Editor settings
├── keymaps.lua -- Key mappings
├── autocmds.lua -- Autocommands
├── plugins.lua -- Plugin declarations (lazy.nvim)
└── lsp.lua -- LSP server configurationPlugins are managed by lazy.nvim and installed automatically on first launch. Run :Lazy inside neovim to manage plugins.
Language servers are managed by Mason and configured via Neovim's native vim.lsp.config (0.11+). Autocompletion is powered by blink.cmp.
| Language | Server | Features |
|---|---|---|
| Terraform | terraformls | Completions, diagnostics, prefill required fields |
| Python | pyright + ruff | Pyright for completions/types, Ruff for linting/formatting |
| YAML | yamlls | Schema-aware completions (K8s, Docker Compose, GitHub Actions, etc.) |
| JSON | jsonls | Schema-aware completions (package.json, tsconfig, etc.) |
Schemas are provided by SchemaStore.nvim (300+ schemas).
Note: For Terraform, run terraform init in each project directory for provider-aware completions.
| Key | Action |
|---|---|
gd | Go to definition |
gy | Go to type definition |
gi | Go to implementation |
gr | Find references |
K | Show documentation |
<leader>rn | Rename symbol |
<leader>ca | Code action |
| Key | Action |
|---|---|
Tab | Next completion |
S-Tab | Previous completion |
CR | Confirm selection |
C-Space | Trigger / toggle docs |
C-e | Dismiss completion |
C-b / C-f | Scroll documentation |
Diagnostics show inline virtual text, gutter signs, and underlines. Holding the cursor on an error line auto-opens a floating window with the full message.
UI: vim-one (colorscheme), lualine (statusline), nvim-web-devicons, vim-smoothie (smooth scrolling)
Editor: vim-surround, vim-repeat, vim-unimpaired, vim-sleuth, vim-abolish, Comment.nvim, splitjoin.vim, nvim-autopairs, editorconfig
Git: fugitive, gitsigns, diffview.nvim, vim-flog, vim-twiggy
Navigation: FZF (files, buffers, ripgrep), nvim-tree (file explorer)
Session: vim-obsession + vim-prosession (auto-save/restore sessions)
Syntax: Treesitter with parsers for Terraform, HCL, Python, TypeScript, JSON, YAML, Lua, and more
Tmux is configured in ~/.tmux.conf with prefix set to control+a. Sessions are automatically saved every minute via tmux-continuum and restored on tmux start via tmux-resurrect.
| Key | Action | |
|---|---|---|
prefix + I | Install plugins | |
prefix + U | Update plugins | |
prefix + w | Window/pane selection | |
prefix + c | New window | |
prefix + , | Rename window | |
prefix + & | Kill window | |
prefix + [1-9] | Select window | |
prefix + - | Split vertically | |
| `prefix + \ | ` | Split horizontally |
prefix + x | Kill pane | |
prefix + [h,j,k,l] | Move to pane | |
prefix + z | Toggle pane fullscreen | |
prefix + shift + [h,j,k,l] | Resize pane |
Herdr is an agent-aware terminal multiplexer - it covers the same sessions/windows/panes ground as tmux, plus status tracking for AI coding agents (Claude Code, Codex, etc.) running in its panes. It's configured in ~/.config/herdr/config.toml with the same control+a prefix as tmux, so the muscle memory carries over. Both tools are installed; use either as your daily driver, or reach for herdr specifically when running coding agents you want to keep tabs on. Sessions persist across restarts and reattaches natively, with no plugin manager needed.
| Key | Action | |
|---|---|---|
prefix + w | Workspace/agent picker | |
prefix + c | New tab | |
prefix + shift + t | Rename tab | |
prefix + shift + x | Close tab | |
prefix + [1-9] | Select tab | |
alt + [1-9] | Select tab (no prefix) | |
prefix + minus | Split stacked | |
| `prefix + \ | ` | Split side-by-side |
prefix + x | Close pane | |
prefix + [h,j,k,l] | Move to pane | |
prefix + z | Toggle pane fullscreen | |
prefix + shift + [h,j,k,l] | Swap pane | |
prefix + r | Resize pane mode | |
prefix + [ | Copy mode (vim-style) | |
ctrl + shift + [left,right] | Reorder current tab | |
prefix + q | Detach |
Installed automatically by install.sh via herdr plugin install (source lives outside this repo under ~/.config/herdr/plugins/, gitignored - not vendored). The marketplace is a self-tagged, unreviewed GitHub index; these were picked and their READMEs checked by hand, not exhaustively vetted against the ~1000 plugins listed there.
| Plugin | What it does | Key |
|---|---|---|
| herdr-auto-title | Renames tabs to match what's running in them | (automatic) |
| vim-herdr-navigation | ctrl+h/j/k/l crosses seamlessly between herdr panes and Neovim splits (vim-tmux-navigator, ported to herdr) | ctrl + [h,j,k,l] |
| herdr-reviewr | Diff/review pane - comment on an agent's changes, send feedback back to it | prefix + shift + c |
| herdr-sessionizer | Fuzzy-open projects/worktrees, bootstrap a workspace layout from TOML | prefix + shift + s |
herdr-sessionizer needs bun to build (in the Brewfile via the oven-sh/bun tap).
Terminal of choice is Alacritty. Configuration is in config/alacritty/alacritty.yml.
SauceCodePro NF, installed via Homebrew.
vim-one in light mode. Comments are displayed in light grey italic.
Press Ctrl+x Ctrl+t to toggle between light and dark themes. This works in both neovim and the shell, and switches all three simultaneously:
You can also run toggle-theme from the command line, optionally with light or dark as an argument.
Claude Code is integrated into Neovim via the claudecode.nvim plugin, providing an in-editor AI assistant panel.
Leader key is Space.
| Key | Action |
|---|---|
<leader>ac | Toggle Claude Code panel |
<leader>as | Send selection to Claude |
<leader>aa | Add current file to Claude |
<C-w> | Navigate away from terminal (e.g. Claude panel) |
config/claude-hooks/ holds portable Claude Code hook scripts, symlinked into ~/.claude/hooks/ by install/link.sh. ~/.claude/settings.json itself is not tracked here (it's inherently per-machine — permissions, plugins, org-specific config), so after installing, register a hook manually in its hooks block, e.g.:
"hooks": {
"PreCompact": [
{
"matcher": "auto",
"hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/precompact-nudge.sh" }]
}
]
}precompact-nudge.sh — fires only on automatic compaction and prints a visible reminder to /clear instead if you're switching to an unrelated task, rather than letting one session run indefinitely.config/claude-mods/ holds Claude Code mods (plugins of function hooks). zsh/config.zsh exports CLAUDE_CODE_PLUGIN_DIRS with every folder there that has a .claude-plugin/, so each claude launched from a shell loads them; no settings.json change is needed. Interactive sessions watch these folders, so editing a mod reloads it live. Check one with claude plugin validate config/claude-mods/<name>.
context-gauge — context fill as a bar at the end of the prompt hint line (ctx ▰▱▱▱▱▱▱▱▱▱ 6% · 62k), plus a band above the prompt from 50% of the window (red from 75%) suggesting /clear before switching tasks. Thresholds are WARN_PCT / HOT_PCT in hooks/register.tsx.git — a status-line entry with the folder, git branch and the branch's PR checks and review (~/.dotfiles ⎇ my-branch · #31 ✓5 ✗1 ●2 approved). PR status comes from gh and is polled every minute.preview — /preview [file.md] (default README.md) renders a markdown file in a side pane: markdown through glow with One Dark / One Light styles (styles/*.json) that follow bin/toggle-theme, and mermaid blocks drawn as text diagrams by termaid (both in the Brewfile). Falls back to Claude Code's own markdown renderer, or the mermaid source, when either tool is missing.runwatch — watches Terrakube jobs, Jenkins builds and PR checks in a side pane and toasts when each finishes (Terrakube shows the plan summary, e.g. plan: +2 ~0 -1, and toasts when a job waits for approval). Runs started by terrakube.sh run … --confirm, jenkins.sh trigger, gh pr create or git push are picked up automatically; /watch tk|jenkins|pr … adds one by hand, and Claude can hand one off through the mod's watch tool, which wakes it with the result instead of it polling. Polls every 20s through the ge-cloudops skills' wrapper scripts, so credentials stay in them.write-gate — holds every Jira/Confluence write (comment, transition, edit, create, link, worklog, page), Lucid comment/share/update, git push and gh pr create|merge until you pick Post it. The exact payload (and, for a push, the commits no remote has) shows in a pane; Reject, or anything typed under Other, blocks it and tells Claude why. Fails closed, and logs each decision to ~/.claude/write-gate.log.Leader key is Space.
| Key | Action |
|---|---|
<leader>k | Toggle file explorer (see explorer keymaps) |
<leader>st | Start screen |
<leader>b | Close buffer (keep split) |
<leader>t | Git file finder |
<leader>e | All files finder |
<leader>r | Buffer finder |
<leader>s | Git status files |
:Rg | Ripgrep search |
<leader>gs | Git status |
<leader>gd | Git 3-way diff |
gdh / gdl | Take left/right in diff |
<leader>dvo | Open Diffview |
<leader>dvc | Close Diffview |
<leader>dvh | Diffview file history |
]g / [g | Next/previous git hunk |
gs | Preview git hunk |
gu | Reset git hunk |
gc / gcc | Comment toggle |
The file explorer (nvim-tree) uses coc-explorer-style keybindings. Confirmations (y/n) are single-keypress — no Enter needed.
| Key | Action |
|---|---|
yy | Copy file/directory (toggle, visual mode supported) |
dd | Cut file/directory (toggle, visual mode supported) |
p | Paste from clipboard |
df | Delete file/directory (trash) |
dF | Delete permanently |
yp | Copy absolute path to system clipboard |
yn | Copy filename to system clipboard |
A | Create new directory |
a | Create new file |
E | Open in vertical split |
V | Visual select (then yy/dd/df for multi-file operations) |
Copied files are highlighted in green, cut files in red with strikethrough.
| Key | Action |
|---|---|
Alt + Right/Left | Move one word forward/backward |
Cmd + Right/Left | Move to end/beginning of line |
Alt + D | Delete word after cursor |
Alt + Backspace | Delete word before cursor |
Ctrl + U | Clear entire line |
Ctrl + R | Command history |
Ctrl + T | File history |
If you encounter permission errors during installation:
sudo chown -R $(whoami):admin /usr/local/
sudo chmod -R 755 /usr/localIf you have questions or notice issues, please open an issue.
hooks/register.tsx 84 lines1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Gauge } from '../types'
5
6// Thresholds are a share of the model's context window, so they follow the
7// model: a band from WARN_PCT, turning red from HOT_PCT.
8const WARN_PCT = 50
9const HOT_PCT = 75
10const BAR_CELLS = 10
11
12const gauge = atom({ plugin: 'context-gauge', key: 'gauge' } as const, null)
13const isHidden = atom({ plugin: 'context-gauge', key: 'isHidden' } as const, false)
14// Drawn at the end of the prompt's hint line: a $.ui.status entry would carry
15// the plugin's name as a label.
16const line = atom({ plugin: 'context-gauge', key: 'line' } as const, '')
17
18const fmt = (n: number) => (n >= 1000 ? `${Math.round(n / 1000)}k` : `${n}`)
19
20const bar = (percent: number) => {
21 const filled = Math.min(BAR_CELLS, Math.round((percent / 100) * BAR_CELLS))
22 return '▰'.repeat(filled) + '▱'.repeat(BAR_CELLS - filled)
23}
24
25async function refresh($: EngineInterface) {
26 const usage = (await $.session.usage()).context
27 if (usage.tokens === undefined) {
28 await update($, gauge, () => null)
29 await update($, line, () => '')
30 return
31 }
32 const percent = usage.percent ?? Math.round((usage.tokens / usage.window) * 100)
33 const next: Gauge = { tokens: usage.tokens, percent }
34 await update($, gauge, () => next)
35 await update($, line, () => `ctx ${bar(percent)} ${percent}% · ${fmt(usage.tokens)}`)
36
37 if (percent < WARN_PCT) await update($, isHidden, () => false)
38}
39
40export const register: Register = on => {
41 on('session.start', async ($, e, next) => {
42 const result = await next(e)
43 await refresh($)
44 return result
45 })
46
47 // turn.step streams, so its hook is a generator; refresh after each main-thread response.
48 on('turn.step', async function* ($, e, next) {
49 const result = yield* next(e)
50 if (e.agentId === undefined) await refresh($)
51 return result
52 })
53
54 on('turn.complete', async ($, e, next) => {
55 const result = await next(e)
56 await refresh($)
57 return result
58 })
59
60 on('ui.render', { component: 'PromptHint' }, async ($, e, next) => {
61 const tail = await read($, line)
62 return next(tail ? { ...e, props: { ...e.props, tail: ` ${tail}` } } : e)
63 })
64
65 on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
66 const g = await read($, gauge)
67 if (e.props.hasSurvey || g === null || g.percent < WARN_PCT || (await read($, isHidden))) {
68 return next(e)
69 }
70
71 const { Box, Button, Text } = $.ui.resolve(e)
72 const isHot = g.percent >= HOT_PCT
73
74 return (
75 <Box>
76 <Text color={isHot ? 'red' : 'yellow'}>
77 Context is {fmt(g.tokens)} ({g.percent}%). Switching tasks? /clear first.{' '}
78 </Text>
79 <Button key="hide" label="Hide" onPress={() => update($, isHidden, () => true)} />
80 </Box>
81 )
82 })
83}
84types/index.d.ts 8 lines1export type Gauge = { tokens: number; percent: number }
2
3declare module 'claude-code' {
4 interface PluginState {
5 'context-gauge': { gauge: Gauge | null; isHidden: boolean; line: string }
6 }
7}
8