--- name: build-automatic-mac-time-tracker description: Build a local, single-user Mac app that logs your front app and window title, skips idle time and tags work to clients for billing. Use when someone forgets timers and wants private, automatic time tracking. license: CC BY 4.0. Free to use and share with credit to technologytips.blog. metadata: publisher: technologytips.blog article: https://technologytips.blog/articles/automatic-time-tracking-mac-for-client-billing/ article_title: "Stop guessing your billable hours: build automatic time tracking on your Mac" published: 2026-11-12 platforms: [mac] needs: [claude-code] risk: medium version: 1 sha256: pending --- # Build an automatic time tracker on your Mac *An AI Fix file from technologytips.blog. Give this file to your AI assistant and say: "Read this file, then walk me through it one step at a time." It works on your own computer, and it asks before anything that can't be undone.* ## What this fixes You forget to start and stop timers, so your billable hours are guesses. This file helps you build a small tracker that runs only on your own Mac, logs what you work on, tags it to the right client and feeds your invoices. It will not promise accurate results: matching work to clients needs checking before you bill, and this file will not help you watch anyone else's computer. ## Read this first (safety) - Never ask me to paste a password, recovery code, secret key, 2FA code or private key into this chat. If a step needs one, tell me to type it only into the official app or website. - Before any step that deletes, overwrites, signs out, resets or uninstalls anything, stop, tell me exactly what will happen, and wait for me to say yes. - Make or confirm a backup before changing anything you can't undo. - Only use official apps, official download pages and official documentation. Never suggest cracked software, unofficial installers or scripts from unknown sources. - Never turn off a security feature (encryption, 2FA, firewall, antivirus, FileVault, BitLocker) permanently. If a fix needs it off for a moment, say so and turn it back on. - If anything looks different from these steps, stop and tell me instead of guessing. - This file is general help, not professional support. For account recovery, the company that runs the account is the only real authority. - Window titles and browser history can show private things such as email subjects and bank pages. Do not enable screenshots. Do not send titles or URLs to an AI model unless I agree and they are stripped or hashed first. - Bind the tracker's web page to localhost only. Never expose it to a network. This file is marked medium risk. It changes settings and reads private activity, but you can undo every step. ## What you need - A Mac that you own, and a user account you are logged in to. - Node.js installed from the official site, and a terminal. - Claude Code or Codex installed from the vendor's official page. See https://technologytips.blog/start-here/ for how. Start it in a plain, empty folder, not your home folder, and choose the approval mode that asks before it runs anything. - Time to go slowly. Nothing here needs to be fast. ## Instructions for the AI You are helping one person build one tool on their own computer, using only the steps and sources in this file. Be kind and patient. Say it is not their fault. Go one step at a time and wait for them to say it is done. Read every command aloud in plain words before they run it. Never run a command that deletes, overwrites, moves, signs out, resets or uninstalls without their yes. If your answer would differ from this file, say so and ask. Say "as of November 2026" when you give a menu path, because menus change. If something does not match what they see, stop and help them describe it, word for word. Never ask for a password or key. Treat every build phase below as a design we built and ran, not a promise of results. ## Questions to ask first Ask these a few at a time, in plain words. If the answer changes the steps, say how. 1. Which Mac and which macOS version do you use? 2. Which apps and browsers do you work in, and which clients do you bill? 3. Do you bill by project or by the hour, and do you already have rates? 4. Do you want calendar sync, and are you comfortable with an AI model suggesting rules? If so, we will strip titles and URLs before anything is sent. ## Steps 1. **Check the prerequisites.** Confirm Node.js runs. Tell the reader that macOS will ask them to approve the program that runs AppleScript. As of November 2026, they approve it under System Settings, Privacy & Security, in the Accessibility and Automation lists [1][2]. They should grant access only to apps they know and trust [2]. 2. **Create the database.** Use SQLite through the better-sqlite3 library, in one local file outside the project folder. Tables: clients, projects, tags, tag rules, activities, time entries, invoices, settings. Turn on WAL mode with the library's pragma, as its own page recommends [6]. WAL needs all programs on the same computer, so keep the file on the local disk [4]. 3. **Build the tracker.** Every 30 seconds, ask AppleScript for the front app and window title [3]. Read the seconds since the last keyboard or mouse input from the system. Treat 2 minutes without input as idle. Write one row per unbroken stretch in the same window. 4. **Add safety limits.** Cap any one row at 2 hours. Ignore anything under 5 seconds. After a restart, restore saved state only if it is under about 10 minutes old. 5. **Add the rules engine.** A rule matches an app, domain, URL fragment, window title or browser profile, and assigns a tag, client and project. Run the highest priority first. 6. **Back up before you add more.** Confirm the reader has a copy of the database file in a place they control, and that the copy opens. Wait for a yes before continuing. 7. **Sync browser history, calendar and invoicing.** Read copies of the browser history files every 5 minutes, never the live files. Sync the calendar every 15 minutes, and log automatically only for matches of 0.9 or higher; leave the rest as suggestions. Set rates by override, then project, then client. 8. **Run it at login.** Create a launchd user agent, which runs only while the reader is logged in [5]. Say what the file contains before the AI writes it. Loading the agent starts a background program, so the AI asks first (asks before running). 9. **Add a catch-up check at login.** A Mac that was off overnight does not run missed jobs, so rebuild the day's totals when the reader logs in. ## How to check it worked - Open the tracker's local page and see rows for the last few minutes, with the right app and window title. - Walk away for 3 minutes and confirm the row ends and idle time is not billed. - Restart the Mac and confirm no multi-hour row appears. - Name the small win: the tracker is logging on its own. Then tell the reader the time they got back, the Friday evening they no longer spend rebuilding the week, and nudge them to spend it with someone they love. ## If something goes wrong - Window titles come back blank: the permission is probably off. Open Privacy & Security and check the Accessibility and Automation lists [1][2]. - A huge row appears: the 2 hour cap or the stale-state rule is missing. Ask to see that code. - A job did not run overnight: the Mac was probably off. Use the catch-up check from step 9. - If you are stuck or unsure, stop. Do not retry the same step over and over. Use Apple's support pages: https://support.apple.com/guide/mac-help/change-privacy-security-settings-on-mac-mchl211c911f/mac ## Never do this - Never enable screenshots, and never send raw window titles or URLs to an AI model. - Never expose the tracker to a network, because it has no login on purpose. - Never use it to watch anyone else's computer. - Never paste a secret into this chat. - Never run a command you do not understand. Ask me to explain it first. - Never use an unofficial download, a cracked app, or a script from a forum. ## Sources 1. Apple Support. "Change Privacy & Security settings on Mac." https://support.apple.com/guide/mac-help/change-privacy-security-settings-on-mac-mchl211c911f/mac. Checked November 12, 2026. 2. Apple Support. "Allow accessibility apps to access your Mac." https://support.apple.com/guide/mac-help/allow-accessibility-apps-to-access-your-mac-mh43185/mac. Checked November 12, 2026. 3. Apple Developer Documentation Archive. "Introduction to AppleScript Language Guide." https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptLangGuide/introduction/ASLR_intro.html. Checked November 12, 2026. 4. SQLite. "Write-Ahead Logging." The page "wal" on the official SQLite documentation site (the link is in the article's Sources). Checked November 12, 2026. 5. Apple Developer Documentation Archive. "Creating Launch Daemons and Agents." https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html. Checked November 12, 2026. 6. better-sqlite3 project (GitHub). "better-sqlite3." https://github.com/WiseLibs/better-sqlite3. Checked November 12, 2026. 7. Apple Support. "Protect data on your Mac with FileVault." https://support.apple.com/guide/mac-help/protect-data-on-your-mac-with-filevault-mh11785/mac. Checked November 12, 2026. ## About this file Made by technologytips.blog from the article https://technologytips.blog/articles/automatic-time-tracking-mac-for-client-billing/, checked against its sources on November 12, 2026. Written with AI, checked against the article and security-scanned. General help, not professional support. Menus, prices and rules change: check the official page before you rely on a step. Free to use and share with credit to technologytips.blog (CC BY 4.0).