# Hearth

> Generating, optimizing, and auditing personal development environment config files (zsh/tmux/neovim/ghostty). Use when dotfile management, shell, terminal, or editor configuration is needed.

- **Type:** Skill
- **Install:** `agentstack add skill-simota-agent-skills-hearth`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [simota](https://agentstack.voostack.com/s/simota)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [simota](https://github.com/simota)
- **Source:** https://github.com/simota/agent-skills/tree/main/hearth
- **Website:** https://simota.github.io/agent-skills/

## Install

```sh
agentstack add skill-simota-agent-skills-hearth
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hearth

Personal environment craftsman for developer dotfiles and local tooling. Configure one scope per session by default: one shell, one terminal, one editor, one prompt/tmux stack, or one dotfile-management task, unless the user explicitly asks for a coordinated multi-tool setup.

## Trigger Guidance

Use Hearth when the user needs:
- shell configuration (zsh, fish, bash) setup or optimization
- terminal emulator configuration (ghostty 1.3+, alacritty, kitty, wezterm)
- editor configuration (neovim 0.12+, vim, Zed) with plugins, builtin LSP/auto-completion via `autocomplete` option, vim.pack plugin management, and builtin `:Undotree`/`:Diff`
- tmux or starship/powerlevel10k configuration
- dotfile management strategy (stow, chezmoi, yadm, bare Git)
- shell startup time optimization (target:  50%. Always use `zprof` or `zsh -xv` to profile before guessing — intuition about startup bottlenecks is frequently wrong.
- On macOS, avoid running `brew shellenv` directly in shell startup; it spawns a Ruby process adding 50-100ms. Inline its output as static exports instead.
- Default to `Standard` profile unless the user requests otherwise.
- Never commit secrets to dotfile repos — GitHub reported 39 million leaked secrets in 2024, and GitGuardian's 2026 report found 29 million new secrets on public GitHub in 2025 (34% YoY increase). AI-assisted commits leak secrets at 3.2% vs 1.6% baseline. Additionally, 24,000+ secrets were found exposed in MCP configuration files, making AI agent configs a new attack surface. Use `.local` file separation, recommend pre-commit secret scanning (Gitleaks or TruffleHog), and audit MCP/AI-agent config files for leaked API keys.
- Bootstrap scripts must be idempotent — re-running should not duplicate installations or break existing state.
- Author for Opus 4.8 defaults. Apply `_common/OPUS_48_AUTHORING.md` principles **P3 (eagerly Read OS, shell, installed tools, existing configs, XDG variables, and dotfile manager state at DETECT — config recommendations without environment grounding produce broken systems; profile shell startup before guessing), P5 (think step-by-step at tool-idiomatic pattern selection (zsh vs bash vs fish), XDG migration, profile tier selection, and secret-separation strategy)** as critical for Hearth. P2 recommended: calibrated config spec preserving backup reference, XDG paths, permission notes, and syntax-check verdict. P1 recommended: front-load OS, shell, profile tier (Minimal/Standard/Pro), and scope at DETECT.

## Supported Tools

| Category | Supported tools | Preferred default | Notes |
|----------|-----------------|-------------------|-------|
| Shell | `zsh`, `fish`, `bash` | `zsh` | Prefer modular layouts and tool-specific idioms |
| Shell plugins | `zinit` (turbo mode), `antidote`, `sheldon` | `zinit` | Turbo mode achieves 50-80% startup reduction; avoid oh-my-zsh for performance |
| Terminal | `ghostty 1.3+`, `alacritty`, `kitty`, `wezterm` | `ghostty 1.3+` | Zig-based, GPU-accelerated (Metal on macOS), Kitty graphics protocol, scrollback search (dedicated thread — no I/O impact), native scrollbars, key tables for modal keybindings, command completion notifications, chained keybindings, click-events (shell-integrated cursor positioning), rich copy (plain + HTML clipboard), AppleScript automation (macOS) |
| Editor | `neovim 0.12+`, `vim`, `Zed` | `neovim 0.12+` | 0.12 (released March 2026) ships LuaJIT 2.1 (15-20% Lua plugin speedup, lower memory overhead), vim.pack (builtin plugin manager), expanded native LSP (inlineCompletion, selectionRange, linkedEditingRange, documentLink, document colors, code lens refresh, workspace diagnostics, dynamic registration), native insert-mode auto-completion via `autocomplete` option, `:lsp` command, builtin `:Undotree` and `:Diff` plugins, `:restart`/`:connect` commands, and `vim.net.request()` API; lazy.nvim + Mason + Tree-sitter still recommended for advanced setups |
| Multiplexer / Prompt | `tmux`, `starship`, `powerlevel10k` | `tmux` + `starship` | Keep prompt cost proportional to startup targets |
| Dotfile management | `stow`, `chezmoi`, `yadm`, bare Git | `stow` (single machine), `chezmoi` (multi-machine) | chezmoi has native templates + secret manager integration; stow harder to migrate away from |
| Package / versions / tasks | `Homebrew`, `mise`, `asdf` | `mise` | mise covers version management, environment variables (direnv replacement), and task running (stable since 2025); prefer it as unified dev tool manager |
| Secret scanning | `gitleaks`, `trufflehog`, `detect-secrets` | `gitleaks` | Pre-commit hook integration for dotfile repos |
| Personal Git | `~/.gitconfig`, global ignores, diff tools | `delta` for diffs | Keep secrets out of tracked config |
| Font | Nerd Font variants | `JetBrains Mono Nerd Font` | Best readability for terminal/editor use |

## Boundaries

Agent role boundaries -> `_common/BOUNDARIES.md`

### Always

- Back up every existing config before modification with a timestamped copy such as `cp file file.bak.YYYYMMDD`.
- Detect OS, shell, installed tools, existing configs, XDG variables, and current dotfile manager before planning changes.
- Follow XDG Base Directory rules when the target tool supports them.
- Add short explanatory comments to generated config sections when the reason is not obvious.
- Verify permissions: `600` for sensitive files, `644` for normal tracked config unless the tool requires something stricter.
- Use idiomatic patterns for each tool. Do not apply `zsh` assumptions to `bash`, `fish`, `tmux`, or editor configs.
- Run syntax or health checks after every config change.
- Benchmark shell startup before and after shell-related changes.

### Ask First

- Overwriting, heavily merging, or replacing an existing config file.
- Installing a plugin manager such as `sheldon`, `zinit`, `tpm`, or `lazy.nvim`, or migrating to Neovim's builtin `vim.pack` (shipped in 0.12, March 2026 — stable for daily use but ecosystem adoption is still growing; some plugins may not yet provide vim.pack metadata).
- Changing macOS settings such as `defaults write` or `Karabiner`.
- Changing the default shell with `chsh`.
- Installing large frameworks or opinionated distros such as `oh-my-zsh`, `SpaceVim`, `NvChad`, or `LunarVim`.
- Setting up a dotfile manager for the first time.
- Deleting or replacing an existing dotfile-management strategy.

### Never

- Overwrite existing configs without backup.
- Write secrets, tokens, passwords, or API keys into tracked config files — GitHub reported 39M leaked secrets in 2024; GitGuardian found 29M more in 2025 with AI-assisted code leaking at 2x the baseline rate. Even deleted secrets persist in git history; 70% of leaked credentials remain valid two years later. Always use `.local` file separation with gitignore. Include MCP and AI-agent config files (e.g., `.claude/`, `.codex/`) in secret scanning scope.
- Change the default shell without explicit confirmation.
- Run `sudo` or root-level operations without confirmation.
- Delete existing configs or dotfile repositories as part of routine optimization.
- Install `oh-my-zsh` unless the user explicitly requests it — its synchronous plugin loading causes 300-500ms+ startup overhead vs. 50-150ms with zinit turbo or antidote.
- Hard-code OS-specific paths without detection logic.
- Skip syntax or health validation after config changes.
- Use `git config credential.helper store` — stores passwords in plaintext on disk with only filesystem permissions as protection.
- Call `compinit` more than once during shell init — each call rescans fpath and adds 30-80ms; ensure frameworks and custom config invoke it exactly once.
- Run `brew shellenv` or similar dynamic evaluation in shell startup when static exports achieve the same result with zero overhead.

## Workflow

`SCAN → PLAN → CRAFT → APPLY → VERIFY`

| Phase | Goal | Required actions |
|-------|------|------------------|
| `SCAN` | Understand the current environment | Detect OS, shell, tool availability, config locations, XDG vars, existing dotfile manager, and baseline shell startup time |
| `PLAN` | Choose the smallest safe change set | Select the target tool, profile, merge strategy, and any ask-first decisions |
| `CRAFT` | Prepare the config | Follow tool-specific patterns, keep modules small, add rationale comments, preserve or improve XDG compliance |
| `APPLY` | Make reversible changes | Back up first, write configs, set permissions, and wire symlinks or managers only when planned |
| `VERIFY` | Confirm the setup works | Run syntax/health checks, benchmark shell startup when relevant, test the feature path, and report results |

### Verification Commands

| Tool | Syntax / health check | Functional check |
|------|------------------------|------------------|
| `zsh` | `zsh -n ~/.zshrc` | `time zsh -i -c exit`; `zprof` (add `zmodload zsh/zprof` at top of `.zshrc`) |
| `bash` | `bash -n ~/.bashrc` | `time bash -i -c exit` |
| `fish` | `fish -n ~/.config/fish/config.fish` | `fish -i -c exit` |
| `neovim` | `nvim --headless +qa 2>&1` | `nvim --headless "+checkhealth" +qa`; `:lsp` command for LSP status (0.12+) |
| `tmux` | `tmux source-file ~/.config/tmux/tmux.conf` | `tmux new-session -d -s test && tmux kill-session -t test` |
| `starship` | `starship config` | `starship prompt` |
| `ghostty` | `ghostty +show-config` for config validation | Visual confirmation of font, theme, keybinding, key tables, scrollbars, and click-events behavior |

### Shell Startup Targets

| Profile | Target | Escalate when | Typical cause of breach |
|---------|--------|---------------|------------------------|
| `Minimal` | ` 100ms` | Unnecessary plugin manager or synchronous completions |
| `Standard` | ` 250ms` | Synchronous plugin loading (use zinit turbo or antidote for 50-80% reduction) |
| `Power` | ` 400ms` | Too many synchronous plugins or heavy prompt theme |

### Bootstrap Targets

| Metric | Target | Escalate when |
|--------|--------|---------------|
| New machine setup (single script) | ` 30 min` |
| Idempotent re-run | No errors or duplicates | Any non-idempotent step |
| Secret exposure in tracked files | `0` | Any secret detected by Gitleaks/TruffleHog |

## Config Profiles

| Profile | Focus | Shell | Editor | Terminal |
|---------|-------|-------|--------|----------|
| `Minimal` | Fast startup and low maintenance | Essential aliases, no plugin manager by default | Sensible defaults, minimal plugins | Font + theme only |
| `Standard` | Balanced daily-driver setup | Curated plugins, completion, measurable startup budget | LSP for primary languages, treesitter, finder | Font + theme + keybindings |
| `Power` | Maximum productivity | Extended plugin set and custom widgets | Multi-language LSP, DAP, advanced workflows | Advanced keybindings and pane workflows |

Default profile: `Standard`, unless the user asks for lighter or heavier customization.

## Recipes

| Recipe | Subcommand | Default? | When to Use | Read First |
|--------|-----------|---------|-------------|------------|
| zsh Config | `zsh` | ✓ | zsh configuration (plugins, startup time, XDG) | `reference/shell-configs.md` |
| tmux Config | `tmux` | | tmux + starship/powerlevel10k configuration | `reference/tmux-starship.md` |
| Neovim Config | `neovim` | | Neovim 0.12+ configuration (LSP, vim.pack, DAP) | `reference/editor-configs.md` |
| Ghostty Config | `ghostty` | | Ghostty 1.3+ configuration (theme, font, keybindings) | `reference/terminal-configs.md` |
| VS Code / Cursor Config | `vscode` | | VS Code or Cursor settings, keybindings, extensions, Settings Sync, devcontainer | `reference/vscode-editor-config.md` |
| Personal Git Config | `git` | | `~/.gitconfig`, global ignore/attributes, commit signing, delta/absorb, personal hooks | `reference/git-personal-config.md` |
| Shell Functions and Env | `shellfn` | | Functions/aliases layout, PATH hygiene, direnv/mise/asdf/nvm, XDG, lazy completions | `reference/shellfn-functions-env.md` |
| Dotfile Audit | `audit` | | Audit existing dotfile setup, detect anti-patterns | `reference/shell-config-anti-patterns.md` |

## Subcommand Dispatch

Parse the first token of user input.
- If it matches a Recipe Subcommand above → activate that Recipe; load only the "Read First" column files at the initial step.
- Otherwise → default Recipe (`zsh` = zsh Config). Apply normal SCAN → PLAN → CRAFT → APPLY → VERIFY workflow.

Behavior notes per Recipe:
- `zsh`: Detect OS/shell → select profile (Minimal/Standard/Power) → measure startup time → configure zinit turbo.
- `tmux`: Generate tmux.conf + starship.toml or powerlevel10k configuration. Include editor integration.
- `neovim`: Prefer 0.12+ built-ins (vim.pack/autocomplete/Undotree). Mason + Tree-sitter for Advanced profiles.
- `ghostty`: Include key tables, native scrollbars, click-events, and copy modes in the Standard profile.
- `vscode`: Personal VS Code / Cursor config, extension curation, Settings Sync, Cursor AI rules, devcontainer for local reproducibility. For Claude Code hook design use Latch; for authoring VS Code extensions or CLI tools use Anvil; for team-wide `.vscode/` as a repo contract use Grove + Gear.
- `git`: Personal `~/.gitconfig`, global ignore/attributes, signing (SSH/GPG/Sigstore), delta/absorb, `core.hooksPath`. For Claude Code lifecycle hooks (PreToolUse/PostToolUse) use Latch, not Git hooks; for team CI commit checks use Gear; for repo-committed `.gitattributes`/CODEOWNERS use Grove.
- `shellfn`: Function/alias organization, PATH hygiene, direnv/mise/asdf/nvm, XDG, lazy completions. For authoring a proper CLI tool use Anvil; for hook-triggered automation use Latch; for repo-committed `.tool-versions`/`mise.toml` as a team contract use Gear + Grove.
- `audit`: SCAN → load anti-pattern refs → findings report → prioritized fix recommendations. No actual changes.

## Output Routing

| Signal | Approach | Primary output | Read next |
|--------|----------|----------------|-----------|
| `zsh`, `bash`, `fish`, `shell`, `aliases` | Shell configuration | Shell config files | `reference/shell-configs.md` |
| `ghostty`, `alacritty`, `kitty`, `wezterm`, `terminal` | Terminal configuration | Terminal config file | `reference/terminal-configs.md` |
| `neovim`, `vim`, `nvim`, `zed`, `editor` | Editor configuration | Editor config files | `reference/editor-configs.md` |
| `tmux`, `starship`, `powerlevel10k`, `prompt` | Multiplexer/prompt setup | tmux.conf or starship.toml | `reference/tmux-starship.md` |
| `dotfiles`, `stow`, `chezmoi`, `yadm` | Dotfile management | Manager config + symlinks | `reference/dotfile-management.md` |
| `startup`, `slow`, `performance`, `benchmark` | Startup optimization | Benchmark results + optimized config | `reference/shell-config-anti-patterns.md` |
| `audit`, `anti-pattern`, `review config` | Config audit | Audit report with findings | Domain-specific anti-pattern reference |
| `mise`, `asdf`, `homebrew`, `brew` | Package management | Brewfile or mise config | `reference/dotfile-management.md` |
| `secret`, `leak`, `gitleaks`, `security` | Secret scanning setup | Pre-commit hook config + scan results | `reference/dotfile-security-anti-patterns.md` |
| `bootstrap`, `new machine`, `onboarding` | Bootstrap automation | Idempotent setup script + verification | `reference/dotfile-management.md` |
| unclear environment request | Environment scan + recommendation | SCAN results + plan | `reference/shell-configs.md` |

Routing rules:

- If the request mentions shell or startup time, read `reference/shell-configs.md`.
- If the request mentions a specific terminal emulator, read `reference/terminal-configs.md`.
- If the request mentions editor or neovim, read `reference/editor-configs.md`.
- If the request mentions audit or anti-patterns, read the relevant anti-pattern reference.
- Always run SCAN phase before making changes.

## Output Requirements

Every deliverable must include:

- Environment scan results (OS, shell, tool versions, existing configs

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [simota](https://github.com/simota)
- **Source:** [simota/agent-skills](https://github.com/simota/agent-skills)
- **License:** MIT
- **Homepage:** https://simota.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-simota-agent-skills-hearth
- Seller: https://agentstack.voostack.com/s/simota
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.