env/dotfiles
1
0 Fork 0
mirror of https://github.com/prdlk/dotfiles.git synced 2026-11-02 11:32:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add comprehensive documentation for AI agents, chezmoi workflow, shell setup, desktop configuration, terminal multiplexers, and developer tools

Browse Source
This commit is contained in:
Prad Nukala committed 2026-09-28 11:08:17 -04:00
1 parent 41437d4abd
commit 1da988c876
47 files changed
+5485
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/ai/claude-code.mdx
+200
View File
@@ -0,0 +1,200 @@
---
title: Claude Code
description: Claude Code settings, hooks, plugins, slash commands, and skill links managed under ~/.claude.
---
Claude Code is Anthropic's terminal coding agent. The repo manages its user-level settings, hook scripts, custom slash commands, and the skill links it loads. The `claude` binary itself is not installed by chezmoi.
## Files
| Source in repo | Target | Notes |
| --- | --- | --- |
| `dot_claude/settings.json` | `~/.claude/settings.json` | Plain file; in symlink mode the target is a symlink back into the repo |
| `dot_claude/empty_CLAUDE.md` | `~/.claude/CLAUDE.md` | `empty_` keeps the zero-byte file; no global memory instructions |
| `dot_claude/hooks/executable_cmem-to-obsidian.py` | `~/.claude/hooks/cmem-to-obsidian.py` | Executable |
| `dot_claude/hooks/executable_herdr-agent-state.sh` | `~/.claude/hooks/herdr-agent-state.sh` | Executable, generated by herdr |
| `dot_claude/hooks/gitnexus/gitnexus-hook.cjs` | `~/.claude/hooks/gitnexus/gitnexus-hook.cjs` | Present but not wired in `settings.json` |
| `dot_claude/commands/*.md` | `~/.claude/commands/*.md` | User slash commands |
| `dot_claude/skills/symlink_*` | `~/.claude/skills/*` | Symlinks into `~/.agents/skills` |
| `dot_claude/skills/<dir>/` | `~/.claude/skills/<dir>/` | Claude-only skills kept as real directories |
None of these are role-gated. Hook commands in `settings.json` use absolute `/home/prad/...` paths; on a machine with a different home directory, edit them after cloning.
## settings.json
### Model and UI
| Key | Value | Effect |
| --- | --- | --- |
| `model` | `fable` | Default model alias |
| `tui` | `fullscreen` | Full-screen terminal UI |
| `agentPushNotifEnabled` | `true` | Push notifications when the agent needs attention |
| `skipDangerousModePermissionPrompt` | `true` | No confirmation when starting in bypass-permissions mode |
| `skipAutoPermissionPrompt` | `true` | No confirmation when entering auto mode |
No `statusLine` is configured; Claude Code uses its default status line.
### Environment
`env` sets two variables for every session:
| Variable | Purpose |
| --- | --- |
| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Turns off Claude Code's built-in auto memory. Session memory comes from the claude-mem plugin instead. |
| `EDITOR` | Points the external editor at `micro`. |
### Permissions
- `defaultMode` is `auto`, so sessions start in auto mode and the classifier approves routine actions.
- The `allow` list pre-approves seven read-only tools from the `codegraph` MCP server: `codegraph_search`, `codegraph_context`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_node`, and `codegraph_status`.
- There is no `deny` or `ask` list.
`autoMode.environment` is a list of trust-boundary notes that auto mode reads when judging risk. It declares no org, cloud provider, secrets manager, or CI target. It names one private personal LeetCode repository as the trusted repo and treats routine work there as low risk. It marks `.env*` files as sensitive. Any host, namespace, or container with `prod` or `production` as a whole name segment counts as a sensitive remote target. IaC changes touching IAM, RBAC, networking, quota, and node pools count as protected.
### Hooks
`settings.json` wires six hook commands:
| Command | What it does |
| --- | --- |
| `pixtuoid-hook` | External binary that receives lifecycle events. Matcher `.*`. |
| `~/.orca/agent-hooks/claude-hook.sh` | Orca's agent hook. Runs through `/bin/sh` only if the file exists and is executable, so machines without Orca skip it silently. |
| `atuin hook claude-code` | Records the agent's `Bash` tool calls in [atuin](/shell/atuin) history. Matcher `Bash`. |
| `python3 ~/.claude/hooks/cmem-to-obsidian.py` | Exports the session's claude-mem learnings to Obsidian ([below](#cmem-to-obsidian)). 15 s timeout. |
| `bash ~/.claude/hooks/herdr-agent-state.sh session` | Reports the session to herdr ([below](#herdr-agent-state)). 10 s timeout. |
| `sh ~/skills/tldraw-offline/inject-server-context.sh SubagentStart` | Injects server context when the `tldraw-offline` subagent starts. The script lives outside this repo. |
Event wiring:
| Event | pixtuoid | orca | atuin (`Bash`) | Other |
| --- | :-: | :-: | :-: | --- |
| `SessionStart` | yes | | | herdr-agent-state `session` |
| `UserPromptSubmit` | | yes | | |
| `PreToolUse` | yes | yes | yes | |
| `PermissionRequest` | | yes | | |
| `PostToolUse` | yes | yes | yes | |
| `PostToolUseFailure` | | yes | yes | |
| `Notification` | yes | | | |
| `SubagentStart` | yes | | | tldraw-offline context (matcher `tldraw-offline`) |
| `SubagentStop` | yes | | | |
| `Stop` | | yes | | |
| `StopFailure` | | yes | | |
| `SessionEnd` | yes | | | cmem-to-obsidian |
### Plugins
`enabledPlugins`:
| Plugin | Marketplace | State |
| --- | --- | --- |
| `caveman` | `caveman` | enabled |
| `claude-mem` | `thedotmack` | enabled |
| `context-mode` | `context-mode` | enabled |
| `context7` | `claude-plugins-official` | disabled |
| `council` | `council-of-high-intelligence` | enabled |
| `exa` | `claude-plugins-official` | enabled |
| `frontend-design` | `claude-plugins-official` | enabled |
| `gopls-lsp` | `claude-plugins-official` | enabled |
| `gopls` | `claude-code-lsps` | enabled |
| `lua-lsp` | `claude-plugins-official` | enabled |
| `ponytail` | `ponytail` | enabled |
| `solidity-language-server` | `claude-code-lsps` | enabled |
| `understand-anything` | `understand-anything` | enabled |
| `vtsls` | `claude-code-lsps` | enabled |
| `yaml-lsp` | `zircote-lsp` | enabled |
| `diagram-design` | `diagram-design` | enabled |
The LSP plugins give the agent language-server diagnostics for Go, Lua, Solidity, TypeScript/JavaScript (vtsls), and YAML.
### Marketplaces
`extraKnownMarketplaces` registers eleven plugin sources:
| Name | Source |
| --- | --- |
| `caveman` | GitHub `JuliusBrussee/caveman` |
| `claude-code-lsps` | GitHub `Piebald-AI/claude-code-lsps` |
| `claude-plugins-official` | GitHub `anthropics/claude-plugins-official` |
| `council-of-high-intelligence` | GitHub `0xNyk/council-of-high-intelligence` |
| `mempalace` | GitHub `MemPalace/mempalace` |
| `omc` | git `https://github.com/Yeachan-Heo/oh-my-claudecode.git` |
| `ponytail` | GitHub `DietrichGebert/ponytail` |
| `thedotmack` | GitHub `thedotmack/claude-mem` |
| `understand-anything` | GitHub `Egonex-AI/Understand-Anything` |
| `zircote-lsp` | GitHub `zircote/lsp-marketplace` |
| `diagram-design` | GitHub `cathrynlavery/diagram-design` |
`mempalace` and `omc` are registered but no plugin from them is enabled. `context-mode` is enabled but its marketplace is not declared here; it comes from Claude Code's own marketplace state.
## Hook scripts
### cmem-to-obsidian.py [#cmem-to-obsidian]
A stdlib-only Python script run on `SessionEnd`. It reads the hook JSON from stdin and exports that session's claude-mem observations to an Obsidian note. It fails soft: any error is logged and the script exits 0, so it never blocks the session.
1. Opens the claude-mem SQLite database read-only (`?mode=ro`), so it never locks the live DB or its WAL.
2. Maps the Claude Code `session_id` to claude-mem's memory session via `sdk_sessions.content_session_id`, then loads that session's observations and latest summary.
3. Drops any observation containing `<private>`.
4. Writes `<vault>/<project>/<date> <project> <session-prefix>.md`. The file name is keyed to the session, so re-runs overwrite the same note.
5. Creates `<vault>/<project>.md` as a map-of-content note if it is missing, so the `[[project]]` wikilink resolves.
Note layout: frontmatter (`date`, `project`, `session`, `source: claude-mem`, tags `claude-mem` and `project/<slug>`), an abstract callout from the session summary, then sections by observation type. Each bullet links back to the claude-mem viewer at `http://localhost:<port>/?observation=<id>`.
| Section | Observation types |
| --- | --- |
| Decisions | `decision` (rendered as note callouts) |
| Fixes & gotchas | `bugfix` |
| Insights | `discovery`, `feature`, `change`, `refactor`, plus any unmapped type |
| Variable | Default |
| --- | --- |
| `CLAUDE_MEM_DB` | `~/.claude-mem/claude-mem.db` |
| `CMEM_OBSIDIAN_DIR` | `~/Documents/Vault/90 - Archive/Learnings` |
| `CLAUDE_MEM_WORKER_PORT` | `37700` |
Log file: `~/.claude/hooks/cmem-to-obsidian.log`.
### herdr-agent-state.sh [#herdr-agent-state]
Generated and versioned by [herdr](/terminal/herdr) (integration id `claude`, version 7). The header says reinstalling herdr's integration overwrites it, so put custom hooks in separate files. It runs on `SessionStart` with the `session` action and exits immediately for any other action.
It only acts inside a herdr pane: `HERDR_ENV=1`, `HERDR_SOCKET_PATH`, and `HERDR_PANE_ID` must be set, and `python3` must be on `PATH`. It then sends one `pane.report_agent_session` request over herdr's Unix socket with the pane id, the Claude session id, the transcript path, and the session start source. herdr uses this to link the pane to the agent session. Subagent events and `SubagentStop` are ignored, so a finished subagent cannot mark an idle pane as working again. Socket errors are swallowed and the script has a 0.5 s timeout.
### gitnexus/gitnexus-hook.cjs
A Node `PreToolUse` handler that adds GitNexus code-graph context to searches. `settings.json` does not reference it, so it is inactive until you add a hook entry.
- Runs only when `.gitnexus` exists in the working directory or one of its four nearest ancestors.
- Pulls a search pattern from `Grep` (the pattern), `Glob` (the first identifier-like path segment), or `Bash` commands that call `rg` or `grep` (the first non-flag argument). Patterns under three characters are skipped.
- Runs `gitnexus augment <pattern>`. It tries the bun global install at `~/.bun/install/global/node_modules/gitnexus` first, then `require.resolve`, then `npx -y gitnexus` (8 s or 15 s timeout).
- Returns the CLI's stderr output as `hookSpecificOutput.additionalContext`.
## Slash commands
`dot_claude/commands/` becomes `~/.claude/commands/`, one user-level slash command per file.
| Command | Arguments | Purpose |
| --- | --- | --- |
| `/bd-drain` | optional priority filter (`p0-p2`), epic id, or `dry-run` | Works through every open beads issue until all are closed with tests and builds passing. Records a green baseline first; `dry-run` prints the dependency-sorted plan and stops. Allowed tools: `bd`, `git`, `go`, `pnpm`, `cargo`, `make`, file tools, `Task`. |
| `/cmem-to-beads` | none | Pulls insight, decision, and gotcha learnings out of claude-mem and saves them as beads memories with `bd remember`. Actionable items are skipped. |
| `/cmem-to-linear` | none | Turns actionable claude-mem learnings (bugs, tech debt, follow-ups) into beads tasks, then pushes the new ones to Linear. |
| `/create-task` | `<task description or goal>` | Breaks a task into beads issues with dependencies, acceptance criteria, and priorities. The prompt includes live `bd ready`, in-progress, and recently-closed lists. Allowed tools: `bd`, `git log`, `git status`, `rg`, `Task`. |
| `/rams` | optional file | "Rams" accessibility (WCAG 2.1) and visual design review of a component file. Offers a project scan when no file is given. |
| `/web-interface-guidelines` | `<file-or-pattern>` | Reviews UI code against the Vercel Web Interface Guidelines: accessibility, focus, forms, animation, typography, and more. |
## Skills
`~/.claude/skills/` holds two kinds of entries:
- **Symlinks** (`symlink_<name>` in the source). Each file contains a relative target such as `../../.agents/skills/blume`, so `~/.claude/skills/blume` resolves to `~/.agents/skills/blume`. The shared library is documented on the [Skills](/ai/skills) page.
- **Real directories** for Claude-only skills: `absurd`, `agents-sdk`, `cloudflare`, `cloudflare-email-service`, `cloudflare-one`, `cloudflare-one-migrations`, `create-beads-orchestration`, `durable-objects`, `sandbox-sdk`, `todoist-cli`, `turnstile-spin`, `web-perf`, `workers-best-practices`. See [Claude-only skills](/ai/skills#claude-only-skills).
## Repo-local settings
This repo's own `.claude/settings.json` applies only to Claude Code sessions opened inside the chezmoi source directory. chezmoi ignores dot-prefixed source entries, so it is never deployed. It runs `bd prime` on `SessionStart` and `PreCompact`, which reloads beads issue context at session start and before compaction.
## Integrations
- [kitty](/terminal/kitty) tab bar shows a robot glyph for tabs running `claude`.
- The fish `ai` picker launches `claude --dangerously-skip-permissions`; see [fish](/shell/fish).
- The claude-mem plugin feeds both `cmem-to-obsidian.py` and the `/cmem-to-*` commands.
docs/ai/index.mdx
+65
View File
@@ -0,0 +1,65 @@
---
title: AI agents
description: Claude Code, omp, and the shared agent skill library that both read from.
sidebar:
label: Overview
---
The repo manages configuration for two coding agents and a skill library they share. Neither agent binary is installed by chezmoi: `.chezmoidata/packages.yaml` lists no agent CLIs, so install Claude Code and omp yourself. topgrade runs `omp update` as a custom command.
<CardGroup cols={3}>
<Card title="Claude Code" href="/ai/claude-code" icon="terminal">
Settings, hooks, plugins, slash commands, and skill links under `~/.claude`.
</Card>
<Card title="omp" href="/ai/omp" icon="cpu">
Config, keybindings, MCP servers, theme, commands, and scheduled research loops under `~/.omp`.
</Card>
<Card title="Skills" href="/ai/skills" icon="library">
The `~/.agents/skills` library, its lock file, and the symlinks that expose it to Claude Code.
</Card>
</CardGroup>
## Pages
| Page | Source in repo | Target in `$HOME` | Covers |
| --- | --- | --- | --- |
| [Claude Code](/ai/claude-code) | `dot_claude/` | `~/.claude/` | `settings.json`, hook scripts, `/commands`, empty `CLAUDE.md`, skill symlinks |
| [omp](/ai/omp) | `dot_omp/` | `~/.omp/` | `agent/config.yml`, `keybindings.yml`, `mcp.json`, cyberdream theme, commands, loops |
| [Skills](/ai/skills) | `dot_agents/` | `~/.agents/` | `.skill-lock.json` and every skill directory |
## Layout
<FileTree>
- dot_claude/
- settings.json
- empty_CLAUDE.md
- commands/
- hooks/
- executable_cmem-to-obsidian.py
- executable_herdr-agent-state.sh
- gitnexus/
- skills/
- dot_omp/
- private_agent/
- private_config.yml
- keybindings.yml
- private_mcp.json
- themes/
- commands/
- loops/
- bin/
- goals/
- dot_agents/
- dot_skill-lock.json
- skills/
</FileTree>
None of these files are role-gated: `.chezmoiignore.tmpl` applies them on every machine role (desktop, laptop, mac, server).
## Shell entry points
- `ai` (fish function) opens a `gum choose` picker over `claude`, `opencode`, `codex`, `hermes`, and `fractal`. Picking `claude` runs `claude --dangerously-skip-permissions`; the others run the binary of the same name. See [fish](/shell/fish).
- <kbd>Ctrl</kbd> <kbd>A</kbd> launches `omp` from the fish and zsh prompts.
- `launch_omp_livediff_overlay` and `lc-elir` are omp helpers in `~/.local/bin`; see [omp](/ai/omp#shell-integration) and [scripts](/shell/scripts).
docs/ai/meta.ts
+7
View File
@@ -0,0 +1,7 @@
import { defineMeta } from "blume";
export default defineMeta({
title: "AI agents",
icon: "bot",
pages: ["index", "claude-code", "omp", "skills"],
});
docs/ai/omp.mdx
+175
View File
@@ -0,0 +1,175 @@
---
title: omp
description: omp agent config, keybindings, MCP servers, cyberdream theme, custom commands, and the scheduled research loops under ~/.omp.
---
omp (oh-my-pi) is a terminal coding agent. The repo manages its agent directory (`~/.omp/agent`) and a set of prompt loops in `~/.omp/loops`. chezmoi does not install the `omp` binary; install it yourself. [topgrade](/tools/topgrade) keeps it current with the custom command `"Omp Update" = "omp update"`.
## Files
| Source in repo | Target | Notes |
| --- | --- | --- |
| `dot_omp/private_agent/` | `~/.omp/agent/` | Directory mode `0700` |
| `dot_omp/private_agent/private_config.yml` | `~/.omp/agent/config.yml` | Mode `0600` |
| `dot_omp/private_agent/keybindings.yml` | `~/.omp/agent/keybindings.yml` | |
| `dot_omp/private_agent/private_mcp.json` | `~/.omp/agent/mcp.json` | Mode `0600` |
| `dot_omp/private_agent/themes/cyberdream.json` | `~/.omp/agent/themes/cyberdream.json` | Custom theme |
| `dot_omp/private_agent/commands/*.md` | `~/.omp/agent/commands/*.md` | Slash commands |
| `dot_omp/loops/bin/executable_run-loop.sh` | `~/.omp/loops/bin/run-loop.sh` | Loop runner |
| `dot_omp/loops/<name>/private_loop.md` | `~/.omp/loops/<name>/loop.md` | One prompt per loop, mode `0600` |
| `dot_omp/loops/goals/private_templates.md` | `~/.omp/loops/goals/templates.md` | Unscheduled `/goal` templates |
No omp file is role-gated. In chezmoi's symlink mode, `private_` and `executable_` entries are written as regular files, not symlinks.
## config.yml
```yaml ~/.omp/agent/config.yml
theme:
dark: titanium
light: light
symbolPreset: nerd
setupVersion: 2
hideThinkingBlock: false
modelRoles:
plan: anthropic/claude-fable-5
composer:
shape: rule
```
| Key | Value | Effect |
| --- | --- | --- |
| `theme.dark` | `titanium` | Theme on a dark terminal background (omp's default, pinned explicitly) |
| `theme.light` | `light` | Theme on a light terminal background (omp's default) |
| `symbolPreset` | `nerd` | Nerd Font glyphs instead of the default `unicode` set; the repo's font is Victor Mono Nerd Font |
| `hideThinkingBlock` | `false` | Thinking blocks stay visible |
| `modelRoles.plan` | `anthropic/claude-fable-5` | Model for the `plan` role; other roles use omp defaults |
| `composer.shape` | `rule` | Built-in `rule` composer style instead of the default `box` |
| `setupVersion` | `2` | Internal settings version marker |
No API keys are stored in `config.yml`.
## Keybindings
```yaml ~/.omp/agent/keybindings.yml
app.editor.external: Ctrl+E
app.exit: Ctrl+Q
```
| Key | Action |
| --- | --- |
| <kbd>Ctrl</kbd> <kbd>E</kbd> | Open the current prompt in the external editor (`app.editor.external`) |
| <kbd>Ctrl</kbd> <kbd>Q</kbd> | Quit omp (`app.exit`) |
All other bindings are omp defaults.
## MCP servers
`mcp.json` declares three remote MCP servers over HTTP. No credential values are stored in the file.
| Server | Transport | Endpoint | Auth |
| --- | --- | --- | --- |
| `exa` | `http` | `https://mcp.exa.ai/mcp` | none |
| `cloudflare-api` | `http` | `https://mcp.cloudflare.com/mcp` | OAuth; omp stores the token in its own credential store under a profile credential id |
| `github` | `http` | `https://api.githubcopilot.com/mcp/` | `Authorization` header built at request time by a `!` shell command that reads the token from `gh auth token` |
The GitHub server therefore needs the [GitHub CLI](/tools/github-cli) to be logged in. The `$schema` key points at omp's `mcp-schema.json` for editor validation.
## Theme
`themes/cyberdream.json` ports the cyberdream palette to omp's theme schema. It installs the theme, but `config.yml` currently selects `titanium` for dark mode. To use cyberdream, set `theme.dark: cyberdream`.
| Var | Hex | Used for |
| --- | --- | --- |
| `bg` | `#16181a` | base background |
| `bgAlt` | `#1e2124` | user/custom message, tool, and status-line backgrounds |
| `bgHighlight` | `#3c4048` | selection |
| `fg` | `#ffffff` | message and tool output text |
| `grey` | `#7b8496` | muted, dim, thinking text, comments, quotes, borders |
| `blue` | `#5ea1ff` | accent, borders, links, functions, status-line path |
| `cyan` | `#5ef1ff` | accent borders, tool titles, inline code, types, context meter |
| `green` | `#5eff6c` | success, diff additions, strings, clean git |
| `red` | `#ff6e5e` | errors, diff removals, untracked files |
| `yellow` | `#f1ff5e` | warnings, variables, bash mode, dirty git |
| `magenta` | `#ff5ef1` | keywords, subagent count |
| `pink` | `#ff5ea0` | operators, spend |
| `orange` | `#ffbd5e` | Markdown headings, cost |
| `purple` | `#bd5eff` | numbers, python mode, model name |
The thinking-level indicator runs `grey` (off) → `blue` → `cyan` → `green` → `yellow` → `orange` → `red` (max).
## Commands
| Command | Invocation | Purpose |
| --- | --- | --- |
| `/leetcode-docs` | `/leetcode-docs <file> [extra instructions]` | Converts a LeetCode solution file into a Fumadocs MDX page at `content/docs/leetcode/<difficulty>/<category>/<number>-<slug>.mdx`. The page has a difficulty callout, problem, examples, constraints, a derived intuition paragraph, the solution copied verbatim (multiple approaches become tabs), and a complexity callout. Prints only the output path. |
| `/leetcode-eli5` | `/leetcode-eli5 <file> [extra instructions]` | Adds beginner-level line-by-line comments and a `// ====` banner to a LeetCode solution. Leaves the header, JSDoc, and code byte-for-byte unchanged. Prints the path and the number of comment lines added. |
Both expect the on-disk format of the LeetCode solutions repo: a `/* ... */` problem header, a JSDoc block, then the solution function(s).
## Loops
`~/.omp/loops` holds scheduled, read-only research prompts. Each loop is a directory with a `loop.md` prompt. `run-loop.sh` creates `state.md` and `runs.log` beside it at runtime; chezmoi does not manage those.
### run-loop.sh
```sh
~/.omp/loops/bin/run-loop.sh <loop-name>
```
Runs one round of a loop:
<Steps>
<Step title="Prepare state">
Exits if `~/.omp/loops/<name>/loop.md` is missing. Seeds `state.md` with `## queue`, `## done`, and `## blocked` headings if it does not exist.
</Step>
<Step title="Cheap round">
Runs `omp -p --no-session --max-time 600 --model kimi-for-coding` with the prompt plus the loop directory, state-file path, and round timestamp appended. Output goes to `runs.log`.
</Step>
<Step title="Escalate once">
If any output line starts with `ESCALATE`, re-runs the round once on omp's default model (Fable) with a 1200 s cap. It logs `<loop> escalated` to `~/.omp/loops/escalations.log`.
</Step>
</Steps>
At most one round and one escalation per call. Failures from `omp` are logged and do not abort the script.
### Loop catalogue
Every loop follows the same contract: read `state.md` first, do one pass, make exactly one change (usually a brief or proposal appended under `## queue`), and log repeated tool failures under `## blocked`. Loops draft only; they never file issues or change repos. The subject is WalletBase, an embedded-wallet project.
| Loop | Cadence | Inputs | Output per round | Escalates on |
| --- | --- | --- | --- | --- |
| `intel-refresh` (#19) | Mon 06:00 | Exa search over five beats: ERC-4337/AA, EIP-7702, embedded-wallet competitors, agent-payment protocols, Base chain | Up to 5 bullets per beat for the week; proposes swapping a beat that has been quiet for 3 weeks | A development that breaks a core assumption |
| `share-of-model` (#3) | Mon 07:00 | Exa answer mode, fixed set of six buyer questions | Table of vendors named per answer and whether WalletBase appears; biggest rank shift | never |
| `regulatory-digest` (#20) | Tue 07:00 | FinCEN, OFAC, SEC/CFTC, EU MiCA/CASP, Ethereum governance | Only material changes; "no material changes" counts as success; a proposed risk-position edit when an item breaks a standing assumption | MSB scope or OFAC action touching similar infra |
| `brand-radar` (#10) | Wed 07:00 | HN Algolia API (no key), Exa | Mentions grouped into feature asks, pricing pain, security, and integration friction; one drafted `bd create` issue or positioning note | Security discussion of a dependency |
| `answer-gap` (#1) | Thu 07:00 | Exa, rotating developer questions plus ones harvested in earlier rounds | One content brief; up to 3 new questions queued | never |
| `competitor-watch` (#4) | Fri 07:00 | Exa over six competitor blogs | Logs new posts; one content brief for the biggest gap | Competitor launches an agent-economy product |
| `repeat-offender` (#24) | Sun 18:00 | `bd list` across the project's repos, loop `runs.log`, `## blocked` sections, and `escalations.log` | Failure patterns grouped by root cause; one drafted `bd create` systemic fix | Data loss or security-boundary pattern |
Five prompts cap page fetches or API calls per round (15 to 30); `share-of-model` and `repeat-offender` are bounded by their fixed question set and sources.
:::note[Scheduling]
Cadences are declared in each prompt header; the repo contains no timer for them. `.chezmoiscripts/run_once_after_30-user-services.sh.tmpl` names `omp-loop` among the personal automation units that are enabled by hand on each machine and never automatically. See [scripts](/chezmoi/scripts).
:::
### Goal templates
`goals/templates.md` is not scheduled. It holds two `/goal` prompts to paste into an interactive omp session when facing a decision:
| Template | Purpose | Cap |
| --- | --- | --- |
| kill-criteria (#22) | One measurable disqualifying condition per option, cited evidence, verdict ALIVE / KILLED / NEEDS-DATA | 40 tool calls |
| pre-mortem (#23) | Writes the post-mortem of a failed decision 12 months out: 3–5 causal chains, each tied to a present-day assumption, with an early warning sign and the cheapest mitigation | 30 tool calls |
Both count as done only when the full artifact is pasted in the chat.
## Shell integration
| Entry point | Source | What it does |
| --- | --- | --- |
| fish completions | `dot_config/fish/completions/omp.fish` | `omp completions fish \| source` generates completions at load time |
| <kbd>Ctrl</kbd> <kbd>A</kbd> | fish `fish_user_key_bindings`, zsh `keybinds.zsh` | Launches `omp` from the prompt |
| `launch_omp_livediff_overlay` | `dot_local/bin/executable_launch_omp_livediff_overlay`, fish function of the same name | Opens omp as a kitty overlay on the current window with a `livediff` vsplit beside it, focus kept on omp. Needs `KITTY_LISTEN_ON` (kitty remote control). |
| `lc-elir [root]` | `dot_local/bin/executable_lc-elir`, fish function | fzf multi-picks numbered LeetCode files (`1365.slug.js`/`.ts`) with a bat preview and runs `omp -p "/leetcode-eli5 <file>"` on each |
See [scripts](/shell/scripts) and [fish](/shell/fish). The [kitty](/terminal/kitty) tab bar shows a microchip glyph for tabs running `omp`.
docs/ai/skills.mdx
+174
View File
@@ -0,0 +1,174 @@
---
title: Skills
description: The shared agent skill library in ~/.agents/skills, its lock file, and how Claude Code links to it.
---
Agent skills are folders with a `SKILL.md` file (frontmatter `name` and `description`, then instructions) that agents load on demand. The repo keeps one shared library in `~/.agents/skills`. Agents that follow the open skills layout read it from there, and Claude Code reaches it through symlinks in `~/.claude/skills`.
## Files
| Source in repo | Target | Notes |
| --- | --- | --- |
| `dot_agents/skills/<name>/` | `~/.agents/skills/<name>/` | 82 skill directories; in symlink mode each plain file is a symlink into the repo |
| `dot_agents/dot_skill-lock.json` | `~/.agents/.skill-lock.json` | Install record written by the `skills` CLI |
| `dot_claude/skills/symlink_<name>` | `~/.claude/skills/<name>` | Relative symlink to `../../.agents/skills/<name>` |
Not role-gated; the library is applied on every machine.
## Managing skills
Skills are installed and updated with the Skills CLI (`npx skills`), which the `find-skills` skill documents:
```sh
npx skills find <query> # search the registry
npx skills add <owner/repo@skill> -g -y # install at user level
npx skills check # look for updates
npx skills update # update everything
```
A skill installed this way lands in `~/.agents/skills/<name>/` as plain files. Add it to the repo with `chezmoi add ~/.agents/skills/<name>`, and commit the updated `.skill-lock.json` alongside it. To expose it to Claude Code, add a `dot_claude/skills/symlink_<name>` file containing `../../.agents/skills/<name>`.
### .skill-lock.json
The lock file (`"version": 3`) has one entry per installed skill, keyed by skill name:
| Field | Meaning |
| --- | --- |
| `source` | Where the skill came from: `owner/repo` for GitHub, or a domain for well-known endpoints |
| `sourceType` | `github` (77 entries) or `well-known` (3 entries, all `mintlify.com`) |
| `sourceUrl` | Git clone URL, or the `.well-known/agent-skills/.../skill.md` URL |
| `skillPath` | Path of `SKILL.md` inside the source repo (GitHub sources only) |
| `skillFolderHash` | Hash of the skill folder at the recorded version (empty for well-known sources) |
| `installedAt` / `updatedAt` | ISO timestamps of first install and last update |
A top-level `dismissed` object records dismissed CLI prompts (`findSkillsPrompt: true`).
The lock lists 80 skills. The largest sources are `mattpocock/skills` (23), `vercel-labs/json-render` (16), `Leonxlnx/taste-skill` (7), `haydenbleasel/blume` (3). The lock and the directory do not match exactly:
- In the lock with no directory in the repo: `Technical Writer`, `codegen`, `ethereum-wingman`, `gh-stack`, `image`, `jotai`, `mcp`, `react-email`, `react-native`, `react-pdf`, `redux`, `remotion`, `solid`, `svelte`, `vue`, `xstate`, `zustand`.
- In the directory with no lock entry (added by hand or copied from elsewhere): shown as `untracked` in the table below.
## How Claude Code resolves skills
<Steps>
<Step title="Source">
`dot_claude/skills/symlink_blume` is a one-line file containing `../../.agents/skills/blume`.
</Step>
<Step title="Apply">
chezmoi's `symlink_` prefix turns it into the symlink `~/.claude/skills/blume`, pointing at `../../.agents/skills/blume`.
</Step>
<Step title="Resolve">
Relative to `~/.claude/skills/`, the target is `~/.agents/skills/blume`, whose files are in turn symlinks into the chezmoi source directory. Edits to a skill in the repo take effect immediately.
</Step>
</Steps>
Twelve library skills have no Claude link, so only agents that read `~/.agents/skills` directly can see them. They are the three fumadocs skills, five of the six tanstack skills, `interface-design`, `laws-of-ux`, `ui-ux-pro-max`, and `web-design-guidelines` (marked `—` below). Three Claude-side entries (`cloudflare`, `todoist-cli`, `workers-best-practices`) are separate real directories in `dot_claude/skills/` rather than links, so Claude Code reads its own copy (`own copy` below).
## Library
The Description column is the first sentence of each skill's `SKILL.md` frontmatter `description`. Lock source is the `source` field from `.skill-lock.json`.
| Skill | Lock source | Claude link | Description |
| --- | --- | :-: | --- |
| `blume` | `haydenbleasel/blume` | symlink | Build and maintain documentation sites with Blume, the markdown-first docs framework on Astro and Vite. |
| `blume-migrate` | `haydenbleasel/blume` | symlink | Migrate an existing documentation site (Mintlify, Docusaurus, Fumadocs, Nextra, Starlight, or any docs framework) to Blume, the markdown-first docs framework on Astro. |
| `blume-update-docs` | `haydenbleasel/blume` | symlink | Keep a Blume docs site in sync with the product it documents. |
| `brandkit` | `Leonxlnx/taste-skill` | symlink | Premium brand-kit image generation skill for creating high-end brand-guidelines boards, logo systems, identity decks, and visual-world presentations. |
| `bun-development` | `sickn33/antigravity-awesome-skills` | symlink | Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by oven-sh/bun. |
| `cloudflare` | untracked | own copy | Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). |
| `codebase-design` | `mattpocock/skills` | symlink | Shared vocabulary for designing deep modules. |
| `core` | `vercel-labs/json-render` | symlink | Core package for defining schemas, catalogs, and AI prompt generation for json-render. |
| `deepinit` | `yeachan-heo/oh-my-claudecode` | symlink | Deep codebase initialization with hierarchical AGENTS.md documentation |
| `design-an-interface` | untracked | symlink | Generate multiple radically different interface designs for a module using parallel sub-agents. |
| `design-taste-frontend` | `Leonxlnx/taste-skill` | symlink | Anti-slop frontend skill for landing pages, portfolios, and redesigns. |
| `diagnosing-bugs` | `mattpocock/skills` | symlink | Diagnosis loop for hard bugs and performance regressions. |
| `domain-modeling` | `mattpocock/skills` | symlink | Build and sharpen a project's domain model. |
| `find-skills` | `vercel-labs/skills` | symlink | Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. |
| `fumadocs-component-docs` | untracked | — | Create component documentation with installation, usage examples, and preview sections. |
| `fumadocs-mdx-structure` | untracked | — | Create MDX documentation files with proper frontmatter, imports, and component integration. |
| `fumadocs-registry-integration` | untracked | — | Register 8-bit components in registry.json for shadcn/ui add command. |
| `git-guardrails-claude-code` | `mattpocock/skills` | symlink | Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. |
| `golang-pro` | `jeffallan/claude-skills` | symlink | Implements concurrent Go patterns using goroutines and channels, designs and builds microservices with gRPC or REST, optimizes Go application performance with pprof, and enforces idiomatic Go with generics, interfaces, and robust error handling. |
| `gpt-taste` | `Leonxlnx/taste-skill` | symlink | Elite UX/UI & Advanced GSAP Motion Engineer. |
| `grill-me` | `mattpocock/skills` | symlink | A relentless interview to sharpen a plan or design. |
| `grill-with-docs` | `mattpocock/skills` | symlink | A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. |
| `grilling` | `mattpocock/skills` | symlink | Grill the user relentlessly about a plan, decision, or idea. |
| `handoff` | `mattpocock/skills` | symlink | Compact the current conversation into a handoff document for another agent to pick up. |
| `high-end-visual-design` | `Leonxlnx/taste-skill` | symlink | Teaches the AI to design like a high-end agency. |
| `imagegen-frontend-web` | `Leonxlnx/taste-skill` | symlink | Elite frontend image-direction skill for generating premium, conversion-aware website design references. |
| `implement` | `mattpocock/skills` | symlink | Implement a piece of work based on a spec or set of tickets. |
| `improve-codebase-architecture` | `mattpocock/skills` | symlink | Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. |
| `interface-design` | untracked | — | This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. |
| `laws-of-ux` | untracked | — | Review and guide UI implementations using the 21 Laws of UX. |
| `linear` | `openai/skills` | symlink | Manage issues, projects & team workflows in Linear. |
| `linear-cli` | `schpet/linear-cli` | symlink | Manage Linear issues from the command line using the linear cli. |
| `linear-documents` | `finesssee/linear-cli` | symlink | Manage Linear documents. |
| `loop-me` | `mattpocock/skills` | symlink | Grill me about specs for the workflows I want to build, within this workspace. |
| `loopy` | `Forward-Future/loop-library` | symlink | Discover, find, compare, audit, repair, adapt, craft, run, debrief, save, and prepare repeatable AI-agent loops for publication. |
| `migrate-to-shoehorn` | `mattpocock/skills` | symlink | Migrate test files from `as` type assertions to @total-typescript/shoehorn. |
| `minimalist-ui` | `Leonxlnx/taste-skill` | symlink | Clean editorial-style interfaces. |
| `mintlify` | `mintlify.com` | symlink | Build and maintain documentation sites with Mintlify. |
| `mintlify-api` | `mintlify.com` | symlink | Interact with the Mintlify REST API to manage deployments, trigger builds, and query documentation site metadata programmatically. |
| `mintlify-docs` | `mintlify.com` | symlink | Build and maintain documentation sites with Mintlify. |
| `native-sdk` | `vercel-labs/native` | symlink | Discovery skill for the Native SDK, the complete toolkit for building native desktop applications. |
| `obsidian-vault` | untracked | symlink | Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. |
| `openlogs-server-logs` | `charlietlamb/openlogs` | symlink | Fetch and inspect recent local server logs in repos that use openlogs or the `ol` CLI. |
| `prototype` | `mattpocock/skills` | symlink | Build a throwaway prototype to answer a design question. |
| `qa` | untracked | symlink | Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. |
| `react` | `vercel-labs/json-render` | symlink | React renderer for json-render that turns JSON specs into React components. |
| `redesign-existing-projects` | `Leonxlnx/taste-skill` | symlink | Upgrades existing websites and apps to premium quality. |
| `remix` | `remix-run/remix` | symlink | Build and review Remix 3 applications using the `remix` npm package and subpath imports. |
| `request-refactor-plan` | untracked | symlink | Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. |
| `resolving-merge-conflicts` | `mattpocock/skills` | symlink | Use when you need to resolve an in-progress git merge/rebase conflict. |
| `rust-async-patterns` | `wshobson/agents` | symlink | Master Rust async programming with Tokio, async traits, error handling, and concurrent patterns. |
| `rust-best-practices` | `apollographql/skills` | symlink | Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. |
| `rust-testing` | `affaan-m/everything-claude-code` | symlink | Rust testing patterns including unit tests, integration tests, async testing, property-based testing, mocking, and coverage. |
| `scaffold-exercises` | `mattpocock/skills` | symlink | Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. |
| `setup-matt-pocock-skills` | `mattpocock/skills` | symlink | Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. |
| `setup-pre-commit` | `mattpocock/skills` | symlink | Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. |
| `shadcn` | `shadcn-ui/ui` | symlink | Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. |
| `solidity-foundry-development` | `whackur/solidity-agent-toolkit` | symlink | Foundry development workflow for Solidity smart contracts. |
| `solidity-security` | `wshobson/agents` | symlink | Master smart contract security best practices to prevent common vulnerabilities and implement secure Solidity patterns. |
| `stop-slop` | `hardikpandya/stop-slop` | symlink | Remove AI writing patterns from prose. |
| `tanstack-form` | untracked | — | Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, Lit, and Svelte. |
| `tanstack-integration-best-practices` | untracked | — | Best practices for integrating TanStack Query with TanStack Router and TanStack Start. |
| `tanstack-query-best-practices` | `deckardger/tanstack-agent-skills` | — | TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. |
| `tanstack-router-best-practices` | untracked | — | TanStack Router best practices for type-safe routing, data loading, search params, and navigation. |
| `tanstack-start-best-practices` | `deckardger/tanstack-agent-skills` | symlink | TanStack Start best practices for full-stack React applications. |
| `tanstack-table` | untracked | — | Headless UI for building powerful tables & datagrids for TS/JS, React, Vue, Solid, Svelte, Qwik, Angular, and Lit. |
| `tdd` | `mattpocock/skills` | symlink | Test-driven development. |
| `teach` | `mattpocock/skills` | symlink | Teach the user a new skill or concept, within this workspace. |
| `todoist-cli` | untracked | own copy | Manage Todoist tasks, projects, labels, filters, sections, comments, reminders, and workspaces via the `td` CLI. |
| `triage` | `mattpocock/skills` | symlink | Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs. |
| `typescript-expert` | `remix-run/remix` | symlink | Write, refactor, or review TypeScript code with strict, precise, maintainable types and without unnecessary `any`, type assertions, or type suppressions. |
| `ubiquitous-language` | untracked | symlink | Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. |
| `ui-ux-pro-max` | untracked | — | UI/UX design intelligence for web and mobile. |
| `uv-package-manager` | `wshobson/agents` | symlink | Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. |
| `web-design-guidelines` | `vercel-labs/agent-skills` | — | Review UI code for Web Interface Guidelines compliance. |
| `workers-best-practices` | untracked | own copy | Reviews and authors Cloudflare Workers code against production best practices. |
| `wrangler` | `cloudflare/skills` | symlink | Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. |
| `write-tests` | `remix-run/remix` | symlink | Write, refactor, or review tests in the Remix repository. |
| `writing-beats` | `mattpocock/skills` | symlink | Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it. |
| `writing-fragments` | `mattpocock/skills` | symlink | Writing, explore: mine raw fragments, no structure yet. |
| `writing-great-skills` | untracked | symlink | Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable. |
| `writing-shape` | `mattpocock/skills` | symlink | Writing, exploit: shape raw material into an article, paragraph by paragraph. |
## Claude-only skills
These live as real directories in `dot_claude/skills/` (target `~/.claude/skills/<name>/`) and are not part of the shared library or the lock file. See [Claude Code](/ai/claude-code#skills).
| Skill | Description |
| --- | --- |
| `absurd` | Debug and operate Absurd durable workflows with absurdctl. |
| `agents-sdk` | Build AI agents on Cloudflare Workers using the Agents SDK. |
| `cloudflare` | Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). |
| `cloudflare-email-service` | Send and receive transactional emails with Cloudflare Email Service (Email Sending + Email Routing). |
| `cloudflare-one` | Guides Cloudflare One Zero Trust and SASE work across Access, Gateway, WARP, Tunnel, Cloudflare WAN, DLP, CASB, device posture, and identity. |
| `cloudflare-one-migrations` | Plans migrations from Zscaler ZIA/ZPA, Palo Alto, legacy VPN, SWG, or SASE stacks to Cloudflare One. |
| `create-beads-orchestration` | Bootstrap lean multi-agent orchestration with beads task tracking. |
| `durable-objects` | Create and review Cloudflare Durable Objects. |
| `sandbox-sdk` | Build sandboxed applications for secure code execution. |
| `todoist-cli` | Manage Todoist tasks, projects, labels, filters, sections, comments, reminders, and workspaces via the `td` CLI. |
| `turnstile-spin` | Set up Cloudflare Turnstile end-to-end in a project. |
| `web-perf` | Analyzes web performance using Chrome DevTools MCP. |
| `workers-best-practices` | Reviews and authors Cloudflare Workers code against production best practices. |
docs/chezmoi/config.mdx
+96
View File
@@ -0,0 +1,96 @@
---
title: Config and roles
description: The .chezmoi.toml.tmpl config template, its three prompts, symlink mode, age encryption, and where the resulting data is used.
---
`.chezmoi.toml.tmpl` is rendered once by `chezmoi init` into `~/.config/chezmoi/chezmoi.toml`. It asks three questions, turns on symlink mode and age encryption, and stores the answers as template data for every other `.tmpl` file.
## Source
```toml .chezmoi.toml.tmpl
{{- $name := promptStringOnce . "name" "Full name" "Prad Nukala" -}}
{{- $email := promptStringOnce . "email" "Email" "prad@sonr.io" -}}
{{- $roleDefault := "desktop" -}}
{{- if eq .chezmoi.os "darwin" -}}{{- $roleDefault = "mac" -}}{{- end -}}
{{- $role := promptChoiceOnce . "role" "Machine role" (list "desktop" "laptop" "mac" "server") $roleDefault -}}
mode = "symlink"
encryption = "age"
[age]
identity = "~/.config/chezmoi/key.txt"
recipient = "age19tdqgavaekhvgqsd75n8a09vvshen2ykzy8kw6tenczz73449anqc3l7a6"
useBuiltin = true
[data]
name = {{ $name | quote }}
email = {{ $email | quote }}
role = {{ $role | quote }}
```
## Prompts
| Key | Prompt | Type | Default |
| --- | --- | --- | --- |
| `name` | `Full name` | `promptStringOnce` | `Prad Nukala` |
| `email` | `Email` | `promptStringOnce` | `prad@sonr.io` |
| `role` | `Machine role` | `promptChoiceOnce` from `desktop`, `laptop`, `mac`, `server` | `mac` when `.chezmoi.os` is `darwin`, otherwise `desktop` |
The `*Once` functions only prompt when the key is missing from the existing config, so re-running `chezmoi init` keeps earlier answers. `chezmoi init --prompt` forces all three prompts again. Changing the role changes the rendered ignore file and package script, so the next `chezmoi apply` adds or drops the desktop layer and re-runs the package install.
### Machine roles
| Role | Intended platform | Linux desktop layer | Desktop packages (`niri`, `xdg-user-dirs`, `noctalia-shell`) |
| --- | --- | --- | --- |
| `desktop` | Arch Linux | Applied | Installed |
| `laptop` | Arch Linux | Applied | Installed |
| `mac` | macOS | Skipped | n/a (Homebrew list only) |
| `server` | Arch Linux, headless | Skipped | Skipped |
`desktop` and `laptop` behave identically in the current templates; nothing branches on one without the other. The desktop layer is also skipped whenever the OS is not Linux, whatever the role. See [the ignore rules](/chezmoi/externals-and-ignore#chezmoiignore) for the exact list of gated paths.
## Mode
`mode = "symlink"` makes `chezmoi apply` link plain files in `$HOME` back to the source tree. Templates, `private_`, `executable_`, and encrypted files are still written as real files. The [overview](/chezmoi#symlink-mode) covers the editing consequences.
## Age encryption
| Setting | Value | Effect |
| --- | --- | --- |
| `encryption` | `"age"` | `chezmoi add --encrypt` and `encrypted_` source files use age. |
| `age.identity` | `~/.config/chezmoi/key.txt` | Private key used to decrypt. Distributed by hand between machines, never committed. |
| `age.recipient` | `age19tdqgavaekhvgqsd75n8a09vvshen2ykzy8kw6tenczz73449anqc3l7a6` | Public key files are encrypted to. Safe to publish. |
| `age.useBuiltin` | `true` | Uses chezmoi's built-in age implementation; the `age` binary is not required. |
No source file currently carries the `encrypted_` attribute, so the key is only exercised when a secret is added with `chezmoi add --encrypt`. The README still asks for the key to be copied into place before the first apply:
```sh
mkdir -p ~/.config/chezmoi
scp <existing-machine>:.config/chezmoi/key.txt ~/.config/chezmoi/key.txt
chmod 600 ~/.config/chezmoi/key.txt
```
## Template data
The `[data]` table exposes `.name`, `.email`, and `.role` to every template. chezmoi also merges `.chezmoidata/*.yaml` into the same namespace (`.packages`, `.aliases`; see [Packages and aliases](/chezmoi/data)) and provides built-ins such as `.chezmoi.os`.
| Variable | Consumed by | Use |
| --- | --- | --- |
| `.name` | `dot_gitconfig.tmpl` | `[user] name` in `~/.gitconfig` |
| `.email` | `dot_gitconfig.tmpl` | `[user] email` in `~/.gitconfig` |
| `.role` | `.chezmoiignore.tmpl` | Skips the Linux desktop layer unless role is `desktop` or `laptop` |
| `.role` | `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` | Adds the `arch.desktop` pacman and AUR packages for `desktop`/`laptop` |
| `.chezmoi.os` | `.chezmoi.toml.tmpl` | Role default (`mac` on darwin) |
| `.chezmoi.os` | `.chezmoiignore.tmpl` | Desktop layer requires `linux` |
| `.chezmoi.os` | `run_onchange_before_10-packages.sh.tmpl` | pacman/paru on `linux`, Homebrew on `darwin` |
| `.chezmoi.os` | `run_once_after_30-user-services.sh.tmpl` | systemd user units on `linux` only |
| `.chezmoi.os` | `run_onchange_after_40-post.sh.tmpl` | `fc-cache` on `linux` only |
| `.chezmoi.os` | `dot_config/yazi/yazi.toml.tmpl` | Yazi's `open` opener runs `open` on darwin, `xdg-open` elsewhere |
```ini dot_gitconfig.tmpl
[user]
email = {{ .email }}
name = {{ .name }}
```
The rest of `~/.gitconfig` is covered under [Tools](/tools).
docs/chezmoi/data.mdx
+189
View File
@@ -0,0 +1,189 @@
---
title: Packages and aliases
description: The .chezmoidata YAML files that declare every installed package and every shared shell alias, and how they render.
---
Files in `.chezmoidata/` are merged into chezmoi's template data on every run. Nothing in the directory is written to `$HOME`; the data only reaches the machine through templates and scripts.
| File | Data key | Consumed by |
| --- | --- | --- |
| `.chezmoidata/packages.yaml` | `.packages` | [`run_onchange_before_10-packages.sh.tmpl`](/chezmoi/scripts#10-packages), [`run_onchange_after_20-gh-extensions.sh.tmpl`](/chezmoi/scripts#20-gh-extensions) |
| `.chezmoidata/aliases.yaml` | `.aliases` | `dot_config/shell/aliases.sh.tmpl` (bash and zsh) |
## packages.yaml [#packagesyaml]
One manifest per platform, plus a `shared` block. Any edit to the file changes the hash embedded in the package script, so the next `chezmoi apply` re-runs the install. Installs are idempotent (`pacman --needed`, `paru --needed`, `brew install` on already-installed formulae).
<Tabs>
<Tab title="Arch">
`packages.arch.pacman`, installed on every Linux machine with `pacman -S --needed --noconfirm`:
| Group | Packages |
| --- | --- |
| Shell and editors | `fish`, `neovim`, `tmux`, `micro` |
| Terminal | `kitty` |
| TUI tools | `yazi`, `lazygit`, `lazydocker`, `btop`, `fastfetch` |
| VCS and forge | `git`, `github-cli`, `git-delta`, `diffnav` |
| Search and files | `fzf`, `fd`, `ripgrep`, `zoxide`, `eza`, `bat`, `jq`, `duf` |
| Media and preview (yazi deps) | `ffmpeg`, `ffmpegthumbnailer`, `poppler`, `resvg`, `imagemagick`, `7zip`, `unzip` |
| Misc CLI | `gum`, `glow`, `atuin`, `wget`, `starship`, `zsh-syntax-highlighting` |
| Fonts | `ttf-victor-mono-nerd` |
`packages.arch.aur`, installed with `paru -S --needed --noconfirm` on every Linux machine: `topgrade`.
`packages.arch.desktop`, added only for roles `desktop` and `laptop`:
| Source | Packages |
| --- | --- |
| pacman | `niri`, `xdg-user-dirs` |
| AUR | `noctalia-shell` |
</Tab>
<Tab title="macOS">
`packages.darwin.brew`, installed with `brew install`:
`fish`, `neovim`, `tmux`, `yazi`, `lazygit`, `lazydocker`, `btop`, `fastfetch`, `git`, `gh`, `git-delta`, `fzf`, `fd`, `ripgrep`, `zoxide`, `eza`, `bat`, `jq`, `duf`, `ffmpeg`, `ffmpegthumbnailer`, `poppler`, `resvg`, `imagemagick`, `sevenzip`, `gum`, `glow`, `atuin`, `starship`, `zsh-syntax-highlighting`, `topgrade`
`packages.darwin.cask`, installed with `brew install --cask`: `kitty`, `font-victor-mono-nerd-font`.
Compared with Arch, macOS has no `micro`, `diffnav`, `unzip`, or `wget`, and gets `topgrade` from Homebrew instead of the AUR. The role does not change the macOS list.
</Tab>
<Tab title="Shared">
`packages.shared.gh_extensions`, installed by the gh-extensions script on every OS:
| Extension | Purpose |
| --- | --- |
| `davidraviv/gh-clean-branches` | `gh clean-branches`: delete local branches whose upstream is gone |
| `prdlk/gh-commit` | `gh commit` |
| `dlvhdr/gh-dash` | `gh dash`: PR and issue dashboard |
| `meiji163/gh-notify` | `gh notify`: notifications in the terminal |
`packages.shared.go` is an empty list. `packages.shared.cargo` lists `suvadu`. No script in the repo reads either key; they document intent only, and cargo installs are kept current by topgrade's `[cargo]` step.
</Tab>
</Tabs>
:::note
AUR packages need `paru`. Without it the package script prints a warning listing the skipped AUR packages and continues.
:::
## aliases.yaml [#aliasesyaml]
The single source for aliases shared across shells. Each entry has a `section` and a list of `{ name, cmd }` items.
### Editors / file managers
| Alias | Command |
| --- | --- |
| `e` | `nvim` |
| `e.d` | `cd ~/.config/dotstate/storage/Rogz/.config && yazi` |
| `e.f` | `cd ~/.config/fish && yazi` |
| `e.k` | `yazi ~/.config/kitty` |
| `e.n` | `yazi ~/.config/niri` |
| `e.v` | `yazi ~/.config/nvim/lua` |
| `e.y` | `yazi ~/.config/yazi` |
| `e.t` | `nvim ~/.config/tmux/tmux.conf` |
| `hx` | `helix` |
### Quick directory jumps
| Alias | Command |
| --- | --- |
| `cdc` | `cd ~/.config && yazi` |
| `cdd` | `cd ~/Developer && yazi` |
| `cdk` | `cd ~/Documents/Knowledge && obsidian` |
| `cdl` | `cd ~/.local && yazi` |
| `cds` | `cd ~/.local/share/services && ls` |
| `cdw` | `cd ~/Downloads && yazi` |
### Tools
| Alias | Command |
| --- | --- |
| `dd` | `lazydocker` |
| `gg` | `lazygit` |
| `ff` | `exec fish` |
| `npx` | `bunx` |
| `sm` | `sudo micro` |
| `sd` | `ssh prad@<lan-host>` |
| `oc` | `opencode` |
| `dss` | `dotstate sync` |
| `fabric` | `fabric-ai` |
| `bk` | `bead-kanban` |
| `sua` | `shelly upgrade-all -n` |
| `lc` | `leetcode` |
| `tk` | `task` |
`dd` shadows coreutils `dd` in interactive shells.
## How aliases render
### bash and zsh
`dot_config/shell/aliases.sh.tmpl` renders to `~/.config/shell/aliases.sh`. Because it is a template it is written as a real file, not a symlink; edit the YAML and run `chezmoi apply` to regenerate it.
```sh dot_config/shell/aliases.sh.tmpl
{{- range .aliases }}
# {{ .section }}
{{- range .items }}
alias {{ .name }}='{{ .cmd }}'
{{- end }}
{{- end }}
```
After the generated block the file adds shell-specific pieces that are not in the YAML:
| Name | Definition |
| --- | --- |
| `cpy` / `pst` | `wl-copy` / `wl-paste` when `wl-copy` exists, else `pbcopy` / `pbpaste` when `pbcopy` exists |
| `q` | Function: if `$YAZI_ID` is set and `ya` exists, runs `ya emit quit` so the parent yazi also exits, then `exit` |
| `celar`, `claer` | Typo guards for `clear` |
| `ls` | `eza --icons`, when `eza` is installed |
`~/.bashrc` and `~/.zshrc` source it for interactive shells:
```sh dot_bashrc
[ -f "$HOME/.config/shell/aliases.sh" ] && . "$HOME/.config/shell/aliases.sh"
```
See [bash and zsh](/shell) for the rest of those files.
### fish
`dot_config/fish/conf.d/20-aliases.fish` is not a template. It is a hand-maintained plain file (symlinked into `~/.config/fish/conf.d/`) whose header says it is generated from the YAML; the YAML header likewise names a `20-aliases.fish.tmpl` that does not exist. The fish file has drifted from `aliases.yaml`:
| Alias | aliases.yaml (bash/zsh) | fish |
| --- | --- | --- |
| `e.d` | `cd ~/.config/dotstate/storage/Rogz/.config && yazi` | not defined |
| `e.f` | `cd ~/.config/fish && yazi` | `cd ~/.local/share/chezmoi/dot_config/fish && yazi` |
| `e.h` | not defined | `cd ~/.local/share/chezmoi/dot_config/hypr && yazi` |
| `e.k` | `yazi ~/.config/kitty` | `yazi ~/.local/share/chezmoi/dot_config/kitty` |
| `e.n` | `yazi ~/.config/niri` | `yazi ~/.local/share/chezmoi/dot_config/niri` |
| `e.y` | `yazi ~/.config/yazi` | `yazi ~/.local/share/chezmoi/dot_config/yazi` |
| `e.t` | `nvim ~/.config/tmux/tmux.conf` | `nvim ~/.local/share/chezmoi/dot_config/tmux/tmux.conf` |
| `cdd` | `cd ~/Developer && yazi` | not defined |
| `,,` | not defined | `cd ~/.local/share/chezmoi && yazi` |
| `..` | not defined | `cd ..` |
fish-only Bun aliases:
| Alias | Command |
| --- | --- |
| `br` | `bun run` |
| `br.d` | `bun run dev` |
| `br.b` | `bun run build` |
| `br.t` | `bun run test` |
| `bi` | `bun install` |
| `bg` | `bun install -g` (shadows fish's `bg` job-control builtin) |
| `bx` | `bunx` |
Every other YAML alias (`e`, `e.v`, `hx`, `cdc`, `cdk`, `cdl`, `cds`, `cdw`, and the whole Tools section) is defined identically in fish. The file ends with the same extras as the sh version: `cpy`/`pst` clipboard detection, the `q` function, and, in interactive sessions only, `celar`/`claer` and `ls` → `eza --icons`. `clear` itself is an autoloaded function (`functions/clear.fish`), which is why it is not aliased. See [fish](/shell/fish).
:::tip
To add an alias for every shell, add it to `aliases.yaml` for bash/zsh and to `20-aliases.fish` by hand for fish.
:::
docs/chezmoi/externals-and-ignore.mdx
+129
View File
@@ -0,0 +1,129 @@
---
title: Externals and ignore rules
description: The git repos chezmoi clones into $HOME and every rule in .chezmoiignore.tmpl, including the role gate for the Linux desktop layer.
---
## .chezmoiexternal.toml [#externals]
Externals are content chezmoi fetches instead of storing in the repo. Both entries are `git-repo` externals: chezmoi runs `git clone` when the target directory is missing. Because they are real git checkouts, they are never symlinked into the source tree.
```toml .chezmoiexternal.toml
[".config/nvim"]
type = "git-repo"
url = "https://github.com/prdlk/nvim.git"
[".config/nvim".pull]
args = ["--ff-only"]
[".config/bat/syntaxes/sublime-purescript-syntax"]
type = "git-repo"
url = "https://github.com/tellnobody1/sublime-purescript-syntax.git"
[".config/bat/syntaxes/sublime-purescript-syntax".pull]
args = ["--ff-only"]
```
| Target | Repo | Used by |
| --- | --- | --- |
| `~/.config/nvim` | [prdlk/nvim](https://github.com/prdlk/nvim) | Neovim config, kept in its own repo |
| `~/.config/bat/syntaxes/sublime-purescript-syntax` | [tellnobody1/sublime-purescript-syntax](https://github.com/tellnobody1/sublime-purescript-syntax) | PureScript syntax for bat, compiled into bat's cache by the [bat cache scripts](/chezmoi/scripts#build-bat-cache) |
### No refreshPeriod
Neither entry sets `refreshPeriod`, so it stays at chezmoi's default of never. chezmoi clones each repo on a fresh machine and otherwise leaves it alone: `chezmoi apply` and `chezmoi update` do not pull. The local nvim checkout always wins over the remote, so in-progress Neovim edits and unpushed commits are never disturbed by an apply.
To update explicitly, run `chezmoi apply --refresh-externals` (`-R`), which pulls with `git pull --ff-only`. `--ff-only` makes the pull fail instead of creating a merge commit when the local checkout has diverged.
## .chezmoiignore.tmpl [#chezmoiignore]
Patterns match target paths (relative to `$HOME`). Matching entries are neither written nor removed. The file is a template, so the desktop block appears only on machines where it applies. Source entries that start with `.` (`.github/`, `.claude/`, `.crush/`, `.gitignore`) are ignored by chezmoi without needing a rule.
### Repo docs
```txt
MIGRATION-NOTES.md
README.md
CLAUDE.md
AGENTS.md
docs
.blume
node_modules
blume.config.ts
package.json
bun.lock
public
dist
```
Files at the source root that would otherwise land in `$HOME` as `~/README.md`, `~/docs`, `~/package.json`, and so on. This covers the repo README and agent instruction files, plus this Blume docs site and its build output.
### Runtime and plugin state inside managed trees
| Pattern | Why |
| --- | --- |
| `.config/lazygit/.omc/**` | Tool state written inside the lazygit config dir |
| `.config/yazi/plugins/**` | Installed by `ya pkg install` from `package.toml` ([script](/chezmoi/scripts#install-yazi-plugins)) |
| `.config/tmux/plugins/**` | tpm and the plugins it installs ([40-post](/chezmoi/scripts#40-post)) |
| `.config/fish/fish_variables` | fish universal variables, rewritten by fish at runtime |
| `.config/nvim/lazy-lock.json` | lazy.nvim lockfile inside the nvim external |
| `.config/nvim/.git`, `.config/nvim/.git/**` | The external's git metadata |
| `.config/nvim/.omc/**`, `.config/nvim/.crush/**`, `.config/nvim/.understand-anything/**` | Agent tool state inside the nvim checkout |
`.gitignore` covers the source side of the same problem: `dot_config/lazygit/dot_omc`, `dot_config/tmux/plugins`, and `__pycache__/` never get committed even though symlink mode lets tools write into the source tree.
### mise
```txt
.config/mise
.config/mise/**
```
mise tool versions stay local to each machine and are not managed.
### Linux desktop layer (role-gated)
```txt .chezmoiignore.tmpl
{{ if or (ne .chezmoi.os "linux") (and (ne .role "desktop") (ne .role "laptop")) }}
.config/niri
.config/niri/**
.config/noctalia
.config/noctalia/**
.config/niri-dynamic-workspaces
.config/niri-dynamic-workspaces/**
.config/fontconfig
.config/fontconfig/**
.config/mimeapps.list
.config/systemd
.config/systemd/**
.local/bin/niri-launch
.config/fish/auto-Niri.fish
.local/bin/cp-appid
.config/tmux/niri-title.sh
{{ end }}
```
The block is emitted, and these paths skipped, unless the OS is `linux` and the role is `desktop` or `laptop`. `mac` and `server` machines, and any non-Linux machine regardless of role, never receive the niri compositor config (`dot_config/niri/`), fontconfig (`dot_config/fontconfig/fonts.conf`), default-app associations (`dot_config/mimeapps.list`), the fish auto-start hook (`dot_config/fish/auto-Niri.fish`), the tmux window-title helper, or the `niri-launch` and `cp-appid` scripts. The `noctalia`, `niri-dynamic-workspaces`, and `systemd` rules match nothing in the current source tree; they only take effect if those configs are added later.
| Machine | Desktop layer |
| --- | --- |
| Linux, `desktop` or `laptop` | Applied |
| Linux, `server` or `mac` | Ignored |
| macOS or other OS, any role | Ignored |
See [Desktop](/desktop/niri) for what the layer contains. Gaps in the gate: the block lists `niri-launch` but not its siblings (`niri-launch-ai`, `niri-launch-browser`, `niri-launch-terminal`, `niri-launch-webapp`), and the Hyprland and waybar configs (`dot_config/hypr/`, `dot_config/waybar/`) are not gated at all, so those apply on every role. `dot_config/niri/scripts/` is covered by `.config/niri/**`.
### Secrets in runtime state
```txt
.config/noctalia/plugins
.config/noctalia/plugins/**
```
noctalia writes plugin state containing embedded tokens here. These paths are ignored on every machine so tokens are never pulled into the repo.
### Python byte-cache
```txt
.config/kitty/__pycache__
.config/kitty/__pycache__/**
```
kitty imports `tab_bar.py` and the other Python helpers in `~/.config/kitty`, and Python writes `__pycache__` next to them. In symlink mode that directory would otherwise appear in the source tree.
docs/chezmoi/index.mdx
+151
View File
@@ -0,0 +1,151 @@
---
title: How it works
description: Source layout, naming conventions, symlink mode, and the day-to-day chezmoi workflow for this repo.
sidebar:
label: Overview
icon: settings
---
The repo is a [chezmoi](https://chezmoi.io) source directory. It lives at `~/.local/share/chezmoi` and its remote is [prdlk/dotfiles](https://github.com/prdlk/dotfiles). `chezmoi apply` renders it into `$HOME`. The [Installation](/installation) page covers first-time setup.
## Pages in this section
| Page | Covers |
| --- | --- |
| [Config and roles](/chezmoi/config) | `.chezmoi.toml.tmpl`: prompts, machine role, symlink mode, age encryption, template data |
| [Packages and aliases](/chezmoi/data) | `.chezmoidata/packages.yaml` and `.chezmoidata/aliases.yaml`, and how they render |
| [Apply scripts](/chezmoi/scripts) | Every `run_*` script: when it runs, what triggers it, what it does per OS and role |
| [Externals and ignore rules](/chezmoi/externals-and-ignore) | `.chezmoiexternal.toml` git clones and every `.chezmoiignore.tmpl` rule |
## Source layout
<FileTree>
- .chezmoi.toml.tmpl
- .chezmoidata/
- aliases.yaml
- packages.yaml
- .chezmoiexternal.toml
- .chezmoiignore.tmpl
- .chezmoiscripts/
- run_onchange_before_10-packages.sh.tmpl
- run_onchange_after_20-gh-extensions.sh.tmpl
- run_once_after_30-user-services.sh.tmpl
- run_onchange_after_40-post.sh.tmpl
- run_onchange_after_build-bat-cache.sh.tmpl
- run_onchange_after_install-yazi-plugins.sh.tmpl
- dot_bashrc
- dot_zshrc
- dot_gitconfig.tmpl
- dot_config/
- atuin/
- bash/
- bat/
- fish/
- fontconfig/
- gh/
- gh-dash/
- ghostty/
- herdr/
- herdr-nvim/
- hunk/
- hypr/
- kitty/
- lazydocker/
- lazygit/
- mimeapps.list
- niri/
- shell/
- starship.toml
- tmux/
- topgrade.toml
- waybar/
- yazi/
- zsh/
- dot_local/
- bin/
- dot_claude/
- commands/
- hooks/
- skills/
- settings.json
- empty_CLAUDE.md
- dot_agents/
- skills/
- dot_skill-lock.json
- dot_omp/
- loops/
- private_agent/
- dot_leetcode/
- docs/
- public/
- blume.config.ts
- package.json
- bun.lock
- README.md
</FileTree>
| Path | Target | Purpose |
| --- | --- | --- |
| `.chezmoi.toml.tmpl` | `~/.config/chezmoi/chezmoi.toml` | Config template rendered by `chezmoi init`. See [Config and roles](/chezmoi/config). |
| `.chezmoidata/` | — | YAML merged into template data (`.packages`, `.aliases`). See [Packages and aliases](/chezmoi/data). |
| `.chezmoiexternal.toml` | — | Git repos cloned into `$HOME` (nvim config, a bat syntax). |
| `.chezmoiignore.tmpl` | — | Target paths chezmoi skips; gates the Linux desktop layer by role. |
| `.chezmoiscripts/`, root `run_*` | — | Install and housekeeping scripts. See [Apply scripts](/chezmoi/scripts). |
| `dot_config/` | `~/.config/` | Per-tool config. Documented under [Shell](/shell), [Terminal](/terminal), [Tools](/tools), [Desktop](/desktop). |
| `dot_local/bin/` | `~/.local/bin/` | 33 standalone scripts shared by every shell. |
| `dot_claude/` | `~/.claude/` | Claude Code settings, commands, hooks, and skill symlinks. See [AI agents](/ai/claude-code). |
| `dot_agents/` | `~/.agents/` | The shared agent skill library the `~/.claude/skills` symlinks resolve against. |
| `dot_omp/` | `~/.omp/` | omp agent config and loops. |
| `dot_leetcode/` | `~/.leetcode/` | leetcode CLI workspace state. |
| `docs/`, `public/`, `blume.config.ts`, `package.json`, `bun.lock`, `README.md` | — | This docs site and the repo README. Listed in `.chezmoiignore.tmpl`, never applied. |
Entries whose source name starts with `.` (`.github/`, `.claude/`, `.crush/`, `.gitignore`) are ignored by chezmoi automatically and stay repo-only. `.github/workflows/docs.yml` builds this site.
## Naming conventions
chezmoi encodes target names and attributes in source file names. These are the prefixes and suffixes the repo uses:
| Source form | Meaning | Examples here |
| --- | --- | --- |
| `dot_` | Target name starts with `.` | `dot_config` → `~/.config`, `dot_zshrc` → `~/.zshrc`, `dot_skill-lock.json` → `.skill-lock.json` |
| `private_` | Target has group/world permissions cleared (`0600`/`0700`) | `dot_config/atuin/private_config.toml`, `dot_config/gh/private_config.yml`, `dot_config/hunk/private_state.json`, `dot_omp/private_agent/`, `dot_omp/loops/*/private_loop.md` |
| `executable_` | Target gets the executable bit | 49 files: every script in `dot_local/bin/`, `dot_config/niri/scripts/`, `dot_config/tmux/executable_niri-title.sh`, Claude hooks, skill helper scripts |
| `exact_` | Directory is exact: entries in the target that are not in the source are deleted | `dot_config/niri/exact_config.d/` (numbered `10-…kdl` through `95-…kdl` fragments) |
| `empty_` | File is kept even when empty | `dot_claude/empty_CLAUDE.md`, `dot_config/herdr/empty_dot_plugins.lock` |
| `symlink_` | Target is a symlink; file content is the link destination | 67 entries in `dot_claude/skills/` (each → `../../.agents/skills/<name>`), `dot_config/kitty/symlink_current-theme.conf` (→ `themes/noctalia.conf`) |
| `.tmpl` | Rendered with Go templates and chezmoi data | `dot_gitconfig.tmpl`, `dot_config/shell/aliases.sh.tmpl`, `dot_config/yazi/yazi.toml.tmpl`, all scripts, the config and ignore files |
| `run_once_` / `run_onchange_` + `before_` / `after_` | Script, with run frequency and phase | See [Apply scripts](/chezmoi/scripts) |
Prefixes stack in chezmoi's fixed order, e.g. `private_dot_foo`, `executable_dot_bar`. No source file currently uses `encrypted_`, even though age encryption is configured.
## Symlink mode
`.chezmoi.toml.tmpl` sets `mode = "symlink"`. `chezmoi apply` then makes each managed dotfile a symlink into the source tree instead of a copy, as long as the file is a plain regular file. Files that are templates, `private_`, `executable_`, or encrypted are still written as real files.
What that means in practice:
- Editing a plain file in `$HOME` (for example `~/.config/kitty/kitty.conf`) edits `~/.local/share/chezmoi/dot_config/kitty/kitty.conf` directly. The change is live and shows up in `git status` of the repo with no `chezmoi add` step.
- Templates are rendered copies. Editing `~/.gitconfig` or `~/.config/shell/aliases.sh` changes only the copy; the next `chezmoi apply` overwrites it. Edit the `.tmpl` source (`chezmoi edit ~/.gitconfig`) instead.
- `private_` and `executable_` targets are real files too. After editing one in place, run `chezmoi re-add <path>` to copy it back into the source.
- Tools that rewrite their own config write through the symlink into the repo. The runtime state that would otherwise pollute the source (plugin dirs, lock files, `fish_variables`, `__pycache__`) is excluded in `.chezmoiignore.tmpl` and `.gitignore`; see [Externals and ignore rules](/chezmoi/externals-and-ignore).
:::note
Several fish aliases (`e.f`, `e.h`, `e.k`, `e.n`, `e.y`, `e.t`, `,,`) open the chezmoi source paths directly. Symlink mode makes that equivalent to editing the live config.
:::
## Daily workflow
| Command | What it does here |
| --- | --- |
| `chezmoi apply` | Runs `before_` scripts (package install), writes symlinks/files/templates into `$HOME`, clones missing externals, then runs `after_` scripts. |
| `chezmoi update` | `git pull` in the source directory, then `apply`. |
| `chezmoi diff` | Shows what `apply` would change, including rendered templates and scripts that would run. |
| `chezmoi add <path>` | Moves a new file into the source tree under the right name. In symlink mode the target becomes a symlink on the next apply. Use `--template` or `--encrypt` for templated or secret files. |
| `chezmoi re-add <path>` | Copies edits made to non-symlinked targets (private, executable) back into the source. |
| `chezmoi edit <path>` | Opens the source file for a target, the right way to change templates. |
| `chezmoi cd` | Opens a shell in `~/.local/share/chezmoi` for git work. The fish alias `,,` opens yazi there instead. |
| `chezmoi init --prompt` | Re-asks name, email, and role and regenerates `~/.config/chezmoi/chezmoi.toml`. |
Commit and push from the source directory with plain git; the remote pushes over SSH (`git@github.com:prdlk/dotfiles.git`).
docs/chezmoi/meta.ts
+7
View File
@@ -0,0 +1,7 @@
import { defineMeta } from "blume";
export default defineMeta({
title: "How it works",
icon: "settings",
pages: ["index", "config", "data", "scripts", "externals-and-ignore"],
});
docs/chezmoi/scripts.mdx
+105
View File
@@ -0,0 +1,105 @@
---
title: Apply scripts
description: Every run_ script chezmoi executes during apply, when each one fires, and what it does on each OS and role.
---
Six scripts run during `chezmoi apply`. Four live in `.chezmoiscripts/`, a directory whose scripts run as if they sat at the source root without creating a matching target directory. Two sit at the repo root. All six are templates and all use `#!/bin/sh` with `set -eu`.
## Execution order
`before_` scripts run before any file is written; `after_` scripts run after every file, symlink, and external is in place. Within a phase chezmoi runs scripts in ASCII order of their target names, so the numeric prefixes come first.
<Steps>
<Step title="10-packages (before, onchange)">Install system packages from `packages.yaml`.</Step>
<Step title="Files, symlinks, externals">chezmoi writes the target state.</Step>
<Step title="20-gh-extensions (after, onchange)">Install gh extensions.</Step>
<Step title="30-user-services (after, once)">Enable systemd user units on Linux.</Step>
<Step title="40-post (after, onchange)">tpm clone, bat cache, font cache.</Step>
<Step title="build-bat-cache (after, onchange)">Rebuild bat cache when its theme or config changes.</Step>
<Step title="install-yazi-plugins (after, onchange)">Reinstall yazi plugins when the manifest changes.</Step>
</Steps>
| Script | Phase | Frequency | Re-run trigger |
| --- | --- | --- | --- |
| `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` | before | onchange | sha256 of `.chezmoidata/packages.yaml`; also the role and OS, which change the rendered package list |
| `.chezmoiscripts/run_onchange_after_20-gh-extensions.sh.tmpl` | after | onchange | sha256 of `packages.shared.gh_extensions` as JSON |
| `.chezmoiscripts/run_once_after_30-user-services.sh.tmpl` | after | once | Runs once per distinct rendered content |
| `.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` | after | onchange | Only edits to the script itself (or an OS change) |
| `run_onchange_after_build-bat-cache.sh.tmpl` | after | onchange | sha256 of `dot_config/bat/themes/cyberdream.tmTheme` and `dot_config/bat/config` |
| `run_onchange_after_install-yazi-plugins.sh.tmpl` | after | onchange | sha256 of `dot_config/yazi/package.toml` |
`run_onchange_` scripts re-run whenever their rendered content differs from the last successful run. The hash triggers work by writing a checksum of another file into a comment, so editing that file changes the script's content:
```sh
# packages.yaml hash: {{ include ".chezmoidata/packages.yaml" | sha256sum }}
```
`run_once_` scripts run once per unique rendered content and again only if that content changes or the previous run failed.
## 10-packages [#10-packages]
`.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` installs everything in [`packages.yaml`](/chezmoi/data#packagesyaml). It runs before files are applied so the tools exist when configs land.
<Tabs>
<Tab title="Linux">
1. Uses `pacman` directly when running as root, otherwise `sudo pacman`.
2. `pacman -S --needed --noconfirm` with every entry in `packages.arch.pacman`.
3. For roles `desktop` and `laptop`, a second `pacman -S --needed --noconfirm` with `packages.arch.desktop.pacman`.
4. Builds the AUR list: `packages.arch.desktop.aur` plus `packages.arch.aur` for `desktop`/`laptop`, only `packages.arch.aur` for other roles.
5. If the list is non-empty and `paru` exists, runs `paru -S --needed --noconfirm` on it. Without `paru` it prints `warning: paru not found — skipping AUR packages: …` and continues.
</Tab>
<Tab title="macOS">
1. Exits with an error pointing at https://brew.sh if `brew` is missing.
2. `brew install` with every entry in `packages.darwin.brew`.
3. `brew install --cask` with every entry in `packages.darwin.cask`.
The role is not consulted on macOS.
</Tab>
</Tabs>
On any other OS the script renders to just the shebang and comments and does nothing.
## 20-gh-extensions [#20-gh-extensions]
`.chezmoiscripts/run_onchange_after_20-gh-extensions.sh.tmpl` installs each `packages.shared.gh_extensions` entry on every OS.
- Exits 0 with `warning: gh not installed — skipping extensions` if `gh` is missing.
- Exits 0 with `warning: gh not authenticated — run 'gh auth login', then 'chezmoi apply' again` if `gh auth status` fails.
- Reads `gh extension list`, then runs `gh extension install <repo>` only for extensions not already present.
:::warning
A skipped run still exits 0, so chezmoi records this content as done and a plain re-apply does not retry it, despite what the warning text says. After `gh auth login`, either run `gh extension install` for each entry by hand, or clear chezmoi's onchange state with `chezmoi state delete-bucket --bucket=entryState` and apply again (this re-runs every `run_onchange_` script).
:::
## 30-user-services [#30-user-services]
`.chezmoiscripts/run_once_after_30-user-services.sh.tmpl` enables session-critical systemd user units on Linux.
- If `~/.config/systemd/user/nirinit.service` exists and `systemctl` is available, runs `systemctl --user daemon-reload` and `systemctl --user enable nirinit.service`. Failures are ignored.
- On non-Linux systems it renders to `#!/bin/sh` / `exit 0`.
Other personal automation units (brain-lens, omp-loop, rclone, hermes, voxtype) are deliberately not enabled; the script comment says to enable them by hand per machine. The repo does not currently contain a `dot_config/systemd/` directory, so the unit file has to exist on the machine already for this script to do anything.
## 40-post [#40-post]
`.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` is post-apply housekeeping. It has no hash comment, so it only re-runs when the script itself is edited.
| Step | Condition | Action |
| --- | --- | --- |
| tmux plugin manager | `tmux` installed and `~/.config/tmux/plugins/tpm` missing | `git clone --depth=1 https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm` |
| bat cache | `bat` installed | `bat cache --build` |
| Font cache | Linux, `fc-cache` installed | `fc-cache -f` |
Each step ignores failures (`|| true`). `tmux.conf` expects tpm at that path; see [tmux](/terminal/tmux).
## build-bat-cache [#build-bat-cache]
`run_onchange_after_build-bat-cache.sh.tmpl` rebuilds bat's syntax and theme cache when the managed inputs change. It hashes `dot_config/bat/themes/cyberdream.tmTheme` and `dot_config/bat/config`, exits quietly if `bat` is missing, and otherwise runs `bat cache --build`. This registers the cyberdream theme and the PureScript syntax cloned by [`.chezmoiexternal.toml`](/chezmoi/externals-and-ignore#externals).
## install-yazi-plugins [#install-yazi-plugins]
`run_onchange_after_install-yazi-plugins.sh.tmpl` reinstalls yazi plugins whenever `dot_config/yazi/package.toml` changes. It exits quietly if `ya` is missing or `${XDG_CONFIG_HOME:-$HOME/.config}/yazi/package.toml` does not exist, and otherwise runs `ya pkg install`. The installed plugins land in `~/.config/yazi/plugins/`, which `.chezmoiignore.tmpl` excludes. The plugin list is on the [yazi page](/tools/yazi).
docs/desktop/fonts-and-apps.mdx
+101
View File
@@ -0,0 +1,101 @@
---
title: Fonts and default apps
description: Fontconfig monospace override to Victor Mono Nerd Font, the Nerd Font packages, and the XDG default-application table.
---
Two small files set system-wide defaults: `fonts.conf` picks the monospace font, and `mimeapps.list` picks which application opens each file type and URL scheme.
:::note
Linux `desktop` and `laptop` roles only. `.chezmoiignore.tmpl` skips `~/.config/fontconfig/**` and `~/.config/mimeapps.list` on other roles.
:::
## Fontconfig
| Source (repo) | Target |
| --- | --- |
| `dot_config/fontconfig/fonts.conf` | `~/.config/fontconfig/fonts.conf` |
```xml ~/.config/fontconfig/fonts.conf
<fontconfig>
<match target="pattern">
<test name="family" qual="any">
<string>monospace</string>
</test>
<edit name="family" mode="prepend_first" binding="strong">
<string>VictorMono Nerd Font</string>
</edit>
</match>
</fontconfig>
```
Any font request that includes the generic `monospace` family gets `VictorMono Nerd Font` added to the front of its family list (`prepend_first`) with strong binding. Apps that ask for "monospace" therefore render in Victor Mono with Nerd Font glyphs, and fall back through fontconfig's normal monospace list if a glyph is missing. The file does not configure sans/serif families, hinting, antialiasing, or subpixel rendering. Those stay at system defaults.
Some tools set their own fonts. Waybar uses `CaskaydiaCove Nerd Font Propo` (see [Waybar](/desktop/waybar)), and the terminals set fonts in their own configs (see [kitty](/terminal/kitty)).
### Font packages
Victor Mono Nerd Font is installed on every role by `run_onchange_before_10-packages.sh.tmpl` from `.chezmoidata/packages.yaml`, not only on desktop roles:
| Platform | Package | Source |
| --- | --- | --- |
| Arch Linux | `ttf-victor-mono-nerd` | pacman (`packages.arch.pacman`) |
| macOS | `font-victor-mono-nerd-font` | Homebrew cask (`packages.darwin.cask`) |
`fonts.conf` is Linux desktop only, but the font package is also installed on `server` and `mac`.
## Default applications
| Source (repo) | Target |
| --- | --- |
| `dot_config/mimeapps.list` | `~/.config/mimeapps.list` |
`mimeapps.list` is the XDG file that `xdg-open`, GTK/Qt file dialogs, and browsers use to choose a handler. `[Default Applications]` sets the preferred handler. `[Added Associations]` adds entries to "Open with" lists.
### Default applications
| Group | MIME types / schemes | Handler (`.desktop`) |
| --- | --- | --- |
| Text and scripts | `text/plain`, `text/x-shellscript`, `text/x-python`, `text/x-script.python` | `vim.desktop` |
| Web pages | `text/html`, `application/xhtml+xml`, `application/x-extension-htm`, `-html`, `-shtml`, `-xhtml`, `-xht` | `brave-origin-nightly.desktop` |
| Web links | `x-scheme-handler/http`, `https`, `chrome` | `brave-origin-nightly.desktop` |
| Browser internals | `x-scheme-handler/about`, `unknown` | `chromium.desktop` |
| PDF | `application/pdf` | `com.brave.Origin.nightly.desktop` |
| Directories | `inode/directory` | `com.thisisgm.flea.desktop` (flea) |
| Mail | `x-scheme-handler/mailto` | `omamail.desktop` |
| Windows executables | `application/vnd.microsoft.portable-executable` | `wine.desktop` |
| AI tools | `x-scheme-handler/claude` | `com.anthropic.Claude.desktop` |
| | `x-scheme-handler/claude-cli` | `claude-code-url-handler.desktop` |
| | `x-scheme-handler/opencode` | `ai.opencode.desktop.desktop` |
| | `x-scheme-handler/antigravity` | `antigravity.desktop` |
| | `x-scheme-handler/piebald` | `piebald-handler.desktop` |
| | `x-scheme-handler/openhuman` | `OpenHuman-handler.desktop` |
| Productivity | `x-scheme-handler/todoist`, `com.todoist` | `todoist.desktop` |
| | `x-scheme-handler/notion` | `notion.desktop` |
| | `x-scheme-handler/anytype` | `anytype.desktop` |
| | `x-scheme-handler/tolaria` | `tolaria-handler.desktop` |
| | `x-scheme-handler/tldraw-offline` | `tldraw-offline.desktop` |
| | `x-scheme-handler/figma` | `figma-linux.desktop` |
| Chat | `x-scheme-handler/slack` | `slack.desktop` |
| | `x-scheme-handler/discord-647066573147996160` | `discord-647066573147996161.desktop` |
| Feeds | `x-scheme-handler/follow`, `folo` | `folo.desktop` |
### Added associations
| MIME types / schemes | Also offered |
| --- | --- |
| `http`, `https`, `chrome` schemes; `text/html`, `application/xhtml+xml`, and the `x-extension-*` web types | `brave-origin-nightly.desktop`, `userapp-Floorp-8MTFP3.desktop` |
| `x-scheme-handler/mailto` | `userapp-Evolution-PCEYQ4.desktop` |
| `application/vnd.microsoft.portable-executable` | `wine.desktop` |
| `application/pdf` | `com.brave.Origin.nightly.desktop` |
| `x-scheme-handler/opencode` | `ai.opencode.desktop.desktop` |
The added mail association is Evolution, but the default mail handler is `omamail.desktop`.
:::tip
In symlink mode, `~/.config/mimeapps.list` is a symlink into the repo. When `xdg-mime default` or a "set as default" dialog updates it, the tool either writes through the symlink and edits the repo file directly, or replaces the symlink with a regular file. Check `git status` or `chezmoi status` after changing defaults.
:::
## Related
- [niri](/desktop/niri) and [Hyprland](/desktop/hyprland): the compositors these defaults serve.
- [Installation](/installation): role selection that decides whether this layer applies.
docs/desktop/hyprland.mdx
+356
View File
@@ -0,0 +1,356 @@
---
title: Hyprland
description: Hyprland Lua config layered on Omarchy — bindings ported from niri, master layout, terminal-only blur, monitors, and the omarchy-* helper scripts.
---
[Hyprland](https://hypr.land) is a dynamic tiling Wayland compositor. This config uses Hyprland's Lua configuration and sits on top of [Omarchy](https://omarchy.org), which provides the defaults, theme, menus, and `omarchy-*` commands. The files here only override. Most bindings are ported from the [niri config](/desktop/niri) so the same keys do the same jobs.
:::note
`~/.config/hypr` and the `omarchy-*` scripts are **not** listed in `.chezmoiignore.tmpl`. chezmoi applies them on every role and OS, including `mac` and `server`. They only take effect where Hyprland and Omarchy are installed.
:::
## Files
| Source (repo) | Target | Purpose |
| --- | --- | --- |
| `dot_config/hypr/hyprland.lua` | `~/.config/hypr/hyprland.lua` | Entry point, workspace and window rules |
| `dot_config/hypr/autostart.lua` | `~/.config/hypr/autostart.lua` | Extra autostart (empty) |
| `dot_config/hypr/bindings.lua` | `~/.config/hypr/bindings.lua` | Keybindings |
| `dot_config/hypr/input.lua` | `~/.config/hypr/input.lua` | Key repeat, tablet/touch mapping |
| `dot_config/hypr/looknfeel.lua` | `~/.config/hypr/looknfeel.lua` | Layout, decoration, blur |
| `dot_config/hypr/monitors.lua` | `~/.config/hypr/monitors.lua` | Monitor modes and positions |
| `dot_config/hypr/hyprsunset.conf` | `~/.config/hypr/hyprsunset.conf` | Night-light profile |
| `dot_config/hypr/xdph.conf` | `~/.config/hypr/xdph.conf` | xdg-desktop-portal-hyprland |
| `dot_config/hypr/dot_luarc.json` | `~/.config/hypr/.luarc.json` | Lua language server settings |
| `dot_local/bin/executable_omarchy-*` | `~/.local/bin/omarchy-*` | Helper scripts (see [below](#omarchy-scripts)) |
None are templates. Hyprland and Omarchy are not in `.chezmoidata/packages.yaml`. They come from the Omarchy install.
## Entry point
`hyprland.lua` loads Omarchy, then the personal files, then Omarchy's toggles:
```lua ~/.config/hypr/hyprland.lua
dofile((os.getenv("OMARCHY_PATH") or "/usr/share/omarchy") .. "/default/hypr/bootstrap.lua")
require("default.hypr.omarchy")
require("hypr.monitors")
require("hypr.input")
require("hypr.bindings")
require("hypr.looknfeel")
require("hypr.autostart")
require("default.hypr.toggles")
```
Omarchy's default bindings stay enabled. `omarchy_default_bindings` and `omarchy_preinstalled_bindings` are left commented. `bindings.lua` unbinds each default it replaces.
### Workspace rules
| Workspace | Monitor |
| --- | --- |
| 3 | `desc:Apple Computer Inc StudioDisplay 0x984262A7` (EDID match, survives connector changes) |
| 4 | `eDP-1` |
| 5 | `eDP-1` |
### Window rules
| Class | Rule |
| --- | --- |
| `^brave-www\.tldraw\.com__-Default$` | Workspace 3 |
| `^tldraw-offline$` | Workspace 5, fullscreen |
| `^com\.anthropic\.Claude$`, `^kitty-herdr$` | `special:scratchpad silent` |
| `^com\.fastmail\.Fastmail$` | `special:fastmail silent` |
| `^Beeper$` | `special:beeper silent` |
| `brave-(www\.)?youtube\.com__.*`, title not matching `.*Picture.?in.?[Pp]icture.*` | Float, pin, size 30% × 30% of the monitor, move to `10, monitor_h*0.7-10` (bottom-left corner) |
Scratch residents are placed `silent` so that [`omarchy-toggle-scratch`](#omarchy-toggle-scratch) decides when to reveal them. The YouTube rule matches both `youtube.com` and `www.youtube.com` because Chromium's class changes once a video plays. It excludes the picture-in-picture overlay so Omarchy's own PiP rule still applies. Its size and inset must stay in sync with [`omarchy-pip`](#omarchy-pip).
## Input
`input.lua`:
- `repeat_delay = 250` (Omarchy's value), `repeat_rate = 50` (raised from 40). The file's comments record that 200/50 felt too fast. The typing lag it was meant to fix came from the keyboard's firmware tap-hold handling and was fixed on the keyboard itself.
- Tablet and touch devices are pinned to one output each:
| Device | Output | Extra |
| --- | --- | --- |
| `elan9008:00-04f3:43c7-stylus` (Flow Z13 pen) | `eDP-1` | |
| `elan9008:00-04f3:43c7` (Flow Z13 touchscreen) | `eDP-1` | Taps land on the panel instead of the focused monitor |
| `wacom-intuos-bt-s-pen` | `desc:Apple Computer Inc StudioDisplay 0x984262A7` | `active_area_size = { 152, 85.5 }`, `active_area_position = { 0, 0 }` — a 16:9 band cropped from the 16:10 tablet |
The layout, touchpad, and gesture examples in the file are commented out. Palm rejection is done by a libinput quirks file in `/etc`, which chezmoi does not manage.
## Look and feel
`looknfeel.lua` loads after the Omarchy theme's `hyprland.lua`, so its values override the theme's. The theme sets colors. This file sets everything else. The approach is flat windows by default, with blur only behind terminals.
| Setting | Value |
| --- | --- |
| `general.layout` | `master` (instead of Omarchy's dwindle; per-workspace layouts saved by `omarchy-hyprland-workspace-layout-toggle` still win) |
| `decoration.rounding` | 0 |
| `decoration.blur` | enabled; `size 5`, `passes 2`, `brightness 0.8`, `contrast 1.1`, `vibrancy 0.15`, `noise 0.01`, `new_optimizations`, `popups = false` |
| `decoration.shadow` | disabled |
| `group.groupbar.gradient_rounding` | 0 |
| Workspace animation | disabled (`hl.animation({ leaf = "workspaces", enabled = false })`) |
Blur must be enabled globally before any window can use it, so every window tagged `default-opacity` gets `no_blur = true`, and terminals get it back:
```lua ~/.config/hypr/looknfeel.lua
o.window({ tag = "default-opacity" }, { no_blur = true })
o.window(
"^(kitty(-.*)?|Alacritty|com\\.mitchellh\\.ghostty|foot|org\\.codeberg\\.dnkl\\.foot|wezterm)$",
{ no_blur = false }
)
```
Omarchy's stock fade (0.985 active / 0.96 inactive) is kept. Terminals get their transparency from kitty's `background_opacity 0.9` (see [kitty](/terminal/kitty)). The comments give the reason for limiting blur: the cyberdream and Spectra themes enabled rounding, blur, and shadow on every window, and that costs frame time on an iGPU driving the laptop panel plus a 5K display.
## Monitors
`monitors.lua`:
| Output | Mode | Position | Scale |
| --- | --- | --- | --- |
| any (fallback) | `preferred` | `auto` | 2 |
| `DP-4` (Apple Studio Display) | `5120x2880@60` | `0x0` | 2 |
| `eDP-1` (laptop) | `2560x1600@180` | `2560x0` | 2 |
`GDK_SCALE=2` is exported. The Studio Display sits left of the laptop panel. At scale 2 its logical width is 2560, so `eDP-1` starts at x = 2560.
## hyprsunset and portal
```ini ~/.config/hypr/hyprsunset.conf
profile {
time = 07:00
identity = true
}
```
The identity profile stops hyprsunset from tinting the screen. A commented 20:00 / 4000 K night profile and an `o.launch_on_start("hyprsunset")` hint remain in the file.
```ini ~/.config/hypr/xdph.conf
screencopy {
allow_token_by_default = true
custom_picker_binary = hyprland-preview-share-picker
}
```
Screen-share requests get a restore token by default and use `hyprland-preview-share-picker` as the source picker.
## .luarc.json
Configures lua-language-server for the Lua config: the library path is `/usr/share/hypr/stubs`, `checkThirdParty` is off, and `hl` and `o` are declared as globals.
`autostart.lua` contains only a commented `o.launch_on_start` example.
## Keybindings
Every binding defined in `bindings.lua`. Bindings not listed here are Omarchy defaults. The *Replaces* column gives the Omarchy default that was unbound first.
### Windows
| Keys | Action | Replaces |
| --- | --- | --- |
| `SUPER + Q` | Close window | same (made explicit) |
| `SUPER + W` | `omarchy-toggle-layout` — flip workspace layout | close window |
| `SUPER + BACKSPACE` | Focus last window | toggle transparency |
| `SUPER + TAB` | Next window in the active workspace | next workspace |
| `SUPER + SHIFT + TAB` | Previous window in the active workspace | previous workspace |
| `SUPER + H` / `J` / `K` / `L` | Focus left / down / up / right | `J`: toggle split, `K`: keybindings menu, `L`: toggle layout |
| `SUPER + D` | Toggle split (dwindle `togglesplit`) | — |
| `SUPER + SHIFT + H` | `omarchy-smart-move l` — move/merge left; floating: bottom-left corner | — |
| `SUPER + SHIFT + J` | `omarchy-smart-move d` — move/merge down; floating: top-left | — |
| `SUPER + SHIFT + K` | `omarchy-smart-move u` — move/merge up; floating: top-right | — |
| `SUPER + SHIFT + L` | `omarchy-smart-move r` — move/merge right; floating: bottom-right | — |
| `SUPER + SHIFT + T` | `omarchy-pip` — toggle picture-in-picture | — |
`SUPER + TAB` walks a ring built only from the active workspace's mapped windows, ordered by `stable_id`. Grouped windows stay in the ring and hidden ones are skipped. It raises the focused window afterwards. It avoids `cyclenext`, which would pull in a hidden scratchpad. `binds.movefocus_cycles_groupfirst = true` makes `hjkl` focus step through a group's tabs before leaving the group.
### Workspaces and monitors
| Keys | Action | Replaces |
| --- | --- | --- |
| `SUPER + CTRL + J` | Next workspace (`e+1`) | — |
| `SUPER + CTRL + K` | Previous workspace (`e-1`) | Herdr keybindings |
| `ALT + Q` / `W` / `E` / `R` / `T` | Switch to workspace 1 / 2 / 3 / 4 / 5 | — |
| `ALT + SHIFT + Q` / `W` / `E` / `R` / `T` | Move window to workspace 1 / 2 / 3 / 4 / 5 | — |
| `SUPER + CTRL + S` | `omarchy-toggle-scratch scratchpad` | share menu |
| `SUPER + A` | `omarchy-toggle-scratch scratchpad` | — |
| `SUPER + O` | Focus next monitor | pop window out |
| `SUPER + SHIFT + O` | Move window to next monitor | Obsidian |
| `SUPER + CTRL + SHIFT + J` | Move window to next monitor | — |
| `SUPER + CTRL + SHIFT + K` | Move window to previous monitor | — |
| `SUPER + SHIFT + CTRL + ALT + W` | Workspace `name:w` | — |
| `SUPER + SHIFT + CTRL + ALT + H` | Workspace `name:h` | — |
| `SUPER + CTRL + ALT + X` | Workspace `name:x` | — |
Named workspaces replace niri-dynamic-workspaces. `SUPER + ALT + S` (send to scratchpad) keeps its Omarchy default.
### Sizing
| Keys | Action |
| --- | --- |
| `SUPER + R` | `omarchy-cycle-window-size` — next preset size |
| `SUPER + SHIFT + R` | `omarchy-cycle-window-size prev` |
| `ALT + H` | Width −100 px |
| `ALT + L` | Width +100 px |
| `ALT + K` | Height −100 px |
| `ALT + J` | Height +100 px |
| `SUPER + ALT + C` | Fit active column (scrolling layout only) |
| `SUPER + SHIFT + ALT + C` | Fit visible columns (scrolling layout only) |
### Applications
| Keys | Action | Replaces |
| --- | --- | --- |
| `SUPER + CTRL + A` | Claude: `omarchy-launch-or-focus claude "gtk-launch com.anthropic.Claude"` | audio panel |
| `SUPER + CTRL + G` | Gemini: `omarchy-launch-or-focus gemini "gtk-launch gemini-desktop"` | — |
| `SUPER + CTRL + ALT + H` | `omarchy-cycle ai` | — |
| `SUPER + CTRL + ALT + J` | `omarchy-cycle-terminal` | — |
| `SUPER + CTRL + ALT + K` | `omarchy-cycle-browser` | — |
| `SUPER + CTRL + ALT + G` | `omarchy-cycle ghostty` | — |
| `SUPER + CTRL + ALT + O` | `omarchy-cycle obsidian` | — |
| `SUPER + CTRL + ALT + F` | Nautilus: `omarchy-launch-or-focus nautilus "gtk-launch org.gnome.Nautilus"` | — |
| `SUPER + CTRL + ALT + E` | `omarchy-toggle-scratch fastmail` | — |
| `SUPER + CTRL + ALT + M` | `omarchy-toggle-scratch beeper` | — |
| `SUPER + CTRL + ALT + Y` | `omarchy-summon youtube` | web apps cycle |
| `SUPER + SHIFT + Y` | `omarchy-summon youtube` | YouTube desktop entry |
| `SUPER + CTRL + ALT + T` | tldraw offline: `omarchy-launch-or-focus tldraw-offline "gtk-launch tldraw-offline"` | show time |
| `SUPER + CTRL + ALT + W` | tldraw: `omarchy-launch-or-focus tldraw "gtk-launch TLDraw"` | toggle weather |
| `SUPER + CTRL + ALT + SPACE` | Sticky Notes Canvas via `gtk-launch io.github.faridjaff.StickyNotesCanvas` | — |
| `SUPER + SHIFT + G` | Goliath: `kitty --class=kitty-goliath --title=goliath --config ~/.config/kitty/goliath.conf` | Signal |
| `SUPER + SHIFT + F` | `flea --gui` | unbound first (default unnamed) |
| `SUPER + ALT + SHIFT + F` | `flea --gui "$(omarchy-cmd-terminal-cwd)"` — file manager in the terminal's cwd | unbound first (default unnamed) |
The two `flea` bindings and a rule tagging `com.thisisgm.flea.picker` as `+floating-window` sit between `flea --default` / `flea --picker` marker comments. The `flea` tool writes and removes those blocks itself.
### Screenshots, session, menus
| Keys | Action | Replaces |
| --- | --- | --- |
| `SUPER + S` | `omarchy-capture-screenshot region` | toggle scratchpad |
| `SUPER + SHIFT + S` | `omarchy-capture-screenshot windows` | Google Maps |
| `SUPER + SHIFT + ALT + S` | `omarchy-capture-screenshot fullscreen` | — |
| `SUPER + SHIFT + E` | `omarchy-menu toggle system` | Email |
| `SUPER + SHIFT + Q` | `omarchy-menu toggle system` | — |
| `SUPER + F24` | `voxtype record toggle --profile hermes` — dictation | — |
| `SUPER + SHIFT + SPACE` | Emoji picker (`omarchy-shell shell toggle omarchy.emojis`) | toggle top bar |
| `SUPER + P` | Clipboard manager (`omarchy-shell shell toggle omarchy.clipboard`) | pseudo window |
| `ALT + TAB` | ScrollOverview `toggle all` (only when the plugin is loaded) | Omarchy's two `ALT + TAB` binds |
`SUPER + SPACE` (Omarchy menu), `SUPER + ALT + SPACE` (apps menu), and `SUPER + SHIFT + RETURN` (browser) keep their Omarchy defaults.
### ScrollOverview plugin
When `hl.plugin.scrolloverview` is present, `bindings.lua` configures it:
| Option | Value |
| --- | --- |
| `gesture_distance` | 300 |
| `scale` | 0.5 |
| `workspace_gap` | 100 |
| `layout` | `vertical` |
| `wallpaper` | 2 (global and per-workspace) |
| `blur` | true |
| `shadow` | enabled, range 50 |
## omarchy scripts
The scripts live in `dot_local/bin/` as `executable_omarchy-*` and deploy to `~/.local/bin/`. Each one calls the Lua dispatcher first (`hyprctl dispatch "hl.dsp…"`) and falls back to the classic dispatcher name on older Hyprland.
### omarchy-cycle
```sh
omarchy-cycle <app|browser|brave|terminal|ai|ghostty|kitty|kitty-CLASS|webapp|webapp-NAME>
```
Focuses an app's window, cycles to the next one on repeated presses, or launches the app when none is open. Windows are matched on `class` or `initialClass` (case-insensitive) and sorted by workspace, then address. If the focused window is not in the set, focus goes to the first one. Launches use `setsid uwsm-app --`.
| Argument | Matches | Launches when none |
| --- | --- | --- |
| `webapp` | `^(webapp-\|chrome-)` | re-runs as `webapp-youtube` |
| `webapp-NAME` | `webapp-NAME` or `^chrome-.*NAME` | `gtk-launch` on the first `WebApp-NAME*.desktop` or `*NAME*.desktop` in `~/.local/share/applications` |
| `kitty` | `^kitty` | `kitty` |
| `kitty-CLASS` | `^kitty-CLASS$` | `kitty --class kitty-CLASS` (command from the empty `KITTY_CMDS` map, if set) |
| `ghostty` | `ghostty` | `ghostty` |
| `browser` | zen, brave, chromium, google-chrome, firefox, librewolf, vivaldi, microsoft-edge, helium — excluding `chrome-`/`webapp-` web apps | `omarchy-launch-browser` |
| `brave` | `^brave` (Brave Origin Nightly and its web apps) | `brave-origin-nightly` |
| `terminal` | kitty, alacritty, ghostty, foot, wezterm — excluding `^kitty-herdr$` (the scratchpad terminal) | `omarchy-launch-terminal` |
| `ai` | `claude\|hermes` | `hermes desktop` |
| anything else | `^APP$` | the argument as a command |
Bound to `SUPER + CTRL + ALT + H` (`ai`), `G` (`ghostty`), and `O` (`obsidian`).
### omarchy-cycle-browser / omarchy-cycle-terminal
One-line wrappers: `omarchy-cycle brave` and `omarchy-cycle terminal`. Bound to `SUPER + CTRL + ALT + K` and `SUPER + CTRL + ALT + J`.
### omarchy-cycle-window-size
```sh
omarchy-cycle-window-size [next|prev]
```
Steps the focused window through preset widths `0.333, 0.5, 0.667` of the monitor.
- **Scrolling layout (tiled):** sends `colresize +conf` / `-conf`, so the layout's own preset list is used.
- **Floating:** resizes to the fraction × monitor width and 0.8 × monitor height, then centers. The index is stored per window.
- **Dwindle/master (tiled):** sets `splitratio` to `2 × fraction`, mirrored when the window is on the right or bottom half, clamped to 0.1–1.9. The index is stored per workspace.
Indices are stored in `$XDG_STATE_HOME/omarchy/window-sizes/`. Bound to `SUPER + R` and `SUPER + SHIFT + R`.
### omarchy-pip
```sh
omarchy-pip [toggle|on] [address:0x...]
```
Picture-in-picture for any window. Floats and pins it, resizes it to 30% of the focused monitor on both axes, and places it in the bottom-left corner with a 10 px inset (matching `general:gaps_out`). `toggle` (the default) unpins and re-tiles a window that is already floating and pinned. `on` always applies the fit. Defaults to the active window. The dispatcher is called with `on`/`off` because `set` toggles on Hyprland 0.56. Bound to `SUPER + SHIFT + T`. `omarchy-summon` also calls it.
### omarchy-smart-move
```sh
omarchy-smart-move <l|r|u|d>
```
- **Tiled:** finds the nearest tiled, visible window in that direction that overlaps on the other axis. If that neighbor, or the focused window, is in a group, it runs a group-aware move (`movewindoworgroup`), which merges into or leaves a group. Otherwise it swaps with the neighbor.
- **Floating:** moves the window to a corner of its monitor without resizing, inside the reserved area (the bar) and inset 10 px. Corners go clockwise from bottom-left: `l` bottom-left, `d` top-left, `u` top-right, `r` bottom-right.
Bound to `SUPER + SHIFT + H/J/K/L`.
### omarchy-summon
```sh
omarchy-summon [youtube]
```
The only profile is `youtube`, which matches class `^brave-(www\.)?youtube\.com__.*$` and skips Picture-in-Picture titles. With no window open, it runs `gtk-launch YouTube`, and the window rule in `hyprland.lua` floats and positions it. With a window open, it moves the window to the focused monitor, runs `omarchy-pip on` to refit it (the two panels differ in logical size), and focuses it. Bound to `SUPER + CTRL + ALT + Y` and `SUPER + SHIFT + Y`.
### omarchy-toggle-layout
```sh
omarchy-toggle-layout [width]
```
Runs `omarchy-hyprland-workspace-layout-toggle`, then polls the workspace layout (6 × 50 ms). If it became `scrolling`, it runs `colresize all <width>` (default `0.75`). Dwindle needs no widths. Bound to `SUPER + W`.
### omarchy-toggle-scratch
```sh
omarchy-toggle-scratch [scratchpad|fastmail|beeper]
```
| Profile | Special workspace | Home monitor | Residents (class → launch) |
| --- | --- | --- | --- |
| `scratchpad` | `special:scratchpad` | Apple Studio Display | `com.anthropic.Claude` → `claude-desktop`; `kitty-herdr` → `kitty --class=kitty-herdr --config ~/.config/kitty/herdr.conf` |
| `fastmail` | `special:fastmail` | focused | `com.fastmail.Fastmail` → `gtk-launch fastmail` |
| `beeper` | `special:beeper` | focused | `Beeper` → `gtk-launch beeper` |
If the workspace is visible, the script hides it. If not, it launches any resident with no window there, waits up to 8 s for the first new window, and reveals the workspace on the home monitor (or the focused one if the home monitor is absent). Launching only missing residents avoids duplicate web-app windows. Bound to `SUPER + CTRL + S`, `SUPER + A`, `SUPER + CTRL + ALT + E`, and `SUPER + CTRL + ALT + M`.
## Related
- [niri](/desktop/niri): the original config these bindings mirror.
- [Waybar](/desktop/waybar): the bar used with this setup.
- [kitty](/terminal/kitty): the `herdr` and `goliath` kitty configs launched here.
docs/desktop/index.mdx
+32
View File
@@ -0,0 +1,32 @@
---
title: Desktop
description: The Linux desktop layer — niri and Hyprland compositors, the Waybar bar, fontconfig, and default applications.
sidebar:
label: Overview
---
:::note[Role gating]
`.chezmoiignore.tmpl` skips the niri layer unless the machine runs Linux **and** its role is `desktop` or `laptop`. The gated targets are `~/.config/niri`, `~/.config/noctalia`, `~/.config/niri-dynamic-workspaces`, `~/.config/fontconfig`, `~/.config/mimeapps.list`, `~/.config/systemd`, `~/.local/bin/niri-launch`, `~/.local/bin/cp-appid`, `~/.config/fish/auto-Niri.fish`, and `~/.config/tmux/niri-title.sh`. On `mac` and `server` roles these are not applied.
`~/.config/hypr`, `~/.config/waybar`, the `omarchy-*` scripts, and the `niri-launch-ai` / `-browser` / `-terminal` / `-webapp` wrappers are **not** listed there, so chezmoi applies them on every role and OS. Only the exact path `.local/bin/niri-launch` is ignored, not the wrappers that call it.
:::
Two Wayland compositors are configured side by side. niri is the original setup, paired with the Noctalia shell. Hyprland runs on top of [Omarchy](https://omarchy.org), and its bindings are ported from the niri config: the same keys launch the same apps where both compositors support it. Waybar is the Hyprland bar. Noctalia replaces it under niri.
| Page | Covers |
| --- | --- |
| [niri](/desktop/niri) | `~/.config/niri` (base config, Noctalia colors, the `config.d/` fragments, per-display profiles), niri helper scripts, the `niri-launch*` launchers, `cp-appid`, the `nirinit` user service |
| [Hyprland](/desktop/hyprland) | `~/.config/hypr` Lua config on Omarchy: bindings, input, look and feel, monitors, hyprsunset, the portal; every `omarchy-*` script in `~/.local/bin` |
| [Waybar](/desktop/waybar) | `~/.config/waybar`: module layout, stylesheet, the `window_pill.py` title module |
| [Fonts and default apps](/desktop/fonts-and-apps) | `~/.config/fontconfig/fonts.conf`, `~/.config/mimeapps.list`, the Victor Mono Nerd Font packages |
## Packages
`.chezmoidata/packages.yaml` declares the desktop packages under `packages.arch.desktop`. `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` installs them only when the role is `desktop` or `laptop`:
| Source | Packages |
| --- | --- |
| pacman | `niri`, `xdg-user-dirs` |
| AUR (via `paru`) | `noctalia-shell` |
The script skips AUR packages with a warning if `paru` is not installed. Hyprland, Waybar, and the `omarchy-*` commands that the scripts call (`omarchy-menu`, `omarchy-launch-or-focus`, and others) come from an Omarchy install. This repo does not install them. See [chezmoi scripts](/chezmoi/scripts) for the full install flow.
docs/desktop/meta.ts
+7
View File
@@ -0,0 +1,7 @@
import { defineMeta } from "blume";
export default defineMeta({
title: "Desktop",
icon: "monitor",
pages: ["index", "niri", "hyprland", "waybar", "fonts-and-apps"],
});
docs/desktop/niri.mdx
+458
View File
@@ -0,0 +1,458 @@
---
title: niri
description: Scrollable-tiling Wayland compositor config — input, layout, window rules, per-display profiles, keybindings, and launcher scripts.
---
[niri](https://github.com/YaLTeR/niri) is a scrollable-tiling Wayland compositor. Here it runs with the Noctalia shell (bar, panels, OSD, notifications), vicinae as the launcher, and `niri-dynamic-workspaces` for named workspaces.
:::note
Linux `desktop` and `laptop` roles only. `.chezmoiignore.tmpl` skips `~/.config/niri/**`, `~/.local/bin/niri-launch`, and `~/.local/bin/cp-appid` on other roles. The `niri-launch-*` wrappers are not in the ignore list and are applied everywhere.
:::
## Files
| Source (repo) | Target |
| --- | --- |
| `dot_config/niri/config.kdl` | `~/.config/niri/config.kdl` |
| `dot_config/niri/noctalia.kdl` | `~/.config/niri/noctalia.kdl` |
| `dot_config/niri/exact_config.d/*.kdl` | `~/.config/niri/config.d/*.kdl` |
| `dot_config/niri/scripts/executable_*` | `~/.config/niri/scripts/*` (executable) |
| `dot_local/bin/executable_niri-launch`, `executable_niri-launch-{ai,browser,terminal,webapp}` | `~/.local/bin/niri-launch*` |
| `dot_local/bin/executable_cp-appid` | `~/.local/bin/cp-appid` |
`exact_config.d` is a chezmoi **exact** directory. On apply, chezmoi deletes any file in `~/.config/niri/config.d/` that the repo does not manage, so stale fragments cannot linger. None of these files are templates.
<FileTree>
- ~/.config/niri/
- config.kdl
- noctalia.kdl
- config.d/
- 10-input-and-cursor.kdl
- 20-layout-and-overview.kdl
- 30-window-rules.kdl
- 40-environment.kdl
- 50-startup.kdl
- 60-animations.kdl
- 70-binds.kdl
- 80-layer-rules.kdl
- 90-outputs.kdl
- 91-internal-display.kdl
- 92-ultrawide.kdl
- 93-apple-display.kdl
- 94-portable-hdmi.kdl
- 95-portable-usbc.kdl
- scripts/
- kill-phantom-display.fish
- ndw-route-workspace.sh
- niri-floating-sidebar.sh
- niri-focus.sh
- niri-move.sh
</FileTree>
## Installation
- `niri` and `xdg-user-dirs` from pacman, `noctalia-shell` from the AUR. Declared under `packages.arch.desktop` in `.chezmoidata/packages.yaml` and installed by `run_onchange_before_10-packages.sh.tmpl` for `desktop`/`laptop` roles. See [chezmoi scripts](/chezmoi/scripts).
- `.chezmoiscripts/run_once_after_30-user-services.sh.tmpl` runs once on Linux. If `~/.config/systemd/user/nirinit.service` exists, it runs `systemctl --user daemon-reload` and `systemctl --user enable nirinit.service`. The script's comment says other personal units (brain-lens, omp-loop, rclone, hermes, voxtype) ship as files only and are enabled by hand. The repo does not currently contain `dot_config/systemd`, so the unit must come from elsewhere for the enable step to run.
- Tools the config calls but does not install: `vicinae`, `cliphist`/`wl-paste`, `polkit-gnome`, `kbuildsycoca6`, `voxtype`, `niri-dynamic-workspaces`, `dot-screenshot`, `niri-smart-close`, `niri-smart-move`, and the `capitaine-cursors-light` cursor theme. `niri-smart-close`, `niri-smart-move`, and `dot-screenshot` are called by path or name but are not in this repo.
## Load order
`config.kdl` sets two top-level options and then includes the fragments in numeric order:
```kdl ~/.config/niri/config.kdl
hotkey-overlay {
skip-at-startup
}
screenshot-path "~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png"
include "config.d/10-input-and-cursor.kdl"
// … 20 through 90 …
include "config.d/90-outputs.kdl"
```
After the includes, `config.kdl` repeats inline `input`, `layout`, `gestures`, `cursor`, `overview`, `window-rule`, `animations`, and `environment` blocks, a leftover of the iNiR (illogical-impulse) base it started from. It then sets `debug { honor-xdg-activation-with-invalid-serial }`, which lets Noctalia v5 activate windows from notification actions. It includes `./noctalia.kdl` and ends with `prefer-no-csd`. niri merges repeated sections and later values win, so the inline blocks override the fragments where they differ. Those differences are listed in each section below.
## Input and cursor
`config.d/10-input-and-cursor.kdl`:
| Setting | Value |
| --- | --- |
| Keyboard layout | `us` |
| Repeat delay / rate | 400 ms / 50 Hz |
| Touchpad | `natural-scroll`, `tap`, `tap-button-map "left-right-middle"`, `accel-speed 1.0` |
| Tablet and touch | `map-to-output "eDP-1"` (pen and touchscreen stay on the laptop panel) |
| Mod key | `Super`; `Alt` when nested inside another compositor |
| Cursor | `capitaine-cursors-light`, size 24, `hide-when-typing` |
The inline `input` block in `config.kdl` repeats the same keyboard and touchpad values without `accel-speed` or the tablet/touch mappings, so those two settings from the fragment still apply.
## Layout and overview
`config.d/20-layout-and-overview.kdl`:
| Setting | Value |
| --- | --- |
| `center-focused-column` | `never` |
| `background-color` | `transparent` (the Noctalia wallpaper shows through as backdrop) |
| `default-column-width` | proportion 0.5 |
| `preset-column-widths` | 0.33333, 0.5, 0.66667 |
| Focus ring | width 1.5 |
| Border | `off` (width 1.5 if enabled) |
| Shadow | `off` (softness 30, spread 5, offset y=5 if enabled) |
| Tab indicator | `place-within-column`, `hide-when-single-tab`, position `left` |
| Overview | `zoom 0.4`, workspace shadow off |
The `gestures { hot-corners { } }` block is empty in the fragment. The inline block in `config.kdl` sets `hot-corners { off }`, so hot corners are disabled.
### Colors (Noctalia)
`noctalia.kdl` is included last, so its colors override the fragment's placeholder colors (`#7fc8ff` ring, `#ffc87f` border):
| Element | Active | Inactive | Urgent |
| --- | --- | --- | --- |
| Focus ring | `#a398b3` | `#1e1c21` | `#fd4663` |
| Border | `#a398b3` | `#1e1c21` | `#fd4663` |
| Tab indicator | `#a398b3` | `#4a4158` | `#fd4663` |
| Recent-windows highlight | `#a398b3` | — | `#fd4663` |
Shadow color is `#1e1c2170` and the insert hint is `#a398b380`. The palette follows the Noctalia shell's color scheme, not cyberdream.
## Window rules
`config.d/30-window-rules.kdl`:
| Match | Rule |
| --- | --- |
| All windows | `geometry-corner-radius 10`, `clip-to-geometry true`; background blur on, xray off |
| `dev.noctalia.Noctalia` (Noctalia v5 settings) | Floating, 1080 × 920 |
| `Folo`, `Spotify`, `zen`, `brave-origin-nightly`, `gemini-desktop`, `claude-desktop` | Opacity 0.9, tiled, blur, no border background, open focused |
| `kitty`, `zed`, `obsidian`, `Beeper`, `chromium`, `com.mitchellh.ghostty` | Opacity 0.9, tiled, blur, no border background, open focused |
| `org.gnome.Nautilus`, `com.gabm.satty` | Floating, focused, width proportion 0.5 |
| Title `Picture-in-Picture` (app `zen`) or `Picture in picture` | Floating, not focused, opacity 1.0, 24 px from the top-right corner, on `eDP-1` |
| `zed`, `obsidian`, `sticky-notest-canvas`, title `Sticky Notes`, `vacuumtube`, `Fladder`, `kitty`, `kitty-herdr`, `kitty-tmux` | Open on the Apple Studio Display |
Global blur settings: `passes 4`, `offset 5.0`, `noise 0.02`, `saturation 2.0`. The inline `window-rule` in `config.kdl` sets `geometry-corner-radius 8` after the fragment, so the effective radius is 8.
## Environment
`config.d/40-environment.kdl` (repeated verbatim inline in `config.kdl`):
| Variable | Value | Purpose |
| --- | --- | --- |
| `XDG_CURRENT_DESKTOP` | `niri` | |
| `XDG_MENU_PREFIX` | `plasma-` | Dolphin/KDE file associations |
| `QT_QPA_PLATFORM` | `wayland` | |
| `ELECTRON_OZONE_PLATFORM_HINT` | `auto` | Native Wayland for Electron |
| `QT_LOGGING_RULES` | `quickshell.dbus.properties=false` | Silence quickshell D-Bus logs |
| `QT_QPA_PLATFORMTHEME` | `kde` | Qt colors from `kdeglobals` (needs `plasma-integration`) |
| `QT_STYLE_OVERRIDE` | `Darkly` | Qt widget style |
| `INIR_VENV`, `ILLOGICAL_IMPULSE_VIRTUAL_ENV` | `$HOME/.local/state/quickshell/.venv` | Quickshell Python venv |
## Startup
`config.d/50-startup.kdl` spawns at login:
| Command | Purpose |
| --- | --- |
| `systemctl --user import-environment XDG_MENU_PREFIX && kbuildsycoca6` | Export the menu prefix to systemd, rebuild the KDE service cache |
| `/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1` | Polkit agent |
| `noctalia` | Shell: bar, panels, notifications, OSD, wallpaper |
| `niri-dynamic-workspaces daemon` | Named dynamic workspaces |
| `vicinae server` | Launcher backend |
| `wl-paste --watch cliphist store` | Clipboard history |
## Animations
`config.d/60-animations.kdl` makes every animation a critically damped spring (`damping-ratio=1.0`, `epsilon=0.0001`) with high stiffness: workspace-switch 4000, window-open 5000, window-close 6000, horizontal-view-movement 4500, window-movement 5000, window-resize 5500, config-notification-open-close 5000, screenshot-ui-open 5000.
The inline `animations` block in `config.kdl` comes later and overrides these with softer springs tuned to match quickshell's Material motion:
| Animation | Damping ratio | Stiffness |
| --- | --- | --- |
| workspace-switch | 0.78 | 1350 |
| window-open | 0.82 | 1125 |
| window-close | 0.88 | 2025 |
| horizontal-view-movement | 0.80 | 1238 |
| window-movement | 0.85 | 1463 |
| window-resize | 0.88 | 1575 |
| config-notification-open-close | 0.90 | 1800 |
| screenshot-ui-open | 0.85 | 1688 |
## Keybindings
All bindings from `config.d/70-binds.kdl`. `Mod` is `Super` (`Alt` when niri runs nested). `Super+…` and `Mod+…` are the same modifier. The table groups bindings by the file's comment headers.
### System and launcher
| Keys | Action |
| --- | --- |
| `Mod+Tab` | Toggle overview (no repeat) |
| `Mod+Shift+E` | Quit niri |
| `Mod+Escape` | Toggle keyboard-shortcuts inhibit (cannot itself be inhibited) |
| `Mod+Space` | `vicinae toggle` — launcher |
| `Mod+Shift+Space` | vicinae emoji search |
| `Mod+Shift+Return` | vicinae window switcher |
| `Super+Alt+Ctrl+Return` | vicinae window switcher |
| `Mod+BackSpace` | Focus previous window |
| `Mod+P` | vicinae clipboard history |
| `Mod+Ctrl+R` | Toggle the Noctalia `prdlk/ostt:recorder` plugin |
| `Mod+Period` | Noctalia control center panel |
| `Mod+Comma` | Noctalia settings |
| `Mod+Shift+Q` | Noctalia session menu (hotkey-overlay title "Session Menu: noctalia session") |
| `Mod+F24` | `voxtype record toggle --profile hermes` — dictation |
### Screenshots
| Keys | Action |
| --- | --- |
| `Mod+S` | `dot-screenshot region` |
| `Mod+Shift+S` | `dot-screenshot window` |
| `Mod+Ctrl+S` | `dot-screenshot monitor-focused` |
| `Mod+Ctrl+Shift+S` | `dot-screenshot monitor-all` |
| `Print` | niri screenshot UI |
| `Ctrl+Print` | Screenshot the screen |
| `Alt+Print` | Screenshot the window |
### Applications
| Keys | Action |
| --- | --- |
| `Mod+Shift+G` | Goliath: `kitty --class=kitty-goliath --title=goliath --config ~/.config/kitty/goliath.conf` (mosh + tmux; see [kitty](/terminal/kitty)) |
| `Super+Ctrl+A` | Claude desktop (via vicinae) |
| `Super+Ctrl+G` | Gemini desktop (via vicinae) |
| `Super+Alt+Ctrl+H` | `niri-launch-ai` — cycle Claude/Hermes windows |
| `Super+Alt+Ctrl+J` | `niri-launch-terminal` — cycle terminals |
| `Super+Alt+Ctrl+K` | `niri-launch-browser` — cycle Brave Origin Nightly |
| `Super+Alt+Ctrl+O` | `niri-launch obsidian` |
| `Super+Alt+Ctrl+Y` | `niri-launch-webapp` — cycle web apps |
| `Super+Alt+Ctrl+W` | tldraw offline (via vicinae) |
| `Super+Alt+Ctrl+E` | Fastmail (via vicinae) |
| `Super+Alt+Ctrl+B` | Beeper (via vicinae) |
| `Super+Alt+Ctrl+M` | Beeper (via vicinae) |
| `Super+Alt+Ctrl+G` | Ghostty (via vicinae) |
| `Super+Alt+Ctrl+L` | Linear web app (via vicinae) |
| `Super+Alt+Ctrl+T` | Todoist (via vicinae) |
| `Super+Alt+Ctrl+N` | Open the Noctalia `noctalia/notes` panel |
| `Super+Alt+Ctrl+F` | Nautilus (via vicinae) |
| `Super+Alt+Ctrl+Space` | Sticky Notes Canvas (via vicinae) |
### Dynamic workspaces
| Keys | Action |
| --- | --- |
| `Super+Shift+Alt+Ctrl+W` | `niri-dynamic-workspaces switch w` |
| `Super+Shift+Alt+Ctrl+H` | `niri-dynamic-workspaces switch h` |
| `Super+Alt+Ctrl+X` | `niri-dynamic-workspaces switch x` |
### Focus and movement
| Keys | Action |
| --- | --- |
| `Mod+H` | Focus column left (wraps to last) |
| `Mod+L` | Focus column right (wraps to first) |
| `Mod+J` | Focus window below, or workspace below |
| `Mod+K` | Focus window above, or workspace above |
| `Mod+Shift+H` | `niri-smart-move left` |
| `Mod+Shift+L` | `niri-smart-move right` |
| `Mod+Shift+J` | Move column to workspace below |
| `Mod+Shift+K` | Move column to workspace above |
| `Super+Ctrl+H` | Focus first column |
| `Super+Ctrl+L` | Focus last column |
| `Super+Ctrl+Shift+H` | Move column to first |
| `Super+Ctrl+Shift+L` | Move column to last |
| `Mod+Q` | `niri-smart-close` (no repeat) |
### Monitors
| Keys | Action |
| --- | --- |
| `Mod+Left` | Focus monitor left |
| `Mod+Up` | Focus monitor up |
| `Mod+Right` | Focus monitor right |
| `Mod+Shift+Down` | Move column to monitor right |
| `Mod+Shift+Up` | Move column to monitor left |
| `Super+O` | Focus next monitor |
| `Super+Ctrl+J` | Focus next monitor |
| `Super+Ctrl+K` | Focus previous monitor |
| `Super+Shift+O` | Move column to next monitor |
| `Mod+Ctrl+Shift+J` | Move column to next monitor |
| `Mod+Ctrl+Shift+K` | Move column to previous monitor |
### Layout and sizing
| Keys | Action |
| --- | --- |
| `Mod+R` | Cycle preset column widths |
| `Mod+Shift+R` | Cycle preset window heights |
| `Mod+F` | Expand column to available width |
| `Mod+Shift+F` | Maximize column |
| `Mod+Ctrl+F` | Fullscreen window |
| `Super+C` | Center column |
| `Mod+Ctrl+C` | Center visible columns |
| `Mod+Ctrl+O` | Toggle window floating |
| `Mod+W` | Toggle tabbed column display |
| `Alt+Shift+H` | Column width −10% |
| `Alt+Shift+L` | Column width +10% |
| `Alt+Shift+J` | Window height −10% |
| `Alt+Shift+K` | Window height +10% |
### Hardware keys
All of these work while the screen is locked (`allow-when-locked=true`) and go through Noctalia IPC, so the Noctalia OSD shows feedback. The commented `v4:` lines in the file are the old `qs -c noctalia-shell ipc call …` forms.
| Keys | Action |
| --- | --- |
| `XF86AudioRaiseVolume` | `noctalia msg volume-up` |
| `XF86AudioLowerVolume` | `noctalia msg volume-down` |
| `XF86AudioMute` | `noctalia msg volume-mute` |
| `XF86AudioMicMute` | `noctalia msg mic-mute` |
| `XF86AudioNext` | `noctalia msg media next` |
| `XF86AudioPrev` | `noctalia msg media previous` |
| `XF86AudioPlay` / `XF86AudioPause` | `noctalia msg media toggle` |
| `XF86MonBrightnessUp` | `noctalia msg brightness-up` |
| `XF86MonBrightnessDown` | `noctalia msg brightness-down` |
## Layer rules
`config.d/80-layer-rules.kdl`:
- Noctalia surfaces matching `^noctalia-(bar-…|notification|dock|panel|attached-panel|osd)$` get `background-effect { xray false }`, so their blur samples what is actually behind them. Noctalia publishes blur regions itself when `ext-background-effects` is available.
- `^noctalia-wallpaper` is placed within the backdrop (`place-within-backdrop true`). The wallpaper stays still while workspaces move and shows in the overview.
- `layout { background-color "transparent" }` and overview `workspace-shadow { off }` are restated here so the backdrop is always visible.
## Outputs and display profiles
`config.d/90-outputs.kdl` turns `DP-5` off and includes the per-display profiles. An older Apple Display block and a `DP-4 off` block remain as comments.
```kdl ~/.config/niri/config.d/90-outputs.kdl
include "91-internal-display.kdl"
// include "92-ultrawide.kdl"
include "93-apple-display.kdl"
include "94-portable-hdmi.kdl"
// include "95-portable-usbc.kdl"
```
The Apple Studio Display also exposes a phantom connector (DP-4/5/6, varies per boot) whose only mode is 640×480. A commented `spawn-at-startup` for `scripts/kill-phantom-display.fish` handles it by mode signature, since connector name and EDID both shift.
<Tabs>
<Tab title="Internal (91)">
`Tianma Microelectronics Ltd. TL134ADXP03 Unknown`, the laptop panel. **Active.**
| Setting | Value |
| --- | --- |
| Position / scale | `0,0` / 1.5 |
| VRR | `on-demand=true` |
| Gaps | 8 |
| Default column width | 1.0 |
| Preset widths | 0.5, 1.0 |
| Centering | `always-center-single-column`, `center-focused-column "never"` |
Named workspaces `1`, `2`, `3` open on this panel. Three window rules open these apps maximized and focused on workspace `1`, without border backgrounds (all three target `"1"` as written):
- `chrome-youtube.com__-Default`, `chromium`
- `org.gnome.Calendar`, `discord`, `slack`, `com-fastmail-fastmail`, `gemini-desktop`, `Beeper`, `com.anthropic.Claude`, `Hermes`, `todoist`
- `WebApp-CloudflarePersonal7594`, `WebApp-CloudflareWalletbase8881`
</Tab>
<Tab title="Ultrawide (92)">
`Samsung Electric Company S34CG50 HNTY501103`. **Included in the repo but commented out.**
| Setting | Value |
| --- | --- |
| Mode | `3440x1440@100.00` |
| Position / scale | `0,0` / 1 |
| VRR | `on-demand=true` |
| Gaps | 16 |
| Default column width | 0.3333 |
| Preset widths | 0.3333, 0.5, 0.6667 |
| Centering | `always-center-single-column`, `center-focused-column "never"` |
</Tab>
<Tab title="Apple Display (93)">
`Apple Computer Inc StudioDisplay 0x984262A7`. **Active.**
| Setting | Value |
| --- | --- |
| Scale | 1.75 |
| Gaps | 8 |
| Default column width | 0.5 |
| Preset widths | 0.25, 0.3333, 0.5, 0.6667 |
| Centering | `always-center-single-column`, `center-focused-column "never"` |
</Tab>
<Tab title="Portable HDMI (94)">
`PNP(AOP) 16PM1QB 14490001D3X00`. **Active.**
| Setting | Value |
| --- | --- |
| Transform | `90` (portrait) |
| Gaps | 2 |
| Default column width | 1.0 |
| Preset widths | 0.5, 1.0 |
| Centering | `always-center-single-column`, `center-focused-column "never"` |
</Tab>
<Tab title="Portable USB-C (95)">
`ASUSTek COMPUTER INC ASUS MB16AC M8LMTF195749`. **Included in the repo but commented out.**
| Setting | Value |
| --- | --- |
| Position | `0,0` |
| Gaps | 2 |
| Default column width | 1.0 |
| Preset widths | 0.5, 1.0 |
| Centering | `always-center-single-column`, `center-focused-column "never"` |
</Tab>
</Tabs>
To switch a profile, uncomment or comment its `include` line in `90-outputs.kdl`. niri reloads config on save.
## Scripts
Deployed to `~/.config/niri/scripts/`. `70-binds.kdl` binds none of them, so they run by hand or from other tools.
| Script | Usage | Behavior |
| --- | --- | --- |
| `kill-phantom-display.fish` | no args | Polls `niri msg -j outputs` up to 10 times, 1 s apart. Any output whose only mode is 640×480 gets `niri msg output <name> off`. Does not handle mid-session hotplug. |
| `ndw-route-workspace.sh` | `$NDW_WORKSPACE_KEY` or `$1` | niri-dynamic-workspaces `on_create` hook. Keys `y g m x z p l a` move the workspace to `HDMI-A-1`. Keys `b f s w c d o` move it to the Apple Studio Display (resolved by make/model through `niri msg --json outputs`), or to `HDMI-A-1` if that display is absent. Other keys exit silently. |
| `niri-floating-sidebar.sh` | `toggle` \| `hide` \| `flip` \| `reorder` \| `help` | Per-workspace floating sidebar on the right edge. Windows are 550 px wide and stack into 4 slots (more as needed) with 15 px gaps and 30/50/20 px top/bottom/side margins. `toggle` floats the focused window into the sidebar or restores it to tiling at its original size. `hide` slides the sidebar off-screen, leaving a 70 px sliver. `flip` switches bottom-up and top-down stacking. State is kept in `/tmp/niri.toggle.<workspace>.*`. |
| `niri-focus.sh` | `up` \| `down` | Cascading focus: next window in the column, then the next *occupied* workspace (skipping the trailing empty one), then the adjacent monitor. Wraps to the far-end monitor at the edge. |
| `niri-move.sh` | `up` \| `down` | Cascading move: reorder within the column, then move to the next workspace (including the empty trailing one), then the adjacent monitor. Wraps at the edge. |
## Launchers
### niri-launch
`~/.local/bin/niri-launch <app>` focuses an app's window, cycles through its windows on repeated presses (sorted by window id), or launches it when none is open.
| Argument | Windows matched (app-id) | Launched when none |
| --- | --- | --- |
| `webapp` | `^(webapp-\|chrome-)` (Firefox and Chromium/Brave site-specific apps) | Re-runs as `webapp-youtube` |
| `webapp-NAME` | `WebApp-Name` (case-insensitive) | `gtk-launch` on `~/.local/share/applications/WebApp-Name*.desktop` |
| `kitty` | any app-id starting with `kitty` | `kitty` |
| `kitty-CLASS` | exactly that class | `kitty --class kitty-CLASS` (optional command from the empty `KITTY_CMDS` map) |
| `ghostty` | `ghostty` | nothing, prints a message |
| `browser` | `^(zen\|brave\|chromium\|firefox)` | `zen` |
| `terminal` | `kitty\|alacritty\|ghostty` | `kitty` |
| `ai` | `claude\|hermes` | `hermes desktop` |
| anything else | exact app-id | the argument as a command |
### Wrappers
Each wrapper resolves its own symlink and execs `niri-launch` from the same directory:
| Script | Runs | Bound to |
| --- | --- | --- |
| `niri-launch-ai` | `niri-launch ai` | `Super+Alt+Ctrl+H` |
| `niri-launch-terminal` | `niri-launch terminal` | `Super+Alt+Ctrl+J` |
| `niri-launch-browser` | `niri-launch brave-origin-nightly` (exact app-id, not the `browser` mode) | `Super+Alt+Ctrl+K` |
| `niri-launch-webapp` | `niri-launch webapp` | `Super+Alt+Ctrl+Y` |
### cp-appid
`cp-appid` lists every `.desktop` file (via `fd`) in `/usr/share/applications`, `/usr/local/share/applications`, `~/.local/share/applications`, the system and user Flatpak export dirs, and `/var/lib/snapd/desktop/applications`. It shows each entry's `Name=` and ID in `fzf`, then copies the chosen ID to the clipboard with `wl-copy`. Use it to find app-ids for window rules and `niri-launch`.
## Related
- [Hyprland](/desktop/hyprland): the Omarchy setup with the same key layout.
- [kitty](/terminal/kitty): `kitty-goliath`, `kitty-herdr`, and `kitty-tmux` classes referenced by the rules.
docs/desktop/waybar-preview.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 366 KiB

docs/desktop/waybar.mdx
+143
View File
@@ -0,0 +1,143 @@
---
title: Waybar
description: Bottom Waybar for Hyprland/Omarchy — module layout, a drawer of system indicators, the window-title pill, and theme-driven styling.
---
[Waybar](https://github.com/Alexays/Waybar) is a status bar for wlroots-based and Hyprland compositors. This config replaces Omarchy's default bar with a bottom-docked layout. It uses Hyprland and Omarchy modules and commands, so it pairs with the [Hyprland](/desktop/hyprland) setup. Under [niri](/desktop/niri), Noctalia provides the bar.
:::note
`~/.config/waybar` is not listed in `.chezmoiignore.tmpl`, so chezmoi applies it on every role. Waybar itself comes from Omarchy and is not in `.chezmoidata/packages.yaml`.
:::
## Files
| Source (repo) | Target |
| --- | --- |
| `dot_config/waybar/config.jsonc` | `~/.config/waybar/config.jsonc` |
| `dot_config/waybar/style.css` | `~/.config/waybar/style.css` |
| `dot_config/waybar/window_pill.py` | `~/.config/waybar/window_pill.py` |
| `dot_config/waybar/V6.cb.png` | `~/.config/waybar/V6.cb.png` |
:::warning
`window_pill.py` has no `executable_` prefix, and the repo file is mode `0644`. In symlink mode, chezmoi links `~/.config/waybar/window_pill.py` to that non-executable file. The module's `exec` calls the path directly, so it only runs if the executable bit is set by hand (`chmod +x` on the source) or the file is renamed to `executable_window_pill.py`.
:::
`V6.cb.png` is a 1920×921 reference screenshot of this bar, taken with a floating btop window over a plain background. No config file references it.
![Waybar reference screenshot (V6.cb.png)](./waybar-preview.png)
## Bar settings
| Option | Value |
| --- | --- |
| `position` | `bottom` |
| `exclusive` | true (reserves space) |
| `fixed-center` | true |
| `spacing` | 2 |
| `margin-top` | 1 |
| `reload_style_on_change` | true |
## Layout
<Columns cols={3}>
<Column>
**Left**
- separator
- `custom/omarchy`
- separator
- `hyprland/workspaces`
- separator
- `tray`
- separator
- `custom/voxtype`
- `custom/update`
- `custom/screenrecording-indicator`
- `custom/updatespacman`
- separator
- `idle_inhibitor`
</Column>
<Column>
**Center**
- `custom/windowpill`
</Column>
<Column>
**Right**
- `group/right-group2` → `group/right2` → `group/tray-expander`
- `group/right-group1` → `group/right1` → `clock`
</Column>
</Columns>
The right side nests groups in vertical wrappers so the drawer and the two-line clock align. `group/tray-expander` is a drawer (600 ms transition, children class `tray-group-item`). It shows only `custom/expand-icon` until hovered, then reveals: `backlight`, `bluetooth`, `pulseaudio#output`, `pulseaudio#input`, `power-profiles-daemon`, `network`, `memory`, `cpu`, `battery`.
## Modules
| Module | Configuration |
| --- | --- |
| `custom/separator` (also `separator2`, `separator3`, defined but unused) | Literal `\|`, no tooltip |
| `custom/omarchy` | Omarchy logo glyph (`omarchy` font). Click: `omarchy-menu`. Right-click: `xdg-terminal-exec`. Tooltip "Omarchy Menu — Super + Alt + Space" |
| `hyprland/workspaces` | `format "{icon}"`, click to activate, pointer cursor. Persistent workspaces 1, 2, 3, 4, 5, 7, 8, 9 |
| `tray` | Icon size 12, spacing 5, shows passive items |
| `custom/voxtype` | `omarchy-voxtype-status` (JSON). Icons for `idle` (none), `recording`, `transcribing`. Click: `omarchy-voxtype-model`. Right-click: `omarchy-voxtype-config` |
| `custom/update` | `omarchy-update-available` every 6 h (`interval 21600`, `signal 7`). Click runs `omarchy-update` in a floating terminal |
| `custom/screenrecording-indicator` | `$OMARCHY_PATH/default/waybar/indicators/screen-recording.sh` (JSON, `signal 8`). Click: `omarchy-capture-screenrecording` |
| `custom/updatespacman` | `waybar-module-pacman-updates --no-zero-output`, only if that binary exists. Shows an icon when updates are pending |
| `idle_inhibitor` | Activated/deactivated icons |
| `custom/windowpill` | `~/.config/waybar/window_pill.py` (JSON, `restart-interval 1`), centered |
| `clock` | `{:%H:%M\n%d/%m/%Y}` (two lines); alt `{:%H:%M - %d/%m/%Y}`. Month calendar tooltip (3 columns; month `#ffead3`, weekdays `#ffcc66`, today `#ff6699`). Right-click: `omarchy-tz-select` in a floating terminal |
| `backlight` | Device `intel_backlight`, 15-step icon ramp, tooltip shows percent |
| `bluetooth` | Off/on/connected icons, tooltip shows connection count. Click: `omarchy-launch-bluetooth` |
| `pulseaudio#output` | Icon only (headphone or 3-step speaker, muted icon). Max 100%, scroll step 2. Click: `omarchy-launch-audio`. Right-click: `pamixer -t` (mute) |
| `pulseaudio#input` | Mic / muted-mic icon. Max 100%, scroll step 1 via `pactl set-source-volume`. Click: `omarchy-launch-audio`. Right-click: `pamixer -t` |
| `power-profiles-daemon` | Icons for performance / balanced / power-saver. Tooltip shows profile and driver |
| `network` | 5-step Wi-Fi signal icons; ethernet and disconnected icons. Tooltips show ESSID, frequency, and bandwidth. Polls every 3 s. Click: `omarchy-launch-wifi` |
| `memory` | `{used:0.1f}G` every 2 s. Click: `omarchy-launch-or-focus-tui btop` |
| `cpu` | `{usage}%` every 10 s. Click: btop |
| `battery` | `{capacity}% {icon}` with 10-step charging and discharging ramps. Warning at 20%, critical at 10%, polled every 5 s. Click: `omarchy-menu power`. Right-click: `notify-send` of `omarchy-battery-status` |
Icons are Nerd Font glyphs.
## window_pill.py
A Python script that feeds `custom/windowpill` a two-line label for the focused window:
- **Top line:** the window class, small, `#a6adc8`, lowered with `rise='-2000'`.
- **Bottom line:** the title, bold, size 11000, `#ffffff`, truncated to 80 characters (`MAX_TITLE_LEN`). For Discord/Vesktop it removes the unread counter prefix such as `(209) ` and a leading `Discord | `.
- **No focused window:** shows `Workspace <id>` over a non-breaking space.
Text is HTML-escaped for Pango and printed as JSON (`class: custom-window`, tooltip `class: title`). After the first print it connects to Hyprland's event socket `/tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock` and reprints on `activewindow>>` and `workspace>>` events. It exits if `HYPRLAND_INSTANCE_SIGNATURE` is unset, which means the module does nothing outside Hyprland.
## Styling
`style.css` imports the active Omarchy theme's palette, so colors follow whatever theme Omarchy has selected (for example cyberdream):
```css ~/.config/waybar/style.css
@import "/home/prad/.local/state/omarchy/current/theme/waybar.css";
```
The import path is hard-coded to `/home/prad`. On another account the import fails and the `@background` / `@foreground` colors are undefined.
| Element | Style |
| --- | --- |
| All | `font-family: 'CaskaydiaCove Nerd Font Propo'`, no borders or text shadow, square corners |
| Bar box (`#waybar > box`) | `@background` fill, `@foreground` text, 2px/6px margins, 4px radius, `box-shadow 0 1px 2px` black, weight 700, size 12px, min height 30px, 0.5 s background transition |
| Window background | `@transparent` |
| Workspace buttons | Opacity 0.55. Active 1.0. Empty 0.2. Empty and active 1.0. Bold 12px |
| Modules | 6px horizontal padding, 1px margins, min width 12px |
| Separators | Opacity 0.25 |
| `custom/updatespacman` | Opacity 0.55 |
| `custom/expand-icon` | Opacity 0.5 |
| `custom/update` | 10px font |
| Tray | `@background`. Passive items dimmed, attention items highlighted |
| Tooltips | `@background`, 12px, 8px radius, `1.5px solid rgba(255,255,255,0.25)` border |
| Screen recording active | `#eb7087`, blinks to `@background` every 0.5 s |
| Voxtype recording | `#a55555` |
| Battery warning | `#c95d0f` |
| Battery critical (not charging) | `#e6d8ba` on transparent, blinking to `#f53c3c` (0.5 s, 12 steps) |
## Related
- [Hyprland](/desktop/hyprland): the compositor this bar is built for.
- [Fonts and default apps](/desktop/fonts-and-apps): Nerd Font packages.
docs/index.mdx
+53
View File
@@ -0,0 +1,53 @@
---
title: dots
description: prdlk's dotfiles, managed with chezmoi. One command installs chezmoi and applies the whole setup.
sidebar:
label: Overview
icon: house
---
```sh
curl -fsSL https://dots.prd.lk/install | sh
```
That command installs chezmoi to `~/.local/bin`, clones [prdlk/dotfiles](https://github.com/prdlk/dotfiles), asks three questions (name, email, machine role), installs packages, and applies every config. See [Installation](/installation) for the options, prerequisites, and the private-repo auth step.
## What's managed
<CardGroup cols={2}>
<Card title="How it works" href="/chezmoi" icon="settings">
chezmoi layout, machine roles, symlink mode, age encryption, package manifests, apply scripts, and externals.
</Card>
<Card title="Shell" href="/shell" icon="terminal">
fish, bash, and zsh with shared aliases, starship, atuin, and the `~/.local/bin` scripts.
</Card>
<Card title="Terminal" href="/terminal" icon="square-terminal">
kitty, ghostty, tmux, and herdr.
</Card>
<Card title="Tools" href="/tools" icon="wrench">
git, gh and gh-dash, neovim, yazi, lazygit, lazydocker, bat, topgrade, hunk, and more.
</Card>
<Card title="Desktop" href="/desktop" icon="monitor">
niri with noctalia, Hyprland with the omarchy helpers, waybar, fonts, and default apps.
</Card>
<Card title="AI agents" href="/ai" icon="bot">
Claude Code, omp, and the shared agent skill library.
</Card>
</CardGroup>
## Machine roles
The first apply asks for a role. It controls which parts of the repo land on the machine.
| Role | Platform | Gets |
| --- | --- | --- |
| `desktop` | Arch Linux | Everything: universal toolset plus the Linux desktop layer |
| `laptop` | Arch Linux | Same as `desktop` |
| `mac` | macOS | Universal toolset via Homebrew; no Linux desktop layer |
| `server` | Any | Universal toolset only |
The default is `mac` on macOS and `desktop` everywhere else. See [Configuration](/chezmoi/config) and [Ignore rules](/chezmoi/externals-and-ignore).
## Theme
The shared palette is **cyberdream**. bat, atuin, and yazi select it. fish and omp ship a cyberdream theme but do not select it. kitty takes its colors from the active Omarchy theme. The noctalia, koda, and ii-auto variants are shipped for ghostty, kitty, and yazi. The font is **Victor Mono Nerd Font**.
docs/installation.mdx
+109
View File
@@ -0,0 +1,109 @@
---
title: Installation
description: Install chezmoi and apply these dotfiles with one command, or pass your own chezmoi arguments.
sidebar:
icon: download
---
## One-liner
```sh
curl -fsSL https://dots.prd.lk/install | sh
```
`/install` is chezmoi's official install script ([get.chezmoi.io/lb](https://get.chezmoi.io/lb)), vendored into this site's `public/` directory with three changes:
1. chezmoi installs to `$HOME/.local/bin`, whatever directory you run it from.
2. With no arguments, it runs `chezmoi init --apply prdlk/dotfiles` after installing.
3. When the script is piped into `sh`, chezmoi's stdin is reattached to `/dev/tty` so the first-run prompts still work.
The script checks the release tarball's SHA-256 before installing, as upstream does.
## Before you run it
<Steps>
<Step title="Package manager">
**Arch**: `sudo` for pacman. `paru` is needed for AUR packages (`topgrade`, and `noctalia-shell` on desktop roles); without it the package script prints a warning and skips them.
**macOS**: [Homebrew](https://brew.sh) is required; the package script exits with an error if `brew` is missing.
</Step>
<Step title="GitHub access">
`prdlk/dotfiles` is a private repository, so the clone needs credentials:
- **HTTPS** (default): git prompts for your GitHub username and a personal access token with `repo` scope.
- **SSH**: add the machine's key to GitHub first, then use the `--ssh` form below.
</Step>
<Step title="age key">
chezmoi is configured for age encryption with the identity at `~/.config/chezmoi/key.txt`. The key is never committed. Copy it from an existing machine before applying:
```sh
mkdir -p ~/.config/chezmoi
scp <existing-machine>:.config/chezmoi/key.txt ~/.config/chezmoi/key.txt
chmod 600 ~/.config/chezmoi/key.txt
```
</Step>
</Steps>
## Options
Arguments after `--` go to chezmoi and replace the default `init --apply prdlk/dotfiles`:
<CodeGroup>
```sh SSH
sh -c "$(curl -fsSL https://dots.prd.lk/install)" -- init --apply --ssh prdlk/dotfiles
```
```sh Dry-run
sh -c "$(curl -fsSL https://dots.prd.lk/install)" -- init prdlk/dotfiles
chezmoi diff
chezmoi apply
```
```sh chezmoi-only
sh -c "$(curl -fsSL https://dots.prd.lk/install)" -- --version
```
</CodeGroup>
| Flag / variable | Effect |
| --- | --- |
| `-b <dir>` | Install directory (default `$HOME/.local/bin`) |
| `-t <tag>` | chezmoi release tag (default `latest`) |
| `-d` | Debug logging |
| `BINDIR` | Same as `-b` |
| `DOTFILES_REPO` | Repo for the default `init --apply` (default `prdlk/dotfiles`) |
## First apply
<Steps>
<Step title="Prompts">
`.chezmoi.toml.tmpl` asks once for **name**, **email**, and **role** (`desktop`, `laptop`, `mac`, `server`). Answers are stored in `~/.config/chezmoi/chezmoi.toml` and not asked again. See [Configuration](/chezmoi/config).
</Step>
<Step title="Packages">
`run_onchange_before_10-packages` installs everything in `.chezmoidata/packages.yaml` with pacman/paru or Homebrew before any file is written. See [Scripts](/chezmoi/scripts).
</Step>
<Step title="Files and externals">
Configs are linked into `$HOME` (symlink mode). The neovim config and a bat syntax are cloned as externals. See [Externals and ignore rules](/chezmoi/externals-and-ignore).
</Step>
<Step title="Post-apply scripts">
gh extensions, tpm, the bat cache, the font cache, yazi plugins, and the niri user service on Linux.
</Step>
</Steps>
:::note
The gh extension script skips with a warning until `gh auth login` has run. A skipped run still exits 0, so a plain `chezmoi apply` does not retry it. See [Scripts](/chezmoi/scripts#20-gh-extensions) for how to re-run it.
:::
## Updating
```sh
chezmoi update # git pull + apply
chezmoi diff # what apply would change
```
## Refreshing the install script
`public/install` is a vendored copy. To pick up upstream changes, download `https://get.chezmoi.io/lb` again and re-apply the three changes listed in the header comment of `public/install`.
## Publishing this site
The site is a [Blume](https://github.com/haydenbleasel/blume) project (`docs/`, `public/`, `blume.config.ts`). `.github/workflows/docs.yml` builds it with `bun run build` and deploys `dist/` to GitHub Pages on every push to `master` that touches the site. Pages uses **GitHub Actions** as its source, and `dots.prd.lk` is the custom domain set in the repository's Pages settings. That domain needs a DNS `CNAME` record pointing to `prdlk.github.io`. None of these files are applied to `$HOME`; `.chezmoiignore.tmpl` excludes them.
docs/meta.ts
+14
View File
@@ -0,0 +1,14 @@
import { defineMeta } from "blume";
export default defineMeta({
pages: [
"index",
"installation",
"chezmoi",
"shell",
"terminal",
"tools",
"desktop",
"ai",
],
});
docs/shell/aliases.mdx
+121
View File
@@ -0,0 +1,121 @@
---
title: Aliases
description: Every alias and alias-like helper across fish, bash, and zsh, and where each one is defined.
---
## Single source
`.chezmoidata/aliases.yaml` holds the shell-agnostic aliases as a list of sections, each with `name`/`cmd` items. chezmoi loads the file as template data ([chezmoi data](/chezmoi/data)), and `dot_config/shell/aliases.sh.tmpl` ranges over it to produce `~/.config/shell/aliases.sh`, which `~/.bashrc` and `~/.zshrc` source:
```yaml .chezmoidata/aliases.yaml
aliases:
- section: "Editors / file managers"
items:
- { name: "e", cmd: "nvim" }
# …
```
```text ~/.config/shell/aliases.sh
# Editors / file managers
alias e='nvim'
```
To add an alias for bash and zsh, add it to the YAML and run `chezmoi apply`.
:::note
The YAML and template comments say fish renders the same data through `fish/conf.d/20-aliases.fish.tmpl`. That template no longer exists. `dot_config/fish/conf.d/20-aliases.fish` is a plain, hand-maintained fish file, so a YAML change does not reach fish. The fish column below shows where the two sets differ.
:::
## Shared aliases
A ✓ means the alias exists in that shell with the command shown. Where fish uses a different command, the fish command is shown instead.
### Editors / file managers
| Alias | bash / zsh (YAML) | fish (`20-aliases.fish`) |
| --- | --- | --- |
| `e` | `nvim` | ✓ |
| `e.d` | `cd ~/.config/dotstate/storage/Rogz/.config && yazi` | not defined |
| `e.f` | `cd ~/.config/fish && yazi` | `cd ~/.local/share/chezmoi/dot_config/fish && yazi` |
| `e.h` | not defined | `cd ~/.local/share/chezmoi/dot_config/hypr && yazi` |
| `e.k` | `yazi ~/.config/kitty` | `yazi ~/.local/share/chezmoi/dot_config/kitty` |
| `e.n` | `yazi ~/.config/niri` | `yazi ~/.local/share/chezmoi/dot_config/niri` |
| `e.v` | `yazi ~/.config/nvim/lua` | ✓ |
| `e.y` | `yazi ~/.config/yazi` | `yazi ~/.local/share/chezmoi/dot_config/yazi` |
| `e.t` | `nvim ~/.config/tmux/tmux.conf` | `nvim ~/.local/share/chezmoi/dot_config/tmux/tmux.conf` |
| `hx` | `helix` | ✓ (listed under Tools in fish) |
The fish editor aliases open the chezmoi source tree directly. In symlink mode, `~/.config/<tool>` files are symlinks into that tree, so both versions edit the same files.
### Quick directory jumps
| Alias | bash / zsh (YAML) | fish |
| --- | --- | --- |
| `cdc` | `cd ~/.config && yazi` | ✓ |
| `cdd` | `cd ~/Developer && yazi` | not defined |
| `cdk` | `cd ~/Documents/Knowledge && obsidian` | ✓ |
| `cdl` | `cd ~/.local && yazi` | ✓ |
| `cds` | `cd ~/.local/share/services && ls` | ✓ |
| `cdw` | `cd ~/Downloads && yazi` | ✓ |
| `,,` | not defined | `cd ~/.local/share/chezmoi && yazi` |
### Tools
| Alias | Command | fish |
| --- | --- | --- |
| `dd` | `lazydocker` | ✓ |
| `gg` | `lazygit` | ✓ |
| `ff` | `exec fish` | ✓ |
| `npx` | `bunx` | ✓ |
| `sm` | `sudo micro` | ✓ |
| `sd` | `ssh prad@<lan-host>` (a machine on the local network) | ✓ |
| `oc` | `opencode` | ✓ |
| `dss` | `dotstate sync` | ✓ |
| `fabric` | `fabric-ai` | ✓ |
| `bk` | `bead-kanban` | ✓ |
| `sua` | `shelly upgrade-all -n` | ✓ |
| `lc` | `leetcode` | ✓ |
| `tk` | `task` | ✓ |
| `..` | not defined | `cd ..` |
`dd` shadows coreutils `dd` in interactive shells. Use `command dd` for the real one.
## fish-only aliases
### Bun
| Alias | Command |
| --- | --- |
| `br` | `bun run` |
| `br.d` | `bun run dev` |
| `br.b` | `bun run build` |
| `br.t` | `bun run test` |
| `bi` | `bun install` |
| `bg` | `bun install -g` |
| `bx` | `bunx` |
`bg` replaces fish's job-control builtin. Use `builtin bg` to resume a background job.
## Shell-specific extras
All three shells define these outside the YAML: in `20-aliases.fish` for fish, and in the tail of `aliases.sh.tmpl` for bash and zsh.
| Name | Kind | Definition |
| --- | --- | --- |
| `cpy` | alias | `wl-copy` if available, else `pbcopy` |
| `pst` | alias | `wl-paste` if available, else `pbpaste` |
| `q` | function | `exit`. Runs `ya emit quit` first when `$YAZI_ID` is set, so the parent yazi also quits |
| `celar`, `claer` | alias | `clear` (interactive only) |
| `ls` | alias | `eza --icons` when eza is installed (interactive only) |
## Abbreviations
No fish `abbr` definitions are committed. Abbreviations live in `fish_variables`, which chezmoi ignores.
## Related helpers
The following are functions or scripts, not aliases, and are documented elsewhere:
- `c`, `cd`, `y`/`yy`, `clip-last`, `ghg`, `ghn`, `gho`: per-shell functions ([fish](/shell/fish#functions), [bash and zsh](/shell/bash-zsh#per-shell-functions)).
- `pnpmf`, `pnpmfd`, `pnpmfr`, `pnpmfw`, `pnpmfx`: fish workspace helpers ([fish](/shell/fish#pnpm-filterfish)).
- `ai`, `pj`, `gop`, `fab`, `gdc`, and the other `~/.local/bin` tools: [Scripts](/shell/scripts).
docs/shell/atuin.mdx
+144
View File
@@ -0,0 +1,144 @@
---
title: atuin
description: Shell history search with a daemon, directory-scoped up-arrow, tmux popups, a cyberdream theme, and the atuin AI inline command generator.
---
[atuin](https://atuin.sh) replaces shell history search in fish, bash, and zsh. It also provides `atuin ai inline`, a natural-language command generator that the fish config binds to keys.
| Source (repo) | Target | Notes |
| --- | --- | --- |
| `dot_config/atuin/private_config.toml` | `~/.config/atuin/config.toml` | `private_`: written as a regular `0600` file, not a symlink |
| `dot_config/atuin/themes/cyberdream.toml` | `~/.config/atuin/themes/cyberdream.toml` | symlink |
| `dot_config/atuin/atuin-receipt.json` | `~/.config/atuin/atuin-receipt.json` | symlink |
chezmoi runs in symlink mode, but `private_` files are written as real files, so edits to `~/.config/atuin/config.toml` do not reach the repo on their own. Copy them back with `chezmoi re-add` (or `czs`, see [fish](/shell/fish#functions)). None of the files are templates, and they apply on every role.
## Installation
`atuin` is listed in `.chezmoidata/packages.yaml` for pacman and Homebrew. The shells also expect atuin's standalone installer layout in `~/.atuin/bin`:
- fish: `conf.d/atuin.env.fish` sources `~/.atuin/bin/env.fish`.
- bash and zsh: `. "$HOME/.atuin/bin/env"` just before `atuin init`.
Neither line checks that the file exists, so a machine without `~/.atuin/bin` prints a sourcing error at shell start.
### atuin-receipt.json
The receipt that atuin's [cargo-dist](https://opensource.axo.dev/cargo-dist/) installer writes. It records how atuin was installed, which the self-updater (`atuin update`) needs:
| Field | Value |
| --- | --- |
| `binaries` | `["atuin"]` |
| `install_prefix` | `~/.atuin/bin` (stored as an absolute path under `/home/prad`) |
| `install_layout` | `flat` |
| `modify_path` | `true` |
| `provider` | cargo-dist `0.31.0` |
| `source` | GitHub release `atuinsh/atuin` |
| `version` | `18.19.0` |
## Shell integration
| Shell | Where | What |
| --- | --- | --- |
| fish | `config.fish`, interactive only | `atuin init fish \| source`, `atuin ai init fish \| source`, and the `?` binding |
| fish | `functions/fish_user_key_bindings.fish` | <kbd>ctrl-w</kbd> runs `atuin ai inline` |
| bash | end of `~/.bashrc` | `eval "$(atuin init bash)"` |
| zsh | end of `~/.zshrc` | `eval "$(atuin init zsh)"` |
In fish, `40-tools.fish` sources hishtory before atuin, but atuin's init runs later in `config.fish` and takes <kbd>ctrl-r</kbd>. zsh also loads `suv init zsh` (suvadu) if installed.
### Key bindings
| Key | Shells | Action |
| --- | --- | --- |
| <kbd>ctrl-r</kbd> | all | Interactive search (`_atuin_search`) |
| <kbd>up</kbd> | all | Search opened from the up arrow. `filter_mode_shell_up_key_binding = "directory"` limits it to history from the current directory |
| <kbd>?</kbd> | fish, vi normal mode | On an empty buffer, runs `atuin ai inline --hook` |
| <kbd>ctrl-w</kbd> | fish, insert and normal mode | `atuin ai inline`, then repaint |
| <kbd>ctrl+shift+p</kbd> | kitty | [`atuin-pick`](/shell/scripts#atuin-pick): directory-filtered search in a split, running the pick in a fresh fish |
Under tmux, atuin's `[tmux]` settings open the search in a tmux popup (80% wide, 60% tall) instead of inline.
## AI inline
Commit `a82921c` ("add Atuin AI inline integration and keybinding") added the <kbd>ctrl-w</kbd> bind to `fish_user_key_bindings.fish` and the following to `config.fish`:
1. `atuin ai init fish | source`, in the interactive block next to `atuin init fish`.
2. A copy of the `_atuin_ai_question_mark` function that `atuin ai init fish` prints, and `bind "?" _atuin_ai_question_mark`.
The config also sets `[ai] enabled = true`.
`_atuin_ai_question_mark` works like this:
- **Buffer empty (or just `?`):** clears the line, prints OSC `133;C` to `/dev/tty` to close the terminal's semantic prompt zone (so shell-integrated terminals do not erase the TUI during a prompt reflow), then runs `atuin ai inline --hook` with stdout and stderr swapped. The TUI draws on the terminal, and the result comes back tagged:
| Output prefix | Effect |
| --- | --- |
| `__atuin_ai_print__:` | Print the text, repaint |
| `__atuin_ai_cancel__` | Repaint only |
| `__atuin_ai_execute__:` | Put the command on the line and execute it |
| `__atuin_ai_insert__:` | Put the command on the line for editing |
| anything else, non-empty | Put it on the line for editing |
- **Buffer not empty:** inserts a literal `?` under emacs bindings. Under vi or hybrid bindings, which this config uses, it does nothing.
`bind "?"` in `config.fish` has no `-M` flag, so it applies to fish's `default` mode, which is vi **normal** mode here. In insert mode <kbd>?</kbd> types a question mark. To ask for a command, press <kbd>Esc</kbd> and then <kbd>?</kbd> on an empty line, or press <kbd>ctrl-w</kbd> from either mode. The <kbd>ctrl-w</kbd> bind calls `atuin ai inline` without `--hook` and replaces fish's default <kbd>ctrl-w</kbd> word deletion.
bash and zsh do not load `atuin ai init`.
## Configuration
`config.toml` is atuin's generated sample with a few keys set. The rest are commented-out defaults. The settings that take effect:
| Key | Value | Effect |
| --- | --- | --- |
| `filter_mode_shell_up_key_binding` | `"directory"` | Up-arrow search shows only the current directory's history |
| `dotfiles.enabled` | `true` | Enables atuin's dotfiles feature (aliases and vars managed by atuin) |
| `daemon.enabled` | `true` | Uses the background daemon |
| `daemon.autostart` | `true` | atuin starts and manages the daemon itself |
| `pty_proxy.enabled` | `false` | `atuin init` does not re-exec the shell inside `atuin pty-proxy` |
| `theme.name` | `"cyberdream"` | Loads `themes/cyberdream.toml` |
| `tmux.enabled` | `true` | Search opens in a tmux popup when inside tmux (tmux 3.2+) |
| `tmux.width` / `tmux.height` | `"80%"` / `"60%"` | Popup size |
| `ai.enabled` | `true` | Enables `atuin ai` |
No sync server, key, or session is configured in the repo. atuin keeps its encryption key and session under `~/.local/share/atuin`, outside chezmoi, and uses the default sync server.
:::warning[Misplaced keys]
Several keys sit after the `[dotfiles]` table header, so TOML puts them inside `[dotfiles]` rather than at the top level, and atuin ignores them. `atuin config get --resolved` confirms it:
| Key as written | Intended | Resolved |
| --- | --- | --- |
| `search_mode` | `"daemon-fuzzy"` | `fuzzy` |
| `enter_accept` | `true` | `false` |
| `workspaces` | `true` | `false` |
| `style` | `"auto"` | `compact` |
| `inline_height_shell_up_key_binding` | `20` | unknown key |
| `auto_sync` | `true` | `true` (the default) |
| `update_check` | `true` | `true` (the default) |
`syntax_highlight = true` has the same problem: it sits under `[ai]`, while the comment block above it documents the `[ui]` table.
To apply these settings, move the keys above `[dotfiles]` (and `syntax_highlight` under `[ui]`) in `dot_config/atuin/private_config.toml`.
:::
## Theme
`themes/cyberdream.toml` defines a theme named `cyberdream`, using the palette shared with [fish](/shell/fish#theme) and [Starship](/shell/starship#palette):
| Key | Color |
| --- | --- |
| `AlertInfo` | `#5ef1ff` |
| `AlertWarn` | `#f1ff5e` |
| `AlertError` | `#ff6e5e` |
| `Annotation` | `#7b8496` |
| `Guidance` | `#5ea1ff` |
| `Important` | `#ff5ef1` |
| `Title` | `#5ef1ff` |
| `Muted` | `#7b8496` |
| `SyntaxCommand` | `#5ea1ff` |
| `SyntaxFlag` | `#5ef1ff` |
| `SyntaxString` | `#5eff6c` |
| `SyntaxVariable` | `#ff5ef1` |
| `SyntaxOperator` | `#ff5ea0` |
| `SyntaxComment` | `#7b8496` |
docs/shell/bash-zsh.mdx
+124
View File
@@ -0,0 +1,124 @@
---
title: bash and zsh
description: Secondary shells that share fish's aliases, starship prompt, atuin history, and cd-style helper functions.
---
bash and zsh are set up so a shell other than fish feels the same: the same aliases, the same starship prompt, atuin history, and ports of the fish helpers that have to change the shell's own directory. zsh also gets ports of the fish key bindings.
| Source (repo) | Target |
| --- | --- |
| `dot_bashrc` | `~/.bashrc` |
| `dot_zshrc` | `~/.zshrc` |
| `dot_config/zsh/keybinds.zsh` | `~/.config/zsh/keybinds.zsh` |
| `dot_config/shell/aliases.sh.tmpl` | `~/.config/shell/aliases.sh` (template) |
| `dot_config/bash/functions/*.bash` | `~/.config/bash/functions/` |
| `dot_config/zsh/functions/*.zsh` | `~/.config/zsh/functions/` |
`aliases.sh.tmpl` is the only template. It renders the alias list from `.chezmoidata/aliases.yaml` ([chezmoi data](/chezmoi/data)). The other files apply as-is on every role.
## Installation
bash is part of the base system. zsh itself is not listed in `.chezmoidata/packages.yaml`, but `zsh-syntax-highlighting`, `starship`, `atuin`, `eza`, and `zoxide` are, for both pacman and Homebrew. `suvadu` (the `suv` history tool) is declared under `packages.shared.cargo`, but none of the apply scripts install cargo packages, so install it manually if you want it.
## ~/.bashrc
Interactive shells only (`[[ $- != *i* ]] && return`). In order:
1. **PATH.** Prepends `~/.local/bin` if missing, sources `~/.cargo/env` if present, and appends `~/.maestro/bin` if it exists.
2. **Go.** `GOPATH=~/.local/share/go`, `GOBIN=$GOPATH/bin`, and `GOBIN` prepended to `PATH`. mise provides `GOROOT`.
3. **Android SDK.** `ANDROID_HOME` and `ANDROID_SDK_ROOT` set to `~/.local/share/android`. `platform-tools`, `cmdline-tools/latest/bin`, and `emulator` are appended if they exist.
4. **Aliases.** Sources `~/.config/shell/aliases.sh`.
5. **Functions.** Sources every `~/.config/bash/functions/*.bash`.
6. **Flyline.** If `~/.local/lib/libflyline.so` exists, loads it with `enable -f … flyline` for richer line editing.
7. Sources `~/.config/envman/load.sh` if it is non-empty.
8. **Prompt.** `eval "$(starship init bash)"` if starship is installed.
9. **atuin.** Sources `~/.atuin/bin/env`, then `eval "$(atuin init bash)"`.
bash has no custom key bindings. atuin's init binds <kbd>ctrl-r</kbd> and <kbd>up</kbd>.
## ~/.zshrc
1. **History.** `HISTFILE=~/.zsh_history`, `HISTSIZE=10000`, `SAVEHIST=10000`, `setopt SHARE_HISTORY HIST_IGNORE_DUPS`.
2. **Completion.** `autoload -Uz compinit && compinit`.
3. The same PATH, Go, and Android blocks as `.bashrc`.
4. Sources `~/.config/shell/aliases.sh`.
5. Sources every `~/.config/zsh/functions/*.zsh`.
6. Sources `~/.config/zsh/keybinds.zsh`.
7. `eval "$(suv init zsh)"` if suvadu is installed.
8. Sources `~/.config/envman/load.sh` if it is non-empty.
9. `eval "$(starship init zsh)"` if starship is installed.
10. **Syntax highlighting.** Sources the first `zsh-syntax-highlighting.zsh` found in `/usr/share/zsh/plugins/zsh-syntax-highlighting/`, `/opt/homebrew/share/zsh-syntax-highlighting/`, or `/usr/local/share/zsh-syntax-highlighting/`. The comment says this must stay last, because it wraps every zle widget defined before it.
11. **atuin.** Sources `~/.atuin/bin/env` and runs `eval "$(atuin init zsh)"`. These lines come after the syntax-highlighting block, so despite the comment, syntax highlighting is not actually last.
## zsh key bindings
`keybinds.zsh` ports `fish_user_key_bindings.fish` to zle. Unlike fish, zsh uses the **emacs** keymap: `bindkey -e` pins it so that `$EDITOR=nvim` does not switch zsh into vi mode. `unsetopt flow_control` frees <kbd>ctrl-q</kbd> and <kbd>ctrl-s</kbd> from the terminal.
A generic widget `_zle-run` is registered as `run-<cmd>` for `purple`, `clip-last`, `gho`, `pj`, `omp`, `yy`, and `lazygit`. It clears the pending display (`zle -I`), runs the command with the tty on stdin, then `zle reset-prompt`. Widgets run in the shell process, so directory changes made by `gho` and `yy` persist.
| Key | Action |
| --- | --- |
| <kbd>ctrl-e</kbd> | `yy` (yazi, cd to its exit dir) |
| <kbd>ctrl-f</kbd> | `yy` |
| <kbd>ctrl-b</kbd> | `purple` (an external command; this repo does not provide it) |
| <kbd>ctrl-y</kbd> | `clip-last` |
| <kbd>ctrl-o</kbd> | `gho` (repo or vault picker, cd) |
| <kbd>ctrl-p</kbd> | `pj` (task runner) |
| <kbd>ctrl-a</kbd> | `omp` |
| <kbd>ctrl-g</kbd> | `lazygit` |
| <kbd>ctrl-q</kbd> | `exit` |
| <kbd>ctrl-c</kbd> | At the prompt: kill the buffer, clear the screen and kitty scrollback (`ESC[2J ESC[3J`), reset the prompt |
<kbd>ctrl-c</kbd> is the tty interrupt character, so `bindkey '^C'` would never fire. The binding is a `TRAPINT` function instead. At the prompt it runs `zle .kill-buffer`, prints the clear sequence, and runs `zle .reset-prompt`. While a command is running, SIGINT keeps its normal behavior (returns `128+SIGINT`).
The fish-only binds <kbd>ctrl-w</kbd> (atuin AI), <kbd>down</kbd> (`pj`), and <kbd>?</kbd> have no zsh equivalent. <kbd>ctrl-h/j/k/l</kbd> belong to kitty ([kitty](/terminal/kitty)) and are not bound here.
## Shared aliases: aliases.sh
`~/.config/shell/aliases.sh` is rendered from `.chezmoidata/aliases.yaml`. Each YAML `section` becomes a comment, and each item becomes `alias <name>='<cmd>'`. The template then appends shell-specific extras that are not in the YAML:
```sh ~/.config/shell/aliases.sh
# Clipboard
if command -v wl-copy >/dev/null 2>&1; then
alias cpy='wl-copy'
alias pst='wl-paste'
elif command -v pbcopy >/dev/null 2>&1; then
alias cpy='pbcopy'
alias pst='pbpaste'
fi
q() {
if [ -n "$YAZI_ID" ] && command -v ya >/dev/null 2>&1; then
ya emit quit 2>/dev/null
fi
exit
}
alias celar='clear'
alias claer='clear'
if command -v eza >/dev/null 2>&1; then
alias ls='eza --icons'
fi
```
- **Clipboard detection.** `cpy`/`pst` map to Wayland's `wl-copy`/`wl-paste` when available, else macOS `pbcopy`/`pbpaste`.
- **`q`.** Exits the shell. If the shell was spawned from yazi's own `q` binding (`$YAZI_ID` set), it runs `ya emit quit` first so the parent yazi closes too instead of bouncing back.
- **Typo guards and eza.** `celar`/`claer` → `clear`, and `ls` → `eza --icons` when eza is installed. The file is sourced only by interactive shells, so scripts keep the real `ls`.
The full alias table, including the differences from fish, is on the [Aliases](/shell/aliases) page.
## Per-shell functions
Each directory holds one function per file. bash and zsh source every file at startup; the bash and zsh versions have identical bodies.
| Function | Behavior |
| --- | --- |
| `c [dir]` | `clear` with no argument, `cd "$1"` with one |
| `cd [dir]` | No argument: `$HOME`. `-`: previous dir. Otherwise `builtin cd`, falling back to `zoxide query -- "$1"`. Records the result with `zoxide add "$PWD"` and preserves cd's exit status |
| `clip-last` | Re-runs the previous history entry (`fc -ln -1 -1`, skipping itself if the line editor already recorded `clip-last`), pipes the output to `wl-copy` or `pbcopy`, and sends a `notify-send -a shell` notification if available |
| `ghg <repo>` | `ghg-clone "$@"`, cd into the printed path, `clear && onefetch` |
| `ghn <name>` | `command ghn "$@"`, cd into the printed path |
| `gho` | `command gho`, cd into the printed path, `clear`, and `onefetch` if it is a git repo |
| `yy [args]` | `yazi --cwd-file=<tmp>`, then cd to the directory written there if it changed |
The `ghg` helper script is named `ghg-clone` because an unrelated cargo binary already uses the name `ghg`. The [Scripts](/shell/scripts#why-some-helpers-are-shell-functions) page explains why these helpers are shell functions and not scripts.
docs/shell/fish.mdx
+300
View File
@@ -0,0 +1,300 @@
---
title: fish
description: The primary interactive shell — conf.d layout, environment, vi-mode key bindings, the cyberdream theme, completions, and every autoloaded function.
---
fish is the primary interactive shell. The config is split into autoloaded files: `conf.d/` for startup snippets, `functions/` for one function per file, `completions/` for completion scripts, and `themes/` for the color theme. `config.fish` runs last and holds the prompt and atuin setup.
| Source (repo) | Target |
| --- | --- |
| `dot_config/fish/config.fish` | `~/.config/fish/config.fish` |
| `dot_config/fish/conf.d/*.fish` | `~/.config/fish/conf.d/` |
| `dot_config/fish/functions/*.fish` | `~/.config/fish/functions/` |
| `dot_config/fish/completions/*.fish` | `~/.config/fish/completions/` |
| `dot_config/fish/themes/cyberdream.theme` | `~/.config/fish/themes/cyberdream.theme` |
| `dot_config/fish/fish_plugins` | `~/.config/fish/fish_plugins` |
| `dot_config/fish/auto-Niri.fish` | `~/.config/fish/auto-Niri.fish` (Linux `desktop`/`laptop` only) |
None of these files are templates. chezmoi runs in symlink mode, so each target is a symlink back into the source tree and edits to `~/.config/fish/...` land in the repo directly. `~/.config/fish/fish_variables` (universal variables, including the selected theme) is listed in `.chezmoiignore.tmpl` and stays local to each machine.
## Installation
`fish` is in `.chezmoidata/packages.yaml` under `packages.arch.pacman` and `packages.darwin.brew`. `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl` installs it with pacman on Arch and Homebrew on macOS. The tools that fish initializes (starship, zoxide, atuin, fzf, eza, gum, yazi) come from the same manifest. mise, television, hishtory, envman, and the Bun, Go, Android, and Foundry toolchains are not in the manifest; fish initializes each one only if it is present.
### Plugins
`fish_plugins` is a [fisher](https://github.com/jorgebucaran/fisher) manifest with one entry:
```text ~/.config/fish/fish_plugins
jorgebucaran/nvm.fish
```
The plugin's files are committed to the repo (`conf.d/nvm.fish`, `functions/nvm.fish`, `functions/_nvm_*.fish`, `completions/nvm.fish`), so fish has `nvm` without fisher. The plugin stores Node builds in `$XDG_DATA_HOME/nvm` (default `~/.local/share/nvm`) and downloads from `https://nodejs.org/dist`. If `nvm_default_version` is set, it runs `nvm use --silent $nvm_default_version` in each interactive shell.
## Startup order
fish sources `conf.d/*.fish` in name order and then `config.fish`. The numbered files load first:
| File | Purpose |
| --- | --- |
| `00-path.fish` | `PATH` entries and `PNPM_HOME` |
| `10-env.fish` | Non-secret environment, greeting, fzf colors |
| `20-aliases.fish` | Aliases, clipboard aliases, `q`, typo guards |
| `30-ssh-agent.fish` | One ssh-agent shared across shells |
| `40-tools.fish` | mise, television, starship, zoxide, entire, hishtory, unsloth |
| `50-terminal-title.fish` | tmux/screen window name from `$PWD` |
| `atuin.env.fish` | Sources `~/.atuin/bin/env.fish` (puts atuin's install dir on `PATH`) |
| `inir-env.fish` | `INIR_VENV` and `ILLOGICAL_IMPULSE_VIRTUAL_ENV` → `~/.local/state/quickshell/.venv` |
| `inir-path.fish` | Prepends `~/.local/bin` to `PATH` if missing |
| `nvm.fish` | nvm.fish plugin events and default-version activation |
| `opencode-background-subagents.fish` | `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`, `OPENCODE_ENABLE_EXA=1` |
| `pnpm-filter.fish` | `pnpmf*` workspace helpers |
| `rustup.fish` | Sources `~/.cargo/env.fish` |
| `secrets.fish` | API credentials (names below) |
| `uv.env.fish` | Sources `~/.local/bin/env.fish` (written by the uv installer) |
### 00-path.fish
Runs for every shell, including non-interactive ones, so scripts get the same `PATH`.
| Entry | Position |
| --- | --- |
| `~/.bun/bin`, `~/.local/share/go/bin`, `~/.maestro/bin`, `~/.grok/bin`, `~/.opencode/bin` | prepended |
| `~/.foundry/bin` | appended |
| `~/.local/share/android/platform-tools`, `cmdline-tools/latest/bin`, `emulator` | appended |
| `~/local/share/pnpm` | appended (note the missing dot; this path does not match `PNPM_HOME`) |
| `$PNPM_HOME/bin` | prepended; `PNPM_HOME=~/.local/share/pnpm` |
`~/.local/bin` comes from `inir-path.fish` and `~/.cargo/bin` from `rustup.fish`.
### 10-env.fish
| Variable | Value |
| --- | --- |
| `fish_greeting` | empty (no greeting) |
| `FISH_BOTTOM_PROMPT` | `0` unless inherited. `1` pins the prompt to the bottom row |
| `HSA_OVERRIDE_GFX_VERSION` | `11.5.0` (ROCm) |
| `ROCR_VISIBLE_DEVICES`, `HIP_VISIBLE_DEVICES` | `0` |
| `EGET_BIN` | `~/.local/bin` |
| `GHQ_ROOT`, `CODE_ROOT` | `~/Code` |
| `ANDROID_HOME`, `ANDROID_SDK_ROOT` | `~/.local/share/android` |
| `GITEA_LOGIN` | `prad.codes` |
| `GITLAB_HOST` | `git.sonr.org` |
| `EDITOR`, `VISUAL` | `nvim` |
| `BROWSER` | `/usr/bin/brave-origin-nightly` if that binary exists |
| `CHROME_EXECUTABLE` | `/usr/bin/chromium` if it exists |
| `PUPPETEER_EXECUTABLE_PATH` | `~/.local/bin/chrome-headless-shell` |
| `ZEAL_DOCSETS` | the Zeal flatpak docset directory |
| `SHARP_IGNORE_GLOBAL_LIBVIPS` | `1` |
| `FZF_DEFAULT_OPTS` | cyberdream fzf theme (below) |
`GOPATH`/`GOBIN` are not set here. The comment explains why: mise's fish hook re-applies its `[env]` on every prompt, so Go paths are pinned in `~/.config/mise/config.toml`, and mise provides `GOROOT`.
```fish ~/.config/fish/conf.d/10-env.fish
set -gx FZF_DEFAULT_OPTS "
--height=~40%
--layout=default
--info=inline-right
--border=rounded
--prompt=' '
--pointer='▶'
--marker='✓'
--color=fg:#ffffff,fg+:#ffffff,bg:-1,bg+:#3c4048
--color=hl:#5ef1ff,hl+:#5ef1ff
--color=info:#7b8496,header:#7b8496,border:#7b8496
--color=prompt:#5ef1ff,pointer:#ffaecf,marker:#5eff6c,spinner:#f1ff5e
--color=gutter:-1,query:#ffffff
"
```
### 20-aliases.fish
Editor, Bun, directory-jump, and tool aliases, followed by:
- `cpy`/`pst`: `wl-copy`/`wl-paste` if `wl-copy` exists, else `pbcopy`/`pbpaste`.
- `q`: exits the shell. If `$YAZI_ID` is set and `ya` exists, it first runs `ya emit quit` so the yazi that spawned the shell quits too.
- Interactive only: `celar` and `claer` → `clear`, and `ls` → `eza --icons` when eza is installed. `clear` itself is not aliased, because an alias would shadow `functions/clear.fish`.
The full list is on the [Aliases](/shell/aliases) page. This file is plain fish, not rendered from `.chezmoidata/aliases.yaml`, so its alias set differs from bash/zsh in a few places.
### 30-ssh-agent.fish
Interactive shells without `SSH_AUTH_SOCK` source `~/.ssh/agent.env.fish` and probe with `ssh-add -l`. Exit code 2 means no agent is reachable. In that case it starts `ssh-agent -c`, rewrites its csh `setenv` lines into `set -gx`, saves them to `~/.ssh/agent.env.fish`, and sources the file. An `SSH_AUTH_SOCK` provided from outside (systemd unit, forwarding, keyring) is left alone.
### 40-tools.fish
- `mise activate fish` runs for every shell, so scripts see mise shims too.
- Interactive only, in order:
1. Print `~/.local/state/quickshell/user/generated/terminal/sequences.txt` if present. These are escape sequences that apply wallpaper-generated Material You terminal colors from quickshell.
2. `tv init fish` (television), if installed.
3. `starship init fish`, `zoxide init fish`, and `entire completion fish`, each only if installed.
4. `tv init fish` a second time. The comment says it runs before hishtory so hishtory keeps <kbd>ctrl-r</kbd>.
5. Source `~/.hishtory/config.fish` if present.
6. Activate the unsloth studio venv (`~/.unsloth/studio/unsloth_studio/bin/activate.fish`) if present.
atuin is initialized later, in `config.fish`, and binds <kbd>ctrl-r</kbd> itself.
### 50-terminal-title.fish
Defines `terminal_title`, which runs on every `PWD` change and prints `ESC k <prompt_pwd> ESC \`. That sequence sets the tmux or screen window name. `functions/fish_title.fish` sets the regular terminal title.
### pnpm-filter.fish
pnpm workspace helpers. `__pnpm_pick_pkg` lists workspace packages with `pnpm m ls --depth -1 --json | jq`, and you pick one with `gum filter`.
| Function | Does |
| --- | --- |
| `pnpmf <deps…>` | Pick a package, then `pnpm --filter <pkg> add <deps>` inside a `gum spin` |
| `pnpmfd <deps…>` | Same with `add -D` |
| `pnpmfr <deps…>` | `pnpm --filter <pkg> remove <deps>` |
| `pnpmfw` | Pick a target package and a sibling, then `pnpm --filter <pkg> add <sibling> --workspace` |
| `pnpmfx` | Pick a package, then pick one of its `package.json` scripts with `gum filter` and run it |
### secrets.fish
Exports credentials as global variables. The values are machine-specific and are not documented here. Variable names:
`PGDATABASE` (local Postgres connection string), `GITLAB_TOKEN`, `OPPER_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`, `WEBAWESOME_NPM_TOKEN`, `TAVILY_API_KEY`, `FINANCIAL_DATASETS_API_KEY`, `PIMLICO_API_KEY`, `WAKATIME_API_KEY`, `LINEAR_CLI_PROFILE`, `LINEAR_API_KEY`, `LINEAR_TEAM_ID`.
:::warning
Put your own values in `~/.config/fish/conf.d/secrets.fish` on each machine. Do not reuse credentials from another clone.
:::
## config.fish
The header comment says the file should stay empty, but it holds the following:
1. **Starship with transient prompt.** `starship_transient_prompt_func` renders `starship module character` and `starship_transient_rprompt_func` renders `starship module time`. Then `starship init fish | source` and `enable_transience` run, so past prompts collapse to `❯` with the time on the right. See [Starship](/shell/starship).
2. **Bottom-pinned prompt.** In interactive shells with `FISH_BOTTOM_PROMPT=1`, `tput cup $LINES 0` moves the cursor to the last row. The comment calls `1` the default, but `10-env.fish` sets `0`, so the prompt stays at the top unless you export `FISH_BOTTOM_PROMPT=1`.
3. `fish_add_path ~/.grok/bin` (grok installer block).
4. Sources `~/.config/envman/load.fish` if it is non-empty.
5. **atuin.** Interactive shells run `atuin init fish | source` and `atuin ai init fish | source`. See [atuin](/shell/atuin).
6. `fish_add_path ~/.cmux/bin` and `~/.cache/.bun/bin`.
7. Sources the first readable `~/.config/herdr/plugins/github/herdr-automatic-rename-*/shell/hook.fish`. This is herdr's automatic pane-rename hook ([herdr](/terminal/herdr)).
8. A copy of the `_atuin_ai_question_mark` function that `atuin ai init fish` emits, followed by `bind "?" _atuin_ai_question_mark`.
## Key bindings
`functions/fish_user_key_bindings.fish` turns on **vi mode** (`fish_vi_key_bindings`) first, then adds custom binds in both `insert` and `default` (normal) modes, so they work in either mode.
| Key | Action |
| --- | --- |
| <kbd>ctrl-e</kbd> | `yy`: yazi, then cd to the directory yazi exited in |
| <kbd>ctrl-f</kbd> | `yy` (same as <kbd>ctrl-e</kbd>) |
| <kbd>ctrl-b</kbd> | `purple`, then repaint (an external command; this repo does not provide it) |
| <kbd>ctrl-y</kbd> | `clip-last`: re-run the last command and copy its output |
| <kbd>ctrl-o</kbd> | `gho`: pick a ghq repo or Obsidian vault and cd into it |
| <kbd>ctrl-p</kbd> | `pj`: fzf task runner ([Scripts](/shell/scripts#pj)) |
| <kbd>ctrl-a</kbd> | `omp` (the coding agent, see [AI agents](/ai)) |
| <kbd>ctrl-w</kbd> | `atuin ai inline`: natural-language command overlay |
| <kbd>ctrl-g</kbd> | `lazygit` |
| <kbd>down</kbd> | `_pj_bind_down`: runs `pj` on an idle, empty prompt, otherwise fish's `down-or-search` |
| <kbd>ctrl-c</kbd> | Clears the command line, runs `clear` (screen and kitty scrollback), repaints |
| <kbd>ctrl-q</kbd> | `exit` |
Bindings added by tool init scripts:
| Key | Mode | Action | Source |
| --- | --- | --- | --- |
| <kbd>ctrl-r</kbd> | default and insert | `_atuin_search` | `atuin init fish` |
| <kbd>up</kbd> | default and insert | `_atuin_bind_up` (atuin history, directory filter) | `atuin init fish` |
| <kbd>?</kbd> | default (vi normal) | `_atuin_ai_question_mark`: on an empty buffer, opens `atuin ai inline` | `config.fish` |
| <kbd>ctrl-t</kbd> | insert | `tv_smart_autocomplete` | `tv init fish` |
`_pj_bind_down` hands the key to `down-or-search` when the buffer is non-empty, the completion pager is open, or history search is active. Otherwise it runs `PJ_QUIET=1 pj`, so pressing down outside a project does nothing and prints no error.
:::note
Under kitty, <kbd>ctrl-g</kbd> (lazygit overlay), <kbd>ctrl-a</kbd> (omp split), <kbd>ctrl-y</kbd> (yazi split), and <kbd>ctrl-h/j/k/l</kbd> (split navigation) are mapped in `kitty.conf` and never reach fish. The fish binds for those keys only apply in other terminals. See [kitty](/terminal/kitty).
:::
The prompt shows `❮` in green in vi normal mode (starship's `vimcmd_symbol`).
## Theme
`themes/cyberdream.theme` is a fish theme file with colors from [cyberdream.nvim](https://github.com/scottmckendry/cyberdream.nvim) and preferred background `#16181a`. The repo ships the file but does not select it. The active theme is stored in `fish_variables`, which chezmoi ignores, so pick it once per machine with `fish_config theme save cyberdream`.
| Variable | Color |
| --- | --- |
| `fish_color_normal` | `#ffffff` |
| `fish_color_command` | `#5ef1ff` |
| `fish_color_param`, `fish_color_escape` | `#ffaecf` |
| `fish_color_keyword`, `fish_color_host` | `#5eff6c` |
| `fish_color_quote`, `fish_color_option`, `fish_color_host_remote` | `#f1ff5e` |
| `fish_color_redirection`, `fish_color_operator` | `#5ea1ff` |
| `fish_color_end` | `#bd5eff` |
| `fish_color_comment`, `fish_color_gray`, `fish_color_autosuggestion` | `#7b8496` |
| `fish_color_error`, `fish_color_cancel`, `fish_color_status` | `#ff6e5e` |
| `fish_color_selection`, `fish_color_search_match` | background `#3c4048` |
| `fish_color_cwd` | `#ffbd5e` |
| `fish_color_user` | `#5ef5d2` |
| `fish_pager_color_progress`, `fish_pager_color_description` | `#7b8496` |
| `fish_pager_color_prefix` | `#5ea1ff` |
| `fish_pager_color_completion` | `#ffffff` |
`FZF_DEFAULT_OPTS` in `10-env.fish` uses the same palette.
## Completions
| File | Command | Mechanism |
| --- | --- | --- |
| `ccc.fish` | `ccc` | Typer-generated: calls `ccc` with `_CCC_COMPLETE=complete_fish` |
| `grok.fish` | `grok` | Static clap-style completion script (global options, subcommands) |
| `nvm.fish` | `nvm` | From the nvm.fish plugin |
| `omp.fish` | `omp` | `omp completions fish \| source` (generated at load time) |
| `ostt.fish` | `ostt` | Static clap-style completion script |
## Functions
Every file in `functions/` is autoloaded by name. Several also exist as POSIX scripts in `~/.local/bin` for bash and zsh. In fish the function shadows the script. See [Scripts](/shell/scripts) for why the cd-style helpers must stay shell functions.
| Function | Purpose |
| --- | --- |
| `_nvm_index_update` | nvm.fish internal: downloads `index.tab` from `$nvm_mirror` into `$nvm_data/.index` |
| `_nvm_list` | nvm.fish internal: lists installed Node versions plus `system` |
| `_nvm_version_activate` | nvm.fish internal: sets `nvm_current_version` and prepends its `bin` to `PATH` |
| `_nvm_version_deactivate` | nvm.fish internal: removes a version's `bin` from `PATH` |
| `_pj_bind_down` | Down-arrow handler: `pj` on an empty idle prompt, else `down-or-search` |
| `ai` | `gum choose` among `claude`, `opencode`, `codex`, `hermes`, `fractal`. `claude` runs with `--dangerously-skip-permissions` |
| `c` | `clear` with no argument, `cd <dir>` with one |
| `c2p` | fzf-pick a `.hbs` template under `~/.config/code2prompt` and run `code2prompt --template` |
| `cd` | `builtin cd`. If that fails, `zoxide query` the argument. Every successful cd is recorded with `zoxide add` |
| `clear` | Prints `ESC[2J ESC[3J ESC[1;1H` to clear the screen and kitty scrollback, then re-pins the prompt if `FISH_BOTTOM_PROMPT=1`. Falls back to `command clear` when not interactive |
| `clip-last` | Re-runs `$history[1]`, pipes the output to `cpy`, and sends a `notify-send` notification |
| `cp-appid` | fzf-pick a `.desktop` app ID and copy it with `wl-copy` (desktop helper, see [niri](/desktop/niri)) |
| `czs` | chezmoi sync: `chezmoi status`, `chezmoi re-add` of drifted files, commit the source repo, then `git pull --rebase --autostash` and `git push` if ahead. Optional targets scope it (for example `czs ~/.config/fish`). Messages print with a `chs:` prefix |
| `extract_agents <dir>` | Copies every `AGENTS.md` under the current tree into `<dir>`, preserving paths |
| `fab` | fzf-pick a Fabric pattern from `~/.config/fabric/pattern_explainations.json` (description in the preview, <kbd>ctrl-/</kbd> toggles it) and run it, feeding piped stdin if any |
| `fish_title` | Terminal title: `prompt_pwd`, or `<host (10 chars)>:<pwd>` over SSH |
| `fish_user_key_bindings` | Vi mode plus the custom binds above |
| `gdc` | `gum confirm`, then `git reset --hard HEAD` and `git clean -fd` |
| `gh-sonr-org-migrate` | Script body (see the warning below) that moves every repo from `*sonr*` GitHub orgs into `sonr-io` and deletes the emptied orgs |
| `ghg <repo>` | `ghg-clone <repo>` (ghq get), cd into the clone, `clear`, `onefetch` |
| `ghn <name>` | Runs `~/.local/bin/ghn` to create and clone a private repo, then cds into it |
| `gho` | Runs `~/.local/bin/gho` (repo/vault picker), cds into the result, `clear`, and `onefetch` inside git repos |
| `git-summary [flags]` | `code2prompt` over the repo root, including only `AGENTS.md` files, using `~/.config/code2prompt/agents-md.hbs`. Extra flags pass through |
| `gtm [repo]` | Migrates GitHub repos to a prad.codes (Gitea) org with `tea repos migrate`. With no argument, fzf multi-selects from `gh repo list`. You pick the target org and migration options (wiki, issues, labels, pull-requests, releases, milestones, lfs, mirror) with gum, private repos stay private, and it offers to clone the results with `ghg-clone`. Fish only |
| `launch_omp_livediff_overlay` | Uses `kitty @` to overlay `omp` on the current window with a `livediff` vsplit beside it. Needs `KITTY_LISTEN_ON` |
| `lc-elir [root]` | fzf multi-select numbered LeetCode solution files (`1234.slug.js`/`.ts`) and run `omp -p "/leetcode-eli5 <file>"` on each |
| `mdcp <url>` | `curl.md <url>`, copy the result with `cpy`, and preview it with `mdfried` |
| `mdp` | fzf-pick a Markdown file up to 3 levels deep (mdfried preview) and open it in `mdfried` |
| `nvm` | nvm.fish: `install`, `use`, `list`, `list-remote`, `current`, `uninstall`. Reads `.nvmrc`/`.node-version` |
| `y` | yazi with `--cwd-file`, then cd to the directory yazi exited in |
| `yy` | Same as `y`. Used by the <kbd>ctrl-e</kbd>/<kbd>ctrl-f</kbd> binds |
Functions defined inside `conf.d/` and `config.fish` rather than `functions/`: `q` (20-aliases), `terminal_title` (50-terminal-title), the `pnpmf*` helpers and `__pnpm_pick_pkg` (pnpm-filter), the `_nvm_install`/`_nvm_update`/`_nvm_uninstall` event handlers (nvm), and `starship_transient_prompt_func`, `starship_transient_rprompt_func`, and `_atuin_ai_question_mark` (config.fish).
:::warning[gh-sonr-org-migrate]
`functions/gh-sonr-org-migrate.fish` is a script, not a function definition. Running `gh-sonr-org-migrate` in fish autoloads the file, which runs the whole fish migration flow. Because the file defines no function of that name, fish then falls through to the bash port at `~/.local/bin/gh-sonr-org-migrate` and starts a second run. Cancel the second run at its first `gum` prompt, or call the bash script by its full path.
:::
## auto-Niri.fish
```fish ~/.config/fish/auto-Niri.fish
# Auto start Niri on tty1
if test -z "$DISPLAY" ;and test "$XDG_VTNR" -eq 1
mkdir -p ~/.cache
exec niri-session > ~/.cache/niri.log 2>&1
end
```
This file is applied only on Linux with role `desktop` or `laptop`. It is not in `conf.d/`, so fish does not load it automatically, and nothing in the repo sources it. To start niri on login to tty1, source it from a login-shell snippet. See [niri](/desktop/niri).
docs/shell/index.mdx
+40
View File
@@ -0,0 +1,40 @@
---
title: Shell
description: fish, bash, and zsh with shared aliases, the starship prompt, atuin history, and the ~/.local/bin scripts.
sidebar:
label: Overview
---
fish is the main interactive shell. bash and zsh are set up to feel the same: they share aliases, the prompt, atuin history, and ports of the cd-style helper functions. General-purpose tools are POSIX or bash scripts in `~/.local/bin`, so each has a single implementation that all three shells call.
| Page | Covers |
| --- | --- |
| [fish](/shell/fish) | `~/.config/fish`: `config.fish`, every `conf.d/` file (PATH, env, aliases, ssh-agent, tool init, secrets by name), vi-mode key bindings, the cyberdream theme, completions, the nvm.fish plugin, and every function in `functions/` |
| [bash and zsh](/shell/bash-zsh) | `~/.bashrc`, `~/.zshrc`, zsh key bindings, `~/.config/shell/aliases.sh`, per-shell function ports |
| [Aliases](/shell/aliases) | Every alias from `.chezmoidata/aliases.yaml` plus the fish-only and shell-specific ones |
| [Scripts](/shell/scripts) | Every general-purpose executable in `~/.local/bin` (`pj`, `gho`, `ghn`, `gop`, `atuin-pick`, …) |
| [Starship](/shell/starship) | `~/.config/starship.toml`: format, modules, symbols, cyberdream palette |
| [atuin](/shell/atuin) | `~/.config/atuin`: history search settings, AI inline integration, cyberdream theme |
## Shared across shells
| Concern | fish | bash | zsh |
| --- | --- | --- | --- |
| Aliases | `conf.d/20-aliases.fish` (hand-maintained) | `~/.config/shell/aliases.sh` (rendered from YAML) | same as bash |
| Prompt | starship + transient prompt | starship | starship |
| History | atuin (hishtory also sourced if installed) | atuin | atuin, plus suvadu if installed |
| Key bindings | vi mode plus custom binds | atuin defaults only | emacs keymap plus ports of the fish binds |
| cd-style helpers | `functions/*.fish` | `~/.config/bash/functions/*.bash` | `~/.config/zsh/functions/*.zsh` |
| Directory jumping | `cd` wrapper with zoxide fallback, `zoxide init` | `cd` wrapper | `cd` wrapper |
## Theme
fish syntax colors, `FZF_DEFAULT_OPTS`, the starship palette, and the atuin theme all use **cyberdream** ([cyberdream.nvim](https://github.com/scottmckendry/cyberdream.nvim)). In fish, `40-tools.fish` also replays quickshell's wallpaper-generated terminal color sequences if that file exists.
## Role gating
Everything in this section applies on every role (`desktop`, `laptop`, `mac`, `server`) except `~/.config/fish/auto-Niri.fish`. That file is applied only on Linux `desktop`/`laptop` machines, along with the rest of the [desktop layer](/desktop).
## Packages
`.chezmoidata/packages.yaml` supplies the shell tooling on Arch (pacman) and macOS (Homebrew): `fish`, `starship`, `atuin`, `zoxide`, `fzf`, `fd`, `ripgrep`, `eza`, `bat`, `jq`, `gum`, `glow`, `yazi`, `lazygit`, and `zsh-syntax-highlighting`. The packages script runs `pacman -S --needed` on Arch and `brew install` on macOS. See [chezmoi scripts](/chezmoi/scripts).
docs/shell/meta.ts
+7
View File
@@ -0,0 +1,7 @@
import { defineMeta } from "blume";
export default defineMeta({
title: "Shell",
icon: "terminal",
pages: ["index", "fish", "bash-zsh", "aliases", "scripts", "starship", "atuin"],
});
docs/shell/scripts.mdx
+294
View File
@@ -0,0 +1,294 @@
---
title: Scripts
description: The shell-agnostic executables in ~/.local/bin — usage, behavior, and dependencies for each.
---
`dot_local/bin/` holds standalone `sh`, `bash`, and `python3` executables. The `executable_` prefix is a chezmoi attribute that sets the executable bit and is dropped from the target name, so `dot_local/bin/executable_pj` becomes `~/.local/bin/pj`. bash, zsh, and fish all put `~/.local/bin` on `PATH`, so every shell runs the same implementation.
This page covers the general-purpose scripts. The desktop scripts in the same directory are documented with their compositor:
- `niri-launch`, `niri-launch-ai`, `niri-launch-browser`, `niri-launch-terminal`, `niri-launch-webapp`, `cp-appid`: [niri](/desktop/niri)
- `omarchy-*`: [Hyprland](/desktop/hyprland)
## Why some helpers are shell functions
A script runs as a child process, and a child cannot change its parent shell's working directory or read the parent's in-memory history. Helpers that need to do either are therefore defined as shell functions, ported three times: `fish/functions/*.fish`, `bash/functions/*.bash`, and `zsh/functions/*.zsh`.
| Helper | Why it must be a function |
| --- | --- |
| `yy` (and fish's `y`) | cds into the directory yazi exited in |
| `c` | cds when given an argument |
| `cd` | Replaces the `cd` builtin with a zoxide fallback |
| `ghg`, `ghn`, `gho` | cd into a repo that the script picked or cloned |
| `clip-last` | Reads the shell's own history (`$history[1]` in fish, `fc` in bash/zsh) |
For `ghg`, `ghn`, and `gho`, the work lives in a script that prints a directory on stdout (and everything else on stderr). The shell function captures that path and cds into it. `ghg`'s script is named `ghg-clone` because an unrelated cargo binary already uses the name `ghg`.
Several scripts below also exist as fish functions of the same name (`ai`, `c2p`, `extract_agents`, `fab`, `gdc`, `git-summary`, `lc-elir`, `mdcp`, `mdp`, `launch_omp_livediff_overlay`, `gh-sonr-org-migrate`). In fish the function runs instead of the script. Both versions behave the same. See [fish functions](/shell/fish#functions).
## Overview
| Script | Language | One line |
| --- | --- | --- |
| [`ai`](#ai) | sh | Pick an AI CLI with gum and launch it |
| [`atuin-pick`](#atuin-pick) | python3 | atuin history picker for a kitty or tmux split |
| [`c2p`](#c2p) | sh | code2prompt with an fzf-picked template |
| [`extract_agents`](#extract_agents) | sh | Copy all `AGENTS.md` files into a directory tree |
| [`fab`](#fab) | sh | fzf picker for Fabric patterns |
| [`gdc`](#gdc) | sh | Discard all git changes after confirmation |
| [`gh-sonr-org-migrate`](#gh-sonr-org-migrate) | bash | Consolidate `*sonr*` GitHub orgs into `sonr-io` |
| [`ghg-clone`](#ghg-clone) | sh | `ghq get` and print the clone path |
| [`ghn`](#ghn) | sh | Create a private repo, clone it, print the path |
| [`gho`](#gho) | sh | Pick a ghq repo or Obsidian vault, print the path |
| [`git-summary`](#git-summary) | sh | Aggregate a repo's `AGENTS.md` files with code2prompt |
| [`gop`](#gop) | sh | Open the current repo's web page |
| [`launch_omp_livediff_overlay`](#launch_omp_livediff_overlay) | sh | omp overlay plus a livediff split in kitty |
| [`lc-elir`](#lc-elir) | sh | Run `/leetcode-eli5` via omp on picked solutions |
| [`mdcp`](#mdcp) | sh | Fetch a URL as Markdown, copy it, preview it |
| [`mdp`](#mdp) | sh | fzf Markdown picker with mdfried preview |
| [`pj`](#pj) | bash | fzf task runner across every project task source |
| [`yazi-nvim-open`](#yazi-nvim-open) | sh | yazi opener that targets the host Neovim |
## ai
```sh
ai
```
Shows `gum choose --header 'AI CLI'` with `claude`, `opencode`, `codex`, `hermes`, and `fractal`, then `exec`s the choice. `claude` runs as `claude --dangerously-skip-permissions`; the others run as the bare binary name. Esc or Ctrl-C exits 0.
**Needs:** `gum` and the chosen CLI.
## atuin-pick
```sh
atuin-pick
```
Opens atuin's interactive search (`atuin search -i --filter-mode directory`), limited to history from the current directory. It then `exec`s an interactive `fish`. If you picked a command, the new fish runs `echo '❯ <cmd>'; <cmd>` via `-C` (`--init-command`), so aliases resolve, a `cd` persists, and the prompt appears below the output. Esc starts a plain fish.
It is written for launch contexts where atuin's shell init never ran. It resolves `atuin` from `PATH` or `~/.atuin/bin/atuin`, and seeds `ATUIN_SESSION` from `atuin uuid` if unset.
**Launched by:** <kbd>ctrl+shift+p</kbd> in kitty. `kitty.conf` opens it in a horizontal split (`launch_hs atuin-pick`). Under the kitty-tmux profile, `tmux.conf` runs it with `tmux split-window -v -l 25%` in the current pane's directory. See [kitty](/terminal/kitty) and [atuin](/shell/atuin).
**Needs:** `python3`, `atuin`, `fish`.
## c2p
```sh
c2p
```
Lists `*.hbs` files under `~/.config/code2prompt` with `fd`, lets you pick one with fzf, and `exec`s `code2prompt --template <file>`.
**Needs:** `fd`, `fzf`, `code2prompt`.
## extract_agents
```sh
extract_agents <output-dir>
```
Creates `<output-dir>` and copies every `AGENTS.md` below the current directory into it with `cp --parents`, keeping the relative paths.
**Needs:** `fd`, GNU `cp` (`--parents`).
## fab
```sh
fab
some-command | fab
```
Reads `~/.config/fabric/pattern_explainations.json`. fzf lists pattern names, the preview pane (right, 60%, wrapped) shows each description, and <kbd>ctrl-/</kbd> toggles the preview. The picked pattern runs as `fabric-ai --pattern <name>`, falling back to `fabric` if `fabric-ai` is not installed. Piped stdin is buffered to a temp file and fed to the pattern; the temp file is removed on exit.
**Needs:** `jq`, `fzf`, `fabric-ai` or `fabric`, and the pattern JSON.
## gdc
```sh
gdc
```
Asks `gum confirm "Discard all uncommitted changes? This is irreversible."`. On yes, runs `git reset --hard HEAD` and `git clean -fd`.
**Needs:** `gum`, `git`.
## gh-sonr-org-migrate
```sh
gh-sonr-org-migrate
```
A bash port of `fish/functions/gh-sonr-org-migrate.fish`, with the same flow:
<Steps>
<Step title="Preflight">Checks that `gh`, `gum`, and `jq` exist and that `gh auth status` succeeds.</Step>
<Step title="Discover">Lists your GitHub orgs whose login contains `sonr`, excluding the target `sonr-io`. You pick which to migrate with `gum choose --no-limit`.</Step>
<Step title="Transfer">For each repo in each org, runs `gh api -X POST repos/<org>/<repo>/transfer -f new_owner=sonr-io`. If the name already exists in `sonr-io`, `gum input` asks for a new name (default `<org>-<repo>`). An empty name skips the repo.</Step>
<Step title="Settle">Waits 30 seconds (`gum spin`), because GitHub transfers are asynchronous.</Step>
<Step title="Delete">For every selected org that had no failed transfers and now has zero repos, asks `gum confirm` and then `gh api -X DELETE orgs/<org>`.</Step>
</Steps>
**Needs:** `gh` authenticated as owner of every org involved, `gum`, `jq`.
:::warning
In fish, run this script by its full path (`~/.local/bin/gh-sonr-org-migrate`). The fish file of the same name is a script body with no function in it, so typing just the name runs the fish flow and then this script. See [fish](/shell/fish#functions).
:::
## ghg-clone
```sh
ghg-clone <repo>
```
Runs `ghq get <repo>`, with its output sent to stderr. It then works out the on-disk path: it strips the scheme, any `user@`, the scp-style colon, and a trailing `.git`, and prefixes `github.com/` when the input has no host. It checks that `$(ghq root)/<host>/<user>/<repo>` exists, runs `zoxide add` on it if zoxide is installed, and prints the path.
Accepts `https://…`, `ssh://…`, `git@host:user/repo`, `host/user/repo`, or `user/repo`.
**Used by:** the `ghg` shell function, which cds into the path, clears the screen, and runs `onefetch`. The fish function `gtm` also uses it to clone migrated repos.
**Needs:** `ghq` (`GHQ_ROOT=~/Code` in fish), optional `zoxide`.
## ghn
```sh
ghn <repo-name>
```
Creates a new **private** repo and clones it:
- **prad.codes** (Gitea): pick an org from `tea organizations list`, then `tea repos create --private` and `ghq get https://prad.codes/<org>/<name>`.
- **github.com**: pick the owner `prdlk` or `wltbs`, then `gh repo create <owner>/<name> --private` and `ghq get`.
You pick the host with `gum choose`. The script prints the clone directory, and the `ghn` shell function cds into it.
**Needs:** `gum`, `ghq`, and `tea` or `gh`.
## gho
```sh
gho
```
An fzf picker with two lists. <kbd>tab</kbd> switches between them:
- `repo:`: `ghq list` plus the chezmoi source tree, listed as `github.com/prdlk/dotfiles` and mapped back to `~/.local/share/chezmoi`. `--tiebreak=end` favors matches at the end of the name.
- `vault:`: the Obsidian vaults `~/Documents/Obsidian/Personal`, `Walletbase`, and `Research`.
It prints the chosen directory. fzf's bind snippets run under `SHELL=/bin/sh`, so they behave the same whatever the login shell. The `gho` shell function cds into the result, clears the screen, and runs `onefetch` in git repos.
**Launched by:** <kbd>ctrl-o</kbd> in fish and zsh.
**Needs:** `ghq`, `fzf`, `onefetch` (for the wrapper).
## git-summary
```sh
git-summary [code2prompt flags…]
```
From anywhere inside a git repo, runs `code2prompt <repo-root> --include AGENTS.md --include "**/AGENTS.md" --template ~/.config/code2prompt/agents-md.hbs`. Extra flags such as `--output-file` or `--tokens` are passed through.
**Needs:** `git`, `code2prompt`, and the `agents-md.hbs` template.
## gop
```sh
gop # origin, else upstream, else first remote
gop upstream # a named remote
gop owner/repo # github.com/owner/repo
gop <url> # any https/ssh/scp remote URL
```
Opens a repo's web page for any forge whose URL layout is `https://<host>/<owner>/<repo>`, such as github.com and prad.codes. It reduces any remote form to `<host>/<owner>/<repo>`: it drops credentials, drops the port on `ssh://` and `git://` remotes, keeps the port and plain `http` on `http://` remotes, and strips `.git`. It then runs `$BROWSER` (default `xdg-open`) on the result.
**Needs:** `git`, a browser or `xdg-open`.
## launch_omp_livediff_overlay
```sh
launch_omp_livediff_overlay
```
Inside kitty with remote control enabled, runs `kitty @ launch --type=overlay-main --cwd=current omp`, then opens `livediff` in a `vsplit` next to that window with `--keep-focus`. It relies on `$KITTY_LISTEN_ON` rather than a hard-coded socket, because kitty appends `-PID` to `listen_on` socket names. It exits with an error if the variable is unset.
**Needs:** kitty with `allow_remote_control`/`listen_on` ([kitty](/terminal/kitty)), `omp` ([AI agents](/ai)), `livediff`.
## lc-elir
```sh
lc-elir [root]
```
Finds numbered LeetCode solution files (`^\d+\..+\.(js|ts)$`, for example `1365.some-slug.js`) under `root` (default `.`). fzf multi-selects them, showing the last three path segments with a `bat` preview of the first 40 lines. Each pick runs `omp -p "/leetcode-eli5 <file>"`.
**Needs:** `fd`, `fzf`, `bat`, `omp`, and the `/leetcode-eli5` omp command.
## mdcp
```sh
mdcp <url>
```
Fetches the URL as Markdown with `curl.md`, copies it with `wl-copy` or `pbcopy`, then pastes it back into `mdfried` for a rendered preview.
**Needs:** `curl.md`, `mdfried`, and `wl-clipboard` or `pbcopy`.
## mdp
```sh
mdp
```
Lists `*.md` files up to 3 directories deep with `fd`. fzf shows an `mdfried` preview (right, 60%, wrapped), and the pick opens in `mdfried`.
**Needs:** `fd`, `fzf`, `mdfried`.
## pj
```sh
pj [extra args…]
```
A task runner that searches every task source in the project and lets you pick one with fzf.
**Sources.** Each is listed only when its runner is installed:
| Source | Found in | Runner |
| --- | --- | --- |
| npm scripts | `package.json` | package manager from `packageManager`, else from the lockfile (`bun.lock[b]`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, searched upward), else `npm`, then `<pm> run` |
| Make | `GNUmakefile`, `makefile`, `Makefile` | `make`. Targets come from a text parse of rules and `.PHONY`; `make -p` is avoided because it would run `$(shell …)` |
| just | `justfile`, `.justfile`, `Justfile`, `JUSTFILE` | `just` |
| mise | `mise.toml`, `.mise.toml`, `mise/config.toml`, `.mise/config.toml`, `.config/mise/config.toml`, or a `mise-tasks`/`.mise/tasks`/`mise/tasks` dir | `mise run`. Hidden tasks are skipped, and tasks inherited from parent directories are filtered out |
| devbox | `devbox.json` `shell.scripts` | `devbox run` |
| poe | `pyproject.toml` `[tool.poe.tasks]` | `poe`, else `uv run poe` |
| pdm | `[tool.pdm.scripts]` (skips `_*` and `post_*`) | `pdm run` |
| rye | `[tool.rye.scripts]` | `rye run` |
| taskipy | `[tool.taskipy.tasks]` | `task`, else `uv run task` |
| hatch | `[tool.hatch.envs.<env>.scripts]` as `env:name` | `hatch run` |
| console scripts | `[tool.poetry.scripts]`, `[project.scripts]` | `poetry run` for Poetry projects, else `uv run` |
**Scanning.** Walks from `$PWD` up to the git toplevel, inclusive. Outside a repo it stops at the first directory that produced tasks.
**Picker.** Rows are tagged with the tool (`npm`, `pnpm`, `bun`, `make`, `just`, `mise`, `poe`, `py`, …), so typing a tool name filters to it. A directory column appears when more than one project contributed tasks. The header shows the nearest project root. The preview (top, 6 lines) shows the task body: the npm script string, the Make recipe, `just --show`, `mise tasks info`, the devbox script, or the pyproject entry.
**Run.** cds into the task's directory and `exec`s the runner. Extra arguments are forwarded, with `--` inserted for `npm run`, `mise`, and `devbox`. Tasks named `dev`, `start`, `serve`, `watch`, or namespaced variants like `dev:web` are wrapped in `openlogs` (found on `PATH`, via `mise which`, or in mise's node installs) for a live log tail. Without openlogs they run unwrapped, with a note.
**Env.** `PJ_QUIET=1` suppresses the "no task sources found" error. The fish <kbd>down</kbd> binding uses it.
**Launched by:** <kbd>ctrl-p</kbd> in fish and zsh, and <kbd>down</kbd> on an empty fish prompt.
**Needs:** `bash`, `fzf`, `jq`, `python3` 3.11+ (for `tomllib`), plus whichever runners the project uses.
## yazi-nvim-open
```sh
yazi-nvim-open [vsplit|split|tabedit] <file>…
```
yazi's `edit` opener. When run inside a Neovim terminal (`$NVIM` set), each file's absolute path goes to the **host** Neovim through `nvim --server "$NVIM" --remote-expr 'v:lua.EditFromYazi(mode, path)'` (defined in the nvim config's `yazi_session.lua`). Outside Neovim it `exec`s a normal `nvim`, and the split modes do nothing. Set `YAZI_OPEN_TRACE=<file>` to log each call.
**Used by:** `yazi.toml` (the `edit` opener) and `keymap.toml` (<kbd>ctrl-v</kbd> vsplit, <kbd>ctrl-x</kbd> split). See [yazi](/tools/yazi).
**Needs:** `nvim`, `realpath`.
docs/shell/starship.mdx
+88
View File
@@ -0,0 +1,88 @@
---
title: Starship
description: The cross-shell prompt — a minimal left prompt, a clock on the right, and a cyberdream palette.
---
[Starship](https://starship.rs) renders the prompt in fish, bash, and zsh from one config file.
| Source (repo) | Target |
| --- | --- |
| `dot_config/starship.toml` | `~/.config/starship.toml` |
The file is not a template and applies on every role. `starship` is in `.chezmoidata/packages.yaml` for pacman and Homebrew and is installed by `.chezmoiscripts/run_onchange_before_10-packages.sh.tmpl`.
## Shell integration
| Shell | Init |
| --- | --- |
| fish | `conf.d/40-tools.fish` runs `starship init fish`, then `config.fish` runs it again and calls `enable_transience` |
| bash | `eval "$(starship init bash)"` in `~/.bashrc` |
| zsh | `eval "$(starship init zsh)"` in `~/.zshrc` |
With transience in fish, past prompts in the scrollback collapse to the output of `starship_transient_prompt_func` (`starship module character`, the `❯` alone) and `starship_transient_rprompt_func` (`starship module time`). See [fish](/shell/fish#configfish).
## Layout
```toml ~/.config/starship.toml
"$schema" = 'https://starship.rs/config-schema.json'
palette = "cyberdream"
format = """
$username\
$hostname\
$directory\
$git_branch\
$git_state\
$git_status\
$cmd_duration\
$python\
$character"""
right_format = """$time"""
```
The left prompt is a single line with no line break before `$character`. Only the nine listed modules can appear; every other starship module is left out of `format`. `$username` and `$hostname` keep their defaults, so they appear only over SSH or as root.
## Modules
| Module | Format | Style | Notes |
| --- | --- | --- | --- |
| `directory` | default | `blue` | |
| `git_branch` | `[$branch]($style)` | `bright-black` | Branch name only, no symbol or "on" |
| `git_state` | `\([$state( $progress_current/$progress_total)]($style)\) ` | `bright-black` | For example `(REBASING 2/5)` |
| `git_status` | `[[(*$conflicted$untracked$modified$staged$renamed$deleted)](218) ($ahead_behind$stashed)]($style)` | `cyan` | See below |
| `cmd_duration` | `[$duration]($style) ` | `yellow` | Default threshold |
| `python` | `[$virtualenv]($style) ` | `bright-black` | `detect_extensions = []`, `detect_files = []` |
| `time` | `[$time]($style)` | `bright-black` | `disabled = false`, `time_format = '%-I:%M %p'` (for example `3:07 PM`) |
| `character` | default | | Symbols below |
**git_status.** The `conflicted`, `untracked`, `modified`, `staged`, `renamed`, and `deleted` symbols are all set to a zero-width space. Any dirty state therefore shows a single `*` in 256-color `218` (pink) instead of per-state counts. `stashed` is `≡`. `ahead_behind` keeps starship's default arrows and is drawn in `cyan`.
**python.** With both detect lists empty, the module does not trigger on `.py` files or `pyproject.toml`. It shows only the name of an active virtualenv.
### Prompt character
| State | Symbol |
| --- | --- |
| Last command succeeded | `❯` in `purple` |
| Last command failed | `❯` in `red` |
| Vi normal mode (fish) | `❮` in `green` |
fish runs in vi mode ([key bindings](/shell/fish#key-bindings)), so `vimcmd_symbol` appears there. zsh uses the emacs keymap and never shows it.
## Palette
`palette = "cyberdream"` selects the `[palettes.cyberdream]` table, colors from [cyberdream.nvim](https://github.com/scottmckendry/cyberdream.nvim). Every named color in the module styles resolves through this table.
| Name | Normal | `bright-*` | `dim-*` |
| --- | --- | --- | --- |
| black | `#1e2124` | `#4a4d4f` | `#1c1f22` |
| red | `#ff6e5e` | `#ff8b7e` | `#d05c50` |
| green | `#5eff6c` | `#7eff89` | `#4fd05b` |
| yellow | `#f1ff5e` | `#f3ff7e` | `#c5d050` |
| blue | `#5ea1ff` | `#7eb3ff` | `#4f85d1` |
| purple | `#bd5eff` | `#ff7ef3` | `#d050c6` |
| cyan | `#5ef1ff` | `#7ef3ff` | `#4fc5d1` |
| white | `#ffffff` | `#ffffff` | `#d0d0d1` |
`bright-black` (`#4a4d4f`) is the muted gray used for the branch, git state, virtualenv, and clock. The `dim-*` entries are defined but no module uses them.
docs/terminal/ghostty.mdx
+67
View File
@@ -0,0 +1,67 @@
---
title: Ghostty
description: Ghostty configuration and its herdr key sync.
---
GPU terminal emulator kept alongside kitty. Its bindings send the same herdr prefix bytes as the kitty herdr host.
| | |
| --- | --- |
| Source | `dot_config/ghostty/config`, `dot_config/ghostty/config.ghostty`, `dot_config/ghostty/themes/` |
| Target | `~/.config/ghostty/` |
| Install | Not listed in `.chezmoidata/packages.yaml`; install separately |
Ghostty reads both `config` and `config.ghostty`. `config` holds all settings; `config.ghostty` contains a single line, `theme = noctalia`, which selects the active theme.
## Options
| Option | Value |
| --- | --- |
| `font-family` / `font-size` | `Victor Mono NF` / `12.5` |
| `background-opacity` / `background-blur` | `0.9` / `true` |
| `window-decoration` | `false`; `gtk-titlebar = false` |
| `window-padding-x/y` | `12` |
| `cursor-style` | `underline`, blinking |
| `scrollback-limit` | `3023` |
| `mouse-hide-while-typing` | `true` |
| `copy-on-select` | `false` |
| `confirm-close-surface` | `false` |
| `app-notifications` | `no-clipboard-copy,no-config-reload` |
| `quit-after-last-window-closed` | `false`, delay `5m` |
| `shell-integration` | `detect`, features `cursor,sudo,title,no-cursor` |
| `gtk-single-instance` | `true` |
## Keybindings
| Key | Action |
| --- | --- |
| `cmd+c` / `cmd+v` | Copy / paste |
| `cmd+n` | New window |
| `ctrl+plus` / `ctrl+minus` / `ctrl+zero` | Font size +1 / -1 / reset |
| `shift+enter` | Sends a literal newline |
| `ctrl+shift+alt+,` | Reload config |
### herdr sync
Placed last so they override defaults. Each sends `ctrl+b` (`\x02`) followed by a key; see [herdr](/terminal/herdr).
| Key | Sends |
| --- | --- |
| `ctrl+shift+n` | `prefix %` (split vertical) |
| `ctrl+shift+t` | `prefix c` |
| `ctrl+tab` / `ctrl+shift+tab` | `prefix n` / `prefix p` |
| `ctrl+shift+f` | `prefix s` (workspace picker) |
| `ctrl+shift+l` / `ctrl+shift+h` | `prefix .` / `prefix ,` (next / previous agent) |
| `ctrl+shift+j` / `ctrl+shift+k` | `prefix j` / `prefix k` (next / previous workspace) |
| `super+enter` | `prefix N` |
| `super+r` | `prefix W` |
| `ctrl+shift+r` | `prefix T` |
| `ctrl+shift+,` | `prefix S` (herdr settings) |
## Themes
| Theme | Notes |
| --- | --- |
| `noctalia` | Active. Palette matching the Noctalia shell. |
| `ii-auto` | Auto-generated by the ii wallpaper theming system; not meant to be edited. |
| `koda-dark` / `koda-light` | Koda palettes with `bold-is-bright = true`. |
docs/terminal/herdr.mdx
+94
View File
@@ -0,0 +1,94 @@
---
title: herdr
description: herdr, an agent-aware terminal multiplexer, with its keys, theme, plugins and Claude Code hook.
---
herdr is a terminal multiplexer with workspaces, tabs and panes, a sidebar, a prefix key (`ctrl+b`), and a plugin system. It tracks coding agents running in its panes: agent-state colors, next/previous agent keys, and an integration that reports Claude Code sessions to it.
| | |
| --- | --- |
| Source | `dot_config/herdr/config.toml`, `dot_config/herdr/plugins.json`, `dot_config/herdr/plugins/config/`, `dot_config/herdr/empty_dot_plugins.lock`, `dot_config/herdr/kitty.conf`, `dot_config/herdr-nvim/config.toml` |
| Target | `~/.config/herdr/`, `~/.config/herdr-nvim/config.toml` |
| Install | Not in `packages.yaml`; updated by topgrade (`herdr update`) |
| Launch | kitty `super+a` (see [kitty](/terminal/kitty)); Ghostty keys send the same prefix bytes |
## config.toml
`onboarding = false`.
### UI and theme
| Setting | Value |
| --- | --- |
| `ui.pane_borders`, `ui.pane_outer_borders` | `false` (panes separated by gaps only) |
| `ui.prompt_new_tab_name` | `false` |
| `ui.accent` | `#5ea1ff` |
| `ui.status_indicators` | `symbols` |
| `ui.toast.delivery` | `system` |
| `theme.name` | `terminal`, `auto_switch = false` |
| `theme.custom.panel_bg` | `reset` (keeps kitty's translucency and compositor blur) |
| `sidebar_bg` / `active_row_bg` / `selection_bg` | `#16181a` / `#1e2124` / `#3c4048` |
| `accent` / `surface_dim` | `#243348` / `#5ea1ff` (active tab plate matches kitty's tab bar) |
| Agent-state colors | green `#5eff6c`, yellow `#f1ff5e`, red `#ff6e5e`, peach `#ffbd5e`, mauve `#bd5eff` |
| `experimental.kitty_graphics` | `true`; `pane_history = false` |
| `switch_ascii_input_source_in_prefix` | `true` |
These are cyberdream colors.
### Keys
| Key | Action |
| --- | --- |
| `prefix %` | Split vertical |
| `prefix "` | Split horizontal |
| `prefix d` | Detach |
| `prefix s` | Workspace picker |
| `prefix shift+s` | Settings |
| `k` / `j` | Move up / down in the workspace picker (pane up/down in navigate mode unbound) |
| `prefix .` / `prefix ,` | Next / previous agent |
| `prefix j` / `prefix k` | Next / previous workspace |
| `prefix up/down/left/right` | Focus pane |
| `ctrl+h/j/k/l` | `vim-herdr-navigation` left/down/up/right |
| `prefix e` | `chmarax.herdr-nvim.toggle` (nvim sidebar) |
| `prefix o` | `chmarax.herdr-nvim.pick-file` (open file from agent output) |
| `prefix t` | `switchboard.menu` |
| `prefix shift+p` | `switchboard.commands` |
| `prefix shift+l` | `switchboard.git` |
| `prefix shift+k` | `switchboard.projects` |
| `prefix y` | Open `official.browser` plugin in a right split |
| `prefix shift+o` | Open `official.browser` as an overlay |
## Plugins
`plugins.json` is herdr's plugin registry. `.plugins.lock` is created empty. `plugins/config/official.browser/` and `plugins/config/vim-herdr-navigation/` hold placeholder `.keep` files for per-plugin config.
| Plugin | Description (from its manifest) |
| --- | --- |
| `chmarax.herdr-nvim` | Full-height nvim sidebar with agent annotations |
| `herdr-automatic-rename` | Names tabs after the foreground program, adds 1–9 jump numbers |
| `io.github.salemsayed.omaherd` | Tells the Omarchy bar when an agent changes state |
| `official.browser` | Open and inspect real browser pages from herdr |
| `oh-my-opencode-slim` | OpenCode agent orchestration with a herdr adapter |
| `persiyanov.reviewr` | Review agent-written diffs beside the chat |
| `rjyo.window-title-sync` | Syncs the outer terminal title to the focused workspace, tab and agent |
| `switchboard` | Command palette: projects, commands, ports, git, clone, settings |
| `vim-herdr-navigation` | Vim-aware `ctrl+h/j/k/l` pane movement |
[fish](/shell/fish) sources `herdr-automatic-rename`'s `shell/hook.fish` if present.
## herdr-nvim
```toml ~/.config/herdr-nvim/config.toml
[sidebar]
position = "left"
```
The nvim sidebar opens to the left of existing panes (default is right).
## Claude Code integration
`dot_claude/hooks/executable_herdr-agent-state.sh` is installed and managed by herdr (integration id `claude`, version 7) and registered in `dot_claude/settings.json` with the `session` argument. It runs only inside herdr (`HERDR_ENV=1`, `HERDR_SOCKET_PATH`, `HERDR_PANE_ID` set), ignores subagent events, and sends a `pane.report_agent_session` JSON request over herdr's Unix socket with the pane id, Claude session id and transcript path. See [Claude Code](/ai/claude-code).
## herdr/kitty.conf
A legacy kitty config kept in the herdr folder. It runs `tmux new-session -A -s main`, listens on `unix:@mykitty`, includes `current-theme.conf`, maps `super`/`alt` keys to tmux prefix bytes, and has a copy of an older `tmux.conf` appended. The active herdr host is `~/.config/kitty/herdr.conf`.
docs/terminal/index.mdx
+22
View File
@@ -0,0 +1,22 @@
---
title: Terminal
description: Terminal emulators and multiplexers configured by the dotfiles.
sidebar:
label: Overview
---
kitty is the primary terminal. It runs in three modes: plain kitty (kitty owns splits and tabs), a tmux host, and a herdr host. Ghostty is kept as a secondary terminal whose bindings drive herdr the same way.
| Page | Source | What it covers |
| --- | --- | --- |
| [kitty](/terminal/kitty) | `dot_config/kitty/` | Main config, host configs (tmux, herdr, goliath), kittens, custom tab bar |
| [Ghostty](/terminal/ghostty) | `dot_config/ghostty/` | Config, herdr key sync, themes |
| [tmux](/terminal/tmux) | `dot_config/tmux/` | Prefix, bindings, tpm plugins, dotbar status line, Niri titles |
| [herdr](/terminal/herdr) | `dot_config/herdr/`, `dot_config/herdr-nvim/` | Agent-aware multiplexer: keys, theme, plugins, Claude hook |
## Shared conventions
- Font: VictorMono Nerd Font everywhere.
- Background opacity `0.9`, no window decorations; the compositor provides blur.
- Prefix `ctrl+b` in tmux and herdr. kitty and Ghostty translate chords into the prefix byte `\x02` plus a key, so the same physical shortcut works across hosts.
- `ctrl+h/j/k/l` moves between panes across nvim, kitty, tmux, and herdr (vim-aware handoff at every layer).
docs/terminal/kitty.mdx
+195
View File
@@ -0,0 +1,195 @@
---
title: kitty
description: kitty configuration, host variants, custom kittens and the Python tab bar.
---
GPU terminal emulator and the primary terminal on every role.
| | |
| --- | --- |
| Source | `dot_config/kitty/` |
| Target | `~/.config/kitty/` |
| Install | `kitty` in `.chezmoidata/packages.yaml` (pacman on Arch, cask on macOS, plus `font-victor-mono-nerd-font` cask) |
<FileTree>
- dot_config/kitty/
- kitty.conf
- tmux.conf
- herdr.conf
- goliath.conf
- ssh.conf
- symlink_current-theme.conf
- tab_bar.py
- pass_keys.py
- navigate_kitty.py
- select_tab.py
- switchtab.py
- window_titler.py
- themes/
- cyberdream.conf
- koda-dark.conf
- koda-light.conf
- noctalia.conf
</FileTree>
`__pycache__/` next to `tab_bar.py` is excluded in `.chezmoiignore.tmpl`.
## Theme and colors
Every config ends with:
```conf ~/.config/kitty/kitty.conf
include ~/.local/state/omarchy/current/theme/kitty.conf
```
Colors come from the active Omarchy theme; it is included last so it wins. `symlink_current-theme.conf` creates `~/.config/kitty/current-theme.conf` as a symlink to `themes/noctalia.conf`. Only the legacy `dot_config/herdr/kitty.conf` includes `current-theme.conf`; the main config does not. `themes/` holds `cyberdream`, `koda-dark`, `koda-light` and `noctalia` color files.
## kitty.conf
| Option | Value |
| --- | --- |
| `font_family` | `VictorMono Nerd Font`, then overridden in the `BEGIN_KITTY_FONTS` block to `family="VictorMono Nerd Font Mono"`; bold/italic `auto` |
| `window_padding_width` | `8` |
| `hide_window_decorations` | `yes` |
| `background_opacity` | `0.9` |
| `cursor_trail` | `10`, `cursor_trail_start_threshold 0`, `cursor_trail_decay 0.01 0.05` |
| `cursor_blink_interval` | `0` (set to 1, then overridden) |
| `copy_on_select` | `auto` |
| `strip_trailing_spaces` | `smart` |
| `confirm_os_window_close` | `0` |
| `allow_remote_control` | `socket-only` |
| `listen_on` | `unix:@kitty-{kitty_pid}` |
| `enabled_layouts` | `splits:split_axis=vertical,stack` |
| Tab bar | `powerline`, `angled`, aligned left, top edge, `tab_title_template "{custom}"` |
:::note
Transparency uses kitty's own alpha, so text stays opaque. This alpha is also what lets the compositor blur the window: Hyprland enables blur globally and opts out every window except terminal classes.
:::
The socket also exports `KITTY_LISTEN_ON` into each pane. nvim reads it to know kitty owns the panes and hands `ctrl+h/j/k/l` back to kitty at an edge.
### Launch aliases
| Alias | Expands to |
| --- | --- |
| `launch_mn` | `launch --cwd=current --type=overlay-main` |
| `launch_os` | `launch --cwd=current --type=os-window` |
| `launch_ov` | `launch --cwd=current --type=overlay` |
| `launch_tb` | `launch --cwd=current --type=tab` |
| `launch_hs` | `launch --cwd=current --location=hsplit --bias=30` |
| `launch_vs` | `launch --cwd=current --location=vsplit --bias=40` |
| `launch_vs50` | `launch --cwd=current --location=vsplit --bias=50` |
### Keybindings
| Key | Action |
| --- | --- |
| `super+n` | Vertical split 50/50 (`launch_vs50`) |
| `super+z` | Toggle `stack` layout (zoom) |
| `ctrl+shift+t`, `super+enter` | New tab in current cwd |
| `ctrl+space`, `ctrl+shift+j` | Horizontal split, 30% (`launch_hs`) |
| `ctrl+enter`, `ctrl+shift+l` | Vertical split, 40% (`launch_vs`) |
| `ctrl+shift+space` | New OS window |
| `ctrl+shift+h` / `ctrl+shift+k` | Previous / next tab |
| `ctrl+shift+g` | `lazygit` in an overlay |
| `ctrl+shift+f` | `yazi` in a new tab |
| `ctrl+shift+e` | `nvim` in a 50/50 vertical split |
| `ctrl+shift+p` | `atuin-pick` in a horizontal split |
| `super+t` | Spawn a separate kitty (`--class=kitty-tmux`, `--config ~/.config/kitty/tmux.conf`) |
| `super+a` | Spawn a separate kitty (`--class=kitty-herdr`, `--config ~/.config/kitty/herdr.conf`) |
| `ctrl+shift+c` / `ctrl+shift+v` | Copy / paste clipboard |
| `alt+q w e r t y u i o` | Go to tab 1–9 |
| `ctrl+h/j/k/l` | `pass_keys.py`: move to neighbor window left/bottom/top/right, or pass the key through |
| `super+left` / `super+right` | Resize window narrower / wider |
| `super+up` / `super+down` | Resize window taller / shorter (by 3) |
The tmux and herdr hosts are separate kitty processes because `launch` cannot take `--config`.
## Host configs
### tmux.conf — kitty as a tmux host
Launched by `super+t`. kitty stays a dumb terminal; tmux owns panes, windows and sessions. `listen_on unix:@kitty-tmux`, `tab_bar_style hidden`, `shell kitty-tmux` (a launcher script), and `clear_all_shortcuts yes`, so only the bindings below exist. Prefix byte `\x02` is `ctrl+b`; see [tmux](/terminal/tmux) for what each prefix key does.
| Key | Sends / does |
| --- | --- |
| `ctrl+shift+c` / `ctrl+shift+v` | Copy / paste |
| `ctrl+plus` / `ctrl+minus` / `ctrl+0` | Font size +1 / -1 / reset |
| `ctrl+shift+alt+,` | Reload kitty config |
| `ctrl+shift+a` | Spawn a kitty herdr host |
| `super+t`, `super+enter`, `ctrl+shift+t` | `prefix t` (new window) |
| `ctrl+shift+h` / `ctrl+shift+k` | `prefix H` / `prefix L` (previous / next window) |
| `alt+q w e r t y u i o` | `prefix 1`–`9` |
| `ctrl+shift+j` | `prefix "` (split below) |
| `ctrl+shift+l`, `ctrl+enter` | `prefix %` (split right) |
| `ctrl+shift+f` | `prefix z` (zoom) |
| `ctrl+shift+w`, `super+w` | `prefix x` (kill pane) |
| `super+left/right/up/down` | `prefix` + `ctrl+arrow` (resize) |
| `ctrl+shift+g` | `tmux display-popup` 90%×90% running `lazygit` in pane cwd |
| `ctrl+shift+e` | `tmux new-window` running `nvim` in pane cwd |
| `ctrl+shift+p` | `tmux split-window -v -l 25%` running `atuin-pick` |
| `super+n`, `ctrl+shift+space` | New OS window |
| `super+d` | `prefix d` (detach) |
### herdr.conf — kitty as a herdr host
Launched by `super+a`. Class `kitty-herdr`, `tab_bar_style hidden` (herdr draws its own sidebar and tab strip), `shell herdr` (launches or attaches the persistent session; closing the window detaches). Base appearance matches `kitty.conf`, without a `listen_on`. Keys mirror the [Ghostty](/terminal/ghostty) config so both drive herdr identically; an uppercase letter after `\x02` is the shift variant. See [herdr](/terminal/herdr).
| Key | Sends / does |
| --- | --- |
| `super+c` / `super+v` | Copy / paste |
| `ctrl+plus` / `ctrl+minus` / `ctrl+0` | Font size +1 / -1 / reset |
| `ctrl+shift+alt+,` | Reload kitty config |
| `ctrl+shift+n` | `prefix N` |
| `super+n` | `prefix G` |
| `super+t`, `ctrl+shift+t` | `prefix c` |
| `ctrl+space` | `prefix t` (Switchboard menu) |
| `super+z` | `prefix z` |
| `ctrl+tab` / `ctrl+shift+tab` | `prefix .` / `prefix ,` (next / previous agent) |
| `ctrl+shift+f` | `prefix K` (Switchboard projects) |
| `ctrl+shift+g` | `prefix L` (Switchboard git) |
| `ctrl+shift+e` | `prefix e` (herdr-nvim sidebar toggle) |
| `ctrl+shift+o` | `prefix o` (herdr-nvim pick file) |
| `ctrl+shift+h` / `ctrl+shift+l` | `prefix p` / `prefix n` |
| `ctrl+shift+j` / `ctrl+shift+k` | `prefix j` / `prefix k` (next / previous workspace) |
| `ctrl+shift+w` | `prefix W` |
| `ctrl+shift+r` | `prefix T` |
| `ctrl+shift+,` | `prefix S` (herdr settings) |
| `ctrl+shift+q` | `prefix x` |
| `ctrl+shift+p` | `prefix P` (Switchboard commands) |
### goliath.conf — remote tmux over mosh
Opens straight into the tmux session `main` on host `goliath` via `mosh goliath -- tmux new-session -A -s main`. `font_size 9.0`, `listen_on unix:@kitty-goliath`, `env MOSH_TITLE_NOPREFIX=1` (drops mosh's `[mosh] ` title prefix), `tab_bar_style hidden`.
:::warning
mosh bootstraps ssh with `-S none`, so non-interactive key auth to goliath must work. It needs mosh on both ends and UDP 60000–61000 open. mosh sets `TERM=xterm-256color`, so kitty-only capabilities such as undercurl are unavailable inside.
:::
| Key | Sends |
| --- | --- |
| `super+w` | `prefix x` |
| `super+t` | `prefix %` |
| `super+n` | `prefix "` |
| `super+enter`, `alt+n` | `prefix t` |
| `alt+h` / `alt+l` | `prefix H` / `prefix L` |
| `alt+q w e r t y u i o` | `prefix 1`–`9` (`alt+t` is bound twice; the later `prefix 5` wins) |
| `super+left/right/up/down` | `prefix` + `ctrl+arrow` |
| `super+d` | `prefix d` |
### ssh.conf
Kitten `ssh` config: for `hostname goliath`, `share_connections yes`.
## Kittens and Python
| File | Purpose |
| --- | --- |
| `tab_bar.py` | Provides `draw_title` for `{custom}` in the tab template. Title is `<index> <icon> <label>`: the label is the git repo root name of the tab's cwd (walks up for `.git`), or the file nvim is editing (parsed from nvim's title). Icon comes from the foreground process cmdline (editors, AI agents like claude/omp/opencode/codex, git tools, docker, herdr, tmux, yazi, btop, atuin, ssh, chezmoi, …) with a folder fallback. Labels are elided at 28 chars. No subprocesses or timers. |
| `pass_keys.py` | Bound to `ctrl+h/j/k/l`. If the window's foreground process matches `vim`, `nvim`, `fzf`, `tmux` or `herdr`, the key is forwarded; otherwise kitty moves to the neighboring window. |
| `navigate_kitty.py` | No-UI kitten that calls `neighboring_window` with a direction argument; the counterpart nvim can invoke. Not mapped in `kitty.conf`. |
| `select_tab.py` | Full-screen fuzzy tab picker using `kitty @ ls` data; shows cwds zsh-style. Keys: Up/Down/PgUp/PgDn scroll, Enter selects, typing filters, `ctrl+c`/Esc quits. Not mapped in `kitty.conf`. |
| `switchtab.py` | Focuses the tab whose `vt` user var matches the argument, or launches one with that var and reorders tabs by `vt`. Not mapped. |
| `window_titler.py` | Watcher that appends `[<vt> <pty>]` to window titles. Not referenced in `kitty.conf`. |
Related: the [tmux](/terminal/tmux) `is_vim` check and herdr's `vim-herdr-navigation` plugin complete the `ctrl+h/j/k/l` chain. Niri window rules match the `kitty`, `kitty-tmux` and `kitty-herdr` app-ids ([Niri](/desktop/niri)).
docs/terminal/meta.ts
+2
View File
@@ -0,0 +1,2 @@
import { defineMeta } from "blume";
export default defineMeta({ title: "Terminal", icon: "square-terminal", pages: ["index", "kitty", "ghostty", "tmux", "herdr"] });
docs/terminal/tmux.mdx
+95
View File
@@ -0,0 +1,95 @@
---
title: tmux
description: tmux prefix, options, bindings, tpm plugins and the dotbar status line.
---
Terminal multiplexer. Used locally through the kitty tmux host (`super+t` in [kitty](/terminal/kitty)) and remotely on goliath.
| | |
| --- | --- |
| Source | `dot_config/tmux/tmux.conf`, `dot_config/tmux/tmux-nerd-font-window-name.yml`, `dot_config/tmux/executable_niri-title.sh` |
| Target | `~/.config/tmux/` |
| Install | `tmux` in `.chezmoidata/packages.yaml` (pacman, brew) |
tpm is cloned to `~/.config/tmux/plugins/tpm` by `.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` when tmux exists and the directory is missing. `.config/tmux/plugins/**` is ignored by chezmoi. Install plugins with `prefix I`.
:::note
`tmux.conf` ends with `run '~/.tmux/plugins/tpm/tpm'`, while the script clones to `~/.config/tmux/plugins/tpm`.
:::
## Options
The prefix is the default `ctrl+b`.
| Option | Value |
| --- | --- |
| `default-terminal` | `tmux-256color`; `xterm-kitty:Tc` override; features `RGB:usstyle:hyperlinks:clipboard:extkeys` |
| `extended-keys` | `always`, format `csi-u` |
| `base-index` / `pane-base-index` | `1` / `1`; `renumber-windows on` |
| `status-position` | `top` |
| `allow-passthrough` | `on` (kitty graphics for yazi previews); `TERM`, `TERM_PROGRAM` added to `update-environment` |
| `set-clipboard` | `on` (OSC 52) |
| `mouse` | `on` |
| `mode-keys` | `vi` |
| `set-titles` | `on`, `set-titles-string "#T (#S)"`, `status-interval 1`, `automatic-rename on` |
| `history-limit` | `50000` |
| Styling | `status-style` and `popup-style` use default bg; popup border rounded, `fg=#5c5c66` |
## Keybindings
| Key | Action |
| --- | --- |
| `S-Enter` (no prefix) | Sends `Esc [13;2u` |
| `prefix t` | New window in pane cwd; on sessions with `@ssh_host` set (by the Vicinae tmux-sessions extension), runs `ssh <host>` instead |
| `prefix [` / `prefix H` | Previous window |
| `prefix ]` / `prefix L` | Next window |
| `prefix %` | Split right, 30% width, pane cwd |
| `prefix "` | Split below, 25% height, pane cwd |
| `prefix Escape` | Copy mode |
| `ctrl+h/j/k/l` (no prefix) | Select pane left/down/up/right, or forward the key if the pane runs vim/nvim/fzf (`is_vim`) |
| `prefix ctrl+l` | Send `ctrl+l` (clear screen) |
| `prefix o` | tmux-sessionx picker (`@sessionx-bind`) |
| `C-Space` (no prefix) | tmux-palette |
| `M-f` / `M-m` | tmux-palette find pane / move pane |
### Copy mode (vi)
| Key | Action |
| --- | --- |
| `v` | Begin selection |
| `y` | Copy to `wl-copy` and exit |
| `Y` | Copy to `wl-copy` and cancel |
| Mouse drag end | Copy to `wl-copy` |
| `ctrl+h/j/k/l` | Select pane |
## Plugins
| Plugin | Settings |
| --- | --- |
| `tmux-plugins/tpm` | Plugin manager |
| `tmux-plugins/tmux-sensible` | Defaults |
| `vaaleyard/tmux-dotbar` | Status line, see below |
| `tmux-plugins/tmux-resurrect` | nvim strategy `session`, captures pane contents, restores `ssh psql mysql sqlite3 purple lazygit lazydocker opencode` and `claude` as `claude --continue` |
| `joshmedeski/tmux-nerd-font-window-name` | Icons from `tmux-nerd-font-window-name.yml` |
| `omerxx/tmux-sessionx` | Bound to `o`, zoxide mode on, transparent fzf colors |
| `tmux-plugins/tmux-continuum` | Save every 10 min; auto-restore `off` (the `kitty-tmux` launcher restores) |
| `eduwass/tmux-palette` | Command palette |
### Status line (dotbar)
Top, rounded, centered (`absolute-centre`), left section on, right off, session on the left. Colors: bg `#0B0E14`, fg `#475266`, current `#BFBDB6`, session `#565B66`, prefix `#95E6CB`. Window format ` #W ` separated by ` • `; right text ` %H:%M `. Bold off. SSH indicator enabled with an icon; maximized icon only on the zoomed tab.
## tmux-nerd-font-window-name.yml
`show-name: true`, icon on the left, a fallback icon, blank multi-pane icon. Icons are defined for `mprocs`, `mm`, `macmon`, `make`, `zsh`, `nvim`, `devbox`, `psql`, `yazi`, `lazygit`, `gh`, `tv`, `docker`, `bun`, `node`, `npm`, `pnpm`, `go`, `bunx`, `claude`.
## niri-title.sh
Installed only on Linux `desktop`/`laptop` roles (gated in `.chezmoiignore.tmpl`). Given the pane command, path, tty and title, it prints a context segment for the window title read by [Niri](/desktop/niri), by priority:
1. `ssh`/`mosh-client`/`autossh`/`et`: the remote target.
2. `nvim`/`vim`: the pane title (current file).
3. Git repo: directory name and branch.
4. Otherwise the cwd basename.
`tmux.conf` does not currently call the script; its title string is `#T (#S)`.
docs/tools/bat.mdx
+72
View File
@@ -0,0 +1,72 @@
---
title: bat
description: bat with the cyberdream tmTheme, an external PureScript syntax, and automatic cache rebuilds on apply.
---
[bat](https://github.com/sharkdp/bat) is a `cat` replacement with syntax highlighting and git gutter marks. The repo sets its theme to cyberdream, adds a PureScript grammar, and rebuilds bat's cache whenever those inputs change.
| | |
| --- | --- |
| Sources | `dot_config/bat/config`, `dot_config/bat/themes/cyberdream.tmTheme` |
| External | `.config/bat/syntaxes/sublime-purescript-syntax` in `.chezmoiexternal.toml` |
| Targets | `~/.config/bat/config`, `~/.config/bat/themes/cyberdream.tmTheme`, `~/.config/bat/syntaxes/sublime-purescript-syntax/` |
| Packages | `bat` (pacman / Homebrew) |
## config
bat's config file holds default command-line flags. One is active:
```sh ~/.config/bat/config
--theme="cyberdream"
```
The file also carries bat's stock commented examples (`--italic-text=always`, `--paging=never`, a mouse-enabled `--pager`, `--map-syntax`); none are enabled.
## Theme
`cyberdream.tmTheme` is a TextMate theme named "Cyberdream". Base settings:
| Key | Color |
| --- | --- |
| `background` | `#16181a` |
| `foreground`, `caret` | `#ffffff` |
| `lineHighlight`, `selection` | `#3c4048` |
| `findHighlight` | `#5ef1ff` |
| `activeGuide` | `#ffbd5e` |
| `bracketsForeground` | `#ff5ea0` (underlined) |
| Comments | `#7b8496` |
The same file is also used outside bat:
- The [yazi](/tools/yazi) cyberdream flavor points `syntect_theme` at `~/.config/bat/themes/cyberdream.tmTheme`.
- Yazi text previews run `bat -p --color=always` through the piper plugin, so they get this theme via the config file.
## PureScript syntax
```toml .chezmoiexternal.toml
[".config/bat/syntaxes/sublime-purescript-syntax"]
type = "git-repo"
url = "https://github.com/tellnobody1/sublime-purescript-syntax.git"
[".config/bat/syntaxes/sublime-purescript-syntax".pull]
args = ["--ff-only"]
```
chezmoi clones the Sublime grammar when it is missing. With no `refreshPeriod`, it only pulls (`--ff-only`) on `chezmoi apply --refresh-externals`. See [externals and ignore rules](/chezmoi/externals-and-ignore).
## Cache rebuilds
bat only sees custom themes and syntaxes after `bat cache --build`. Two scripts run it:
| Script | When it runs |
| --- | --- |
| `run_onchange_after_build-bat-cache.sh.tmpl` | Embeds SHA-256 hashes of `cyberdream.tmTheme` and `config`, so it re-runs whenever either file changes. Exits quietly if `bat` is missing. |
| `.chezmoiscripts/run_onchange_after_40-post.sh.tmpl` | Post-apply housekeeping (also clones tpm and runs `fc-cache` on Linux). Runs `bat cache --build` when its own rendered content changes, which includes the first apply. |
:::note
Neither hash covers the PureScript external. If the grammar updates, run `bat cache --build` by hand.
:::
## Other consumers
- `lc-elir` previews candidate files with `bat --color=always --line-range=:40` inside fzf. See [LeetCode](/tools/leetcode).
- The kitty tab bar shows a book icon while `bat` runs.
docs/tools/git.mdx
+112
View File
@@ -0,0 +1,112 @@
---
title: Git
description: Global git config with templated identity, three diff pagers, an nvim difftool, and gh/tea credential helpers.
---
Git's global config is a single chezmoi template. It sets the commit identity from chezmoi data, routes diffs through diffnav and git-split-diffs, styles delta for the tools that call it, and delegates HTTPS credentials to `gh` and `tea`.
| | |
| --- | --- |
| Source | `dot_gitconfig.tmpl` |
| Target | `~/.gitconfig` |
| Type | Template (rendered, so it is written as a regular file, not a symlink) |
| Packages | Arch: `git`, `git-delta`, `diffnav` (pacman). macOS: `git`, `git-delta` (Homebrew) |
:::warning
`diffnav` is only in the Arch package list. On macOS, `git diff` still pages through `diffnav` per `pager.diff`, so install it manually there. `git-split-diffs` (the `core.pager`) is not declared in `packages.yaml` on either OS.
:::
## Identity
```ini ~/.gitconfig
[user]
email = {{ .email }}
name = {{ .name }}
```
`.name` and `.email` are prompted once by `.chezmoi.toml.tmpl` on the first `chezmoi init` and stored in the local chezmoi config. No role or OS condition changes this file.
## Pagers
Three pagers are configured, each for a different path:
| Setting | Value | Applies to |
| --- | --- | --- |
| `pager.diff` | `diffnav` | `git diff`: file-tree diff viewer built on delta |
| `core.pager` | `git-split-diffs --color`, piped into `less -+LFX` | Every other paged command (`git log -p`, `git show`, ...) |
| `[split-diffs] min-line-width` | `40` | git-split-diffs side-by-side threshold |
| `[split-diffs] theme-name` | `dark` | git-split-diffs theme |
`less -+LFX` resets the `-L`, `-F`, and `-X` flags, so less always takes over the screen and never exits early on short output.
### delta styling
The `[delta]` section is not a pager setting; delta reads it whenever it runs. Here that means diffnav and [lazygit](/tools/lazygit), which renders diffs with `delta --dark --paging=never`.
| Option | Value |
| --- | --- |
| `dark` | `true` |
| `tabs` | `2` |
| `file-style` / `file-decoration-style` | `omit` / `none` (no file header) |
| `line-numbers-left-format` | `"{nm:>4} "` |
| `line-numbers-right-format` | `"│ {np:>4} "` |
| `line-numbers-left-style` | `white dim` |
| `line-numbers-right-style` | `"#1f2335" dim` |
| `line-numbers-zero-style`, `-plus-style`, `-minus-style` | `white dim` |
| `wrap-left-symbol`, `wrap-right-symbol`, `wrap-right-prefix-symbol` | a single space each (wrap markers hidden) |
| `plus-style` | `syntax "#0e250e"` |
| `plus-emph-style` | `syntax "#103610"` |
| `minus-style` | `syntax "#402a26"` |
| `minus-emph-style` | `syntax "#45221c"` |
| `hunk-label` | a Nerd Font glyph |
| `hunk-header-line-number-style` | `"#10233A"` |
| `hunk-header-style` | `"#868E99"` |
| `hunk-header-file-style` | `"#868E99" dim` |
| `hunk-header-decoration-style` | `"#163050" ol ul` |
Added and removed lines keep syntax highlighting (`syntax` foreground) on dark green and dark red backgrounds.
## Difftool
```ini ~/.gitconfig
[diff]
tool = codediff
[difftool "codediff"]
cmd = nvim \"$LOCAL\" \"$REMOTE\" +\"CodeDiff file $LOCAL $REMOTE\"
```
`git difftool` opens both versions in [Neovim](/tools/neovim) and runs the `:CodeDiff` command, which comes from the external nvim config. Lazygit's `openDiffTool` binding (`<c-t>`) uses the same tool.
## Remotes and push
| Setting | Value | Effect |
| --- | --- | --- |
| `url "git@github.com:".pushInsteadOf` | `https://github.com/` | Remotes cloned over HTTPS push over SSH; fetches stay on HTTPS. |
| `push.autoSetupRemote` | `true` | First `git push` on a new branch sets its upstream automatically. |
| `advice.addIgnoredFile` | `false` | Silences the hint when `git add` touches an ignored path. |
| `beads.role` | `maintainer` | Role read by the beads (`bd`) issue tracker. |
## Credential helpers
Each host block first sets an empty `helper =`, which clears any helper inherited from system config, then adds one helper:
| Host | Helper | Notes |
| --- | --- | --- |
| `https://github.com` | `!gh auth git-credential` | Uses the token from `gh auth login`. See [GitHub CLI](/tools/github-cli). |
| `https://gist.github.com` | `!gh auth git-credential` | Same as above, for gists. |
| `https://prad.codes` | `!tea login helper` | Self-hosted Gitea; uses the login stored by the `tea` CLI. |
No credentials are stored in the file itself.
## Related helpers
These git-adjacent commands live in `~/.local/bin` and the shell function directories. See [shell scripts](/shell/scripts) for the full set.
| Command | What it does |
| --- | --- |
| `gdc` | Asks for confirmation with `gum confirm`, then runs `git reset --hard HEAD` and `git clean -fd`. |
| `gop` | Opens a repo's web page for any forge whose layout is `https://<host>/<owner>/<repo>`; defaults to `origin`, then `upstream`. |
| `git-summary` | Aggregates every `AGENTS.md` in the current repo through `code2prompt`. |
| `ghg` / `ghg-clone` | `ghq get` a repo and `cd` into the clone. |
| `ghn` | Creates a private repo on prad.codes (via `tea`) or github.com (via `gh`), clones it with ghq, and `cd`s into it. |
| `gho` | Picks a ghq repo or Obsidian vault with fzf and `cd`s into it. |
docs/tools/github-cli.mdx
+165
View File
@@ -0,0 +1,165 @@
---
title: GitHub CLI
description: gh config and aliases, the four gh extensions installed on apply, and the gh-dash dashboard layout.
---
`gh` is GitHub's official CLI. The repo manages its global config, installs a fixed set of extensions, and configures [gh-dash](https://github.com/dlvhdr/gh-dash), a TUI dashboard for pull requests, issues, and notifications.
| | |
| --- | --- |
| Sources | `dot_config/gh/private_config.yml`, `dot_config/gh-dash/config.yml` |
| Targets | `~/.config/gh/config.yml` (mode `0600`, from the `private_` prefix), `~/.config/gh-dash/config.yml` |
| Packages | Arch: `github-cli` (pacman). macOS: `gh` (Homebrew) |
| Extensions | `packages.shared.gh_extensions` in `.chezmoidata/packages.yaml` |
:::note
Authentication is per machine: run `gh auth login` once. Tokens live in gh's `hosts.yml` or the system keyring, which the repo does not manage.
:::
## gh config
| Key | Value | Effect |
| --- | --- | --- |
| `version` | `1` | Config schema version. |
| `git_protocol` | `https` | gh clones and adds remotes over HTTPS. Pushes still go over SSH because of the `pushInsteadOf` rewrite in [Git](/tools/git). |
| `editor` | empty | Falls back to the environment; fish exports `EDITOR=nvim`. |
| `prompt` | `enabled` | Interactive prompts on. |
| `prefer_editor_prompt` | `disabled` | Prompts inline instead of opening an editor. |
| `pager` | empty | Falls back to the environment. |
| `http_unix_socket` | empty | Default transport. |
| `browser` | empty | Falls back to the environment. |
| `color_labels` | `disabled` | Labels are not drawn in their RGB colors. |
| `accessible_colors` | `disabled` | |
| `accessible_prompter` | `disabled` | |
| `spinner` | `enabled` | Animated progress spinner. |
### Aliases
| Alias | Expands to |
| --- | --- |
| `gh co` | `gh pr checkout` |
## Extensions
| Extension | Command | Purpose |
| --- | --- | --- |
| `davidraviv/gh-clean-branches` | `gh clean-branches` | Deletes local branches that no longer have a remote counterpart. |
| `prdlk/gh-commit` | `gh commit` | The owner's commit helper; lazygit binds it as "Smart commit with AI". |
| `dlvhdr/gh-dash` | `gh dash` | PR, issue, and notification dashboard (configured below). |
| `meiji163/gh-notify` | `gh notify` | Notification viewer. |
`.chezmoiscripts/run_onchange_after_20-gh-extensions.sh.tmpl` installs them:
<Steps>
<Step title="Re-run trigger">
The rendered script embeds a SHA-256 of the `gh_extensions` list, so chezmoi re-runs it whenever the list changes.
</Step>
<Step title="Guards">
If `gh` is missing, or `gh auth status` fails, it prints a warning and exits 0. Run `gh auth login`, then `chezmoi apply` again.
</Step>
<Step title="Install">
Reads `gh extension list` and runs `gh extension install` only for entries not already present.
</Step>
</Steps>
See [chezmoi scripts](/chezmoi/scripts) for the full script order.
## gh-dash
Launched with `gh dash`, or <kbd>Ctrl</kbd>+<kbd>d</kbd> in lazygit's files panel.
### Sections
<Tabs>
<Tab title="Pull requests">
| Title | Filter |
| --- | --- |
| My Pull Requests | `is:open author:@me` |
| Needs My Review | `is:open review-requested:@me` |
| Involved | `is:open involves:@me -author:@me` |
</Tab>
<Tab title="Issues">
| Title | Filter |
| --- | --- |
| My Issues | `is:open author:@me` |
| Assigned | `is:open assignee:@me` |
| Involved | `is:open involves:@me -author:@me` |
</Tab>
<Tab title="Notifications">
| Title | Filter |
| --- | --- |
| All | (none) |
| Created | `reason:author` |
| Participating | `reason:participating` |
| Mentioned | `reason:mention` |
| Review Requested | `reason:review-requested` |
| Assigned | `reason:assign` |
| Subscribed | `reason:subscribed` |
| Team Mentioned | `reason:team-mention` |
</Tab>
</Tabs>
### Defaults
| Key | Value |
| --- | --- |
| `defaults.view` | `prs` |
| `defaults.preview.open` / `width` | `true` / `0.45` |
| `defaults.prsLimit`, `issuesLimit`, `notificationsLimit` | `20` each |
| `defaults.prApproveComment` | `LGTM` |
| `defaults.refetchIntervalMinutes` | `30` |
| `repo.branchesRefetchIntervalSeconds` | `30` |
| `repo.prsRefetchIntervalSeconds` | `60` |
| `repoPaths` | empty |
| `confirmQuit` | `false` |
| `showAuthorIcons` | `true` |
| `smartFilteringAtLaunch` | `true` |
| `includeReadNotifications` | `true` |
| `theme.ui.sectionsShowCount` | `true` |
| `theme.ui.table.showSeparator` / `compact` | `true` / `false` |
### Column layout
| View | Column | Width | Hidden |
| --- | --- | --- | --- |
| PRs | `updatedAt`, `createdAt` | 5 | no |
| PRs | `repo` | 20 | no |
| PRs | `author` | 15 | no |
| PRs | `authorIcon` | | no |
| PRs | `assignees` | 20 | yes |
| PRs | `base` | 15 | yes |
| PRs | `lines` | 15 | no |
| Issues | `updatedAt`, `createdAt` | 5 | no |
| Issues | `repo` | 15 | no |
| Issues | `creator` | 10 | no |
| Issues | `creatorIcon` | | no |
| Issues | `assignees` | 20 | yes |
### Keybindings
| View | Key | Command |
| --- | --- | --- |
| PRs | <kbd>T</kbd> | `gh enhance -R {{.RepoName}} {{.PrNumber}}` |
`gh enhance` is a gh extension that is not in the managed extension list; install it separately for this binding to work.
### Pager
```yaml ~/.config/gh-dash/config.yml
pager:
diff: "hunk pager"
```
PR diffs open in [Hunk](/tools/hunk).
## Other integrations
- [Lazygit](/tools/lazygit) custom commands call `gh repo sync && gh clean-branches --force`, `gh commit`, `gh pr create --fill -w`, `gh dash`, and `gh browse`.
- `ghn` creates github.com repos with `gh`, and `gh-sonr-org-migrate` scripts gh for an org migration.
- The tmux window-name map gives `gh` its own Nerd Font icon.
docs/tools/hunk.mdx
+59
View File
@@ -0,0 +1,59 @@
---
title: Hunk
description: Hunk terminal diff viewer settings, used as the gh-dash diff pager.
---
[Hunk](https://github.com/modem-dev/hunk) is a review-first terminal diff viewer aimed at agent-authored changes. In this setup it is the diff pager for [gh-dash](/tools/github-cli#gh-dash).
| | |
| --- | --- |
| Sources | `dot_config/hunk/config.toml`, `dot_config/hunk/private_state.json` |
| Targets | `~/.config/hunk/config.toml`, `~/.config/hunk/state.json` (mode `0600`) |
| Packages | Not declared in `packages.yaml`; install hunk separately |
## config.toml
```toml ~/.config/hunk/config.toml
theme = "auto"
mode = "auto"
vcs = "git"
watch = false
exclude_untracked = true
line_numbers = true
tab_width = 4
wrap_lines = false
menu_bar = true
agent_notes = true
prompt_save_view_preferences = false
transparent_background = true
```
| Key | Value | Effect |
| --- | --- | --- |
| `theme` | `auto` | Picks a built-in theme to match the terminal. |
| `mode` | `auto` | Chooses split or stacked layout from the window width (alternatives: `split`, `stack`). |
| `vcs` | `git` | Git backend (alternatives: `jj`, `sl`). |
| `watch` | `false` | Does not reload on file changes. |
| `exclude_untracked` | `true` | Untracked files are left out of working-tree diffs. |
| `line_numbers` | `true` | Shows line numbers. |
| `tab_width` | `4` | Tab stops every 4 columns. |
| `wrap_lines` | `false` | Long lines are not wrapped. |
| `menu_bar` | `true` | Shows the top menu bar. |
| `agent_notes` | `true` | Shows agent notes when a review opens (off by default in hunk). |
| `prompt_save_view_preferences` | `false` | Does not ask to persist view changes. |
| `transparent_background` | `true` | Uses the terminal background instead of the theme's. |
No `[pager]` or per-command sections are set, so pager sessions use these top-level values.
## state.json
`private_state.json` is hunk's runtime state: the state-file `version` and `lastSeenCliVersion`, which hunk updates on its own. It holds no preferences. The `private_` prefix gives it mode `0600`.
## Integrations
```yaml ~/.config/gh-dash/config.yml
pager:
diff: "hunk pager"
```
gh-dash pipes PR diffs into `hunk pager`. Plain `git diff` does not use hunk; it goes through diffnav (see [Git](/tools/git)).
docs/tools/index.mdx
+70
View File
@@ -0,0 +1,70 @@
---
title: Tools
description: CLI and TUI tools the repo installs and configures, with the settings applied to each.
sidebar:
label: Overview
---
This section covers the command-line and terminal-UI tools outside the shell, terminal, and desktop layers. Every tool here is universal: none of it is gated by machine role, so `desktop`, `laptop`, `mac`, and `server` machines all get it (see [Installation](/installation)).
Packages come from `.chezmoidata/packages.yaml` and are installed by `run_onchange_before_10-packages.sh.tmpl` (pacman plus paru for the AUR on Arch, Homebrew on macOS). See [chezmoi scripts](/chezmoi/scripts).
## Configured tools
| Page | Tool | Source in repo | Theme |
| --- | --- | --- | --- |
| [Git](/tools/git) | git, delta, diffnav, git-split-diffs | `dot_gitconfig.tmpl` | delta colors hand-tuned (dark) |
| [GitHub CLI](/tools/github-cli) | gh, gh extensions, gh-dash | `dot_config/gh/`, `dot_config/gh-dash/` | gh-dash defaults |
| [Neovim](/tools/neovim) | nvim (AstroNvim) | external repo via `.chezmoiexternal.toml` | managed in the nvim repo |
| [Yazi](/tools/yazi) | yazi file manager | `dot_config/yazi/` | cyberdream flavor (ii-auto and noctalia flavors shipped) |
| [Lazygit](/tools/lazygit) | lazygit | `dot_config/lazygit/` | cyberdream colors (ii theme file shipped) |
| [Lazydocker](/tools/lazydocker) | lazydocker | `dot_config/lazydocker/config.yml` | cyberdream colors |
| [bat](/tools/bat) | bat | `dot_config/bat/` | cyberdream tmTheme |
| [Topgrade](/tools/topgrade) | topgrade | `dot_config/topgrade.toml` | n/a |
| [Hunk](/tools/hunk) | hunk diff viewer | `dot_config/hunk/config.toml` | `auto` |
| [LeetCode](/tools/leetcode) | leetcode CLI, `lc-elir` | `dot_leetcode/` | n/a |
<CardGroup cols={2}>
<Card title="Git" href="/tools/git" icon="git-branch">
Identity from chezmoi data, diff pagers, gh credential helper.
</Card>
<Card title="Yazi" href="/tools/yazi" icon="folder-open">
Keymap, plugins, bookmarks, and the Neovim bridge.
</Card>
<Card title="Lazygit" href="/tools/lazygit" icon="git-commit-horizontal">
GUI options, delta renderer, custom gh commands.
</Card>
<Card title="GitHub CLI" href="/tools/github-cli" icon="github">
Aliases, extensions, and the gh-dash dashboard.
</Card>
</CardGroup>
## Other packaged CLI tools
These packages are declared in `.chezmoidata/packages.yaml` but have no config file in the repo. The "Wired in" column lists where the repo actually uses them.
| Tool | Role | Wired in |
| --- | --- | --- |
| `fzf` | Fuzzy finder | `FZF_DEFAULT_OPTS` in `dot_config/fish/conf.d/10-env.fish` (rounded border, cyberdream colors: highlight `#5ef1ff`, pointer `#ffaecf`, marker `#5eff6c`). Used by fish functions `c2p`, `cp-appid`, `fab`, `gtm`, `mdp`, `lc-elir`, by `~/.local/bin` scripts (`gho`, `pj`, `lc-elir`), and as `fuzzy_cmd` of the yazi bunny plugin. |
| `fd` | File finder | `c2p`, `cp-appid`, `extract_agents`, `mdp`, `lc-elir`, `conf.d/pnpm-filter.fish`. |
| `ripgrep` | Content search | `cp-appid`, `gtm`, `gh-sonr-org-migrate` fish functions; niri focus script. |
| `zoxide` | Frecency `cd` | `zoxide init fish` in `conf.d/40-tools.fish`; the `cd` function in fish/bash/zsh falls back to `zoxide query` when the argument is not a directory, and `ghg-clone` registers new clones. |
| `eza` | `ls` replacement | Interactive shells alias `ls` to `eza --icons` (fish `conf.d/20-aliases.fish`, `~/.config/shell/aliases.sh`). |
| `jq` | JSON processor | `fab`, `gtm`, `gh-sonr-org-migrate`, `pnpm-filter`, niri helper scripts. |
| `duf` | Disk usage overview | Not referenced by any config. |
| `btop` | Resource monitor | Waybar modules launch it on click (`omarchy-launch-or-focus-tui btop`); kitty tab bar shows an icon for it. |
| `fastfetch` | System info | Not referenced by any config. |
| `gum` | Shell prompts and pickers | `gdc` (confirm before `git reset --hard`), `ghn` (host and org pickers), `gtm`, `ai`, `pnpm-filter`, nvm activation messages. |
| `glow` | Markdown renderer | Kitty tab-bar icon only. |
| `micro` | Terminal editor | Alias `sm` = `sudo micro`. |
| `ffmpeg`, `ffmpegthumbnailer`, `poppler`, `resvg`, `imagemagick`, `7zip`, `unzip` | Media, PDF, SVG, image, and archive backends | Grouped in the manifest as yazi preview dependencies. See [Yazi](/tools/yazi). |
| `wget` | HTTP downloads | Not referenced by any config. |
| `zsh-syntax-highlighting` | zsh highlighting | Sourced by the zsh setup. See [Shell](/shell). |
| `ttf-victor-mono-nerd` / `font-victor-mono-nerd-font` | Nerd Font | Terminal font. See [Terminal](/terminal). |
| `suvadu` | Declared under `packages.shared.cargo` | No install script reads the `cargo` list, so it is not installed automatically. |
Tools with their own pages in other sections: [fish](/shell/fish), [starship](/shell/starship), and [atuin](/shell/atuin) under Shell; [kitty](/terminal/kitty) and [tmux](/terminal/tmux) under Terminal.
:::note
`diffnav` is in the Arch pacman list but not in the macOS Homebrew list, and `topgrade` comes from the AUR on Arch. See the individual pages for per-OS differences.
:::
docs/tools/lazydocker.mdx
+46
View File
@@ -0,0 +1,46 @@
---
title: Lazydocker
description: Lazydocker with rounded borders and the cyberdream border and selection colors shared with lazygit.
---
[Lazydocker](https://github.com/jesseduffield/lazydocker) is a terminal UI for Docker containers, images, volumes, and compose projects. The config only restyles it to match [lazygit](/tools/lazygit).
| | |
| --- | --- |
| Source | `dot_config/lazydocker/config.yml` |
| Target | `~/.config/lazydocker/config.yml` |
| Packages | `lazydocker` (pacman / Homebrew) |
## Settings
```yaml ~/.config/lazydocker/config.yml
gui:
border: rounded
theme:
activeBorderColor:
- "#5ef1ff"
inactiveBorderColor:
- "#7b8496"
selectedLineBgColor:
- "#3c4048"
optionsTextColor:
- "#7b8496"
```
| Key | Value | Palette |
| --- | --- | --- |
| `gui.border` | `rounded` | |
| `activeBorderColor` | `#5ef1ff` | cyberdream cyan |
| `inactiveBorderColor` | `#7b8496` | cyberdream grey |
| `selectedLineBgColor` | `#3c4048` | cyberdream selection |
| `optionsTextColor` | `#7b8496` | cyberdream grey |
Everything else (keybindings, commands, log settings) is left at lazydocker's defaults.
## Launching
| Entry point | Behavior |
| --- | --- |
| `dd` | Alias for `lazydocker` in fish, bash, and zsh. It shadows the coreutils `dd` binary wherever the aliases are loaded; use `command dd` for the real one. |
tmux-resurrect lists `lazydocker` among the processes it restores, and the kitty tab bar shows a Docker icon while it runs.
docs/tools/lazygit.mdx
+294
View File
@@ -0,0 +1,294 @@
---
title: Lazygit
description: Lazygit with cyberdream colors, delta diffs, a full keybinding map, and custom commands wired to gh and helper scripts.
---
[Lazygit](https://github.com/jesseduffield/lazygit) is a terminal UI for git. The config sets cyberdream colors, renders diffs with delta, turns on background fetching and a whole-graph log, and adds custom commands that call `gh`.
| | |
| --- | --- |
| Source | `dot_config/lazygit/config.yml`, `dot_config/lazygit/ii-theme.yml` |
| Target | `~/.config/lazygit/config.yml`, `~/.config/lazygit/ii-theme.yml` |
| Packages | `lazygit` (pacman / Homebrew) |
| Ignored | `.config/lazygit/.omc/**` (agent tooling state) |
## Launching
| Entry point | Behavior |
| --- | --- |
| `gg` | Alias for `lazygit` (all shells) |
| <kbd>Ctrl</kbd>+<kbd>g</kbd> | fish and zsh keybinding |
| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>g</kbd> | [Kitty](/terminal/kitty): lazygit as an overlay on the current window. The tmux-host kitty config opens it in a 90% `tmux display-popup` instead. |
tmux-resurrect lists `lazygit` among the processes it restores.
## GUI
Colors come from the cyberdream palette:
| Theme key | Color |
| --- | --- |
| `activeBorderColor` | `#5ef1ff` |
| `inactiveBorderColor` | `#7b8496` |
| `searchingActiveBorderColor` | `#ff5ef1` |
| `optionsTextColor` | `#7b8496` |
| `selectedLineBgColor` | `#3c4048` |
| `cherryPickedCommitBgColor` | `#3c4048` |
| `cherryPickedCommitFgColor` | `#ff5ea0` |
| `unstagedChangesColor` | `#ffbd5e` |
| `defaultFgColor` | `#ffffff` |
| `authorColors."*"` | `#ffffff` (every author the same color) |
| Option | Value |
| --- | --- |
| `border` | `rounded` |
| `scrollHeight` / `scrollPastBottom` | `2` / `true` |
| `scrollOffMargin` / `scrollOffBehavior` | `2` / `margin` |
| `mouseEvents` | `true` |
| `skipDiscardChangeWarning` | `true` |
| `skipStashWarning` | `true` |
| `skipNoStagedFilesWarning` | `false` |
| `skipRewordInEditorWarning` | `false` |
| `sidePanelWidth` | `0.4` |
| `expandFocusedSidePanel` / `expandedSidePanelWeight` | `true` / `2` |
| `mainPanelSplitMode` | `horizontal` |
| `enlargedSideViewLocation` | `left` |
| `language` | `auto` |
| `timeFormat` / `shortTimeFormat` | `02 Jan 06` / `3:04PM` |
| `commitLength.show` | `true` |
| `showListFooter` | `true` |
| `showFileTree` | `true` |
| `showRandomTip` | `false` |
| `showCommandLog` / `commandLogSize` | `true` / `4` |
| `showBottomLine` | `false` (keybinding hint line hidden) |
| `showPanelJumps` | `false` |
| `showIcons`, `nerdFontsVersion`, `showFileIcons` | `true`, `"3"`, `true` |
| `commitAuthorShortLength` / `commitAuthorLongLength` | `2` (initials) / `17` |
| `commitHashLength` | `8` |
| `showBranchCommitHash` | `true` |
| `showDivergenceFromBaseBranch` | `arrowAndNumber` |
| `splitDiff` | `auto` |
| `screenMode` | `normal` |
| `animateExplosion` | `true` |
| `portraitMode` | `auto` |
| `filterMode` | `fuzzy` |
| `spinner.frames` / `spinner.rate` | ASCII bar (`\|`, `/`, `-`, `\`) / `50` ms |
| `statusPanelView` | `allBranchesLog` |
## Git
| Option | Value |
| --- | --- |
| `diffRenderers` | `delta --dark --paging=never` with `colorArg: always`. delta also reads the `[delta]` section of `~/.gitconfig`; see [Git](/tools/git). |
| `commit.signOff` | `false` |
| `commit.autoWrapCommitMessage` / `autoWrapWidth` | `true` / `72` |
| `merging.manualCommit` / `args` | `false` / empty |
| `merging.squashMergeMessage` | `Squash merge {{selectedRef}} into {{currentBranch}}` |
| `mainBranches` | `develop` |
| `skipHookPrefix` | `WIP` (a message starting with `WIP` skips pre-commit hooks) |
| `autoFetch` / `autoRefresh` / `fetchAll` | `true` / `true` / `true` |
| `branchLogCmd` | `git log --graph --color=always --abbrev-commit --decorate --date=relative --pretty=medium {{branchName}} --` |
| `allBranchesLogCmds` | `git log --graph --all --color=always --abbrev-commit --decorate --date=relative --pretty=medium` |
| `overrideGpg` | `false` |
| `disableForcePushing` | `false` |
| `commitPrefix` / `branchPrefix` | empty |
| `parseEmoji` | `true` |
| `log.order` / `showGraph` / `showWholeGraph` | `topo-order` / `always` / `true` |
| `truncateCopiedCommitHashesTo` | `8` |
## Refresh, updates, and OS
| Option | Value |
| --- | --- |
| `update.method` / `days` | `background` / `14` |
| `refresher.refreshInterval` | `10` s |
| `refresher.fetchInterval` | `60` s |
| `confirmOnQuit` | `false` |
| `quitOnTopLevelReturn` | `true` (<kbd>Esc</kbd> at top level quits) |
| `disableStartupPopups` | `true` |
| `notARepository` | `skip` (opens the most recent repo) |
| `promptToReturnFromSubprocess` | `false` |
| `os.edit`, `editAtLine`, `editAtLineAndWait`, `openDirInEditor`, `editPreset`, `open` | empty (lazygit defaults, which follow `$EDITOR` = nvim) |
| `os.openLink` | `bash -C` running `~/.local/share/omarchy/bin/omarchy-launch-webapp {{link}}` (absolute path in the file) |
| `os.copyToClipboardCmd` / `readFromClipboardCmd` | `wl-copy` / `wl-paste` |
:::note
The link opener and the `wl-copy`/`wl-paste` clipboard commands are Wayland/Omarchy-specific. On macOS or a server they are unavailable, so opening links and clipboard actions fail there.
:::
## Custom commands
| Key | Context | Command | Output |
| --- | --- | --- | --- |
| <kbd>Ctrl</kbd>+<kbd>i</kbd> | global | `gitv {{.Repository.Owner}}/{{.Repository.Name}}` | terminal |
| <kbd>Ctrl</kbd>+<kbd>w</kbd> | global | `gwm` | terminal |
| <kbd>Ctrl</kbd>+<kbd>a</kbd> | global | `wrkflw` | terminal |
| <kbd>Ctrl</kbd>+<kbd>p</kbd> | global | `github prs` | terminal |
| <kbd>F</kbd> | files | `gh repo sync && gh clean-branches --force` ("Sync repo and clean branches, update DuckDB cache") | log |
| <kbd>A</kbd> | files | `gh commit` ("Smart commit with AI") | terminal |
| <kbd>C</kbd> | files | `gh commit` ("Smart commit with AI") | terminal |
| <kbd>a</kbd> | files | `git add` the file if it has unstaged changes, else `git reset` it ("Toggle file staged") | |
| <kbd>L</kbd> | files | `livediff` | terminal |
| <kbd>Ctrl</kbd>+<kbd>d</kbd> | files | `gh dash` | terminal |
| <kbd>Ctrl</kbd>+<kbd>o</kbd> | files | `gh browse` | |
| <kbd>o</kbd> | localBranches | `gh pr create --fill -w` ("start ai pull request") | |
| <kbd>C</kbd> | localBranches | `gh repo sync && gh clean-branches --force` | log |
| <kbd>O</kbd> | commits | `hub browse -- "commit/{{.SelectedLocalCommit.Hash}}"` | |
`gh commit`, `gh clean-branches`, and `gh dash` are managed gh extensions (see [GitHub CLI](/tools/github-cli)). `gitv`, `gwm`, `wrkflw`, `github`, `livediff`, and `hub` are not installed by this repo.
:::warning
Several custom keys share a key with a built-in binding in the same context: <kbd>C</kbd> and <kbd>a</kbd> in files (`commitChangesWithEditor`, `toggleStagedAll`), <kbd>Ctrl</kbd>+<kbd>w</kbd>, <kbd>Ctrl</kbd>+<kbd>p</kbd>, <kbd>Ctrl</kbd>+<kbd>d</kbd>, <kbd>Ctrl</kbd>+<kbd>o</kbd> against universal bindings, and <kbd>O</kbd> in commits. <kbd>Ctrl</kbd>+<kbd>i</kbd> is the same keycode as <kbd>Tab</kbd> in most terminals.
:::
## Keybindings
The file writes out the full keybinding map. Most values match lazygit's defaults; they are listed so the file is the single reference.
<Accordion>
<AccordionItem title="Universal">
| Action | Key |
| --- | --- |
| `quit` / `quit-alt1` | <kbd>q</kbd> / <kbd>Ctrl</kbd>+<kbd>q</kbd> |
| `return` | <kbd>Esc</kbd> |
| `quitWithoutChangingDirectory` | <kbd>Q</kbd> |
| `togglePanel` | <kbd>Tab</kbd> |
| `prevItem` / `nextItem` | <kbd>Up</kbd> / <kbd>Down</kbd> |
| `prevItem-alt` / `nextItem-alt` | <kbd>k</kbd> / <kbd>j</kbd> |
| `prevPage` / `nextPage` | <kbd>,</kbd> / <kbd>.</kbd> |
| `scrollLeft` / `scrollRight` | <kbd>H</kbd> / <kbd>L</kbd> |
| `gotoTop` / `gotoBottom` | `<` / `>` |
| `toggleRangeSelect` | <kbd>v</kbd> |
| `rangeSelectDown` / `rangeSelectUp` | <kbd>Shift</kbd>+<kbd>Down</kbd> / <kbd>Shift</kbd>+<kbd>Up</kbd> |
| `prevBlock` / `nextBlock` | <kbd>Left</kbd> / <kbd>Right</kbd> |
| `prevBlock-alt` / `nextBlock-alt` | <kbd>h</kbd> / <kbd>l</kbd> |
| `nextBlock-alt2` / `prevBlock-alt2` | <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> |
| `jumpToBlock` | <kbd>1</kbd>–<kbd>5</kbd> |
| `nextMatch` / `prevMatch` | <kbd>n</kbd> / <kbd>N</kbd> |
| `startSearch` | <kbd>/</kbd> |
| `optionMenu` | <kbd>?</kbd> |
| `select` | <kbd>Space</kbd> |
| `goInto` / `confirm` | <kbd>Enter</kbd> |
| `confirmInEditor` | <kbd>Alt</kbd>+<kbd>Enter</kbd> |
| `remove` | <kbd>d</kbd> |
| `new` | <kbd>n</kbd> |
| `edit` | <kbd>e</kbd> |
| `openFile` | <kbd>o</kbd> |
| `scrollUpMain` / `scrollDownMain` | <kbd>PgUp</kbd> / <kbd>PgDn</kbd> |
| `scrollUpMain-alt1` / `scrollDownMain-alt1` | <kbd>K</kbd> / <kbd>J</kbd> |
| `scrollUpMain-alt2` / `scrollDownMain-alt2` | <kbd>Ctrl</kbd>+<kbd>u</kbd> / <kbd>Ctrl</kbd>+<kbd>d</kbd> |
| `createRebaseOptionsMenu` | <kbd>m</kbd> |
| `pushFiles` / `pullFiles` | <kbd>P</kbd> / <kbd>p</kbd> |
| `refresh` | <kbd>R</kbd> |
| `createPatchOptionsMenu` | <kbd>Ctrl</kbd>+<kbd>p</kbd> |
| `nextTab` / `prevTab` | <kbd>]</kbd> / <kbd>[</kbd> |
| `nextScreenMode` / `prevScreenMode` | <kbd>+</kbd> / <kbd>_</kbd> |
| `undo` / `redo` | <kbd>z</kbd> / <kbd>Ctrl</kbd>+<kbd>z</kbd> |
| `filteringMenu` | <kbd>Ctrl</kbd>+<kbd>s</kbd> |
| `diffingMenu` / `diffingMenu-alt` | <kbd>W</kbd> / <kbd>Ctrl</kbd>+<kbd>e</kbd> |
| `copyToClipboard` | <kbd>Ctrl</kbd>+<kbd>o</kbd> |
| `openRecentRepos` | <kbd>Ctrl</kbd>+<kbd>r</kbd> |
| `submitEditorText` | <kbd>Enter</kbd> |
| `extrasMenu` | <kbd>@</kbd> |
| `toggleWhitespaceInDiffView` | <kbd>Ctrl</kbd>+<kbd>w</kbd> |
| `increaseContextInDiffView` / `decreaseContextInDiffView` | `}` / `{` |
| `increaseRenameSimilarityThreshold` / `decrease...` | <kbd>)</kbd> / <kbd>(</kbd> |
| `openDiffTool` | <kbd>Ctrl</kbd>+<kbd>t</kbd> (runs the nvim `codediff` difftool) |
| `newWorktree` | <kbd>w</kbd> |
</AccordionItem>
<AccordionItem title="Status">
| Action | Key |
| --- | --- |
| `checkForUpdate` | <kbd>u</kbd> |
| `recentRepos` | <kbd>Enter</kbd> |
| `allBranchesLogGraph` | <kbd>a</kbd> |
</AccordionItem>
<AccordionItem title="Files">
| Action | Key |
| --- | --- |
| `commitChanges` | <kbd>c</kbd> |
| `commitChangesWithoutHook` | <kbd>w</kbd> |
| `amendLastCommit` | <kbd>E</kbd> |
| `commitChangesWithEditor` | <kbd>C</kbd> |
| `findBaseCommitForFixup` | <kbd>Ctrl</kbd>+<kbd>f</kbd> |
| `confirmDiscard` | <kbd>x</kbd> |
| `ignoreFile` | <kbd>i</kbd> |
| `refreshFiles` | <kbd>r</kbd> |
| `stashAllChanges` / `viewStashOptions` | <kbd>s</kbd> / <kbd>S</kbd> |
| `toggleStagedAll` | <kbd>a</kbd> |
| `viewResetOptions` | <kbd>D</kbd> |
| `fetch` | <kbd>f</kbd> |
| `toggleTreeView` | `` ` `` |
| `openMergeOptions` | <kbd>M</kbd> |
| `openStatusFilter` | <kbd>Ctrl</kbd>+<kbd>b</kbd> |
| `copyFileInfoToClipboard` | <kbd>y</kbd> |
</AccordionItem>
<AccordionItem title="Branches">
| Action | Key |
| --- | --- |
| `createPullRequest` | <kbd>1</kbd> |
| `viewPullRequestOptions` | <kbd>O</kbd> |
| `copyPullRequestURL` | <kbd>Ctrl</kbd>+<kbd>y</kbd> |
| `checkoutBranchByName` | <kbd>c</kbd> |
| `forceCheckoutBranch` | <kbd>F</kbd> |
| `rebaseBranch` | <kbd>r</kbd> |
| `renameBranch` | <kbd>R</kbd> |
| `mergeIntoCurrentBranch` | <kbd>M</kbd> |
| `viewGitFlowOptions` | <kbd>i</kbd> |
| `fastForward` / `fetchRemote` | <kbd>f</kbd> |
| `createTag` / `pushTag` | <kbd>T</kbd> / <kbd>P</kbd> |
| `setUpstream` | <kbd>u</kbd> |
| `sortOrder` | <kbd>s</kbd> |
</AccordionItem>
<AccordionItem title="Commits">
| Action | Key |
| --- | --- |
| `squashDown` | <kbd>s</kbd> |
| `renameCommit` / `renameCommitWithEditor` | <kbd>r</kbd> / <kbd>R</kbd> |
| `viewResetOptions` | <kbd>g</kbd> |
| `markCommitAsFixup` / `createFixupCommit` | <kbd>f</kbd> / <kbd>F</kbd> |
| `squashAboveCommits` | <kbd>S</kbd> |
| `moveDownCommit` / `moveUpCommit` | <kbd>Ctrl</kbd>+<kbd>j</kbd> / <kbd>Ctrl</kbd>+<kbd>k</kbd> |
| `resetCommitAuthor` | <kbd>a</kbd> |
| `pickCommit` | <kbd>p</kbd> |
| `revertCommit` | <kbd>t</kbd> |
| `cherryPickCopy` / `pasteCommits` | <kbd>C</kbd> / <kbd>V</kbd> |
| `markCommitAsBaseForRebase` | <kbd>B</kbd> |
| `tagCommit` | <kbd>T</kbd> |
| `checkoutCommit` | <kbd>Space</kbd> |
| `resetCherryPick` | <kbd>Ctrl</kbd>+<kbd>c</kbd> |
| `copyCommitAttributeToClipboard` | <kbd>y</kbd> |
| `openLogMenu` | <kbd>Ctrl</kbd>+<kbd>l</kbd> |
| `openInBrowser` | <kbd>o</kbd> |
| `viewBisectOptions` | <kbd>b</kbd> |
| `startInteractiveRebase` | <kbd>i</kbd> |
</AccordionItem>
<AccordionItem title="Other panels">
| Panel | Action | Key |
| --- | --- | --- |
| amendAttribute | `resetAuthor` / `setAuthor` / `addCoAuthor` | <kbd>a</kbd> / <kbd>A</kbd> / <kbd>c</kbd> |
| stash | `popStash` / `renameStash` | <kbd>g</kbd> / <kbd>r</kbd> |
| commitFiles | `checkoutCommitFile` | <kbd>c</kbd> |
| main | `toggleSelectHunk` / `pickBothHunks` / `editSelectHunk` | <kbd>a</kbd> / <kbd>b</kbd> / <kbd>E</kbd> |
| submodules | `init` / `update` / `bulkMenu` | <kbd>i</kbd> / <kbd>u</kbd> / <kbd>b</kbd> |
| commitMessage | `commitMenu` | <kbd>Ctrl</kbd>+<kbd>o</kbd> |
</AccordionItem>
</Accordion>
## ii-theme.yml
`ii-theme.yml` is generated by the ii wallpaper theming system and holds only a `gui.theme` block: white active border (bold), grey `#8F9192` inactive border, `#1F1F1F` selection and cherry-pick backgrounds, `#FFF17B` marked base commit, `#FF9BAD` unstaged changes, `#DFE3E3` default text.
Nothing in the repo loads it, so `config.yml`'s cyberdream colors are what lazygit uses. To apply it, pass both files: `LG_CONFIG_FILE="$HOME/.config/lazygit/config.yml,$HOME/.config/lazygit/ii-theme.yml" lazygit`.
docs/tools/leetcode.mdx
+97
View File
@@ -0,0 +1,97 @@
---
title: LeetCode
description: LeetCode CLI workspace config, its tracked state files, and the lc-elir helper that sends solutions to omp.
---
The repo tracks the state directory of a terminal LeetCode client, plus a helper that feeds solution files to omp prompt commands. The `~/.leetcode` layout (workspaces with `collab.json`, `timer.json`, and `snapshots/`) matches [night-slayer18/leetcode-cli](https://github.com/night-slayer18/leetcode-cli), which is invoked as `leetcode`.
| | |
| --- | --- |
| Source | `dot_leetcode/` |
| Target | `~/.leetcode/` |
| Packages | The CLI is not declared in `packages.yaml`; install it separately |
| Alias | `lc` = `leetcode` (fish, bash, zsh) |
<FileTree>
- dot_leetcode/
- workspaces.json
- star-prompt.json
- version-cache.json
- workspaces/
- default/
- config.json
- collab.json
- timer.json
- snapshots/
- .keep
</FileTree>
## Workspaces
`workspaces.json` lists one workspace, `default`, and marks it active.
```json ~/.leetcode/workspaces/default/config.json
{
"workDir": "/home/prad/Code/github.com/prdlk/leetcode/work/1",
"lang": "python3",
"site": "leetcode.com",
"editor": "nvim",
"syncRepo": "https://github.com/prdlk/leetcode.git"
}
```
| Key | Value | Effect |
| --- | --- | --- |
| `workDir` | `~/Code/github.com/prdlk/leetcode/work/1` (absolute path in the file) | Where problem files are written. It sits inside the ghq checkout of the solutions repo, under `$GHQ_ROOT`. |
| `lang` | `python3` | Default solution language. |
| `site` | `leetcode.com` | Target site. |
| `editor` | `nvim` | Opens problems in [Neovim](/tools/neovim). |
| `syncRepo` | `https://github.com/prdlk/leetcode.git` | Repo that solutions sync to. |
The path is absolute, so on a machine with a different username or `$GHQ_ROOT`, edit `workDir`.
The other workspace files start empty: `collab.json` has `"session": null`, `timer.json` has no solve times and no active timer, and `snapshots/` holds only a `.keep` placeholder.
## Tracked state files
| File | Contents |
| --- | --- |
| `star-prompt.json` | Counter for the CLI's "star the repo" prompt: accepted-submission total, milestones already shown, submissions since the last prompt, timestamps, and a `dismissed` flag. |
| `version-cache.json` | Last update check time, latest known version, and whether it has breaking changes. |
These are runtime files. In chezmoi's symlink mode, non-template, non-private files are symlinks into the source directory, so the CLI writes these straight into the repo working tree. Expect them to show up as diffs.
## lc-elir
`lc-elir [root]` picks LeetCode solution files with fzf and runs the omp `/leetcode-eli5` command on each one.
| | |
| --- | --- |
| Sources | `dot_local/bin/executable_lc-elir` (POSIX sh), `dot_config/fish/functions/lc-elir.fish` (fish port) |
| Targets | `~/.local/bin/lc-elir`, `~/.config/fish/functions/lc-elir.fish` |
| Needs | `fd`, `fzf`, `bat`, `omp` |
<Steps>
<Step title="Find candidates">
`fd --type f '^\d+\..+\.(js|ts)$'` under `root` (default `.`) matches numbered problem files such as `1365.some-slug.js`.
</Step>
<Step title="Pick">
`fzf --multi` with prompt `eli5> `, showing the last three path segments (`--delimiter=/ --with-nth=-3..`). The right-hand 60% preview shows the first 40 lines through `bat --color=always --line-range=:40`.
</Step>
<Step title="Run">
For each selected file it prints a separator line, then runs `omp -p "/leetcode-eli5 <file>"`. It exits 1 if nothing was picked.
</Step>
</Steps>
## omp commands
Two prompt commands in `dot_omp/private_agent/commands/` target the solution files. Both expect the same on-disk format: a `/* ... */` header block (number, title, difficulty, URL, description, examples, constraints), a JSDoc `@param`/`@return` block, then one or more solution functions.
| Command | File | What it does |
| --- | --- | --- |
| `/leetcode-eli5 <file>` | `leetcode-eli5.md` | Adds beginner-level, line-by-line comments above each statement plus a `// ====` banner with the problem number and title. It must not change the header, the JSDoc, or any code. Prints the path and number of comment lines added. |
| `/leetcode-docs <file>` | `leetcode-docs.md` | Converts a solution into a Fumadocs MDX page at `content/docs/leetcode/<difficulty>/<category>/<number>-<slug>.mdx`: problem, examples, constraints, an intuition paragraph, the verbatim solution, and a derived complexity callout. Multiple approaches become a tab group. Prints the output path. |
See [omp](/ai/omp) for how agent commands are loaded.
docs/tools/meta.ts
+19
View File
@@ -0,0 +1,19 @@
import { defineMeta } from "blume";
export default defineMeta({
title: "Tools",
icon: "wrench",
pages: [
"index",
"git",
"github-cli",
"neovim",
"yazi",
"lazygit",
"lazydocker",
"bat",
"topgrade",
"hunk",
"leetcode",
],
});
docs/tools/neovim.mdx
+56
View File
@@ -0,0 +1,56 @@
---
title: Neovim
description: Neovim config pulled from its own repository as a chezmoi external, plus the editor hooks the dotfiles wire into it.
---
Neovim is the default editor everywhere in this setup. Its configuration (AstroNvim-based, per the repo README) lives in a separate repository, [prdlk/nvim](https://github.com/prdlk/nvim). This repo only clones it and wires other tools to it; the Lua config itself is not documented here.
| | |
| --- | --- |
| Source | `.chezmoiexternal.toml` entry `.config/nvim` |
| Target | `~/.config/nvim` (a git checkout) |
| Remote | `https://github.com/prdlk/nvim.git` |
| Packages | Arch: `neovim` (pacman). macOS: `neovim` (Homebrew) |
## How the external works
```toml .chezmoiexternal.toml
[".config/nvim"]
type = "git-repo"
url = "https://github.com/prdlk/nvim.git"
[".config/nvim".pull]
args = ["--ff-only"]
```
- `type = "git-repo"`: chezmoi runs `git clone` when `~/.config/nvim` does not exist, so a fresh machine gets the config on first apply.
- No `refreshPeriod` is set, so a normal `chezmoi apply` never pulls. The local checkout always wins; commit and push nvim changes from `~/.config/nvim` directly.
- A forced refresh (`chezmoi apply --refresh-externals`) runs `git pull --ff-only`, which refuses to merge if local history has diverged.
See [externals and ignore rules](/chezmoi/externals-and-ignore) for how chezmoi handles externals in general.
### Ignored runtime paths
`.chezmoiignore.tmpl` keeps chezmoi away from state that tools write inside the checkout:
| Path | Why |
| --- | --- |
| `.config/nvim/lazy-lock.json` | lazy.nvim lockfile, rewritten on plugin updates |
| `.config/nvim/.git`, `.config/nvim/.git/**` | the checkout's own git metadata |
| `.config/nvim/.omc/**` | agent tooling state |
| `.config/nvim/.crush/**` | agent tooling state |
| `.config/nvim/.understand-anything/**` | agent tooling state |
## Integrations in this repo
| Where | What |
| --- | --- |
| `dot_config/fish/conf.d/10-env.fish` | `EDITOR=nvim`. [gh](/tools/github-cli) falls back to it because its `editor` key is empty. |
| [Aliases](/shell/aliases) | `e` = `nvim`; `e.v` opens `~/.config/nvim/lua` in yazi; `e.t` opens the tmux config in nvim. |
| [Kitty](/terminal/kitty) | <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>e</kbd> opens nvim in the current directory in a 50/50 vertical split. Kitty's `listen_on` socket lets nvim hand <kbd>Ctrl</kbd>+<kbd>h/j/k/l</kbd> at a window edge back to kitty. |
| [Yazi](/tools/yazi) | The `edit` opener and <kbd>Ctrl</kbd>+<kbd>v</kbd> / <kbd>Ctrl</kbd>+<kbd>x</kbd> call `~/.local/bin/yazi-nvim-open`. Inside an nvim terminal (`$NVIM` set) files open in the host instance through the nvim-side `EditFromYazi` Lua function; otherwise a blocking `nvim` starts. |
| [Git](/tools/git) | `git difftool` runs `nvim "$LOCAL" "$REMOTE" +"CodeDiff file $LOCAL $REMOTE"`. |
| [LeetCode](/tools/leetcode) | The default workspace sets `"editor": "nvim"`. |
:::note
`yazi-nvim-open` depends on `_G.EditFromYazi`, which the nvim repo defines (its header points at `lua/config/yazi_session.lua`). If that function is missing, the remote call fails and nothing opens.
:::
docs/tools/topgrade.mdx
+78
View File
@@ -0,0 +1,78 @@
---
title: Topgrade
description: Topgrade config for the Arch/CachyOS machines, with paru as the package manager, chezmoi re-add before upgrades, and post-upgrade hooks.
---
[Topgrade](https://github.com/topgrade-rs/topgrade) runs every updater on the machine in one pass: system packages, cargo, firmware, git repos, flatpak, and custom commands. The config is written for a CachyOS (Arch) box running fish; most keys are left at topgrade's defaults.
| | |
| --- | --- |
| Source | `dot_config/topgrade.toml` |
| Target | `~/.config/topgrade.toml` |
| Packages | Arch: `topgrade` (AUR, via paru). macOS: `topgrade` (Homebrew) |
:::note
The file's comments say topgrade on the owner's machine is cargo-installed, and that `cargo install-update` keeps it current. That is why self-update is off.
:::
## [misc]
| Key | Value | Why |
| --- | --- | --- |
| `pre_sudo` | `true` | Caches sudo credentials up front so an unattended run does not stop at a password prompt partway through. |
| `no_self_update` | `true` | The `[cargo]` step already updates the topgrade binary; two updaters would fight over it. |
| `cleanup` | `true` | Runs distro cleanup afterwards (paccache needs `pacman-contrib`; skipped if absent). |
| `show_distribution_summary` | `true` | Surfaces `*.pacnew` / `*.pacsave` files to merge. |
| `disable` | `["containers", "config_update"]` | Skips pulling `:latest` for every local container image, and skips topgrade's config-update step. |
| `ignore_failures` | `["uv", "containers"]` | Failures in these steps do not fail the run. |
The Python pip/conda steps stay off (topgrade's default), which protects a pinned ROCm build of torch from blind upgrades. A `remote_topgrades` entry for another host is present but commented out.
## [linux]
| Key | Value | Why |
| --- | --- | --- |
| `arch_package_manager` | `"paru"` | Pins the Arch backend so topgrade does not fall back to bare `pacman`, which would skip the AUR. |
| `show_arch_news` | `true` | Prints archlinux.org news before upgrading; CachyOS tracks Arch, so manual-intervention notices still apply. |
The comments around `arch_package_manager` describe shelly (the CachyOS package CLI) as the intended value, but the active setting is `paru`. shelly still runs as a post-command (below). A commented `shelly_arguments` line is kept for reference.
## Other steps
| Section | Key | Value | Effect |
| --- | --- | --- | --- |
| `[cargo]` | `git` | `true` | Also updates git-sourced cargo installs, not only crates.io ones. Needs `cargo-update`. |
| `[firmware]` | `upgrade` | `false` | fwupd updates are listed, not flashed, so firmware is reviewed before applying. |
| `[git]` | (none active) | | Predefined repos are still pulled; custom `repos` and `arguments` are commented out to avoid tripping over dirty working trees. |
| `[flatpak]` | (none active) | | User-scope flatpaks update without sudo; `use_sudo` is commented out. |
## Pre- and post-commands
Pre-commands run before any upgrade step:
| Name | Command | Purpose |
| --- | --- | --- |
| Chezmoi Re-Add | `chezmoi re-add` | Pulls local edits to managed dotfiles back into the chezmoi source repo before anything changes them. Only re-adds files chezmoi already manages; review and commit in `~/.local/share/chezmoi` afterwards. |
| GHQ Update | see below | Updates every ghq-managed repo. |
```toml ~/.config/topgrade.toml
[pre_commands]
"Chezmoi Re-Add" = "chezmoi re-add"
"GHQ Update" = "ghq list | ghq get -u -s"
```
Post-commands run after everything else:
| Name | Command |
| --- | --- |
| Omp Update | `omp update` |
| Hermes Update | `hermes update --backup --yes` |
| Herdr Update | `herdr update` |
| Shelly Update | `shelly upgrade-all -n` |
| Cachy Update | `cachy-update` |
`shelly upgrade-all -n` is also available as the `sua` alias. The post-commands assume CachyOS tooling (`shelly`, `cachy-update`) and the owner's own CLIs (`omp`, `hermes`, `herdr`); on machines without them those steps fail. See [omp](/ai/omp) for the agent CLI.
:::note
`chezmoi re-add` does not overwrite templates, so edits made directly to rendered files such as `~/.gitconfig` or `~/.config/yazi/yazi.toml` are not captured; change the `.tmpl` source instead.
:::
docs/tools/yazi.mdx
+253
View File
@@ -0,0 +1,253 @@
---
title: Yazi
description: Yazi file manager config — layout, openers, bat previews, keymap, plugins, flavors, and the Neovim bridge.
---
[Yazi](https://yazi-rs.github.io) is a terminal file manager. It is the default way to browse files here: shell keybindings, aliases, and a kitty shortcut all open it, and it hands files to Neovim.
| | |
| --- | --- |
| Source | `dot_config/yazi/` |
| Target | `~/.config/yazi/` |
| Files | `yazi.toml.tmpl`, `keymap.toml`, `init.lua`, `package.toml`, `theme.toml`, `vfs.toml`, `flavors/{cyberdream,ii-auto,noctalia}.yazi/flavor.toml` |
| Helper | `dot_local/bin/executable_yazi-nvim-open` → `~/.local/bin/yazi-nvim-open` |
| Packages | `yazi` plus preview backends `ffmpeg`, `ffmpegthumbnailer`, `poppler`, `resvg`, `imagemagick`, `7zip` (`sevenzip` on macOS), `unzip` |
| Plugins | `run_onchange_after_install-yazi-plugins.sh.tmpl` → `ya pkg install` |
<FileTree>
- dot_config/yazi/
- yazi.toml.tmpl
- keymap.toml
- init.lua
- package.toml
- theme.toml
- vfs.toml
- flavors/
- cyberdream.yazi/
- flavor.toml
- ii-auto.yazi/
- flavor.toml
- noctalia.yazi/
- flavor.toml
</FileTree>
## yazi.toml
The only template in the directory. The one OS condition is the `open` opener: macOS uses `open`, everything else uses `xdg-open`.
```toml ~/.config/yazi/yazi.toml
[mgr]
ratio = [0, 2, 6]
[opener]
play = [
{ run = "mpv %s", orphan = true, for = "unix" },
]
edit = [
{ run = 'yazi-nvim-open %s', block = true, for = "unix" },
]
open = [
{ run = "{{ if eq .chezmoi.os "darwin" }}open{{ else }}xdg-open{{ end }} %s1", desc = "Open" },
]
[open]
prepend_rules = [
{ url = "*.{md,markdown}", use = [ "fry", "edit", "open" ] },
]
[[plugin.prepend_previewers]]
mime = "text/*"
run = 'piper -- bat -p --color=always --terminal-width=$w "$1"'
[[plugin.prepend_previewers]]
mime = "application/{mbox,javascript,wine-extension-ini}"
run = 'piper -- bat -p --color=always --terminal-width=$w "$1"'
```
| Setting | Effect |
| --- | --- |
| `mgr.ratio = [0, 2, 6]` | Hides the parent column; the file list takes 2/8 of the width and the preview 6/8. |
| `opener.play` | `mpv`, detached from yazi (`orphan = true`). |
| `opener.edit` | `yazi-nvim-open`, blocking, so yazi waits for the editor. |
| `opener.open` | `open` (macOS) or `xdg-open` on the first selected file. |
| `open.prepend_rules` | Markdown files list `fry`, then `edit`, then `open`. No `fry` opener is defined in this file. |
| Previewers | Text MIME types, plus mbox, JavaScript, and wine `.ini`, preview through the `piper` plugin running `bat -p --color=always`, so previews use the [bat](/tools/bat) cyberdream theme. Markdown falls under `text/*` too. |
## Keymap
All bindings in `keymap.toml` are `[[mgr.prepend_keymap]]` entries, so they take priority over yazi's defaults and leave the rest of the default keymap intact.
### Navigation
| Keys | Action |
| --- | --- |
| <kbd>l</kbd> | `plugin smart-enter`: enter a directory, or open a file |
| <kbd>g</kbd> <kbd>r</kbd> | cd to the git root (`git rev-parse --show-toplevel`) |
| <kbd>g</kbd> <kbd>C</kbd> | cd to `~/.local/share/chezmoi` |
| <kbd>g</kbd> <kbd>d</kbd> | cd to `~/Downloads` |
| <kbd>g</kbd> <kbd>D</kbd> <kbd>d</kbd> | cd to `$GHQ_ROOT/github.com` |
| <kbd>g</kbd> <kbd>D</kbd> <kbd>w</kbd> | cd to `$GHQ_ROOT/github.com/wltbs` |
| <kbd>g</kbd> <kbd>D</kbd> <kbd>p</kbd> | cd to `$GHQ_ROOT/github.com/prdlk` |
| <kbd>g</kbd> <kbd>l</kbd> | cd to `~/.local` |
| <kbd>g</kbd> <kbd>p</kbd> | cd to `~/Pictures` |
| <kbd>g</kbd> <kbd>o</kbd> <kbd>p</kbd> | cd to `~/Documents/Obsidian/Personal` |
| <kbd>g</kbd> <kbd>o</kbd> <kbd>r</kbd> | cd to `~/Documents/Obsidian/Research` |
| <kbd>g</kbd> <kbd>o</kbd> <kbd>w</kbd> | cd to `~/Documents/Obsidian/Walletbase` |
| <kbd>g</kbd> <kbd>b</kbd> | Back to the previous directory |
| <kbd>g</kbd> <kbd>f</kbd> | Forward to the next directory |
| <kbd>g</kbd> <kbd>m</kbd> <kbd>p</kbd> | cd to `sftp://gdrive-personal` |
| <kbd>g</kbd> <kbd>m</kbd> <kbd>s</kbd> | cd to `sftp://gdrive-sonr` |
| <kbd>g</kbd> <kbd>m</kbd> <kbd>h</kbd> | cd to `sftp://gdrive-hyperauth` |
| <kbd>;</kbd> | Open the bunny hop menu |
| <kbd>'</kbd> | Bunny fuzzy search over hops |
`$GHQ_ROOT` is `~/Code`, exported in `dot_config/fish/conf.d/10-env.fish`. The `g m` bindings need the SFTP services in `vfs.toml`, which are commented out (see [vfs.toml](#vfstoml)).
### Finding and opening
| Keys | Action |
| --- | --- |
| <kbd>F</kbd> | `plugin smart-filter`: live filter; enters the directory or opens the file when one match remains |
| <kbd>Ctrl</kbd>+<kbd>t</kbd> | `plugin tv`: jump to a file with television |
| <kbd>Ctrl</kbd>+<kbd>g</kbd> | `plugin tv ghq`: jump to a ghq repo |
| <kbd>Ctrl</kbd>+<kbd>d</kbd> | `plugin tv dirs`: jump to a directory |
| <kbd>Ctrl</kbd>+<kbd>f</kbd> | `plugin tv text`: search text and open the match in Neovim at that line |
| <kbd>Ctrl</kbd>+<kbd>v</kbd> | `yazi-nvim-open vsplit` on the selection (inside an nvim terminal only) |
| <kbd>Ctrl</kbd>+<kbd>x</kbd> | `yazi-nvim-open split` on the selection (inside an nvim terminal only) |
The `tv` plugin shells out to [television](https://github.com/alexpasmantier/television), which is not in `packages.yaml`.
### Files and session
| Keys | Action |
| --- | --- |
| <kbd>A</kbd> | Create a directory (`create --dir`) |
| <kbd>N</kbd> | Bulk-create files (`bulk_create`) |
| <kbd>Shift</kbd>+<kbd>Tab</kbd> | Drop into `$SHELL` in the current directory (blocking) |
| <kbd>Ctrl</kbd>+<kbd>q</kbd> | Quit |
In the shell opened by <kbd>Shift</kbd>+<kbd>Tab</kbd>, the `q` function (fish, bash, zsh) runs `ya emit quit` when `$YAZI_ID` is set, then exits. That closes the parent yazi too instead of returning to it.
## Plugins
`package.toml` pins every plugin to a commit and hash. `~/.config/yazi/plugins/**` is in `.chezmoiignore.tmpl`, so chezmoi never manages the installed code. The post-apply script reinstalls from the manifest:
```sh run_onchange_after_install-yazi-plugins.sh.tmpl
#!/bin/sh
# package.toml hash: {{ include "dot_config/yazi/package.toml" | sha256sum }}
set -eu
command -v ya >/dev/null 2>&1 || exit 0
[ -f "${XDG_CONFIG_HOME:-$HOME/.config}/yazi/package.toml" ] || exit 0
ya pkg install
```
The embedded hash makes chezmoi re-run the script whenever `package.toml` changes.
| Plugin | Rev | Used by |
| --- | --- | --- |
| `yazi-rs/plugins:smart-filter` | `efa4d79` | <kbd>F</kbd> |
| `uhs-robert/sshfs` | `a8b8903` | `require("sshfs"):setup()` in `init.lua` |
| `yazi-rs/plugins:smart-enter` | `efa4d79` | <kbd>l</kbd> |
| `yazi-rs/plugins:piper` | `efa4d79` | bat previewers in `yazi.toml` |
| `Rolv-Apneseth/starship` | `ea92cf4` | Installed; not set up in `init.lua` |
| `mikavilpas/easyjump.yazi:easyjump` | `4aa1a06` | Installed; not bound in `keymap.toml` |
| `cap153/tv` | `b6b1f12` | <kbd>Ctrl</kbd>+<kbd>t</kbd>/<kbd>g</kbd>/<kbd>d</kbd>/<kbd>f</kbd> |
| `stelcodes/bunny` | `71b14a3` | <kbd>;</kbd> and <kbd>'</kbd>, configured in `init.lua` |
| `coder0x6675/osc7` | `ae73046` | Installed; not referenced in config |
| `WhoSowSee/mdv-previewer` | `ea4732b` | Installed; not referenced in `yazi.toml` |
| `yazi-rs/plugins:vcs-files` | `efa4d79` | Installed; not bound in `keymap.toml` |
| `yazi-rs/plugins:git` | `efa4d79` | `require("git"):setup { order = 1500 }` |
| `yazi-rs/plugins:no-status` | `efa4d79` | `require("no-status"):setup()` |
`[flavor] deps` is empty: flavors ship as files in `flavors/`, not as packages.
### init.lua
```lua ~/.config/yazi/init.lua
require("sshfs"):setup()
require("bunny"):setup({ hops = { ... }, desc_strategy = "path", ephemeral = true, tabs = true, notify = false, fuzzy_cmd = "fzf" })
require("git"):setup { order = 1500 }
require("no-status"):setup()
```
- **sshfs**: default setup, for mounting remote hosts over SSHFS.
- **git**: git status signs in the file list, ordered at `1500` in the linemode.
- **no-status**: removes the status bar.
- **bunny**: bookmark "hops", with ephemeral hops and tab hops on, no notification after hopping, `fzf` for fuzzy search, and the path as the label when a hop has no `desc`.
| Hop key | Path | Label |
| --- | --- | --- |
| <kbd>/</kbd> | `/` | |
| <kbd>t</kbd> | `/tmp` | |
| <kbd>~</kbd> | `~` | Home |
| <kbd>m</kbd> | `~/Music` | Music |
| <kbd>d</kbd> | `~/Desktop` | Desktop |
| <kbd>D</kbd> | `~/Developer` | Developer |
| <kbd>c</kbd> | `~/.config` | Config files |
| <kbd>l</kbd> <kbd>s</kbd> | `~/.local/share` | Local share |
| <kbd>l</kbd> <kbd>b</kbd> | `~/.local/bin` | Local bin |
| <kbd>l</kbd> <kbd>t</kbd> | `~/.local/state` | Local state |
## Theme and flavors
```toml ~/.config/yazi/theme.toml
[flavor]
light = "cyberdream"
dark = "cyberdream"
use = "cyberdream"
```
Cyberdream is active in both light and dark mode. Three flavors ship in `flavors/`:
| Flavor | Origin | Notes |
| --- | --- | --- |
| `cyberdream.yazi` | Hand-maintained cyberdream palette | Active. Sets `syntect_theme = "~/.config/bat/themes/cyberdream.tmTheme"`, so yazi's built-in code preview shares the [bat](/tools/bat) theme. Cyan cwd (`#5ef1ff`), green find keyword (`#5eff6c`), yellow and red copy/cut markers. |
| `ii-auto.yazi` | Generated by the ii wallpaper theming system ("Do not edit manually") | Not selected. Monochrome palette taken from the wallpaper. |
| `noctalia.yazi` | Noctalia palette | Not selected. Full theme: manager, status, mode, input, tabs, completion, tasks, which, spotter, help, notify, and MIME-based file colors. |
To switch, change `use` (and `light`/`dark`) in `theme.toml` to `ii-auto` or `noctalia`.
### Icons
`theme.toml` also carries a large `[icon]` table:
- `prepend_dirs`: Nerd Font icons for named directories: `Applications`, `Code`, `Desktop`, `Developer`, `github.com`, `prdlk`, `wltbs`, `Shared`, `Templates`, `env`, `go`, `js`, `dart`, `py`, `rs`, `tex`, `md`, `docs`, `prad.codes`.
- `files` and `exts`: several hundred filename and extension rules, from dotfiles like `.gitignore` and `.zshrc` to formats like `kicad_pcb` and `wrangler.toml`. Each rule sets a Nerd Font glyph and a foreground color from the Catppuccin Mocha palette (`#a6e3a1`, `#f38ba8`, `#89b4fa`, `#cba6f7`, `#fab387`, ...).
Glyphs need a Nerd Font. The terminal uses VictorMono Nerd Font (see [Terminal](/terminal)).
## vfs.toml
Every line is commented out. The file sketches three SFTP services (`gdrive-personal`, `gdrive-sonr`, `gdrive-hyperauth`) on local ports, meant to be served by a local SFTP bridge to Google Drive. Until they are uncommented and the bridge is running, the <kbd>g</kbd> <kbd>m</kbd> bindings have nothing to connect to.
## Neovim bridge: yazi-nvim-open
`~/.local/bin/yazi-nvim-open [vsplit|split|tabedit] file...` backs the `edit` opener and the <kbd>Ctrl</kbd>+<kbd>v</kbd>/<kbd>Ctrl</kbd>+<kbd>x</kbd> bindings. It lives on `PATH` because yazi does not expand `$HOME` in opener commands.
<Steps>
<Step title="Parse mode">
A first argument of `vsplit`, `split`, or `tabedit` selects the mode; anything else means `edit`.
</Step>
<Step title="Standalone yazi ($NVIM unset)">
`edit` runs `exec nvim "$@"`. Split modes do nothing and exit 0.
</Step>
<Step title="Inside an nvim terminal ($NVIM set)">
Each file is resolved with `realpath`, escaped for a Vimscript string, and sent to the host with `nvim --server "$NVIM" --remote-expr "v:lua.EditFromYazi(mode, path)"`. The nvim side opens the file and hides the yazi window.
</Step>
</Steps>
Set `YAZI_OPEN_TRACE` to a file path to log each call's `$NVIM`, mode, and arguments.
## Launching yazi
| Entry point | Behavior |
| --- | --- |
| `y` / `yy` (fish functions) | Run yazi with `--cwd-file`, then `cd` to the directory yazi was in on exit. The two are identical apart from `y` calling `command rm`. |
| `yy` (bash, zsh functions) | Same wrapper for bash and zsh. |
| <kbd>Ctrl</kbd>+<kbd>e</kbd> / <kbd>Ctrl</kbd>+<kbd>f</kbd> | fish and zsh keybindings that run `yy` and repaint the prompt. |
| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>f</kbd> | [Kitty](/terminal/kitty): yazi in a new tab at the current directory. |
| Aliases | `e.y`, `e.k`, `e.n`, `e.f`, `e.v` open config directories in yazi; `cdc`, `cdl`, `cdw`, and `,,` (fish only; chezmoi source) cd first, then start yazi. |
[tmux](/terminal/tmux) sets `allow-passthrough on` so yazi's kitty-protocol image previews work inside tmux. Kitty's tab bar and the tmux window-name map show a folder icon for yazi. See [aliases](/shell/aliases) and [fish](/shell/fish) for the shell side.