# Dotfiles > A headless Ubuntu server build of my dotfiles, with a shared Herdr session. # Overview Source: https://ubuntu-server.dotfiles.timmo.dev/ The headless [Ubuntu Server](https://ubuntu.com/server) build of my dotfiles. It is a cut-down copy of the [Omarchy desktop](https://dotfiles.timmo.dev/) setup with the terminal and service tooling only, and it hosts a [Herdr](/server/herdr/) session that other machines attach to. [GNU Stow](https://www.gnu.org/software/stow/) links each package into place, and a compiled `dot` CLI sets up, updates and checks the machine. Private machine details live in a separate overlay. :::note[Work in progress] This build is ahead of the real server. See the [server overview](/server/overview/) for what is still open. ::: ```bash # Pull, refresh config, re-stow and rebuild dot update # Run the health checks and save a report dot doctor ``` :::caution[Personal setup] These docs and the public dotfiles are for reference. They are tuned for my machines and a private overlay that is not public, so installation is not recommended. Have your agents borrow the ideas you want instead. ::: ## How it fits together
Stow links the packages into place
dot sets up and maintains the machine
Agents share skills and guidance
## Core | Page | Why | | --- | --- | | [Getting started](/getting-started/) | Bootstrap the server | | [Configuration](/configuration/) | Private overlay, packages, and tracked app config | | [Distros](/distros/) | The desktop build and any others, with their own docs sites | | [`dot` CLI](/dot/overview/) | Setup, sync, stow, doctor, and git helpers ([command reference](/dot/commands/)) | | [Stow packages](/stow/) | One-line blurbs for everything else that is stowed | ## Server | Page | Why | | --- | --- | | [Overview](/server/overview/) | What this build keeps, drops, and still has open | | [Herdr](/server/herdr/) | Shared agent session that remote clients attach to | ## Agents | Page | Why | | --- | --- | | [Overview](/agents/overview/) | How OpenCode, skills, and companions fit together | | [Skills](/agents/skills/) | Shared catalogue and repo-local skills | | [OpenCode](/agents/opencode/overview/) | Primary coding-agent harness | | [Pi](/agents/pi/) | Lightweight companion agent | ## Machine-readable docs Build-time [llms.txt](https://llmstxt.org) bundles and a read-only docs MCP, generated from the same source as the site. | URL | Use | | --- | --- | | https://ubuntu-server.dotfiles.timmo.dev/llms.txt | Compact page index | | https://ubuntu-server.dotfiles.timmo.dev/llms-full.txt | Full docs bundle | | https://ubuntu-server.dotfiles.timmo.dev/mcp | Hosted MCP (search, page and navigation) | | `/{route}.md` | One page as Markdown | Ask AI on the site is off. For live repo state, use [context](https://context.timmo.dev) rather than these static bundles. --- # Agents Source: https://ubuntu-server.dotfiles.timmo.dev/agents/opencode/agents Agents set the execution posture (permissions, tool access, delegation) for OpenCode sessions. They are loaded from `~/.config/opencode/agents/`. | Agent | Description | | --- | --- | | [`build-ask`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/agents/build-ask.md) | Build agent that executes clear tasks and relies on permissions for write actions | | [`coordinator`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/agents/coordinator.md) | Manages low-context delegated sessions through delivery | | [`general-readonly`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/agents/general-readonly.md) | General-style parallel subagent that researches with read-only tools and a narrow shell inspection allowlist (for delegation from read-only primaries). | | [`grill`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/agents/grill.md) | Read-only planning stress-test agent for light or full round-based grilling | | [`refactorer`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/agents/refactorer.md) | Refactor code while preserving behavior and following local command and skill workflows | | [`researcher-readonly`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/agents/researcher-readonly.md) | Primary-source research subagent that compares claim-specific evidence and cannot delegate further | | [`researcher`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/agents/researcher.md) | Interactive primary-source research agent that compares claim-specific evidence | | [`reviewer`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/agents/reviewer.md) | Reviews code for quality, bugs, security, and best practices | --- # Commands Source: https://ubuntu-server.dotfiles.timmo.dev/agents/opencode/commands Commands are thin routing prompts: they name an agent, declare required skills or injected context, and define the output shape. They are loaded from `~/.config/opencode/commands/`. | Command | Description | Agent | | --- | --- | --- | | [`/code-review`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/commands/code-review.md) | Review current work or a pull request with the code-review skill in the read-only reviewer agent | `reviewer` | | [`/commit-push`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/commands/commit-push.md) | Split current changes into coherent commits and push | `default` | | [`/commit`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/commands/commit.md) | Split current changes into coherent commits via the dot git commit gateway | `default` | | [`/grill`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/commands/grill.md) | Stress-test a plan, decision, or idea with light or full question rounds | `grill` | | [`/plan`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/commands/plan.md) | Manual entrypoint to native plan mode from the current conversation context | `plan` | | [`/research`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/commands/research.md) | Research a topic from primary sources and compare evidence where judgement is involved | `researcher` | --- # OpenCode Source: https://ubuntu-server.dotfiles.timmo.dev/agents/opencode/overview [OpenCode](https://opencode.ai) is the main interactive agent UI: sessions, slash commands, plugins, and [Herdr](https://herdr.dev) panes. Most day-to-day agent work happens here. Config source lives under `agents/.config/opencode/`. ## Layout | Piece | Why | | --- | --- | | `agents/.config/opencode/` | Agents, commands, `plugins/`, and shared `lib/` | | Shared [skills](/agents/skills/) | Skills repo `main` + repo-local skills (see Skills page) | | Private overlay | Machine-specific OpenCode packages, AGENTS source, and MCP wiring | ## Layers | Layer | Role | | --- | --- | | Agents | Execution posture (permissions, tools, plan mode, delegation) | | Commands | Thin routers: intent, arguments, required skills/context, output shape | | Skills | Reusable workflows and behavioural contracts ([Skills](/agents/skills/)) | | Plugins | Context injection and enforcement hooks (commit context, guards, workflows) | Commands do not own long workflows; skills and plugins do. AGENTS stays to cross-cutting policy that no skill description already carries. ## Sync and publish | Command / flow | Purpose | | --- | --- | | `dot agent sync` | Mirror global AGENTS into other harness instruction files (Cursor, Claude) | | `dot mcp sync` | Regenerate MCP configs from private `mcp.yml`; OpenCode repos opt in via `opencode_mcp` in private `dot-git.yml` | | `dot skills` | Check and apply skill updates from the skills repo | | `dot update` / `dot init` | Run agents-sync (and related refresh) as part of maintenance | ## Runtime Sessions often run inside Herdr panes (OpenCode integration checked by `dot doctor`). The public Zsh config aliases `opencode` to OpenCode 2 (`opencode2`). Companion harnesses [Pi](/agents/pi/) and [Cursor](/agents/cursor/) share skills and/or AGENTS guidance but not this full plugin and command stack. See [Agents](/agents/overview/) for how the harnesses fit together. ## Reference OpenCode-only generated catalogues (do not hand-edit): | Catalogue | Contents | | --- | --- | | [Agents](/agents/opencode/agents/) | Execution postures | | [Commands](/agents/opencode/commands/) | Slash-command routers | | [Plugins](/agents/opencode/plugins/) | Context and enforcement hooks | Skills: [Skills](/agents/skills/) (catalogue in the skills repo, plus local skills). Regenerate OpenCode catalogues with `mise run docs:gen` after the sources change. The [`dot` command reference](/dot/commands/) is separate (CLI, not OpenCode). --- # Plugins Source: https://ubuntu-server.dotfiles.timmo.dev/agents/opencode/plugins Plugins provide context, evidence, or enforcement hooks for OpenCode. Server plugins are loaded from `~/.config/opencode/plugins/`. | Plugin | Description | | --- | --- | | [`commit-context`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/commit-context.ts) | Injects session-attributed commit scope into commit command prompts | | [`context-capture`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/context-capture.ts) | Opt-in capture of the assembled starter context for token profiling | | [`env-protection`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/env-protection.ts) | Blocks direct access to .env files, and any extra secret files listed in env-protection.yml, to prevent leaking secrets | | [`generated-artifact-guard`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/generated-artifact-guard.ts) | Blocks direct mutation of generated dotfiles artefacts | | [`mcp-repo-gate`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/mcp-repo-gate.ts) | Per-repo MCP server gating for OpenCode | | [`notes-guard`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/notes-guard.ts) | Blocks direct file access to the repository notes vault | | [`notification`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/notification.ts) | Sends contextual desktop notifications and terminal attention for agent events | | [`pitchfork-dev-server-guard`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/pitchfork-dev-server-guard.ts) | Enforces a project's declared pitchfork dev-server workflow for agents | | [`readonly-subagent-shell-guard`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/readonly-subagent-shell-guard.ts) | Rejects shell syntax that can turn read-only subagent commands into writes | | [`review-handoff-guard`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/review-handoff-guard.ts) | Nudges a session that goes idle with edited files and no change-review-handoff | | [`skill-updates`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/skill-updates/tui.tsx) | Shows the dotfiles, skills and package update counts in the prompt footer, from `dot updates status --json` | | [`subagent-chrome-devtools-guard`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy-quattro/agents/.config/opencode/plugins/subagent-chrome-devtools-guard.ts) | Blocks Chrome DevTools tools from delegated subagent sessions | --- # Agents Source: https://ubuntu-server.dotfiles.timmo.dev/agents/overview Coding agents in this setup share skills and AGENTS guidance. [OpenCode](https://opencode.ai) is the primary harness; Pi is a thinner companion. Shared skills live in a separate repo. `dot` keeps a checkout detached at the latest `main` and links it into `~/.agents/skills/`. | Piece | Why | | --- | --- | | [Skills](/agents/skills/) | Shared catalogue plus repo-local skills | | [OpenCode](/agents/opencode/overview/) | Day-to-day sessions, slash commands, plugins, Herdr panes | | [Pi](/agents/pi/) | Lightweight companion sessions | ## Shared wiring | Mechanism | Role | | --- | --- | | `dot agent sync` | Mirror global AGENTS into other harness instruction files | | `dot mcp sync` | Regenerate MCP configs from the private overlay; OpenCode repos opt in per checkout | | `dot skills` | Check and apply updates from the skills repo | | `~/.agents/skills/` | Shared skills linked from the latest skills repo `main` | OpenCode owns the full agent, command, and plugin stack. Pi reuses skills and AGENTS, not that stack. --- # Pi Source: https://ubuntu-server.dotfiles.timmo.dev/agents/pi [Pi](https://pi.dev) is a lighter companion agent for smaller sessions. It is used sparingly here: shared skills and AGENTS guidance without the full [OpenCode](https://opencode.ai) plugin and command stack. | Piece | Why | | --- | --- | | `pi/` stow package | Pi-side config; mainly `.pi/agent/extensions/` | | Shared skills | Same `~/.agents/skills/` set as OpenCode | | `dot agent sync` | Keeps project/global AGENTS aligned with the OpenCode AGENTS source | | `workflow.ts` extension | Compaction follow-up and light [Herdr](https://herdr.dev) helpers under `.pi/` | Use Pi when a thin session is enough. Use [OpenCode](/agents/opencode/overview/) for day-to-day interactive work, slash commands, plugins, and Herdr panes. There is no generated Pi command catalogue in these docs. --- # Skills Source: https://ubuntu-server.dotfiles.timmo.dev/agents/skills Reusable agent workflows live in [timmo001/skills](https://github.com/timmo001/skills). The generated catalogue is [SKILLS.md](https://github.com/timmo001/skills/blob/main/SKILLS.md#skills-catalogue) (name + description per skill). That repo is the source of truth; this docs site does not regenerate a full skills page. | Piece | Why | | --- | --- | | `~/.local/share/dot/skills` | dot-managed checkout of the skills repo, detached at the latest `main` and linked into `~/.agents/skills/` | | `.agents/skills/` | Repo-local skills for this checkout only | | `dotfiles-skills/` | Global skills tied to dotfiles paths or private overlays | | `dot skills` | Validate, import, and update skills from the standalone repo | Edit reusable skills in `~/repos/skills` and push to `main`; the next `dot update` picks them up. Do not edit the managed checkout or live `~/.agents/skills` directly. ## Local skills Repo-only skills under `.agents/skills/` (registered via `skills.paths` in `opencode.json`). Shared first-party skills stay in the skills repo catalogue above. | Skill | Role | | --- | --- | | `dotfiles-docs` | Author and maintain the Blume docs site (`docs/`, dotfiles.timmo.dev) | Harness overview: [Agents](/agents/overview/). OpenCode layers and catalogues: [OpenCode](/agents/opencode/overview/). --- # Configuration Source: https://ubuntu-server.dotfiles.timmo.dev/configuration Behaviour prefers CLI flags. Environment variables cover process context and secrets. Machine-specific and private data stay in `~/.config/dotfiles-private`. | Piece | Why | | --- | --- | | Private overlay | Host-only config, secrets, package lists, browser checks, `dot-git.yml` | | Public packages | apt packages listed in `.dot-public-packages`; command-line tools come from mise | | Stow packages | App config in this repo; see [Stow packages](/stow/) and the Server / Agents pages | | Env vars | `DOT_*`, `DOTFILES_*`, and `OMARCHY_HOST` (host-specific packages) influence `dot` and session tooling | | Private file (typical) | Role | | --- | --- | | `dot-git.yml` | Managed repos, shortcuts, notifications, activity, PR tracking, and OpenCode MCP opt-ins | | Package manifests | Private install lists | | Browser checks | Machine-specific doctor expectations | | MCP spec (`mcp.yml`) | Source for `dot mcp sync` | Prefer reading the stowed source and private YAML over expanding this page further. Flags and env details live in `dot --help` and code. --- # Home Assistant Source: https://ubuntu-server.dotfiles.timmo.dev/development/home-assistant I work on [Home Assistant Core](https://github.com/home-assistant/core) and the [frontend](https://github.com/home-assistant/frontend) most days. `dot homeassistant` (`dot ha`) sets up each repository, then runs its dev server as a [pitchfork](https://pitchfork.jdx.dev) daemon so it gets a stable HTTPS URL from pitchfork's proxy. Under [Herdr](/server/herdr/), each command opens its own tab in the `[HA] Core` or `[HA] Frontend` workspace. The short `hacdev`, `hafdev*` and `hadev*` functions in `.zshrc` just call `dot ha`. Repository paths, workspaces, daemon names, URLs and serve targets live in the private `~/.config/dot/homeassistant.yml`, and the pitchfork config lives in the private overlay too, so it is copied below with real URLs replaced. ## Commands | Command | Alias | | --- | --- | | `dot homeassistant` | `dot ha` | | `dot homeassistant core` | `dot ha c` | | `dot homeassistant frontend` | `dot ha f` | | Case | Command | Shortcut | | --- | --- | --- | | What is running, and where | `dot ha status [target...]` | `hadevstatus`, `hacdevstatus`, `hafdevstatus`, `hafdevservestatus`, `hafdevsuitesstatus` | | Logs | `dot ha logs [--follow] [--lines ]` | `hacdevlogs`, `hafdevlogs`, `hafdevservelogs`, `hafdevdesignlogs`, `hafdevdemologs`, `hafdeve2eapplogs` | | Core with the local frontend build | `dot ha core dev [--background]` | `hacdev`, `hacdevbg` | | Core, rebased onto `upstream/dev` first | `dot ha core dev --latest [--background]` | `hacdevlatest`, `hacdevlatestbg` | | Core setup (Git, venv, bootstrap) | `dot ha core setup [--latest]` | Run by `hacdev*` | | Frontend watch build alone | `dot ha frontend dev [--background] [--attach]` | `hafdev`, `hafdevbg` | | Frontend against another Core | `dot ha frontend serve [] [--background]` | `hafdevserve` | | Frontend against prod | `dot ha frontend serve prod [--background]` | `hafdevserveprod`, `hafdevserveprodbg` | | Frontend through Home Assistant Link | `dot ha frontend serve link [--background]` | `hafdevserveprodnc`, `hafdevserveprodncbg` | | Gallery | `dot ha frontend gallery [--background]` | `hafdevdesign`, `hafdevdesignbg` | | Demo | `dot ha frontend demo [--background]` | `hafdevdemo`, `hafdevdemobg` | | E2E test app | `dot ha frontend e2e [--background]` | `hafdeve2eapp`, `hafdeve2eappbg` | | Production build | `dot ha frontend build` | `hafbuild` | | E2E tests | `dot ha frontend test e2e [app\|demo\|gallery]` | None | | Core and frontend in Herdr tabs | `dot ha dev [--background]` | `hadev`, `hadevbg` | | Stop servers (all by default) | `dot ha stop [target...]` | `hadevstop`, `hacdevstop`, `hafdevstop`, `hafdevservestop`, `hafdevdesignstop`, `hafdevdemostop`, `hafdeve2eappstop`, `hafdevsuitesstop` | | Target | Daemon | URL | | --- | --- | --- | | `core` | `ha-core/dev` | `https://dev.ha-core.localhost` | | `build` | `ha-frontend/build` | Through Core's URL | | `serve` | `ha-frontend/serve` | `https://serve.ha-frontend.localhost` | | `prod` | `ha-core/prod` | `https://prod.ha-core.localhost` | | `gallery`, `demo`, `e2e` | The frontend's own background mode | Printed when started | Port 443 already reaches pitchfork's proxy (listening on 8443), so the URLs need no port. The proxy builds each hostname from the daemon name and namespace. Its auto-start is off, so a stopped daemon's URL shows pitchfork's "No daemon found" page rather than starting it; only the commands start daemons. ## How the commands behave - Interactive runs go through `dot status run`, which pins a header with the state, URL and elapsed time, and keeps the terminal title in step. - Each runs its setup first: `dot ha core setup` for Core (Git, virtual environment, `script/bootstrap`), `script/bootstrap` for the frontend. - If the daemon is already running, it asks before restarting it. `dot ha dev`'s Frontend tab follows a running build instead. - `--background` starts the daemon and returns once it's ready; otherwise it follows the logs, and Ctrl+C stops it. - Every `dot ha frontend` command takes the frontend's build lock, so it asks to stop the `build` and `serve` daemons first. Lint, format, type checks and unit tests don't take the lock and stay plain `pnpm`. :::note Pitchfork doesn't pass the caller's environment to a daemon. `dot ha f serve` writes the Core URL to `~/.local/state/dot/homeassistant/serve.args`, and the `serve` daemon reads it when it starts. ::: ## Core behind the proxy The proxy sets `Host` to `localhost:` and adds `X-Forwarded-*` headers. Core rejects those unless it trusts the proxy. In the dev Core, turn on **Trust X-Forwarded-For** and add `127.0.0.1/32` and `::1/128` to **Trusted proxies**, under **Settings > System > Network > Reverse proxy**. Serving against a remote Core also needs `https://serve.ha-frontend.localhost` in that instance's **CORS allowed origins**, on the same page. [![Open your Home Assistant instance and show your network configuration.](https://my.home-assistant.io/badges/network.svg)](https://my.home-assistant.io/redirect/network/) The browser blocks an HTTPS page from calling a plain HTTP Core, so the login works but the frontend can't connect afterwards. `ha-core/prod` fronts the prod instance on an HTTPS URL with `dot http forward`, which drops the proxy's `X-Forwarded-*` headers so the remote Core accepts the requests without trusting this machine as a proxy. `dot ha f serve prod` starts it before `serve`. Core only registers the frontend routes if `hass_frontend` exists when it starts, and a fresh build briefly removes it. `ha-core/dev` depends on `ha-frontend/build`, so starting Core starts the build too and waits for it to be ready. ## Agents Agents use the same `dot ha` commands. Under an agent, `dot ha` skips setup, Herdr tabs and prompts: it reuses a running daemon, runs suites in the background, and fails with a message instead of stopping a conflicting daemon. `dot ha core setup` and `dot ha logs --follow` refuse to run. The Home Assistant workspace `AGENTS.md` tells agents not to run `hass`, `pnpm dev`, `pnpm dev:serve` or `pnpm build` directly, and to ask before stopping or swapping a running daemon. ## Pitchfork config `~/.config/pitchfork/config.toml` enables the proxy and registers both repositories as namespaces: ```toml [daemons] [settings.proxy] auto_start = false enable = true https = true port = 8443 [namespaces.ha-core] dir = "/home//repos/home-assistant/core" config = ["/home//.config/dotfiles-private/pitchfork/.config/pitchfork/home-assistant/core.toml"] [namespaces.ha-frontend] dir = "/home//repos/home-assistant/frontend" config = ["/home//.config/dotfiles-private/pitchfork/.config/pitchfork/home-assistant/frontend.toml"] ``` `home-assistant/core.toml`: ```toml [daemons.dev] run = "exec .venv/bin/hass -c config" depends = ["ha-frontend/build"] port = 8123 ready_port = { port = 8123, timeout = "5m" } retry = true stop_signal = { signal = "SIGTERM", timeout = "60s" } [daemons.prod] run = "exec dot http forward --port 8126 --target http://homeassistant.local:8123" port = 8126 ready_port = 8126 ``` `home-assistant/frontend.toml`: ```toml [daemons.build] run = "exec env HA_DEV_BACKGROUND=0 pnpm dev --fetch-translations" ready_output = { pattern = "Build done", timeout = "10m" } [daemons.serve] run = """ args="${XDG_STATE_HOME:-$HOME/.local/state}/dot/homeassistant/serve.args" eval "set -- $(cat "$args" 2>/dev/null)" exec env HA_DEV_BACKGROUND=0 pnpm dev:serve --fetch-translations "$@" """ port = 8124 ready_port = { port = 8124, timeout = "10m" } ``` ## dot config `~/.config/dot/homeassistant.yml`: ```yaml core: directory: ~/repos/home-assistant/core workspace: "[HA] Core" daemon: ha-core/dev url: https://dev.ha-core.localhost frontend: directory: ~/repos/home-assistant/frontend workspace: "[HA] Frontend" build: ha-frontend/build serve: daemon: ha-frontend/serve url: https://serve.ha-frontend.localhost targets: prod: title: Prod url: https://prod.ha-core.localhost daemon: ha-core/prod link: title: Link url: https://.ui.nabu.casa ``` --- # Distros Source: https://ubuntu-server.dotfiles.timmo.dev/distros Each machine type lives on its own `distro/*` branch. The default branch is the full Omarchy desktop, and the others are cut-down copies for machines without that desktop. Every branch publishes its own copy of these docs, so each site describes only what that branch ships. The **Distro** switcher in the header moves between them. | Distro | Branch | Docs | | --- | --- | --- | | **Omarchy desktop**: Arch and Omarchy on the desktop and laptop | [`distro/arch-omarchy-quattro`](https://github.com/timmo001/dotfiles/tree/distro/arch-omarchy-quattro) | [dotfiles.timmo.dev](https://dotfiles.timmo.dev/) | | **Ubuntu server**: headless Ubuntu server and remote Herdr host | [`distro/ubuntu-server`](https://github.com/timmo001/dotfiles/tree/distro/ubuntu-server) | [ubuntu-server.dotfiles.timmo.dev](https://ubuntu-server.dotfiles.timmo.dev/) | :::caution[Personal setup] Like the rest of these docs, each distro is tuned for my own machines. Borrow the pieces you want rather than installing one wholesale. ::: ## How the sites publish | Piece | Why | | --- | --- | | `docs/distros.ts` | Shared list of distros for the header switcher, kept on the default branch and merged into the others | | `docs/current-distro.ts` | Which entry this branch is, setting its site and GitHub branch | | `docs/wrangler.jsonc` | Worker name and custom domain for this branch's site | | [Cloudflare Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) | One Worker per distro, each deploying from its own branch | --- # Command Reference Source: https://ubuntu-server.dotfiles.timmo.dev/dot/commands This page lists every `dot` command from the same Effect command tree that powers parsing, help, dispatch, and shell completions. ## `dot init` Run one-time first-use machine setup ```text dot init [flags] ``` Run the one-time first-use setup workflow for a fresh machine. Init prepares repos, stow links, mise tools, apt packages, the firewall and the login shell, and trusts mise configs in tracked repos. After init completes, enable lingering so user services run without a login, log in again, then run dot doctor. Before the bounded workflow starts, init updates or clones the optional private overlay according to DOT_ALLOW_PRIVATE. Use dot update for ongoing maintenance. **Options** | Option | Description | | --- | --- | | `--force` | Re-run init even if the machine looks initialised | | `--log` `` | Init log path (default: ~/.local/state/dot/init.log) | | `--help` `-h` | Show help information | **Examples** ```bash dot init dot init --force ``` ## `dot install` Ensure prerequisites, backup/adopt dotfiles and install the pinned OpenCode release ```text dot install [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ## `dot update` Aliases: `dot up` Self-update, pull repos, stow dotfiles, rebuild. Phase flags are inclusive: passing any of --pull, --stow, or --app runs only the selected phases. Internal --no-self-update, --post-hook-repo and --started-at flags support the active self-update handoff; internal --summary-file lets update system print the summary last. ```text dot update [flags] ``` A full update pulls the public dotfiles, installs Bun dependencies, rebuilds and relaunches dot, then scans and pulls tracked repositories, trusting mise configs only in repositories it freshly clones. It moves the dot-managed skills checkout to the latest skills main before rebuilding skill-maintenance. Pulls are fast-forward-only and never stash or rebase: Git refuses an update if local edits would be overwritten or histories have diverged. It regenerates completions, runs the required MCP sync, stows, installs mise tools, restarts pitchfork daemons still running an old mise binary, updates Pi extensions, rebuilds again, runs agents sync, backfills the init marker, reloads agents (as dot reload agents), and starts the doctor check. It finishes with a summary of updated repositories and every completed or skipped step, in order. Phase flags are inclusive: passing any of --pull, --stow, or --app runs only the selected phases. Scoped runs skip agents sync and init-marker backfill. Use --repo PATH (repeatable) to pull selected repositories, restore their pinned submodules and run configured post-update commands after HEAD changes. Changed public or private dotfiles also rebuild, stow and sync agent instructions once per batch. Add --pull to only pull and run post-update commands, skipping the dotfiles rebuild and stow. Herdr plugins are refreshed only inside Herdr. --no-reload skips the agent reload and doctor check. **Options** | Option | Description | | --- | --- | | `--repo` `` | Fast-forward this repository when local work can be preserved, then run its post-update command; repeat for a batch. Changed dotfiles also rebuild and stow | | `--pull` | Run the repository pull phase only | | `--stow` | Generate completions, sync MCP configs, and stow only | | `--app` | Install Bun dependencies and rebuild the dot binary only | | `--check` | Report dotfiles pulls, pending pins and stow changes, skipping local work | | `--check-all` | Also check development repos for pulls, skipping local work | | `--no-self-update` | Skip the internal self-update phase, which pulls the public and private dotfiles | | `--no-reload` | Skip agent reload and module refresh | | `--post-hook-repo` `` | Internal post-hook repository | | `--summary-file` `` | Internal: write the final summary to this file instead of printing it | | `--started-at` `` | Internal: epoch ms the run started, for the summary timing | | `--help` `-h` | Show help information | **Exit codes** ```text 0 Update completed, or no actionable updates were found 1 Fatal workflow failure 2 Update check could not finish 10 Update check found pulls, pending pins or stow changes ``` ### `dot update system` Select and run Dotfiles, apt, and Topgrade updates ```text dot update system [flags] ``` Select maintenance steps interactively, then run them in order: Dotfiles, apt packages, GitHub CLI extensions, and Topgrade. Interactive runs pre-select Dotfiles, apt packages, and GitHub CLI extensions; extra Topgrade steps start unselected. Non-interactive runs and --yes select every step, and --step runs only the steps given. Cancelling the prompt exits without running updates. **Options** | Option | Description | | --- | --- | | `--yes` | Select every update without prompting | | `--step` `` | Run only this step without prompting; repeat for several (choices: dotfiles, apt, github-cli, yazi, rustup, tldr, vim, containers, claude_code, claude_code_plugins, uv) | | `--no-self-update` | Skip dot update's self-update pull when the dotfiles are already pulled | | `--help` `-h` | Show help information | **Examples** ```bash dot update system dot update system --yes dot update system --step dotfiles --step github-cli ``` ## `dot deps` Validate and publish grouped native dependency updates ```text dot deps [flags] [] ``` Read native policy and manifests from a pinned remote target, preserving the caller's checkout. Exclude whole groups covered by any open dependency PR, including failed, pending and draft PRs. --all bypasses only PR inventory and exclusion. --dry-run discovers updates without repository scripts, installs, checks or writes to Git. Bare dot deps starts groups by priority and prepares and validates them concurrently in isolated worktrees, bounded by --concurrency. Check commands share the same concurrency cap across groups; setup and shared Git operations are serialised. A command's optional skipFor exclusions apply only when every updated dependency matches; mixed or unknown groups retain checks. The first ready group takes the publication slot and publishes one checked commit without creating PRs or waiting for hosted CI. Host permissions are read from $XDG_CONFIG_HOME/dot/dependencies.yml (default ~/.config/dot/dependencies.yml), keyed by owner/repository with trusted and allowBypass booleans. Required hosted checks must have equivalent validation.checks mappings; protected direct pushes require explicit allowBypass permission and existing account rights. Workflow edits require a credential with workflow write access. Unsupported policy remains blocking. Git-backed claims serialise each repository/target across machines and service or manual runs. Publication atomically advances the ownership record and target; target movement rebuilds and revalidates, up to three attempts per group. Failed work and per-group logs remain under $XDG_STATE_HOME/dot/dependencies. Clean published worktrees are removed, including submodules. Setup/check mutations and commit-hook mutations prevent publication. Independent groups continue after failures, including groups sharing files; a partial run exits non-zero. A normal invocation authorises passing updates, regardless of Renovate automerge policy. **Options** | Option | Description | | --- | --- | | `--dry-run` | Discover updates without running scripts, installing packages or publishing | | `--all` | Bypass open-PR inventory and exclusion only; leave PRs untouched | | `--target` `` | Remote target branch (default: repository default branch) | | `--timeout` `` | Deadline per command/provider lookup (default: 30 seconds) | | `--concurrency` `` | Maximum concurrent groups, lookups, PR inspections or check commands, 1-16 (default: 4) | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | repository | **Examples** ```bash dot deps --dry-run dot deps owner/repository --dry-run dot deps --dry-run --all --target main ``` ### `dot deps service` Run one cross-machine dependency service interval ```text dot deps service [flags] ``` Run configured repositories sequentially under one Git-backed service claim. Configuration supplies coordinationRepository, repositories, intervalMinutes and concurrency. Every repository requires host trust. Shared state prevents overlapping machine runs and records the next eligible interval. Repository/target claims also cover manual dot deps runs. Claims renew every 30 seconds and expire after two minutes; a lost claim interrupts work, and dependency publication atomically checks its target claim. State is stored on dedicated dot-deps-state branches. The user timer runs hourly at ten past, except between 01:00 and 07:00. Exit status 2 means completed with unsuccessful update groups (warning); 3 means the shared interval was skipped. --no-cooldown ignores the shared interval and each repository's interval but never an active claim; `dot services start dot-deps.timer` applies it to that one start automatically. Startup, policy and service failures exit 1. Local configuration validation with --dry-run performs no remote writes. Policy is read from published target commits, so repository policies must be pushed before enabling the service. **Options** | Option | Description | | --- | --- | | `--config` `` | Service YAML config (default: $XDG_CONFIG_HOME/dot/dependency-service.yml) | | `--dry-run` | Validate local service configuration and trust without running updates or writing to Git | | `--no-cooldown` | Run even if the shared interval is not due; an active claim still blocks the run | | `--help` `-h` | Show help information | **Examples** ```bash dot deps service --dry-run dot deps service dot deps service --no-cooldown ``` ### `dot deps import` Import dependency policy from other tools ```text dot deps import [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | #### `dot deps import renovate` Import Renovate policy into dot-deps.yml with an editor schema ```text dot deps import renovate [flags] [] ``` Create dot-deps.yml and its editor schema from a repository's JSON Renovate config, migrating an existing dot-deps.json policy. The first import resolves presets with an isolated, pinned Renovate runtime. Later imports replace explicit override sections, including edits within them, while preserving the native base policy and local check mappings. Unsupported settings are recorded as publication blockers. Importing creates no commits or PRs. Ordinary previews use the saved native policy without running Renovate or refreshing presets. **Options** | Option | Description | | --- | --- | | `--source` `` | Repository-relative Renovate JSON file (default: renovate.json) | | `--timeout` `` | Deadline per import pass (default: 5 minutes) | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | directory | **Examples** ```bash dot deps import renovate dot deps import renovate /path/to/repository ``` ## `dot run` Run a command with a deadline and process-group cleanup ```text dot run [flags] [] ``` Pass the executable and its arguments after --. Standard input, output and errors are inherited. Completion, timeout and SIGINT/SIGTERM/SIGHUP all release the owned process group, first with SIGTERM and then SIGKILL after the cleanup grace period. Use foreground commands: processes that deliberately leave the group or send work to an existing server are outside this ownership. For isolated OpenCode jobs, pass run --standalone. **Options** | Option | Description | | --- | --- | | `--timeout` `` | Execution deadline, for example '5 minutes' or '30 seconds' | | `--kill-after` `` | Cleanup grace period before SIGKILL (default: 5 seconds) | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Executable to run after -- | | `` | Arguments passed unchanged to the command | **Exit codes** ```text Child exit code on completion 124 Execution deadline exceeded 125 Process execution failed 128 + signal number on interruption ``` **Examples** ```bash dot run --timeout '5 minutes' -- opencode2 run --standalone 'Process this capture' ``` ## `dot http` Local HTTP helpers ```text dot http [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot http forward` Forward HTTP and websockets to another server without proxy headers ```text dot http forward [flags] ``` Listens on 127.0.0.1 and forwards HTTP requests and websockets to the target origin, dropping Host and X-Forwarded-* headers so a server that doesn't trust this machine as a proxy accepts them. Use it behind a local HTTPS proxy, such as a pitchfork daemon, to reach a plain HTTP server from an HTTPS page. **Options** | Option | Description | | --- | --- | | `--port` `` | Local port to listen on, bound to 127.0.0.1 | | `--target` `` | Origin to forward to, such as http://host:8123 | | `--help` `-h` | Show help information | **Examples** ```bash dot http forward --port 8126 --target http://homeassistant.local:8123 ``` ## `dot status` Run work under a pinned terminal status header ```text dot status [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot status run` Run a command or pitchfork daemon under a pinned status header ```text dot status run [flags] [] ``` Pins a header to the top of the terminal with the state (Setting up, Starting, Running, Done, Stopped or Failed), the URL and the elapsed time, and keeps the terminal title in step with a spinner while work is in progress. --setup runs in an interactive zsh first. With --pitchfork, an already running daemon prompts before restarting (--attach follows it instead), its logs are followed once it is ready, and Ctrl+C stops it. --background returns once the daemon is ready. Without a TTY, state changes print as lines. **Options** | Option | Description | | --- | --- | | `--title` `` | Name shown in the header and terminal title | | `--url` `` | URL pinned in the header | | `--via` `` | What serves the URL when it is not this command, shown beside it | | `--setup` `` | zsh command run first, under the Setting up state | | `--pitchfork` `` | Pitchfork daemon to start and follow instead of a command | | `--conflicts` `` | Pitchfork daemon that cannot run alongside --pitchfork or the command; asks to stop it first. Repeat for more | | `--attach` | Follow an already running --pitchfork daemon instead of asking to restart it | | `--background` | Return once the pitchfork daemon is ready, leaving it running | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Command and arguments to run after -- | **Examples** ```bash dot status run --title 'Lint' -- pnpm lint dot status run --title 'Core' --url https://dev.example.localhost --setup 'script/bootstrap' --pitchfork core/dev ``` ## `dot updates` Check watched package, Dotfiles and skills updates ```text dot updates [flags] ``` Read cached status immediately and refresh it in the background after 15 minutes. Refresh checks watched apt packages, all dot-managed repositories and whether the managed skills checkout is behind timmo001/skills main, and writes the cache atomically under a shared lock. status --json prints the cached sections and the bar and footer output for other readers such as the OpenCode skill-updates plugin. Use --package-file, --cache-dir and --timeout to override defaults. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot updates status dot updates refresh ``` ### `dot updates status` Print cached status-bar JSON and refresh stale data in the background ```text dot updates status [flags] ``` **Options** | Option | Description | | --- | --- | | `--json` | Print cached dotfiles, skills and package sections, and the bar and footer output, as JSON | | `--help` `-h` | Show help information | **Examples** ```bash dot updates status dot updates status --json ``` ### `dot updates refresh` Refresh package, Dotfiles and skills status ```text dot updates refresh [flags] ``` **Options** | Option | Description | | --- | --- | | `--package-file` `` | Watched package list (default: public dotfiles manifest) | | `--cache-dir` `` | Status cache directory (default: XDG status-bar cache) | | `--timeout` `` | Maximum seconds for each external check | | `--dot-only` | Refresh only Dotfiles status, keeping cached package status | | `--help` `-h` | Show help information | **Examples** ```bash dot updates refresh dot updates refresh --dot-only ``` ## `dot services` Monitor registered systemd user services and timers ```text dot services [flags] ``` Each job registers itself with a YAML descriptor in ~/.config/dot/services.d/, shipped by the stow package that owns the unit. A descriptor names the unit and its monitoring policy: label, history, failAfter (consecutive failures before a job counts as failed), staleAfter (a duration such as "1 hour", counted from the latest of the last completed run, the last boot or resume, and one interval before the first calendar run due after those, so sleep, power off and gaps in the schedule are not missed runs), restartLimit ({ count, within }) for long-running services, notify, logs ({ dir, file }) for jobs that keep their own run logs, and repository (a GitHub owner/repo slug from dot-git.yml) naming the repository that logs and agents open in. A long-running service can add status ({ file }) pointing at a JSON file it writes with health ("ok", "warning", "degraded" or "failed"), summary and updated (epoch milliseconds); while systemd sees the service as healthy, a report from its current run replaces the health and summary. Without repository, the repository containing the unit's executable is used, falling back to the public dotfiles. Optional exitStatuses maps non-zero exit codes to "warning" or "skipped", for example { "2": "warning", "3": "skipped" }. Warnings break the failure streak and count as completed work for staleness; skipped invocations retain the last completed outcome. These are monitor classifications; systemd still records non-zero exits. Run history comes from the user journal. A job can summarise each run by printing a line containing "[RESULT] " followed by a short outcome; the last such line per invocation becomes that run's summary in status, run logs, notifications and the timmo.services panel. Units with OnFailure=dot-service-failed@%n.service call dot services notify, which raises a desktop notification once failAfter is reached and refreshes the timmo.services panel. Timer services with ExecCondition=dot services schedule check run only at their calendar times, or within --grace of one, not as later catch-up runs after boot or resume; those runs show as skipped. dot services start always runs them. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot services status dot services logs dot-deps.timer ``` ### `dot services status` Show the health of registered user services ```text dot services status [flags] ``` **Options** | Option | Description | | --- | --- | | `--json` | Print the full snapshot as JSON | | `--help` `-h` | Show help information | **Examples** ```bash dot services status dot services status --json ``` ### `dot services start` Run a registered job now, or restart a long-running service ```text dot services start [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Registered timer or service unit | **Examples** ```bash dot services start dot-deps.timer ``` ### `dot services stop` Stop a registered job's running service, leaving its timer scheduled ```text dot services stop [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Registered timer or service unit | **Examples** ```bash dot services stop notes-capture-daemon.service ``` ### `dot services logs` Open a registered job's logs in a Herdr tab for the repository that owns it ```text dot services logs [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Registered timer or service unit | **Examples** ```bash dot services logs notes-capture-daemon.service ``` ### `dot services run` Inspect a registered job's recent runs ```text dot services run [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | #### `dot services run logs` Print the journal output of a registered job's most recent runs, newest first, with its latest run log ```text dot services run logs [flags] ``` **Options** | Option | Description | | --- | --- | | `--count` `` | Number of recent runs to include | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Registered timer or service unit | **Examples** ```bash dot services run logs dot-deps.timer dot services run logs skill-updates-agent.timer --count 5 | wl-copy ``` ### `dot services investigate` Open an agent in a registered job's repository, briefed with its recent runs, logs, file locations and commands to investigate them ```text dot services investigate [flags] ``` **Options** | Option | Description | | --- | --- | | `--agent` `` | Installed launcher from dot herdr agents, such as opencode2 | | `--modifiers` `` | Qt keyboard modifier bitmask, as for dot herdr repo open | | `--print` | Print the investigation brief instead of opening the agent | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Registered timer or service unit | **Examples** ```bash dot services investigate skill-updates-agent.timer --agent opencode2 ``` ### `dot services notify` Notify when a registered job has failed (used by OnFailure=) ```text dot services notify [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Registered timer or service unit | **Examples** ```bash dot services notify dot-deps.service ``` ### `dot services schedule` Timer schedule checks for registered jobs ```text dot services schedule [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | #### `dot services schedule check` Skip a timer's catch-up run after boot or resume (used by ExecCondition=) ```text dot services schedule check [flags] ``` **Options** | Option | Description | | --- | --- | | `--grace` `` | How long after a calendar time a catch-up run still goes ahead (default: 5 minutes) | | `--help` `-h` | Show help information | **Examples** ```bash dot services schedule check dot services schedule check --grace '4 hours' ``` ## `dot fans` Control chassis fans from a Home Assistant temperature ```text dot fans [flags] ``` Reads ~/.config/dot/fans.yml: entity (a Home Assistant temperature sensor), device (a liquidctl --match string), channels (a list such as fan1 and fan2), ramp ({ from, to } in °C) and speed ({ min, max } in percent). Watches the entity through ha-bridge and ramps the channels linearly from speed.min at ramp.from to speed.max at ramp.to, in 5% steps. An unavailable or non-numeric reading, no reading within 30 seconds, or a stopped watcher sets speed.max until readings resume; the watcher restarts after 15 seconds. Health is written to $XDG_STATE_HOME/dot/fans/status.json for the status field of a dot services descriptor. Stopping hands the device back to motherboard control with liquidctl initialize. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot fans run ``` ### `dot fans run` Control chassis fans from a Home Assistant temperature (used by dot-fans.service) ```text dot fans run [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot fans run ``` ## `dot tunnel` Run shared Cloudflare tunnels on one machine at a time ```text dot tunnel [flags] ``` Runs cloudflared with the token in ~/.config/dot/tunnels/.token, checking every 15 seconds which connectors the tunnel has, through the Cloudflare API with the token in ~/.config/dot/tunnels/cloudflare-api-token (Account > Cloudflare Tunnel > Read). The connector whose live connections opened first keeps the tunnel. A machine that finds another connector stops its own cloudflared and waits until none is left, so a laptop that wakes from sleep after another machine took over gives the tunnel back. Health is written to $XDG_STATE_HOME/dot/tunnels//status.json for the status field of a dot services descriptor: ok while serving, warning while another machine holds the tunnel or the API can't be checked. Without an answer from the API it never starts cloudflared, and keeps a running one going. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot tunnel run timmo ``` ### `dot tunnel run` Run a Cloudflare tunnel on one machine at a time (used by dot-tunnel@.service) ```text dot tunnel run [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Tunnel name, matching ~/.config/dot/tunnels/.token | **Examples** ```bash dot tunnel run timmo ``` ## `dot stow` Re-stow public/private dotfiles ```text dot stow [flags] ``` **Options** | Option | Description | | --- | --- | | `--public` | Stow public dotfiles only | | `--private` | Stow private dotfiles only | | `--help` `-h` | Show help information | ## `dot session` Inspect agent sessions ```text dot session [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot session status` Query an OpenCode 2 session's model, variant and context pressure ```text dot session status [flags] ``` Read-only OpenCode 2 session inspection through the configured launcher. Pass the exact session ID supplied in the agent's environment context; it is not inferred from the focused pane, working directory or a guessed shell variable. Reports the selected model and variant, supported variants, model limits, latest completed assistant token measurement, its age, the latest completed compaction, and separately labelled cumulative usage and cost. Context tokens include non-cached input, cache reads and writes, output and reasoning, matching OpenCode's display. Input usage includes non-cached and cached input. Pressure uses whichever percentage is higher: context-window usage or input-limit usage. Current usage is unknown after compaction without a new measurement, after a model/variant switch, or with a staged revert. Later tool results and messages are not counted. Looks back through at most 20 messages per type and marks incomplete lookups. --warn-at defaults to 70 percent: a workflow heuristic, not a proven cognitive degradation threshold. The command does not change models, compact or open sessions. **Options** | Option | Description | | --- | --- | | `--warn-at` `` | Context or input percentage prompting a scope or handoff review (default: 70) | | `--json` | Print model, limits, context measurement and cumulative usage as JSON | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Exact OpenCode 2 session ID from the agent's injected context | **Examples** ```bash dot session status ses_example --json dot session status ses_example --warn-at 80 ``` ## `dot snapshot` Save a CPU and memory snapshot with process rankings ```text dot snapshot [flags] ``` Print a Markdown CPU and memory summary with a usage-filtered process tree. --sort mem defaults to an 80 MiB measured subtree PSS cutoff; --sort cpu defaults to 1% of one core. Adjust these with --min-memory-mib and --min-cpu. Each tree row shows aligned memory and CPU totals beside the process name. Totals include hidden children, so small workers can qualify together; parent and child totals overlap. Expand the largest remaining qualifying branch until --limit visible processes are reached (default: 40, including ancestors). Zero-usage branches are omitted. The saved report adds CPU, memory and process-name rankings with the same cutoffs and per-table limit, plus pressure measurements. Interactive human runs open it in $EDITOR (vi if unset). The internal dot agent detect check automatically selects JSON. JSON retains all sampled processes and the complete processTree, and reportSelection identifies visible PIDs, cutoffs, the limit and omitted count. Missing measurements are null; unavailable parents are marked. CPU is sampled over approximately one second; 100% per process means one logical CPU. PSS divides shared pages between processes. Reports are saved in the system temporary directory ($TMPDIR, normally /tmp), named dot-snapshot-.md or .json. Existing output files are never overwritten. **Options** | Option | Description | | --- | --- | | `--sort` `` | Sort the process tree and JSON process list by CPU or memory (choices: cpu, mem) | | `--limit` `` | Maximum visible tree processes, including parents, and entries per ranking table | | `--min-memory-mib` `` | Minimum measured subtree PSS in MiB for memory sorting (default: 80) | | `--min-cpu` `` | Minimum measured subtree CPU percentage for CPU sorting (default: 1; 100% = one core) | | `--help` `-h` | Show help information | **Examples** ```bash dot snapshot dot snapshot --sort cpu dot snapshot --limit 40 dot snapshot --min-memory-mib 50 ``` ## `dot firewall` Reconcile managed ufw firewall rules ```text dot firewall [flags] ``` Ensure the managed ufw allow rules are present with their exact source, destination, interface/direction, and purpose comment. Missing rules are added, stale-comment rules are deleted and re-added, then ufw is reloaded once. A source-restricted rule does not satisfy a managed any-source rule. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot firewall ``` ## `dot doctor` Run parallel health checks for dependencies, repositories, stow integrity, services, apt packages, firewall rules, and OpenCode/Herdr integration. A timestamped report is always written under ~/.local/state/dot/logs/. ```text dot doctor [flags] ``` Run health checks on the dotfiles system. All checks run in parallel and each section streams to the terminal as it finishes, followed by a grouped summary. A timestamped log is always written under ~/.local/state/dot/logs/. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Checks performed** ```text Dependencies and configured gh extensions Repositories, origin HEAD, git config, and stow integrity OpenCode, Herdr, notifications, timers, and registered services Public/private apt packages, managed firewall rules, and Syncthing ``` **Exit codes** ```text 0 No critical errors (warnings may still be present) 1 One or more critical errors found ``` ## `dot clean` Unstow managed dotfiles ```text dot clean [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ## `dot agent` Agent harness tooling: instruction sync, linting and detection ```text dot agent [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot agent sync` Mirror AGENTS.md to agent harness instruction files ```text dot agent sync [flags] ``` Mirror ~/.config/opencode/AGENTS.md to each agent harness's instruction file, then trust each tracked repository from private dot-git.yml in Claude Code (~/.claude.json) so it opens without the workspace trust prompt. Each repository is trusted once, the first time its checkout exists; dot remembers it in its state directory, so untrusting it in Claude Code later sticks. Runs as part of dot update and dot init. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot agent sync ``` ### `dot agent lint` Run the repository's agent_lint commands from private dot-git.yml on changed files ```text dot agent lint [flags] [] ``` Collect files changed in the working tree against HEAD, plus untracked files that are not ignored, and run the configured agent_lint commands in parallel from the repository root under dot run --timeout, reporting results in config order. Deleted files and submodule changes are left out. Paths narrow the changed files. --all uses every tracked and untracked file that is not ignored instead, so commands run without changes. --only runs just the named commands and reports only those. A run argument of exactly {files} expands to the changed files matching the command's include globs; commands without it run as they are, but only when a changed file matches. Each result is passed, failed, timed-out or skipped, with the last lines of output for failures. Exits non-zero when any command fails or times out. Repositories without agent_lint print a notice and exit zero. **Options** | Option | Description | | --- | --- | | `--json` | Print one JSON report instead of log lines | | `--all` | Lint every file, not only changed ones | | `--only` `` | Run only the command with this name; repeatable | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | path | **Examples** ```bash dot agent lint dot agent lint --json dot agent lint src/one.ts src/two.ts --json dot agent lint --all --only Typecheck --json ``` ### `dot agent oxlint` Run the advisory generic Oxlint pass on JavaScript and TypeScript changes in an opted-in repository. Repository-owned Oxlint takes precedence. Use --changed normally, explicit paths to lint whole files, or --all when explicitly requested. Pass --force to run despite those skips. ```text dot agent oxlint [flags] [] ``` Run the generic @timmo001/oxlint-rules recommended config from a dot-managed cache without changing the target repository. The current repository must set agent_oxlint: true in private dot-git.yml. Repositories with their own Oxlint config, dependency, script, or local binary are skipped because their local setup takes precedence. Pass --force to run anyway. Diagnostics are advisory and do not make these personal rules authoritative for the host repository. --changed compares the working tree and untracked files with HEAD, prints only findings on added or modified lines, and exits non-zero when any remain. Paths with --changed limit that comparison to those files or directories. dot git commit runs the same check on the files it commits. **Modes** ```text --changed Lint uncommitted changes, reporting only changed lines; add paths to narrow ... Lint explicit files or directories in full --all Lint the complete repository tree --force Run even if opt-in or repository Oxlint would skip --opt-in Enable and commit the existing config entry; add paths or --all to also lint ``` **Options** | Option | Description | | --- | --- | | `--all` | Lint the complete repository tree | | `--changed` | Lint uncommitted changes and report only findings on changed lines; paths narrow the scope | | `--opt-in` | Enable the existing private config entry and commit the single-line change | | `--force` | Run even if the repository is not opted in or already has Oxlint | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | path | **Opt-in** ```text --opt-in adds or sets only agent_oxlint: true in an existing private repository entry, preserving all other bytes. If the entry is missing, it offers the repo induct wizard with agent Oxlint prefilled as enabled. Without a terminal it prints induction instructions. The config must be tracked and clean. Active commit hooks are refused rather than bypassed so formatters cannot expand the change. Commits through dot git commit without pushing; unrelated staged files are excluded. An existing opt-in creates no commit. ``` **Examples** ```bash dot agent oxlint --changed dot agent oxlint --changed src/example.ts dot agent oxlint src/example.ts dot agent oxlint src/one.ts src/two.ts dot agent oxlint --all dot agent oxlint --force src/example.ts dot agent oxlint --opt-in ``` ### `dot agent detect` Detect whether an AI coding agent is running dot ```text dot agent detect [flags] ``` Detect whether dot is running under an agent harness from agent environment variables, falling back to a Linux /proc process-ancestry check. Exits 0 when an agent is detected and 1 otherwise, so scripts can branch with `if dot agent detect`. Set DOT_AGENT=1 to force detection on or DOT_AGENT=0 to force it off. **Modes** ```text (default) Print the detected agent, or a no-agent message --quiet Print only the provider id (nothing when no agent) --json Print the detection result as JSON ``` **Options** | Option | Description | | --- | --- | | `--quiet` `-q` | | | `--json` | Print JSON | | `--help` `-h` | Show help information | **Examples** ```bash dot agent detect dot agent detect --quiet dot agent detect --json dot agent detect && echo running under an agent ``` ### `dot agent permission` Apply OpenCode permissions to other agent harnesses ```text dot agent permission [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | #### `dot agent permission hook` Enforce OpenCode permission rules in Claude Code ```text dot agent permission hook [flags] ``` Claude Code PreToolUse hook. Reads the hook event from stdin, maps the tool call onto OpenCode actions (shell, read, edit, external_directory, MCP server tools, webfetch, websearch, todowrite), and evaluates the permissions in ~/.config/opencode/opencode.json, followed by any opencode.json in the directories from below home down to the session directory, with OpenCode's semantics: the last matching rule wins and each part of a compound shell command is checked. Prints allow, ask or deny for Claude Code, or nothing when no rule decides so Claude Code's own prompting applies. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot agent permission hook < event.json ``` ### `dot agent review` Hold agent harnesses to the change review handoff ```text dot agent review [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | #### `dot agent review hook` Hold Claude Code to the change-review-handoff skill ```text dot agent review hook [flags] ``` Claude Code Stop hook. Reads the hook event from stdin and the session transcript it names. When the current turn edited files outside /tmp and ~/.claude, and nothing after the last edit opened a Plannotator review, loaded change-review-handoff or messaged the Plannotator Inbox, it blocks the stop once and tells the agent to hand the change off or say why it does not apply. A repeated stop in the same turn always goes through. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot agent review hook < event.json ``` ## `dot notes` Integrate with the notes tool ```text dot notes [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot notes capture` Manage the notes capture Worker ```text dot notes capture [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | #### `dot notes capture sync` Sync watched repositories to the notes capture picker ```text dot notes capture sync [flags] ``` Regenerate the notes capture repository picker from repositories with GitHub notifications enabled in the private dot-git.yml configuration. Updates only CAPTURE_REPOSITORIES in the ignored capture/wrangler.local.jsonc file, creating it from the deploy template when needed. Mirrors non-secret settings from the active Worker, then deploys when the live picker differs. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot notes capture sync ``` ## `dot git` Work across tracked Git repositories ```text dot git [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot git diff` Show repository change state across all tracked repositories. ```text dot git diff [flags] ``` **Modes** ```text (default) Text summary of repos with changes --bar-json JSON output for status bars --panel-json Full JSON panel snapshot ``` **Options** | Option | Description | | --- | --- | | `--bar-json` | JSON output for status bars and shell modules | | `--panel-json` | Full JSON snapshot for the native shell panel | | `--help` `-h` | Show help information | **Examples** ```bash dot git diff dot git diff --bar-json dot git diff --panel-json ``` ### `dot git log` Show recent commits across managed repositories ```text dot git log [flags] ``` Lists the latest commits on each managed checkout's branch, including fetched upstream commits that are not pulled yet. Results are cached per repository and only re-read when HEAD or the upstream ref moves; --refresh re-reads everything. **Options** | Option | Description | | --- | --- | | `--refresh` | Re-read every repository, ignoring the cache | | `--panel-json` | Return managed repositories and their recent commits as JSON | | `--help` `-h` | Show help information | **Examples** ```bash dot git log dot git log --panel-json dot git log show --path ~/repos/example --sha abc1234 dot git log show --path ~/repos/example --from def5678 --sha abc1234 dot git log show --path ~/repos/example --changes uncommitted ``` #### `dot git log show` Return changed files and a diff preview as JSON for the Git panel, for one commit, a commit range or a repository's local changes ```text dot git log show [flags] ``` **Options** | Option | Description | | --- | --- | | `--path` `` | Managed repository checkout path | | `--sha` `` | Full or abbreviated commit SHA | | `--from` `` | Show the net changes to --sha from this earlier commit, or from the empty tree with root | | `--file` `` | Repository-relative file to limit the result to; repeatable | | `--changes` `` | Preview uncommitted changes including untracked files, commits not pushed upstream, or fetched commits not pulled yet (choices: uncommitted, unpushed, incoming) | | `--help` `-h` | Show help information | ### `dot git commit` Commit staged changes through the guarded gateway. Subjects must be one line, have no trailing full stop, and stay within the hard length limit. Explicit --path scopes never imply git add -A; --amend keeps the existing message unless --message is supplied. ```text dot git commit [flags] ``` Create a commit through dot's guarded gateway instead of raw git commit. The subject is validated as a single line with no trailing full stop and a length limit, then the staged set (or an explicit --path scope) is committed. It never runs git add -A. Pass --amend to rewrite the previous commit instead of creating a new one; it keeps the existing message unless you pass --message. With --push, an amend force-pushes with --force-with-lease, never a plain force. In repositories opted into agent Oxlint, the files being committed are linted and only findings on added or modified lines are reported. Warnings print and the commit continues; errors refuse the commit until they are fixed or --skip-agent-oxlint is passed. Agents are routed here by the dot-git-commit skill and blocked from raw git commit in the OpenCode permission config. **Modes** ```text (default) Commit the staged set --path Commit only named files --amend Rewrite the previous commit --dry-run Preview the plan without changes ``` **Options** | Option | Description | | --- | --- | | `--message` `-m` `` | Single-line commit subject | | `--path` `` | Commit only this file; repeatable | | `--amend` | Amend the previous commit | | `--push` | Push after committing | | `--dry-run` | Preview without changing anything | | `--skip-agent-oxlint` | Commit despite agent Oxlint errors on changed lines | | `--help` `-h` | Show help information | **Message guards** ```text Single line Rejects multi-line messages No em/en-dash Rejects em/en-dashes; use a hyphen No full stop Rejects a trailing full stop Warn over 60 Warns on stderr, still commits Reject over 120 Fails; shorten the subject ``` **Base branch guard** ```text Refuses commits to the base branch of a repo you do not own. Owners you control are listed in git config dot.owner. Work on a feature branch. For a maintained fork with an owned origin, opt in one exact branch with git config --local dot.maintainedForkBranch . The exception requires owned origin fetch and push targets; global settings are ignored. ``` **Examples** ```bash dot git commit -m "Add commit gateway" dot git commit -m "Scope to one file" --path src/git/commands/Status.ts dot git commit -m "Commit and push" --push dot git commit --amend dot git commit --amend -m "Reword the previous commit" dot git commit -m "Preview only" --dry-run ``` ### `dot git notifications` Read the authenticated GitHub notification inbox as JSON. --all and --participating filter it. ```text dot git notifications [flags] ``` **Modes** ```text (default) Open the shell notification panel --bar-json Status-bar JSON ``` **Options** | Option | Description | | --- | --- | | `--bar-json` | JSON output for status bars and shell modules | | `--all` | Include read notifications | | `--participating` | Only participating threads | | `--mark-read` `` | Mark a thread as read | | `--help` `-h` | Show help information | **Examples** ```bash dot git notifications dot git notifications --bar-json dot git notifications --participating dot git notifications dismiss --dry-run dot git notifications --mark-read 12345 ``` #### `dot git notifications dismiss` Show a coloured repository summary, then review merged dependencies followed by remaining unread notifications. Done queues work in the background while progress appears above the next choices. Every repository offers Done, Open on GitHub, Skip and Stop. Stop ends the questions and finishes queued work before a completion and issues summary. --repo selects a single notification stack. Bar hiding preferences do not restrict this inbox. ```text dot git notifications dismiss [flags] ``` **Options** | Option | Description | | --- | --- | | `--repo` `` | Configured repository name/path or GitHub owner/repository | | `--dry-run` | Print repository batches and reasons without changing notifications | | `--help` `-h` | Show help information | **Examples** ```bash dot git notifications dismiss dot git notifications dismiss --repo owner/repository dot git notifications dismiss --dry-run dot git notifications dismiss dependencies --mode all dot git notifications dismiss remaining ``` #### `dot git notifications dismiss dependencies` Review unread merged Renovate/Dependabot updates regardless of CI results. All-mode excludes unverifiable CI and exits 2 when some notifications could not be inspected but nothing failed. Opening GitHub returns to the review without dismissing anything. The dot-notifications-dismiss.timer user timer runs all-mode every 15 minutes; dot services start dot-notifications-dismiss.timer runs it now. ```text dot git notifications dismiss dependencies [flags] ``` **Options** | Option | Description | | --- | --- | | `--repo` `` | Configured repository name/path or GitHub owner/repository | | `--dry-run` | Print repository batches and reasons without changing notifications | | `--mode` `` | Mark all verified dependencies done, or prompt per repository; omit to choose (choices: all, repos) | | `--help` `-h` | Show help information | #### `dot git notifications dismiss remaining` Review all other unread notifications per repository, including PRs with unresolved CI and their reasons. This pass always requires a choice before dismissal. ```text dot git notifications dismiss remaining [flags] ``` **Options** | Option | Description | | --- | --- | | `--repo` `` | Configured repository name/path or GitHub owner/repository | | `--dry-run` | Print repository batches and reasons without changing notifications | | `--help` `-h` | Show help information | ### `dot git releases` Compare enabled repositories with their latest published stable release, explain impact and retain local reviews. ```text dot git releases [flags] ``` Read the last local snapshot, collecting one on first use. --refresh fetches immutable release and branch refs immediately; --scheduled follows each repository's local-time cron and records attempted minutes. Draft and prerelease releases are excluded. Before the first stable release, the comparison covers the full history with the same quiet rules, and the first version is 0.1.0 (1.0.0 for a major impact), today's CalVer or the upstream fork base. Failed checks retain previous evidence marked stale; with --refresh the output is still printed, then the command exits non-zero naming each repository that could not be refreshed. Quiet changes remain inspectable. Desktop notifications require --notify and honour configured minimum impact and cooldown. --open opens the release review, optionally selected by --repo, without fetching. Local reviews require the displayed snapshot ID. Finding overrides follow exact evidence; an overall override follows the release-relevant comparison. Changed evidence invalidates its review. Use --impact auto to clear an override. Extra CI-only commits do not repeat delivery. Incomplete or stale evidence cannot be reviewed. **Options** | Option | Description | | --- | --- | | `--repo` `` | Select an enabled repository by name or GitHub slug | | `--scheduled` | Check only in a due cron minute, once per minute | | `--refresh` | Fetch now, bypassing the schedule and cache | | `--notify` | Send eligible desktop notifications with review actions | | `--panel-json` | Complete JSON review snapshots, including quiet changes and errors | | `--help` `-h` | Show help information | **Policy** ```text Optional releases config selects oxlint-rules or system-bridge and a watched branch. Private overrides precede preset rules; the first match wins for each fact. Match paths with globs, change_types, exact dependencies, roles, submodules or explicit subjects regexes. Selectors are ANDed; values within each selector are ORed. Explicit path overrides match either rename endpoint. Preset rename impact is the highest affected old/new boundary; both endpoints must be quiet for a quiet rename. Subject selectors follow surviving source lines or individual structured values, excluding reverted intent. Each net fact is classified once; any attributed subject can match the first applicable ordered rule. Every override supplies impact (none/patch/minor/major) and a readable reason. Dependency versions never imply consumer minor or major changes. Notification enabled/minimum_impact/cooldown_minutes are stored for future explicit delivery. ``` **Examples** ```bash dot git releases dot git releases --refresh --panel-json dot git releases --scheduled --notify --panel-json dot git releases --open --repo example/project dot git releases review --repo example/project --snapshot ID --finding FINDING --impact patch dot git releases review --repo example/project --snapshot ID --finding ONE --finding TWO --impact none dot git releases review --repo example/project --snapshot ID --impact auto dot git releases publish --repo example/project --snapshot ID --notes-file notes.md dot git releases publish --repo example/project --snapshot ID --notes-file notes.md --notes-mode replace --confirm PLAN ``` #### `dot git releases review` Review exact local release evidence without publishing anything ```text dot git releases review [flags] ``` **Options** | Option | Description | | --- | --- | | `--repo` `` | Configured repository name or GitHub slug | | `--snapshot` `` | Exact displayed snapshot ID; stale selections are rejected | | `--panel-json` | Return the updated complete JSON snapshot | | `--finding` `` | Finding ID, or overall for the current release-relevant comparison (default); repeatable to set several findings at once | | `--impact` `` | Local release impact; auto clears the override (choices: none, patch, minor, major, auto) | | `--help` `-h` | Show help information | #### `dot git releases publish` Preview version changes, validation, pushes and release notes. --interactive explains and confirms in the terminal; --confirm PLAN executes a reviewed plan with live progress. --notes-file supplies hand-written notes. ```text dot git releases publish [flags] ``` Requires an explicit private releases.publish recipe. The preview is read-only. Confirmation binds the reviewed snapshot, version files, commands and target. Preparation runs in an isolated worktree. Only agreed version changes, plus any releases.publish.generated_files the commands regenerate (such as a lockfile), are committed through dot git commit, then the version commit and tag are pushed atomically. GitHub release notes are generated from the previous stable release (or the full history for a first release), unless --notes-file supplies hand-written notes. The file must exist and not be empty; its text is shown in the preview and bound to the plan, so pass the same --notes-file on confirmation and an edited file needs a new preview. --notes-mode prepend (default) puts the file before the generated notes, editing the release straight after creation; replace uses only the file. Progress includes command output and a saved log. Release creation does not wait for GitHub publication jobs; follow the returned Actions URL. Failed preparation is retained for inspection. Refresh and preview again after resolving a failure. **Options** | Option | Description | | --- | --- | | `--repo` `` | Configured repository name or GitHub slug | | `--snapshot` `` | Exact displayed snapshot ID; stale selections are rejected | | `--panel-json` | Stream JSON progress and the final plan or release result | | `--interactive` | Explain, confirm and run the release in this terminal, with an optional log pager | | `--confirm` `` | Execute the exact plan ID returned by the preview | | `--notes-file` `` | Markdown file with hand-written release notes, read at preview and again at confirmation | | `--notes-mode` `` | Put --notes-file before the generated notes (prepend, default) or use it alone (replace) (choices: prepend, replace) | | `--help` `-h` | Show help information | ### `dot git issues` Track open issues for enabled repositories, independently of GitHub notifications ```text dot git issues [flags] ``` Opt in with issues.enabled in private dot-git.yml. Open issues exclude pull requests and are ordered by latest update. Rules under the top-level issues.exclude list hide matching issues, such as a Dependency Dashboard; each rule matches when every field it sets (title, author, label and optional repo) matches, case-insensitively. Queries fetch at most every five minutes unless --refresh is supplied. Failed fetches retain the last successful list and report an error. **Options** | Option | Description | | --- | --- | | `--repo` `` | Select an enabled repository by name or GitHub slug | | `--refresh` | Fetch now instead of using the five-minute cache | | `--panel-json` | Return enabled repositories and their open issues as JSON | | `--help` `-h` | Show help information | **Examples** ```bash dot git issues --panel-json dot git issues --refresh ``` ## `dot mcp` Manage agent MCP server configs ```text dot mcp [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot mcp sync` Regenerate MCP configs for all harnesses from the spec ```text dot mcp sync [flags] ``` Regenerate each active harness's native MCP config from the private spec (mcp.yml). Repository opencode_mcp lists in dot-git.yml opt into named servers using generated, Git-ignored .opencode/opencode.jsonc files; removing an opt-in removes its generated config. Existing unowned or tracked configs are preserved and reported as conflicts. Global configs are written into the stowed private source tree; run dot stow after. Claude Code's user scope is updated through the claude CLI instead of a file. Some agent harnesses are documented stubs and are not written. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Examples** ```bash dot mcp sync ``` ## `dot skills` Maintain imported agent skills ```text dot skills [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot skills validate` Validate the standalone skills repository ```text dot skills validate [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot skills import` Import or refresh a reviewed skill snapshot ```text dot skills import [flags] ``` **Options** | Option | Description | | --- | --- | | `--apply` | Apply a clean imported snapshot | | `--metadata-only` | Materialise metadata only | | `--reviewed-sha` `` | Set the reviewed upstream SHA | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Imported skill name | ### `dot skills updates` Check/apply imported skill updates ```text dot skills updates [flags] ``` **Options** | Option | Description | | --- | --- | | `--check` | Check only | | `--update` | Apply clean updates | | `--json` | Report as JSON | | `--skill` `` | Limit to one skill | | `--no-commit` | Apply without committing | | `--skip-review` | Skip local-edit review | | `--help` `-h` | Show help information | **Examples** ```bash dot skills updates --json dot skills updates --update --skill agentic-workflows --no-commit ``` #### `dot skills updates agent` Run skill update automation ```text dot skills updates agent [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | #### `dot skills updates agent github` Run GitHub skill update automation ```text dot skills updates agent github [flags] ``` **Options** | Option | Description | | --- | --- | | `--skills-dir` `` | Use this Skills checkout | | `--help` `-h` | Show help information | #### `dot skills updates agent device` Run local device skill update automation ```text dot skills updates agent device [flags] ``` **Options** | Option | Description | | --- | --- | | `--config` `` | Use this YAML config | | `--run-id` `` | Wait for this workflow run | | `--help` `-h` | Show help information | ### `dot skills check` Check adapted imports against upstream ```text dot skills check [flags] ``` **Options** | Option | Description | | --- | --- | | `--open-opencode` | Attempt OpenCode analysis | | `--diff-origin` | Diff against upstream origins | | `--skill` `` | Check one skill | | `--help` `-h` | Show help information | **Examples** ```bash dot skills check --skill agentic-workflows ``` ### `dot skills consumers` Manage repositories that receive shared skill copies ```text dot skills consumers [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | #### `dot skills consumers add` Share skills with a repository through consumers.yml, push the change and install them there straight away ```text dot skills consumers add [flags] ``` **Options** | Option | Description | | --- | --- | | `--repo` `` | owner/name of the consumer repository (default: the current directory's GitHub repository) | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Skills to share with the repository | **Examples** ```bash dot skills consumers add code-review testing dot skills consumers add --repo timmo001/ha-bridge writing-style ``` #### `dot skills consumers remove` Stop sharing skills with a repository through consumers.yml, push the change and remove the copies there straight away. Dropping the last skill, or --all, also drops its entry. ```text dot skills consumers remove [flags] [] ``` **Options** | Option | Description | | --- | --- | | `--repo` `` | owner/name of the consumer repository (default: the current directory's GitHub repository) | | `--all` | Stop sharing every skill, remove the copies now and drop the repository | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Skills to stop sharing with the repository | **Examples** ```bash dot skills consumers remove writing-style dot skills consumers remove --repo timmo001/ha-bridge --all ``` ## `dot completions` Generate shell completions ```text dot completions [flags] [] ``` Generate the managed dot and skill-maintenance completion files for the selected shell so the next dot stow installs them. **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Shell to generate completions for | **Examples** ```bash dot completions zsh dot completions bash dot completions fish ``` ## `dot repo` List and induct tracked repositories in private dot-git.yml ```text dot repo [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot repo list` List tracked repositories and shortcuts from private dot-git.yml ```text dot repo list [flags] [] ``` Read-only lookup of the repositories and path shortcuts configured in private dot-git.yml, the same list behind the prefix+s picker and repository shortcuts. Reads the config directly, so it does not depend on the generated picker cache. Each entry reports name, path, github (null for shortcuts), aliases, kind, whether the checkout exists and whether it is the deepest tracked path containing the working directory. Each entry also reports herdr: live state from the shared Herdr server (HERDR_SOCKET_PATH or the default socket), with open, the workspaces labelled with the repository name or inside its worktrees (id, label, focused, tabCount, paneCount, agentStatus, checkoutPath, linkedWorktree), and the agents running in them (name, agent, status, workspaceId, paneId, focused, cwd). herdr is null when the server cannot be reached; agent status is a snapshot. A query matches name, aliases, GitHub slug or repository name, and path, case-insensitively, with exact matches first. --open keeps only repositories with an open Herdr workspace, and fails when the Herdr server cannot be reached. Prints JSON with --json or when run under an AI agent, otherwise an aligned table. Exits 1 when a query matches nothing, and fails when private config is unavailable or invalid. **Options** | Option | Description | | --- | --- | | `--open` | Only list repositories open in Herdr | | `--json` | Print JSON (the default under an AI agent) | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Filter by name, alias, GitHub slug or path (exact matches first) | **Examples** ```bash dot repo list dot repo list notes dot repo list arch-repo --json dot repo list --open --json ``` ### `dot repo search` Fuzzy-search tracked repositories and shortcuts ```text dot repo search [flags] ``` Ranks tracked repositories from private dot-git.yml by fuzzy match on name, aliases, GitHub repository name, GitHub slug, directory name and path (path matches count for less). Each whitespace-separated term must match some field, with typo and partial-word tolerance loose enough for ambiguous queries, though a term found only inside other words (her in weather) scores lower; matches under 40 or more than 20 points below the best are dropped. Returns the top 5 by default; use --limit to change that or --all for every close match, such as a whole group of repositories. Results carry the same fields as dot repo list, including herdr, plus score (1 to 100) and matched (the fields that matched), highest score first. JSON is { results, hint }, where hint says how many more matches --limit or --all would show and is omitted when there are none; the table ends with the same hint. Prints JSON with --json or when run under an AI agent, otherwise an aligned table. Exits 1 when nothing matches. **Options** | Option | Description | | --- | --- | | `--limit` `` | Maximum results (default: 5) | | `--all` | Return every close match instead of the top 5 | | `--json` | Print JSON (the default under an AI agent) | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | Fuzzy terms matched against name, aliases, GitHub repository name and slug, directory and path | **Examples** ```bash dot repo search dotfiles dot repo search home assistant dot repo search notse --limit 3 --json dot repo search ha --all ``` ### `dot repo induct` Induct a local repository into private dot git config with a preview before committing ```text dot repo induct [flags] [] ``` The terminal wizard asks for Normal (first and default) or Home Assistant, then every repository field using private dot-git-presets.yml defaults and local Git identity, including an optional release watching template from its release_templates. Flags prefill the wizard. With --noninteractive, flags override preset defaults and the command only previews; repeat the reviewed options with --commit to save. Each run validates the complete config and shows the exact diff. The config must be tracked and clean; active commit hooks are refused. Existing entries and formatting are preserved. Commits through dot git commit without pushing or including unrelated staged files. Repositories already inducted are rejected; use dot agent oxlint --opt-in to enable their agent pass. **Options** | Option | Description | | --- | --- | | `--preset` `` | Private preset (default: normal) (choices: normal, home-assistant) | | `--name` `` | Friendly repository label | | `--github` `` | GitHub owner/repository (default: origin remote) | | `--aliases` `` | Space- or comma-separated aliases; empty for none | | `--post-update` `` | Post-update command; empty for none | | `--agent-oxlint` | Enable agent Oxlint; --no-agent-oxlint disables it | | `--activity-enabled` | Enable activity checks; --no-activity-enabled disables them | | `--activity-schedule` `` | Activity schedule: five-field cron or work | | `--notifications-enabled` | Enable notifications; --no-notifications-enabled disables them | | `--notifications-schedule` `` | Notification schedule: five-field cron or work | | `--ignore-bot-activity` | Filter bot-only activity; --no-ignore-bot-activity shows it | | `--pull-requests` | Show open pull requests in the Git panel; --no-pull-requests hides them | | `--issues` | Show open issues in the Git panel; --no-issues hides them (default: the preset, for repositories you own with GitHub issues enabled) | | `--browser` `` | Named browser from dot-git.yml; empty for the desktop default | | `--herdr-after` `` | Herdr workspace to open after; empty for none (default: last entry with the preset prefix) | | `--notes-remote` `` | Git remote for notes; empty for none (default: upstream when present) | | `--agent-lint` `` | Agent lint command, split on spaces; empty for none | | `--opencode-mcp` `` | Space- or comma-separated OpenCode MCP servers; empty for none | | `--release-template` `` | Private release template name from dot-git-presets.yml, or none | | `--release-branch` `` | Branch compared with the published release (default: the template's branch, then origin's default branch) | | `--noninteractive` | Use flags and preset defaults without questions; preview by default | | `--commit` | Commit the proposed entry with --noninteractive after reviewing its preview | | `--help` `-h` | Show help information | **Arguments** | Argument | Description | | --- | --- | | `` | path | **Examples** ```bash dot repo induct dot repo induct ~/repos/example --noninteractive --preset normal --name Example --aliases example dot repo induct ~/repos/example --noninteractive --preset normal --name Example --aliases example --commit ``` ## `dot pr` Watch, list, read reviews on and queue pull requests ```text dot pr [flags] ``` **Options** | Option | Description | | --- | --- | | `--help` `-h` | Show help information | ### `dot pr watch` Watch pull request runs, checks and reviews, streaming progress and a full report ```text dot pr watch [flags] [] ``` Follow every GitHub Actions run on each pull request's head commit, including Copilot code review runs, plus external status checks. Superseded runs of the same workflow on the same commit are ignored, and a new push moves the watch to the new head. Progress streams to stdout one line per event; failed job logs and the final review dump go to a Markdown report whose path is printed first and last. Failed jobs are reported as soon as they finish, even while the rest of the run continues. The watch ends after two settled polls, waiting up to five more minutes for requested bot reviews. The review dump lists reviews newest first, unresolved threads with every comment in full, and resolved or minimized threads with only their replies. The command never changes the pull request. Designed for OpenCode 2 background shells: the completion notification carries the short summary and the report holds the detail. **Options** | Option | Description | | --- | --- | | `--repo` `` | Repository slug when the PRs are elsewhere | | `--stop-on` `` | Stop early on a failed job or check, or review feedback: a new review's open threads or review body findings, or unanswered threads already there at the start; repeatable (choices: failure, review) | | `--timeout` `` | Overall watch deadline (default: 60 minutes) | | `--interval` `` | Seconds between polls | | `--log-lines` `` | Trailing failed-log lines kept per job; 0 keeps everything | | `--output` `` | Report path (default: ~/.local/state/dot/pr-watch/--