Timewarp

TL;DR

Timewarp helps you fill out your timesheets without having to keep track yourself.

It runs quietly on your Windows PC and watches which window is in front — that's it. It notes the app name and window title (like 25-125_SLD-E101.dwg - AutoCAD) and saves it to a local SQLite database on your computer. Nothing is uploaded or shared — you control the data, and it never leaves your machine unless you choose to sync it (e.g. via OneDrive). This is not a corporate monitoring tool. It's a personal utility that works for you.

When it's time to fill out your timecard, you open your AI assistant and ask in plain English:

"What did I work on this week?"

It reads your local data and tells you: "You spent 4 hours in AutoCAD on project 25-125, 1 hour in a design review meeting, 30 minutes on emails..." — and you copy that into your timesheet. Done.

How it works under the hood: Every second, Timewarp checks which window is active using the Windows API. It groups those seconds into sessions (ignoring brief alt-tabs), extracts project numbers from file names when possible, and stores everything in a local SQLite database. Your AI assistant accesses this database through a local MCP connection — the same way it accesses files on your computer — and can answer questions about your work history.

Compatible with any MCP-enabled AI app, including Claude Desktop, ChatGPT Desktop, and others that support the Model Context Protocol.

Architecture

Everything stays on your machine. The MCP server is a local process that communicates with your AI app over stdin/stdout — it does not open any network ports or send data anywhere.

Installation

Step 1: Download and run

Download timewarp.exe from the latest release, put it somewhere permanent (e.g. C:\Tools\Timewarp\timewarp.exe), and double-click it.

Step 2: First-run setup

On the first launch, Timewarp walks you through setup automatically:

1. Choose a data folder — A dialog explains your options and opens a folder picker. Pick a folder inside OneDrive if you use multiple computers (each PC saves its own file, no sync conflicts), or any local folder if you only use one machine.
2. Start at login — Timewarp asks if you want it to run automatically when you log in. If you click Yes, a UAC prompt will appear (it needs admin rights to create the scheduled task). You can remove this later with timewarp.exe -uninstall.

Don't have admin rights? Skip the UAC prompt and instead create a shortcut to timewarp.exe in your Startup folder. Press Win+R, type shell:startup, and drag the shortcut there. It works the same way — Timewarp will start every time you log in.

After setup, a small purple clock icon appears in your system tray — Timewarp is now tracking.

Step 3: Connect to your AI app

Right-click the tray icon and click Connect to Claude Desktop. Timewarp automatically finds your Claude Desktop config file and adds itself. Restart Claude Desktop and you're done.

Using ChatGPT Desktop or another MCP-compatible app? Click Copy MCP Config instead — this copies the JSON to your clipboard so you can paste it into your app's config file manually. The MCP server config looks like this:

{
  "mcpServers": {
    "timewarp": {
      "command": "C:\\Tools\\Timewarp\\timewarp.exe",
      "args": ["-mcp", "-dbpath", "C:\\Users\\You\\OneDrive\\TimewarpData"]
    }
  }
}

Once connected, you can ask things like:

• "What did I work on this week?"
• "How much time did I spend in AutoCAD?"
• "Break down my week by day for my timecard"
• "List my top apps this week"

What to Ask

Once Timewarp is running and connected, just ask in plain English. Here are some examples:

Your AI app will call the appropriate Timewarp tools automatically. You don't need to know the tool names or syntax — just describe what you need.

System Tray Menu

Right-click the tray icon to access these options:

MCP Tools

These are the tools your AI app can call to query your data:

Example: Weekly Summary

Ask: "Summarize my work this week for my timecard"

Your AI app calls get_weekly_summary and receives:

{
  "week": "2026-03-02/2026-03-08",
  "machines": ["DESKTOP-VINC", "LAPTOP-VINC"],
  "attributed": [
    {
      "project_number": "25-125",
      "total_minutes": 252,
      "processes": ["acad.exe", "OUTLOOK.EXE", "Bluebeam Revu"],
      "sample_titles": ["25-125_SLD-E101.dwg - AutoCAD"]
    }
  ],
  "unattributed": [
    { "process": "chrome.exe", "total_minutes": 48, "sample_titles": ["..."] }
  ],
  "meetings": [
    { "subject": "25-019 Design Review", "total_minutes": 62, "sessions": 2 }
  ],
  "inactivity_minutes": 94
}

How Sessions Work

Timewarp doesn't just record every second individually. It stitches activity into sessions:

• Gaps under 30 seconds in the same app are bridged (you alt-tabbed to copy something and came back)
• Sessions under 10 seconds are discarded (you accidentally clicked the wrong window)
• Project numbers are extracted from window titles using the pattern YY-NNN (e.g. 25-125 from 25-125_SLD-E101.dwg)
• Meetings are detected from Teams/Zoom/Webex window titles
• Suppressed processes like mstsc.exe (Remote Desktop), LockApp.exe, and ShellExperienceHost.exe are never recorded

Command-line Flags

Prometheus Metrics (Optional)

Timewarp can expose a Prometheus endpoint for real-time dashboarding. It is off by default — enable it from the tray menu or by toggling it on.

Endpoint: http://localhost:9183/metrics

Building from Source

git clone https://github.com/vinistoisr/timewarp.git
cd timewarp
go build -ldflags "-H=windowsgui" -o timewarp.exe .

Requires Go 1.24+.