Skip to content

CLAUDE.md

Latest commit

 

History

History
135 lines (101 loc) · 5.43 KB

CLAUDE.md

File metadata and controls

135 lines (101 loc) · 5.43 KB

FolderTime Machine

A macOS menu bar app that watches user-specified folders for changes and automatically triggers Time Machine backups.

App Overview

  • Name: FolderTime Machine
  • Type: macOS menu bar utility (no dock icon, no main window)
  • Framework: SwiftUI
  • Minimum Target: macOS Tahoe (macOS 26). Support older versions where feasible.
  • Distribution: Non-sandboxed, direct distribution (DMG). Required because tmutil needs system-level access.
  • Launch at Login: Yes, supported via SMAppService (or LaunchAtLogin for older macOS).

Core Feature: Folder Watching & Backup Triggering

The app watches user-specified folders for file changes. When changes are detected, it waits for a configurable quiet period (default: 45 seconds of no further changes), then triggers a full Time Machine backup via tmutil startbackup.

Technical Approach

  • File watching: Use FSEvents API to monitor watched folders recursively (all subdirectories).
  • Debounce: After detecting a change, reset a timer. Only trigger backup after the quiet period elapses with no new changes. Default: 45 seconds. User-configurable.
  • Backup trigger: Run tmutil startbackup via Process (Foundation). This triggers a full Time Machine backup (not per-folder — that's how Time Machine works).
  • Persistence: Store watched folder list and settings in UserDefaults or a plist. Must survive app restarts.

Primary Use Case

Catching file changes made by Claude Code (or any tool that writes multiple files in bursts) and ensuring they get backed up automatically.

UI Design

Menu Bar

  • Custom icon: a time-machine-inspired icon (clock/gear/shield aesthetic)
  • Clicking the icon opens a dropdown menu

Menu Bar Dropdown

From top to bottom:

  1. Watched Folders Section

    • List of currently watched folders (show folder path)
    • "+" button to add a new folder (opens folder picker / NSOpenPanel)
    • "-" button next to each folder to remove it
    • Users can add as many folders as they need

  2. Recent Triggers Section

    • Header: "Recent Backups" or similar
    • Show the last 10 triggered backups
    • Each entry: timestamp + which folder triggered it

  3. Settings

    • Debounce interval (configurable, default 45 seconds)
    • Launch at login toggle
    • Any other configurable settings should be exposed here

  4. Quit

Architecture Guidelines

  • Keep it simple. This is a focused utility, not a complex app.
  • No notifications unless added later.
  • No folder status indicators.
  • Everything that can be configurable should be configurable.
  • Use modern Swift concurrency (async/await) where appropriate.
  • Use SwiftUI for all UI.

Build & Run

  • Xcode project (not SPM-only)
  • Single-target macOS app
  • No third-party dependencies unless absolutely necessary

Workflow Rules

Before Making Changes

  • Zip the current project and name it the current version (e.g., FolderTimeMachine-v1.0.zip) before starting work.
  • Ask if the user wants to submit to GitHub or not.
  • Then begin the work following the steps below.

1. Plan Mode Default

  • Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
  • If something goes sideways, STOP and re-plan immediately — don't keep pushing
  • Use plan mode for verification steps, not just building
  • Write detailed specs upfront to reduce ambiguity

2. Subagent Strategy

  • Use subagents liberally to keep main context window clean
  • Offload research, exploration, and parallel analysis to subagents
  • For complex problems, throw more compute at it via subagents
  • One task per subagent for focused execution

3. Self-Improvement Loop

  • After ANY correction from the user: update tasks/lessons.md with the pattern
  • Write rules for yourself that prevent the same mistake
  • Ruthlessly iterate on these lessons until mistake rate drops
  • Review lessons at session start for relevant project

4. Verification Before Done

  • Never mark a task complete without proving it works
  • Diff behavior between main and your changes when relevant
  • Ask yourself: "Would a staff engineer approve this?"
  • Run tests, check logs, demonstrate correctness

5. Demand Elegance (Balanced)

  • For non-trivial changes: pause and ask "is there a more elegant way?"
  • If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
  • Skip this for simple, obvious fixes — don't over-engineer
  • Challenge your own work

6. Autonomous Bug Fixing

  • When given a bug report: just fix it. Don't ask for hand-holding
  • Point at logs, errors, failing tests — then resolve them
  • Zero context switching required from the user
  • Go fix failing CI tests without being told how

Task Management

  1. Plan First: Write plan to tasks/todo.md with checkable items
  2. Verify Plan: Check in before starting implementation
  3. Track Progress: Mark items complete as you go
  4. Explain Changes: High-level summary at each step
  5. Document Results: Add review section to tasks/todo.md
  6. Capture Lessons: Update tasks/lessons.md after corrections

Core Principles

  • Simplicity First: Make every change as simple as possible. Impact minimal code.
  • No Laziness: Find root causes. No temporary fixes. Senior developer standards.

Out of Scope (For Now)

  • App Store distribution
  • Sandboxing
  • Per-folder backup (not supported by Time Machine)
  • Notifications
  • Scheduling / interval-based backups
  • Exclude patterns for watched folders