diff --git a/docs/ai/claude-code.mdx b/docs/ai/claude-code.mdx new file mode 100644 index 0000000..1ec5809 --- /dev/null +++ b/docs/ai/claude-code.mdx @@ -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//` | `~/.claude/skills//` | 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 ``. +4. Writes `// .md`. The file name is keyed to the session, so re-runs overwrite the same note. +5. Creates `/.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/`), an abstract callout from the session summary, then sections by observation type. Each bullet links back to the claude-mem viewer at `http://localhost:/?observation=`. + +| 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 `. 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` | `` | 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` | `` | 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_` 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. diff --git a/docs/ai/index.mdx b/docs/ai/index.mdx new file mode 100644 index 0000000..8961646 --- /dev/null +++ b/docs/ai/index.mdx @@ -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. + + + + Settings, hooks, plugins, slash commands, and skill links under `~/.claude`. + + + Config, keybindings, MCP servers, theme, commands, and scheduled research loops under `~/.omp`. + + + The `~/.agents/skills` library, its lock file, and the symlinks that expose it to Claude Code. + + + +## 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 + + + +- 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/ + + + +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). +- Ctrl A 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). diff --git a/docs/ai/meta.ts b/docs/ai/meta.ts new file mode 100644 index 0000000..3d9665f --- /dev/null +++ b/docs/ai/meta.ts @@ -0,0 +1,7 @@ +import { defineMeta } from "blume"; + +export default defineMeta({ + title: "AI agents", + icon: "bot", + pages: ["index", "claude-code", "omp", "skills"], +}); diff --git a/docs/ai/omp.mdx b/docs/ai/omp.mdx new file mode 100644 index 0000000..b3fa7ed --- /dev/null +++ b/docs/ai/omp.mdx @@ -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//private_loop.md` | `~/.omp/loops//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 | +| --- | --- | +| Ctrl E | Open the current prompt in the external editor (`app.editor.external`) | +| Ctrl Q | 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 [extra instructions]` | Converts a LeetCode solution file into a Fumadocs MDX page at `content/docs/leetcode///-.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 [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 +``` + +Runs one round of a loop: + + + + Exits if `~/.omp/loops//loop.md` is missing. Seeds `state.md` with `## queue`, `## done`, and `## blocked` headings if it does not exist. + + + 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`. + + + 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 ` escalated` to `~/.omp/loops/escalations.log`. + + + +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 | +| Ctrl A | 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 "` on each | + +See [scripts](/shell/scripts) and [fish](/shell/fish). The [kitty](/terminal/kitty) tab bar shows a microchip glyph for tabs running `omp`. diff --git a/docs/ai/skills.mdx b/docs/ai/skills.mdx new file mode 100644 index 0000000..7e03e96 --- /dev/null +++ b/docs/ai/skills.mdx @@ -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//` | `~/.agents/skills//` | 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_` | `~/.claude/skills/` | Relative symlink to `../../.agents/skills/` | + +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 # search the registry +npx skills add -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//` as plain files. Add it to the repo with `chezmoi add ~/.agents/skills/`, and commit the updated `.skill-lock.json` alongside it. To expose it to Claude Code, add a `dot_claude/skills/symlink_` file containing `../../.agents/skills/`. + +### .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 + + + + `dot_claude/skills/symlink_blume` is a one-line file containing `../../.agents/skills/blume`. + + + chezmoi's `symlink_` prefix turns it into the symlink `~/.claude/skills/blume`, pointing at `../../.agents/skills/blume`. + + + 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. + + + +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//`) 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. | diff --git a/docs/chezmoi/config.mdx b/docs/chezmoi/config.mdx new file mode 100644 index 0000000..11b98f9 --- /dev/null +++ b/docs/chezmoi/config.mdx @@ -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 :.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). diff --git a/docs/chezmoi/data.mdx b/docs/chezmoi/data.mdx new file mode 100644 index 0000000..4b2be29 --- /dev/null +++ b/docs/chezmoi/data.mdx @@ -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). + + + + +`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` | + + + + +`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. + + + + +`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. + + + + +:::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@` | +| `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. +::: diff --git a/docs/chezmoi/externals-and-ignore.mdx b/docs/chezmoi/externals-and-ignore.mdx new file mode 100644 index 0000000..ac01909 --- /dev/null +++ b/docs/chezmoi/externals-and-ignore.mdx @@ -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. diff --git a/docs/chezmoi/index.mdx b/docs/chezmoi/index.mdx new file mode 100644 index 0000000..ddf4a92 --- /dev/null +++ b/docs/chezmoi/index.mdx @@ -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 + + + +- .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 + + + +| 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/`), `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 ` 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 ` | 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 ` | Copies edits made to non-symlinked targets (private, executable) back into the source. | +| `chezmoi edit ` | 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`). diff --git a/docs/chezmoi/meta.ts b/docs/chezmoi/meta.ts new file mode 100644 index 0000000..c2f0239 --- /dev/null +++ b/docs/chezmoi/meta.ts @@ -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"], +}); diff --git a/docs/chezmoi/scripts.mdx b/docs/chezmoi/scripts.mdx new file mode 100644 index 0000000..e86d447 --- /dev/null +++ b/docs/chezmoi/scripts.mdx @@ -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. + + + Install system packages from `packages.yaml`. + chezmoi writes the target state. + Install gh extensions. + Enable systemd user units on Linux. + tpm clone, bat cache, font cache. + Rebuild bat cache when its theme or config changes. + Reinstall yazi plugins when the manifest changes. + + +| 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. + + + + +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. + + + + +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. + + + + +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 ` 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). diff --git a/docs/desktop/fonts-and-apps.mdx b/docs/desktop/fonts-and-apps.mdx new file mode 100644 index 0000000..a278f24 --- /dev/null +++ b/docs/desktop/fonts-and-apps.mdx @@ -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 + + + + monospace + + + VictorMono Nerd Font + + + +``` + +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. diff --git a/docs/desktop/hyprland.mdx b/docs/desktop/hyprland.mdx new file mode 100644 index 0000000..7276073 --- /dev/null +++ b/docs/desktop/hyprland.mdx @@ -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 +``` + +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 +``` + +- **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 ` (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. diff --git a/docs/desktop/index.mdx b/docs/desktop/index.mdx new file mode 100644 index 0000000..49a063d --- /dev/null +++ b/docs/desktop/index.mdx @@ -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. diff --git a/docs/desktop/meta.ts b/docs/desktop/meta.ts new file mode 100644 index 0000000..34f573b --- /dev/null +++ b/docs/desktop/meta.ts @@ -0,0 +1,7 @@ +import { defineMeta } from "blume"; + +export default defineMeta({ + title: "Desktop", + icon: "monitor", + pages: ["index", "niri", "hyprland", "waybar", "fonts-and-apps"], +}); diff --git a/docs/desktop/niri.mdx b/docs/desktop/niri.mdx new file mode 100644 index 0000000..7cc30b2 --- /dev/null +++ b/docs/desktop/niri.mdx @@ -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. + + + +- ~/.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 + + + +## 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. + + + + `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` + + + `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"` | + + + `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"` | + + + `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"` | + + + `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"` | + + + +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 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..*`. | +| `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 ` 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. diff --git a/docs/desktop/waybar-preview.png b/docs/desktop/waybar-preview.png new file mode 100644 index 0000000..881e19e Binary files /dev/null and b/docs/desktop/waybar-preview.png differ diff --git a/docs/desktop/waybar.mdx b/docs/desktop/waybar.mdx new file mode 100644 index 0000000..e0ae6c8 --- /dev/null +++ b/docs/desktop/waybar.mdx @@ -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 + + + + **Left** + + - separator + - `custom/omarchy` + - separator + - `hyprland/workspaces` + - separator + - `tray` + - separator + - `custom/voxtype` + - `custom/update` + - `custom/screenrecording-indicator` + - `custom/updatespacman` + - separator + - `idle_inhibitor` + + + **Center** + + - `custom/windowpill` + + + **Right** + + - `group/right-group2` → `group/right2` → `group/tray-expander` + - `group/right-group1` → `group/right1` → `clock` + + + +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 ` 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. diff --git a/docs/index.mdx b/docs/index.mdx new file mode 100644 index 0000000..fbf045f --- /dev/null +++ b/docs/index.mdx @@ -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 + + + + chezmoi layout, machine roles, symlink mode, age encryption, package manifests, apply scripts, and externals. + + + fish, bash, and zsh with shared aliases, starship, atuin, and the `~/.local/bin` scripts. + + + kitty, ghostty, tmux, and herdr. + + + git, gh and gh-dash, neovim, yazi, lazygit, lazydocker, bat, topgrade, hunk, and more. + + + niri with noctalia, Hyprland with the omarchy helpers, waybar, fonts, and default apps. + + + Claude Code, omp, and the shared agent skill library. + + + +## 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**. diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..ebba3b2 --- /dev/null +++ b/docs/installation.mdx @@ -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 + + + + **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. + + + `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. + + + 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 :.config/chezmoi/key.txt ~/.config/chezmoi/key.txt + chmod 600 ~/.config/chezmoi/key.txt + ``` + + + +## Options + +Arguments after `--` go to chezmoi and replace the default `init --apply prdlk/dotfiles`: + + + +```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 +``` + + + +| Flag / variable | Effect | +| --- | --- | +| `-b ` | Install directory (default `$HOME/.local/bin`) | +| `-t ` | 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 + + + + `.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). + + + `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). + + + 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). + + + gh extensions, tpm, the bat cache, the font cache, yazi plugins, and the niri user service on Linux. + + + +:::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. diff --git a/docs/meta.ts b/docs/meta.ts new file mode 100644 index 0000000..221ed4c --- /dev/null +++ b/docs/meta.ts @@ -0,0 +1,14 @@ +import { defineMeta } from "blume"; + +export default defineMeta({ + pages: [ + "index", + "installation", + "chezmoi", + "shell", + "terminal", + "tools", + "desktop", + "ai", + ], +}); diff --git a/docs/shell/aliases.mdx b/docs/shell/aliases.mdx new file mode 100644 index 0000000..77ef2a9 --- /dev/null +++ b/docs/shell/aliases.mdx @@ -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/` 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@` (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). diff --git a/docs/shell/atuin.mdx b/docs/shell/atuin.mdx new file mode 100644 index 0000000..010f4d8 --- /dev/null +++ b/docs/shell/atuin.mdx @@ -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` | ctrl-w 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 ctrl-r. zsh also loads `suv init zsh` (suvadu) if installed. + +### Key bindings + +| Key | Shells | Action | +| --- | --- | --- | +| ctrl-r | all | Interactive search (`_atuin_search`) | +| up | all | Search opened from the up arrow. `filter_mode_shell_up_key_binding = "directory"` limits it to history from the current directory | +| ? | fish, vi normal mode | On an empty buffer, runs `atuin ai inline --hook` | +| ctrl-w | fish, insert and normal mode | `atuin ai inline`, then repaint | +| ctrl+shift+p | 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 ctrl-w 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 ? types a question mark. To ask for a command, press Esc and then ? on an empty line, or press ctrl-w from either mode. The ctrl-w bind calls `atuin ai inline` without `--hook` and replaces fish's default ctrl-w 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` | diff --git a/docs/shell/bash-zsh.mdx b/docs/shell/bash-zsh.mdx new file mode 100644 index 0000000..0491406 --- /dev/null +++ b/docs/shell/bash-zsh.mdx @@ -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 ctrl-r and up. + +## ~/.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 ctrl-q and ctrl-s from the terminal. + +A generic widget `_zle-run` is registered as `run-` 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 | +| --- | --- | +| ctrl-e | `yy` (yazi, cd to its exit dir) | +| ctrl-f | `yy` | +| ctrl-b | `purple` (an external command; this repo does not provide it) | +| ctrl-y | `clip-last` | +| ctrl-o | `gho` (repo or vault picker, cd) | +| ctrl-p | `pj` (task runner) | +| ctrl-a | `omp` | +| ctrl-g | `lazygit` | +| ctrl-q | `exit` | +| ctrl-c | At the prompt: kill the buffer, clear the screen and kitty scrollback (`ESC[2J ESC[3J`), reset the prompt | + +ctrl-c 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 ctrl-w (atuin AI), down (`pj`), and ? have no zsh equivalent. ctrl-h/j/k/l 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 =''`. 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 ` | `ghg-clone "$@"`, cd into the printed path, `clear && onefetch` | +| `ghn ` | `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=`, 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. diff --git a/docs/shell/fish.mdx b/docs/shell/fish.mdx new file mode 100644 index 0000000..3f45995 --- /dev/null +++ b/docs/shell/fish.mdx @@ -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 ctrl-r. + 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 ctrl-r itself. + +### 50-terminal-title.fish + +Defines `terminal_title`, which runs on every `PWD` change and prints `ESC k 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 ` | Pick a package, then `pnpm --filter add ` inside a `gum spin` | +| `pnpmfd ` | Same with `add -D` | +| `pnpmfr ` | `pnpm --filter remove ` | +| `pnpmfw` | Pick a target package and a sibling, then `pnpm --filter add --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 | +| --- | --- | +| ctrl-e | `yy`: yazi, then cd to the directory yazi exited in | +| ctrl-f | `yy` (same as ctrl-e) | +| ctrl-b | `purple`, then repaint (an external command; this repo does not provide it) | +| ctrl-y | `clip-last`: re-run the last command and copy its output | +| ctrl-o | `gho`: pick a ghq repo or Obsidian vault and cd into it | +| ctrl-p | `pj`: fzf task runner ([Scripts](/shell/scripts#pj)) | +| ctrl-a | `omp` (the coding agent, see [AI agents](/ai)) | +| ctrl-w | `atuin ai inline`: natural-language command overlay | +| ctrl-g | `lazygit` | +| down | `_pj_bind_down`: runs `pj` on an idle, empty prompt, otherwise fish's `down-or-search` | +| ctrl-c | Clears the command line, runs `clear` (screen and kitty scrollback), repaints | +| ctrl-q | `exit` | + +Bindings added by tool init scripts: + +| Key | Mode | Action | Source | +| --- | --- | --- | --- | +| ctrl-r | default and insert | `_atuin_search` | `atuin init fish` | +| up | default and insert | `_atuin_bind_up` (atuin history, directory filter) | `atuin init fish` | +| ? | default (vi normal) | `_atuin_ai_question_mark`: on an empty buffer, opens `atuin ai inline` | `config.fish` | +| ctrl-t | 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, ctrl-g (lazygit overlay), ctrl-a (omp split), ctrl-y (yazi split), and ctrl-h/j/k/l (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 ` 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 ` | Copies every `AGENTS.md` under the current tree into ``, preserving paths | +| `fab` | fzf-pick a Fabric pattern from `~/.config/fabric/pattern_explainations.json` (description in the preview, ctrl-/ toggles it) and run it, feeding piped stdin if any | +| `fish_title` | Terminal title: `prompt_pwd`, or `:` 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 ` | `ghg-clone ` (ghq get), cd into the clone, `clear`, `onefetch` | +| `ghn ` | 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 "` on each | +| `mdcp ` | `curl.md `, 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 ctrl-e/ctrl-f 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). diff --git a/docs/shell/index.mdx b/docs/shell/index.mdx new file mode 100644 index 0000000..1937c3a --- /dev/null +++ b/docs/shell/index.mdx @@ -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). diff --git a/docs/shell/meta.ts b/docs/shell/meta.ts new file mode 100644 index 0000000..af6c4b1 --- /dev/null +++ b/docs/shell/meta.ts @@ -0,0 +1,7 @@ +import { defineMeta } from "blume"; + +export default defineMeta({ + title: "Shell", + icon: "terminal", + pages: ["index", "fish", "bash-zsh", "aliases", "scripts", "starship", "atuin"], +}); diff --git a/docs/shell/scripts.mdx b/docs/shell/scripts.mdx new file mode 100644 index 0000000..6d9afb7 --- /dev/null +++ b/docs/shell/scripts.mdx @@ -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 '❯ '; ` 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:** ctrl+shift+p 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 `. + +**Needs:** `fd`, `fzf`, `code2prompt`. + +## extract_agents + +```sh +extract_agents +``` + +Creates `` 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 ctrl-/ toggles the preview. The picked pattern runs as `fabric-ai --pattern `, 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: + + + Checks that `gh`, `gum`, and `jq` exist and that `gh auth status` succeeds. + Lists your GitHub orgs whose login contains `sonr`, excluding the target `sonr-io`. You pick which to migrate with `gum choose --no-limit`. + For each repo in each org, runs `gh api -X POST repos///transfer -f new_owner=sonr-io`. If the name already exists in `sonr-io`, `gum input` asks for a new name (default `-`). An empty name skips the repo. + Waits 30 seconds (`gum spin`), because GitHub transfers are asynchronous. + For every selected org that had no failed transfers and now has zero repos, asks `gum confirm` and then `gh api -X DELETE orgs/`. + + +**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 +``` + +Runs `ghq get `, 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)///` 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 +``` + +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//`. +- **github.com**: pick the owner `prdlk` or `wltbs`, then `gh repo create / --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. tab 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:** ctrl-o 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 --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 # any https/ssh/scp remote URL +``` + +Opens a repo's web page for any forge whose URL layout is `https:////`, such as github.com and prad.codes. It reduces any remote form to `//`: 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 "`. + +**Needs:** `fd`, `fzf`, `bat`, `omp`, and the `/leetcode-eli5` omp command. + +## mdcp + +```sh +mdcp +``` + +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 ` 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..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 down binding uses it. + +**Launched by:** ctrl-p in fish and zsh, and down 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] … +``` + +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=` to log each call. + +**Used by:** `yazi.toml` (the `edit` opener) and `keymap.toml` (ctrl-v vsplit, ctrl-x split). See [yazi](/tools/yazi). + +**Needs:** `nvim`, `realpath`. diff --git a/docs/shell/starship.mdx b/docs/shell/starship.mdx new file mode 100644 index 0000000..dd7f244 --- /dev/null +++ b/docs/shell/starship.mdx @@ -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. diff --git a/docs/terminal/ghostty.mdx b/docs/terminal/ghostty.mdx new file mode 100644 index 0000000..dd46ba4 --- /dev/null +++ b/docs/terminal/ghostty.mdx @@ -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`. | diff --git a/docs/terminal/herdr.mdx b/docs/terminal/herdr.mdx new file mode 100644 index 0000000..0c42e77 --- /dev/null +++ b/docs/terminal/herdr.mdx @@ -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`. diff --git a/docs/terminal/index.mdx b/docs/terminal/index.mdx new file mode 100644 index 0000000..ee5d52f --- /dev/null +++ b/docs/terminal/index.mdx @@ -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). diff --git a/docs/terminal/kitty.mdx b/docs/terminal/kitty.mdx new file mode 100644 index 0000000..a69bfea --- /dev/null +++ b/docs/terminal/kitty.mdx @@ -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) | + + +- 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 + + +`__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 `