Workstation System Administration

Guide, document, collaborate on, and preserve the configuration of a macOS development workstation.

• Guide — This README provides an overview and entry point for collaborators.

  CLAUDE.md defines the agent's workflow and also serves as a useful reference for humans — it documents project structure, conventions, and key paths not found elsewhere.

  Detailed runbooks live in docs/.

• Document — Record decisions, configuration state, and session history (CLAUDE.md, docs/, session-logs/).

• Collaborate — The human gives direction; the Claude Code agent executes.

  During a session, the human can follow along via the command log (.claude/command-log.txt) and session logs (session-logs/) to understand what's happening and learn from the agent's approach.

  Results are reviewed together and refined through iteration — small commits, frequent feedback, and course corrections as needed.

• Preserve — Back up dotfiles and configs (bak_home/, bak_pkg/). Detect drift between the live system and the repo with scripts/drift-check.

Workflow

Work happens in Claude Code sessions. Each session follows this pattern:

1. Startup — Automated checks assess the system state (drift, unpushed commits, existing session logs).
2. Work — Proceed with the task at hand, logging decisions as you go.
   • Monitor activity with tail -f .claude/command-log.txt.
3. Capture — Sync workstation changes back into the repo with scripts/sync-in, commit incrementally, and push to main.

Startup details are defined in CLAUDE.md and implemented by the hooks in .claude/hooks/.

Repo Structure

local/
├── .claude/
│   ├── hooks/
│   │   ├── log-bash.sh            # Pre/Post Bash hook — logs commands
│   │   └── session-start.sh       # SessionStart hook — drift, unpushed, checklist
│   ├── command-log.txt            # Live shell activity log
│   └── settings.json              # Hook configuration
├── bak_home/                      # Mirrors ~/ — dotfiles and configs
├── bak_pkg/                       # Package manager snapshots
├── docs/
│   ├── gpg-keys.md                # GPG key generation and backup
│   ├── migration-runbook.md       # Step-by-step new machine setup
│   └── ssh-keys.md                # SSH key generation and backup
├── scripts/
│   ├── drift-check                # Diff repo vs live system
│   ├── sync-in                    # Copy live system → repo
│   └── usage.md                   # Script usage and examples
├── session-logs/                  # Per-session decision and reasoning logs
├── CLAUDE.md                      # Agent instructions and project context
└── manifest.json                  # Source of truth — declares all tracked files

Tracking

manifest.json is the single source of truth for what this repo tracks. It has three sections: files, directories, and packages. Every entry declares a path (relative to ~/) and a category (shell, tools, ssh, packages). Both scripts/sync-in and scripts/drift-check read from it — adding a new entry is all that's needed to start tracking.

For script usage and examples, see scripts/usage.md.