--- title: Environment Variables description: All DOT_*, DOTFILES_*, and OMARCHY_* options that influence dot. sidebar: order: 2 --- These variables tune paths and behaviour for `dot`. Most have sensible defaults; set them only when you need to override the default. ## Managed toolchain The global mise configuration (`mise/.config/mise/config.toml`) pins the shared developer toolchain, including the Skills CLI used by `dot skill-updates` and [memex](https://github.com/nicosuave/memex) for browsing and searching local coding-agent history. The matching Herdr plugin provides session palettes, browsing, resume, indexing, and web UI actions. Node.js and Bun versions are also declared in the repository root `mise.toml` for `dot` and `docs` tasks. Python 3.14 and [uv](https://docs.astral.sh/uv/) are installed through mise for Python package and virtual-environment management. Use `uv` directly for project work; `topgrade` leaves mise pins unchanged unless you run `mise install` or `dot update`. The stowed `mise` wrapper keeps the global config under dotfiles control. Commands such as Omarchy's `mise use -g ` are redirected to `~/.local/state/mise/omarchy-config.toml`, while reads, installs, upgrades, project-local writes, and mise-generated tool shims continue normally. It also selects mise's HTTP backend for Claude Code so updates use Anthropic's native binary distribution instead of the retired npm archive. To intentionally change the stowed global config, opt in explicitly: ```bash mise --write-global-config use -g --pin node@26 ``` The configuration also provides the Android SDK command-line tools and sets the SDK environment for Gradle and `sdkmanager`. Individual Android repositories still declare their required platform and build-tools versions; install those SDK packages with `sdkmanager` when a checkout requires them. ## Paths and overlay | Variable | Description | | ---------------------- | ------------------------------------------------------------- | | `DOTFILES_PUBLIC_DIR` | Public dotfiles path (default `~/.config/dotfiles`). | | `DOTFILES_PRIVATE_DIR` | Private dotfiles path (default `~/.config/dotfiles-private`). | | `DOT_ALLOW_PRIVATE` | Private overlay policy: optional `auto`, required `always`, or skipped `never` (default `auto`). A failed attempted clone is fatal in `auto` mode. | ## Git and GitHub | Variable | Description | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DOT_GIT_CONFIG_FILE` | Private git repo config for `git-diff`, `git-notifications --bar-json`, `update`, and `doctor` (default `$DOTFILES_PRIVATE_DIR/dot-git.yml`). | | `DOT_GITHUB_RETRIES` | Extra `gh` retry attempts after the first try (default `2`). | | `DOT_GITHUB_RATE_LIMIT_TTL_SECONDS` | Seconds to cache `gh api rate_limit` results (default `60`). | | `DOT_GITHUB_RATE_LIMIT_MIN_REMAINING` | Minimum REST quota remaining before `gh` calls wait (default `0`). | | `DOT_GITHUB_RATE_LIMIT_MAX_WAIT_SECONDS` | Upper bound on rate-limit backoff waits (default `60`). | | `DOT_FETCH_TTL_SECONDS` | Seconds to reuse the last upstream fetch (default `300`). | | `DOT_GH_EXTENSIONS_FILE` | Public `gh` extension list installed by `dot init` (default `$DOTFILES_PUBLIC_DIR/.dot-gh-extensions`). | | `DOT_GH_MCP_BEARER` | Bearer token for the read-only GitHub MCP server. The shell wrappers and `opencode-server` set it only for agent harness processes; it is not exported globally. | ## Packages | Variable | Description | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `DOT_PUBLIC_PACKAGES_FILE` | Public Arch/AUR package list for `dot init` and package checks (default `$DOTFILES_PUBLIC_DIR/.dot-public-packages`). | | `DOT_PUBLIC_PACMAN_REPO_CONFIG` | Signed public pacman repo snippet written by `dot` (default `/etc/pacman.d/timmo.conf`). | | `DOT_PUBLIC_PACMAN_MAIN_CONFIG` | Main pacman config scanned for the public repo include (default `/etc/pacman.conf`). | | `DOT_PRIVATE_PACKAGE_REPO_FILE` | Private pacman repo config (default `$DOTFILES_PRIVATE_DIR/.dot-private-package-repo`). | | `DOT_PRIVATE_PACKAGES_FILE` | Private package list override (default base list plus `.dot-private-packages--`). | | `DOT_PRIVATE_PACKAGE_MAP_FILE` | Private package name-to-source map for `dot private-pkg-publish` (default `$DOTFILES_PRIVATE_DIR/.dot-private-package-map`). | | `DOT_PRIVATE_PACMAN_REPO_CONFIG` | Pacman repo snippet path written by `dot` (default `/etc/pacman.d/timmo-private.conf`). | | `DOT_PRIVATE_PACMAN_MAIN_CONFIG` | Main pacman config file scanned for the private repo `Include` (default `/etc/pacman.conf`). | | `DOT_PRIVATE_BROWSER_CHECKS_FILE` | Private browser-extension doctor checks (default `$DOTFILES_PRIVATE_DIR/.dot-browser-checks`). | ## Omarchy and Hyprland | Variable | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------ | | `OMARCHY_REPO_BASE_DIR` | Omarchy repo base path (default `~/.config`). | | `OMARCHY_HOST` | Hypr host override name; `dot init` defaults to `desktop` when unset unless `--host ` is passed. | ## Init and logging | Variable | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `DOT_INIT_NONINTERACTIVE` | Force non-interactive init mode (`1\|0`, default `0`). | | `DOT_INIT_LOG_FILE` | Default `dot init` log path when `--log` is not passed (default `~/.local/state/dot/init.log`). | | `DOT_LOG_FILE` | Active log file for the current `dot` run. Set automatically during `dot init`; child commands inherit it when `DOT_TEE_INHERIT_LOG=1`. | | `DOT_LOG_MIRROR_FILE` | Secondary log destination mirrored after each write. Set automatically when `dot init --log` targets a GVFS path that cannot be written directly. | | `DOT_TEE_INHERIT_LOG` | When `1`, child processes launched by `dot` append stdout/stderr to `DOT_LOG_FILE` (set automatically during `dot init`). | | `DOT_UFW_RULES_FILE` | ufw rules file scanned by the firewall setup and doctor check (default `/etc/ufw/user.rules`). | ## Agents sync `dot agents-sync` mirrors `~/.config/opencode/AGENTS.md` to agent harness instruction files. It runs automatically at the end of full `dot update` and `dot init`; phase-scoped updates skip it. There is no environment toggle to disable it. Each target receives a transformed copy with harness-appropriate formatting where needed. All targets include a `dot agents-sync` HTML comment with source path and timestamp. OpenCode remains the single source of truth; other agent harnesses get plain file copies, not symlinks. | Variable | Description | | --------------------------- | --------------------------------------------------------------------------------------------- | | `DOT_AGENTS_SYNC_SOURCE` | AGENTS file to mirror (default `~/.config/opencode/AGENTS.md`). | | `DOT_AGENTS_SYNC_RULE_FILE` | Override path for a primary agents-sync target (default `~/.cursor/rules/global-agents.mdc`). | ## MCP sync | Variable | Description | | --------------------- | --------------------------------------------------------------------------------------- | | `DOT_MCP_CONFIG_FILE` | Private MCP sync spec read by `dot mcp-sync` (default `$DOTFILES_PRIVATE_DIR/mcp.yml`). | ## Debugging and output | Variable | Description | | ------------------------- | --------------------------------------------------------------------------------------------- | | `DOT_DEBUG` | Enable stderr debug logging from `dot` subsystems (`1` or any non-empty value). | | `DOT_USAGE_DIR` | Usage event root (default `$XDG_STATE_HOME/tool-usage`). | | `DOT_USAGE_DISABLE` | Disable automatic live `dot` usage recording when set to `1`; explicit backfill still writes. | | `DOT_CONTEXT_CAPTURE` | Capture assembled OpenCode starter context when set to `1`. | | `DOT_CONTEXT_CAPTURE_DIR` | Parent for private `context-baseline-*` capture directories (default `/tmp/opencode`). | | `NO_COLOR` | Disable ANSI colour in TTY-aware output such as `context git` (any non-empty value). | Context capture writes numbered system-prompt segments, `system-index.json`, per-tool schemas, and `tools.jsonl` into a unique private child directory. It measures assembled context without changing prompts or tool definitions. ## Agent detection | Variable | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `DOT_AGENT` | Override AI agent detection used by `dot is-agent` and the interactive-TUI guard: `1` forces agent mode, `0` forces it off, unset auto-detects. | ## Notes | Variable | Description | | --------------- | ------------------------------------------------------------------------------------------------------------- | | `NOTES` | Notes vault git repo used by the standalone `notes` CLI/MCP server and OpenCode note commands (preferred; default `~/Documents/notes`). | | `DOT_NOTES_DIR` | Compatibility notes vault override used when `NOTES` is unset. |