laptop

Personal macOS configuration management system with automated dotfiles synchronization, security scanning, and one-command setup/rollback capabilities.

Core Components

This repository manages configurations for the following applications:

Category	Application	Config Location
Shell	Zsh + Oh-My-Zsh	`~/.zshrc`, `~/.zsh/`
Terminal	Ghostty, iTerm2	`~/.config/ghostty/config`, `iterm2/`
Editor	Neovim, Vim	via Homebrew
Version Control	Git, Tig	`~/.gitconfig`, `~/.tigrc`
Multiplexer	tmux	`~/.tmux.conf`
Fuzzy Finder	fzf	`~/.fzf.zsh`
Packages	Homebrew	`Brewfile`
Runtimes	mise	`~/.config/mise/config.toml`
Launcher	Raycast	`raycast/*.rayconfig`
AI Assistant	Claude Code	`~/.claude/` (settings, hooks, agents, skills)

Brewfile includes:

100+ CLI tools (aws, gh, ripgrep, bat, jq, etc.)
40+ GUI applications (Cursor, Ghostty, Arc, Raycast, etc.)
80+ VSCode/Cursor extensions

Architecture

Symlink Strategy

Configuration files reside in this repository and symlink to their standard locations:

~/.zshrc          → laptop/zsh/.zshrc
~/.gitconfig      → laptop/git/.gitconfig
~/.config/ghostty → laptop/ghostty/config

Why symlinks?

Git tracks actual content, not just symlink paths
No specialized tooling required (stow, chezmoi, etc.)
Easy to understand and debug
Industry-standard approach

Directory Structure

laptop/
├── install.sh              # Main installer
├── rollback.sh             # Restore from backup
├── Brewfile                # Homebrew packages manifest
│
├── zsh/                    # Shell configuration
│   ├── .zshrc              # Main config (loads below in order)
│   ├── .aliases            # Shell aliases
│   ├── functions/          # Custom zsh functions (5)
│   └── configs/            # Modular configs
│       ├── *.zsh           # Main configs (color, editor, history, etc.)
│       └── post/           # Loaded last (PATH, completion, mise)
│
├── git/                    # Git configuration
│   ├── .gitconfig          # Main git config
│   ├── .gitignore          # Global gitignore
│   ├── .gitmessage         # Commit message template
│   └── .git_template       # Git hooks template
│
├── ghostty/                # Ghostty terminal config
├── iterm2/                 # iTerm2 settings plist
├── tmux/                   # tmux configuration
├── tig/                    # Tig (git TUI) config
├── fzf/                    # Fuzzy finder config
├── mise/                   # mise runtime manager config
├── bin/                    # Executable scripts (tat)
├── raycast/                # Raycast settings export
├── claude/                 # Claude Code configuration → ~/.claude/
│   ├── CLAUDE.md           # User global instructions (Workflow Orchestration, §1–5)
│   ├── settings.json       # Hooks, plugins, permissions
│   ├── statusline.sh       # Custom status line script
│   ├── loop.md             # Default no-arg /loop maintenance routine
│   ├── hooks/              # Lifecycle hooks (5)
│   ├── agents/             # Global agents (3): verify-subagent-result, governance-proposer,
│   │                       #   rule-auditor (shareable role agents → claude-skills marketplace)
│   ├── skills/             # Skills (2): governance-review, rule-history (others → claude-skills marketplace)
│   └── commands/           # Custom slash commands (1): implement-with-notes
│
├── .claude/                # Project-local config (NOT symlinked to ~/.claude/)
│   ├── agents/             # Project agents (1): diagnose-dotfiles (dotfiles-specific)
│   └── skills/             # Local skills (14)
│
├── scripts/
│   └── auto-sync.sh        # Hourly auto-sync script
│
├── .github/
│   └── workflows/main.yml  # CI/CD (gitleaks + shellcheck)
│
├── .pre-commit-config.yaml # Pre-commit hooks
├── .gitleaks.toml          # Secret scanning rules
└── .gitignore              # Security-focused ignore patterns

Security

Three-Layer Protection

Pre-commit Hooks - Runs before every commit:
- gitleaks - Scans for secrets and credentials
- detect-private-key - Catches SSH/PGP keys
- trailing-whitespace, end-of-file-fixer - Code hygiene
Comprehensive .gitignore - Blocks 30+ sensitive patterns:
- Environment files (.env, .secrets.env)
- Cloud credentials (AWS, GCP, Azure)
- SSH/GPG keys (id_rsa*, *.pem)
- Terraform state (*.tfstate, *.tfvars)

Secrets Template - API keys belong in ~/.secrets.env:

# ~/.secrets.env (gitignored, created by install.sh)
export OPENAI_API_KEY=""
export ANTHROPIC_API_KEY=""
export GITHUB_TOKEN=""

Security Scanning Commands

# Manual gitleaks scan
gitleaks detect --source=. --no-git

# Run all pre-commit hooks
pre-commit run --all-files

Automation

Auto-Sync (launchd)

An hourly launchd agent runs scripts/auto-sync.sh:

Regenerates Brewfile from current installations
Runs gitleaks scan (aborts if secrets detected)
Executes pre-commit hooks
Commits and pushes changes automatically

Log files:

~/.dotfiles_autosync.log - Standard output
~/.dotfiles_autosync.error.log - Errors

Manual sync:

./scripts/auto-sync.sh

Installation

New Machine Setup

# Clone repository
git clone https://github.com/snkrheadz/laptop.git ~/ghq/github.com/snkrheadz/laptop

# Run installer
cd ~/ghq/github.com/snkrheadz/laptop
./install.sh

What install.sh does:

Checks macOS and installs Xcode CLI tools
Installs Homebrew (if not present)
Creates timestamped backup of existing configs
Creates symlinks to repository configs
Installs all Homebrew packages from Brewfile
Sets up mise and installs runtimes (Go, Node.js, Python, Ruby)
Sets up gitleaks + pre-commit hooks
Configures launchd auto-sync agent
Creates ~/.secrets.env template

Rollback

# List available backups
./rollback.sh

# Restore specific backup
./rollback.sh 20231223_120000

What rollback.sh does:

Disables auto-sync launchd agent
Removes all symlinks
Restores files from backup

Update Packages

# Dump current installations to Brewfile
brew bundle dump --force --file=Brewfile

# Install packages from Brewfile
brew bundle --file=Brewfile

Runtime Management (mise)

mise manages programming language runtimes (Go, Node.js, Python, Ruby).

Installed Runtimes

Runtime	Version
Go	1.24.3
Node.js	25.2.1, 22.16.0
Python	3.13.x
Ruby	3.4.8

Commands

# List installed runtimes
mise list

# Install all runtimes from config
mise install

# Install specific runtime
mise use go@1.23.1

# Update to latest versions
mise upgrade

Configuration

Edit mise/config.toml to change versions:

[tools]
go = "1.24.3"
node = "25.2.1"
python = "3.13"
ruby = "3.4.8"

Customization

Local Overrides

Create ~/.zshrc_local for machine-specific settings (automatically sourced, not tracked):

# ~/.zshrc_local
export WORK_PROJECT_PATH="/path/to/work"
alias deploy="./scripts/deploy-work.sh"

Adding New Dotfiles

Add config file to appropriate directory (e.g., tool/.toolrc)

Update install.sh to create symlink:

safe_ln "$DOTFILES_DIR/tool/.toolrc" "$HOME/.toolrc"

Update rollback.sh symlinks array
Commit and push

Development Notes

zsh Loading Order

1. zsh/functions/*        # Custom functions
2. zsh/configs/pre/*      # Pre-configs (code exists in .zshrc but directory unused)
3. zsh/configs/*.zsh      # Main configs
4. zsh/configs/post/*     # Post-configs (PATH, completion, mise)
5. ~/.aliases             # Shell aliases
6. oh-my-zsh              # Plugins: git, zsh-autosuggestions

Avoiding Conflicts

Don't create functions with names that conflict with oh-my-zsh aliases
- Example: g is already defined by the git plugin
Run alias after installation to check for conflicts

Symlink Safety

install.sh uses safe_ln() which removes existing symlinks before creating new ones. This prevents circular references when running install.sh multiple times.

Claude Code Configuration

This repository manages Claude Code settings via symlinks to ~/.claude/:

claude/
├── CLAUDE.md           # User global instructions (Workflow Orchestration, §1–5)
├── settings.json       # Hooks, plugins, permissions
├── statusline.sh       # Custom status line script
├── loop.md             # Default no-arg /loop maintenance routine
├── hooks/              # Lifecycle hooks (5)
│   ├── validate-shell.sh           # PostToolUse: shellcheck validation
│   ├── session-context.sh          # SessionStart: project context (+ PreCompact restore)
│   ├── pre-tool-guard.sh           # PreToolUse: sensitive file access blocking
│   ├── post-failure-proposal.sh    # PostToolUseFailure: governance failure capture
│   └── pre-compact-save.sh         # PreCompact: working state preservation
├── agents/             # Global agents (3, always loaded)
│   ├── verify-subagent-result.md
│   ├── governance-proposer.md   # pairs with governance-review/rule-history skills
│   └── rule-auditor.md
│   # side-job-researcher is personal → kept machine-local in ~/.claude/agents/ (not here)
└── skills/             # Skills (2): governance tooling only
    ├── governance-review/  # Governance rule freshness audit
    └── rule-history/       # Governance rule history
    # Shareable skills AND agents migrated to the snkrheadz/claude-skills marketplace
    # (core/pm/eng/marketer/designer/research packs); invoked as /<pack>:<skill> or
    # enabled per role via `/plugin install <pack>@claude-skills`.

Managed Components

Component	Description
`CLAUDE.md`	User global instructions (Workflow Orchestration, §1–5)
`settings.json`	Hooks, plugins, permissions
`statusline.sh`	Status line: model, dir+branch, duration, cost (session/daily), lines, braille bars (ctx/5h/7d)
`hooks/`	5 lifecycle hooks (PostToolUse, SessionStart, PreToolUse, PostToolUseFailure, PreCompact)
`agents/`	3 global agents (verify-subagent-result + governance-proposer/rule-auditor)
`skills/`	2 governance skills (others → snkrheadz/claude-skills marketplace)
role agents	eng/marketer/designer/research packs in the snkrheadz/claude-skills marketplace

Status Line

Displays in Claude Code CLI (segments joined by |, conditional ones shown only when data exists):

Opus 4.8 | laptop 🌿main | ⏱ 5m | 💰$0.50/$5.20 | +120-45 | ctx ⣿⣿⣄ 45% | 5h ⣄⠀⠀ 12% | 7d ⣶⠀⠀ 18%

Segment	Meaning
`Opus 4.8`	Model display name
`laptop 🌿main`	Current directory + git branch
`⏱ 5m`	Session duration
`💰$0.50/$5.20`	Cost: this session / today's cumulative total
`+120-45`	Lines added/removed (hidden when zero)
`ctx ⣿⣿⣄ 45%`	Context window usage (braille bar, green→yellow→red gradient)
`5h ⣄⠀⠀ 12%`	5-hour rate limit usage (shown if available)
`7d ⣶⠀⠀ 18%`	7-day rate limit usage (shown if available)

Vim mode and 🤖<agent> (subagent name) segments are appended when active.

Hooks

Hook	Lifecycle Event	Description
`validate-shell.sh`	PostToolUse	Runs shellcheck on `.sh` files after Write/Edit
`session-context.sh`	SessionStart (+ PreCompact)	Injects project context at session start / restores it on compaction
`pre-tool-guard.sh`	PreToolUse	Blocks access to sensitive files
`post-failure-proposal.sh`	PostToolUseFailure	Captures governance failures (Bash/Write/Edit) for rule proposals
`pre-compact-save.sh`	PreCompact	Preserves working state before context compaction

Agents

Global agents (live in this repo, symlinked to ~/.claude/agents/, always loaded):

Agent	Purpose
`verify-subagent-result`	SubAgent result verification
`governance-proposer`	Governance rule proposals
`rule-auditor`	Rule freshness auditing

Project agent (real file in .claude/agents/, this repo only): diagnose-dotfiles. Personal agents (machine-local real files in ~/.claude/agents/, not dotfiles-managed): side-job-researcher — mirrors the machine-local side-job-search skill, so it is neither synced nor published.

Role agents (eng/marketer/designer/research) ship via the snkrheadz/claude-skills marketplace; enable a pack with /plugin install <pack>@claude-skills to make its agents available in every project — e.g. eng provides code-architect, architecture-reviewer, verify-shell, verify-app, build-validator, aws-/gcp-best-practices-advisor, and more.

Available Skills

Governance skills (live in this repo, symlinked to ~/.claude/skills/):

/governance-review - Governance rule freshness audit
/rule-history - Governance rule history

All other shareable skills migrated to the snkrheadz/claude-skills marketplace (core / pm / eng packs) and are invoked as /<pack>:<skill> after /plugin install <pack>@claude-skills — e.g. /eng:quick-commit, /eng:test-and-fix, /eng:refactor-swarm, /core:first-principles.

Local Skills (Project-specific)

The .claude/skills/ directory contains 14 project-specific skills that are only available in this repository (not symlinked to ~/.claude/). These skills are tailored for managing this dotfiles repository.

Skill	Description
`brew-manage`	Homebrew package management (add/remove/search, Brewfile update)
`claude-config`	Claude Code configuration (settings.json, hooks, agents, skills)
`dotfiles-rollback`	Backup confirmation and rollback to previous state
`dotfiles-sync`	Manual dotfiles sync (Brewfile update, commit, push)
`git-config`	Git config files (.gitconfig, .gitmessage, .gitignore)
`health-check`	Dotfiles health check (symlinks, configs, dependencies)
`hf-spaces`	HuggingFace Spaces search (research demos, model prototypes)
`launchd-manage`	Auto-sync launchd agent management (start/stop/logs)
`mise-runtime`	Runtime management with mise (Go, Node.js, Python, Ruby)
`new-machine-setup`	New machine setup guide (macOS → dotfiles)
`security-check`	Security scanning (gitleaks, pre-commit, secrets)
`symlink-manage`	Symlink status check and repair (broken link detection)
`tmux-config`	tmux configuration (.tmux.conf, keybindings)
`zsh-config`	zsh configuration (functions, configs, aliases)

Usage: These skills are invoked using slash commands (e.g., /brew-manage, /health-check) when working in this repository with Claude Code.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 349 Commits
.claude		.claude
.github/workflows		.github/workflows
bin		bin
claude		claude
fzf		fzf
ghostty		ghostty
git		git
iterm2		iterm2
mise		mise
raycast		raycast
scripts		scripts
tig		tig
tmux		tmux
zsh		zsh
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
Brewfile		Brewfile
CLAUDE.md		CLAUDE.md
README.md		README.md
install.sh		install.sh
rollback.sh		rollback.sh

Folders and files

Latest commit

History

Repository files navigation

laptop

Core Components

Architecture

Symlink Strategy

Directory Structure

Security

Three-Layer Protection

Security Scanning Commands

Automation

Auto-Sync (launchd)

Installation

New Machine Setup

Rollback

Update Packages

Runtime Management (mise)

Installed Runtimes

Commands

Configuration

Customization

Local Overrides

Adding New Dotfiles

Development Notes

zsh Loading Order

Avoiding Conflicts

Symlink Safety

Claude Code Configuration

Managed Components

Status Line

Hooks

Agents

Available Skills

Local Skills (Project-specific)

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages