🛠️ Dotfiles & Agent Environment

An agent-first development environment for macOS and Linux.

Two things live here: a shared context and safety layer that lets Antigravity CLI (agy) and Claude Code work from the same skills, hooks, and rules — and the SDK, a set of small Go tools that make letting an agent actually do things survivable.

---

🧰 The SDK

Nine single-binary Go tools (plus a shared library) covering the loop: let an agent work → let it commit without losing anything → see what's happening → roll it out everywhere → keep the repo it pushes to configured the way you meant.

→ What each tool solves, with demos

---

🚀 Quick Start

git clone https://github.com/sfc-gh-eraigosa/dotfiles.git ~/git/dotfiles
~/git/dotfiles/install.sh

The installer is interactive — prompts are front-loaded, but on Windows/WSL the Desktop deploy runs at the end, so stay nearby. It symlinks core configs (.zshrc, .tmux.conf, …) into $HOME, initializes nvm/pyenv/goenv/rbenv, builds the SDK binaries into ~/opt/bin/, and installs both assistants pre-loaded with the shared skills.

---

🤖 Agent Configuration

Both assistants read the same skills, hooks, and progressive context — write a skill once, use it in either.

• Shared skills — every SKILL.md is linked into both assistants by sync-skills. ai/skills/
• Safety hooks — the same guard scripts block rm -rf * and gate gss push. ai/hooks/
• Agent teams — specialized personas installed as native subagents. ai/teams/
• Declarative plugins — extensions defined in code, auto-synced. docs/ai-plugins.md
• Progressive context — AGENTS.md at each level (CLAUDE.md is a symlink to it).

Choosing between them: Claude Code for long-context multi-file refactors and slash-command workflows; Antigravity for fast tool-call loops and repos with .agents/ config. Either works headless in a tmux pane. You can switch mid-project — they read the same context.

---

📂 Structure

---

⌨️ Common Commands

---

🍎 macOS-Style Keyboard (on by default)

Heads up: this repo deliberately makes every machine's keyboard behave like a Mac. install.sh turns this on by default, so a fresh install will change your shortcuts. The goal is one set of muscle memory everywhere — the same Cmd+C works on the Windows box, the Linux desktop, and the Mac.

The Command key is Super (the ⊞/⌘ key next to Alt). Ctrl is left alone, so Ctrl+C is still SIGINT in a terminal.

In a terminal the destructive chords are handled for you: Cmd+C copies (never SIGINT), and Cmd+S / Cmd+Z / Cmd+D are inert rather than freezing, suspending, or logging out of your shell.

Turning it off

One flag covers every OS — Linux (keyd + GNOME) and Windows (AutoHotkey + the Copilot-key remap):

gff set keyboard.macos.enabled false && ./install.sh   # leave every keyboard stock

To remove it from a Linux machine that already has it:

~/opt/scripts/system/macos-keys-linux.sh --uninstall

If a remap ever misbehaves, hold Backspace + Esc + Enter together to panic-quit the keyd daemon and get a stock keyboard back instantly.

Full key table, platform coverage, and troubleshooting: docs/macos-keys.md.

---

🖥️ Machine-Local Customization

Host-specific settings that would break other machines go in ~/.zshrc.local — sourced last, overrides everything, never tracked. See docs/machine-local-overrides.md.

---

🤝 Contributing

See CONTRIBUTING.md for the development workflow and how to validate changes with the Makefile. Merges go through the Mergify queue — docs/mergify.md.

Licensed under the Apache License, Version 2.0.

---

Safeguards: 🛡️ Turn Break Mandate, 🛠️ OS-Level GSS Confirmation, 🧪 27-Case Hook Test Suite, 🧪 Automated CI Validation.