Dot

My personal dotfiles for AI-driven, CLI-first development on Linux and macOS. Chezmoi manages the files; mise manages tools and tasks. Read, borrow, or fork to build your own workstation.

Install · Use · Agents · Credentials · Adapt

Highlights

• Terminal: Ghostty, Zellij, and Fish with Starship, Atuin, zoxide, fzf, yazi, and lazygit — tuned for fast keyboard navigation and ultrawide displays.
• Editor: Neovim with LazyVim, styled across every tool with fmind/theme.
• Agents: Antigravity (primary), Claude Code, Copilot, and OpenCode share one persona and skill catalog; dot agent session sync archives local sessions and dot agent stats reports usage and costs (including retired Codex and Grok archives).
• Development: Python 3.14 with uv, Ruff, ty, and pytest, plus cloud and service CLIs; projects pin their own stack tools.
• Automation: the dot CLI checks workstation health, manages multi-repo workspaces, handles provider logins and scoped secrets, and tracks agent context budgets.

Prerequisites

Platform	Requirements	CI coverage
Linux x86-64	glibc 2.39+ (Debian 13 / Ubuntu 24.04+)	Full repository gate and starter tests
macOS Apple Silicon	macOS 15+, Xcode Command Line Tools	Templates, Python, and starter tests

The macOS baseline follows Homebrew's supported versions; other platforms are untested. CI validates templates, code, and builds without running the host installer end to end.

Install the host prerequisites first; everything else installs in user space:

# Debian / Ubuntu
sudo apt install -y git curl libatomic1 build-essential gnome-keyring xclip wl-clipboard libnotify-bin pulseaudio-utils
# ChromeOS Linux with GPU acceleration: allow Ghostty to open the GPU, then restart Linux
sudo usermod -aG render "$USER"

# macOS
xcode-select --install

The installer requires mise 2026.10.18 or newer and installs it if absent. Ghostty is the recommended terminal. A container engine is optional: on macOS, mise installs Colima with the Docker CLI, Compose, and Buildx (colima start runs the engine); on Linux, install Docker Engine from your distribution.

Installation

Warning

These are personal dotfiles: adapt them and back up your files first. Setup overwrites managed files without backups. Agents run with broad autonomous permissions, and apply automatically trusts configured workspaces and owner-allowlisted repositories. Review the settings and trust behavior before use.

Inspect install.sh, then run:

git clone https://github.com/fmind/dot.git ~/.local/share/chezmoi
bash ~/.local/share/chezmoi/install.sh

Enter your own Git name, email, personal-repository email, and GitHub username when prompted (the defaults are mine). Open a new shell and run dot doctor to verify the workstation.

Rerun install.sh to resume an interrupted setup (SKIP_GIT_PULL=true skips fetching upstream). From an initialized checkout, mise run full reapplies files and synchronizes locked tools, dot, and completions.

Shell

Ghostty and Zellij launch Fish while leaving your login shell untouched. Fish attaches to Zellij once at startup and returns to a plain shell when you detach or exit. In other terminals, run fish or set the shell command to ~/.local/share/mise/shims/fish.

Everyday use

dot --help                # Discover commands
dot doctor                # Check workstation health
dot doctor --headroom     # One-line disk and memory check before large work
dot config show           # Inspect effective settings
dot agent stats           # Review agent usage and prompt statistics
dot status --fetch        # Refresh remotes, then show repository status
dot orphan                # List files no longer managed by chezmoi

Edit managed files in ~/.local/share/chezmoi, then preview and apply:

cd ~/.local/share/chezmoi
mise run diff
mise run apply

The Dot CLI guide covers every command, diagnostic, and recovery workflow.

Daily keyboard and shell ergonomics:

• Fish abbreviations: a runs agy (ac continue, ai interactive prompt, ap print), g git (gl lazygit), m mise (mr mise run), v Neovim, y yazi, and h dot (hd doctor, hh headroom, hs repos needing attention with fetch, hp pull, ho orphans, hc caches, ha agent stats).
• Zellij: Alt a opens Antigravity, Alt g lazygit, Alt y yazi, and Alt / the session manager. New panes (Alt n) tile as up to four equal columns for 21:9 or 32:9 ultrawide displays; a fifth pane (or Ctrl b, Space) switches to a half-stacked layout. Multi-pane and active-program sessions stay resurrectable from Alt / after a reboot or kill; detach (Ctrl o, d) to park a single-pane shell until the next reboot.
• Neovim: <leader>gm toggles a buffer's Git diff between the index and the default branch's merge-base. Tab accepts completions, Enter inserts a newline (and continues or outdents lists in Markdown, text, and commit buffers), and mise lsp powers diagnostics and completions in mise.toml.

Dot configuration

Machine-local settings live in unmanaged ~/.config/dot.yaml and merge with built-in defaults. Edit and validate them with dot config edit, or select an alternate ~/.config/dot.*.yaml profile via dot --config <path> or DOT_CONFIG_PATH.

Usage reports

dot agent stats separates token counts and estimated API value from billed costs (--monthly groups by UTC calendar month). dot agent session sync captures longer local transcripts before harnesses prune them; see the usage guide.

Repository tasks

Run these from the checkout; mise tasks lists every task and alias.

Command	Purpose
mise run diff	Preview dotfile changes
mise run apply	Apply files and eligible hooks
mise run doctor	Check workstation health (dot, chezmoi, and mise)
mise run full	Install locked repo and global tools, apply dotfiles, deploy dot, completions
mise run upgrade	Upgrade dependencies, tools, the theme pin, and plugins (includes full)
mise run all	Check, test, and build the repository (without rewriting files or deploying)

Contributor details: AGENTS.md, verification, and releases. Python follows the latest 3.14 patch release until required tools ship 3.15 wheels.

Agent layer

Antigravity, Claude Code, Copilot, and OpenCode share one persona (dot_agents/AGENTS.md) and one skill catalog (skills/). Launching agy from Fish or Zellij (Alt a) puts mise shims first on PATH so agent commands respect each project's tool pins. General-purpose subagents inherit the same persona and skills without custom role definitions; see cross-harness agents.

Agent skills

Setup links skills/ into ~/.agents/skills/ alongside independently installed packages (restart agent sessions after catalog changes). See skill authoring, catalog maintenance, and retired-link cleanup.

Everyday slash commands:

• Deliverables & writing: /clipboard copies the last deliverable (or /clipboard <selection>) via native OS tools (clipboard); /stakeholder-writing turns technical work into decision-ready reports and proposals; /draft-doc creates Google Docs (.md or .gdoc); /draft-mail drafts Gmail replies without sending; /fact-check verifies claims and links.
• Engineering & maintenance: /full-review audits a repository and applies verified fixes; /smoke exercises every task and CLI command; /trim <path> cuts tokens without losing meaning; /auth-status checks CLI logins and prints exact re-login commands; /task-prompts writes handoff prompts (resume agy with agy -c, compact with /compact).

Credentials

Authentication & Logins

dot login                 # This machine's providers (auth.login); opens the browser only when needed
dot login --check         # Report which providers need a login (exit 1 if any)
dot login github          # GitHub
dot login workspace       # Google Workspace
dot login gcp             # Google Cloud and ADC
dot login colab           # ADC with Colab scopes, then verify session access

GitHub pushes use SSH even for HTTPS clones (register a key in GitHub settings). dot login also reconciles GitHub scopes and, when GWS_PROJECT or auth.workspace.project is set, Workspace APIs and OAuth setup (dot setup github or dot setup workspace <project-id> runs either alone). Configure per-machine providers in ~/.config/dot.yaml under auth.login (default [github, gcp, workspace]; colab is opt-in); see the authentication guide.

Agent harnesses manage their own logins (mise locks every harness except self-updating Antigravity):

Harness	Command	Guide
Antigravity	agy	agy
Claude Code	claude auth login	agent-harnesses
Copilot	copilot login	agent-harnesses
OpenCode	opencode, then /connect	agent-harnesses

Add optional MCP servers with mcp-setup.

Commit signing

Each machine signs commits and annotated tags (git tag NAME -m MSG) with its own passphraseless Ed25519 SSH key (~/.ssh/id_ed25519_signing) so agent shells can sign unattended and any machine can be revoked independently; the private key never enters this repository, and machines without it commit unsigned. A signature proves the machine, not a human. Provision a new machine once (dot setup github drops the temporary write:ssh_signing_key scope afterwards):

ssh-keygen -t ed25519 -N '' -C "git-signing@$(hostname)" -f ~/.ssh/id_ed25519_signing
dot login github --grant write:ssh_signing_key
gh ssh-key add ~/.ssh/id_ed25519_signing.pub --type signing --title "$(hostname) signing"
dot setup github
printf '*@fmind.dev namespaces="git" %s\n' "$(cat ~/.ssh/id_ed25519_signing.pub)" >>"$(chezmoi source-path)/dot_config/git/allowed_signers"
chezmoi apply ~/.gitconfig ~/.config/git/allowed_signers

Commit the new allowed_signers line so every machine verifies signatures locally (git log --show-signature), and once every machine signs, enable vigilant mode in GitHub keys. To retire a machine, delete its line and GitHub key.

Secret Management

Secrets are never exported at shell startup:

• Native credential seeds: Hugging Face, Kaggle, and OpenCode credentials deploy only when absent so later logins (hf auth login, kaggle auth login, OpenCode /connect) survive apply. For customer work, isolate accounts with the override guide.

• Scoped secrets: pass a personal key to a single command with dot secret run (an existing environment value wins, and an empty one fails instead of loading the personal key; see scoped credentials). Personal model integrations default to GCP Agent Platform with ADC, OpenCode uses OpenRouter, and PyPI publishes via Trusted Publishing:

  dot secret run OPENROUTER_MANAGEMENT_KEY -- <command>

• Encrypted sources: only the owner's ~/.config/chezmoi/key.txt decrypts committed *.age files; without it, apply skips them. Back up your key and never copy it to a customer-managed machine. Import new secrets with mode 0600 and chezmoi add --encrypt (--create for native login seeds), never pass secret values in command arguments, and refresh encrypted seeds after rotating native credentials.

Adapting this

Fork and replace these personal defaults:

1. Identity: prompts in .chezmoi.toml.tmpl, the clone URL in install.sh, and allowed_signers before adding your signing key. Use unmanaged ~/.config/git/config.local for local Git overrides.
2. Secrets: replace the age recipient in .chezmoi.toml.tmpl and remove or re-encrypt *.age sources before applying (Secret Management).
3. Persona: edit dot_agents/AGENTS.md, shared across all harnesses.
4. Workspaces & trust: update pull.directories (also seeds Claude's additionalDirectories), trust.github_owners, and trust.agy_projects in ~/.config/dot.yaml, plus personal-checkout includeIf paths in dot_gitconfig.tmpl. Manage mise trust via mise trust or unmanaged ~/.config/mise/conf.d/trust.toml.
5. Theme & design: update .chezmoiexternal.toml.tmpl, pinned to an fmind/theme commit (mise run upgrade advances it; personal work only).

Uninstall / rollback

There is no single uninstaller: record chezmoi managed, run chezmoi purge (removes source, config, and state while leaving deployed files) and mise implode --config (removes mise and its tools), then restore backups and remove remaining deployed files, shell blocks, fonts, and agent state.

To roll back, preserve local edits, check out the previous release tag, and run mise run full followed by mise run vim to restore locked tools, the CLI, and Neovim plugins. Newer files, application data, and migrations are not rolled back.

Security

Report vulnerabilities through SECURITY.md.

License

MIT © Médéric Hurier (Fmind)