Dock Timelapse

io.github.bcldvdPublished by GitHub account bcldvdv0.2.0Updated Oct 24, 2026

Record how your macOS Dock evolves and render Apple-style timelapse videos of it.

VerifiedSTDIODesktop onlyProductivity & WorkflowMedia & Design

Overview

AI-generated overview

Records how your macOS Dock changes over time and renders Apple-style timelapse videos of it, with tools to check status, history and renders.

What you can do
  • Check recording state, the current Dock and the saved snapshot history with changes
  • Start or stop the hourly background recording agent, and trigger a capture on demand
  • Render timelapse videos, previews and single frames from the recorded data
When to use it
Useful if you want a visual record of how your macOS Dock and app habits evolved, or want an assistant to start recording, report which apps were added since a date, and produce a shareable timelapse video.
Requirements
macOS with uv installed; runs locally over stdio, typically via uvx. ffmpeg is bundled. Optional Dock screenshots require granting Screen Recording permission in System Settings. No accounts, API keys or environment variables are declared.
Before you install
It reads the Dock's own preferences and, if screenshots are enabled, captures the screen, so it sees your app list and wallpaper. Installing recording sets up a launchd background agent that runs hourly; uninstalling stops it but keeps the history. Data is stored locally in the Application Support folder.

Installation

In SourceWeft

  1. Open Dock Timelapse in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Dock Timelapse

Your Dock tells the story of the tools you live in. Dock Timelapse records it quietly every day and turns its evolution into an Apple-style timelapse: apps springing in, others handing over their spot, a day counter ticking, all drawn over your own wallpaper.

[Landscape timelapse]   [Portrait timelapse]

Demo render with an invented nine-month history. The real output is 1920×1080 and 1080×1920 H.264 at 60 fps.

Replacements and arrivals, labelled next to the iconEnd card with the story in numbers
[Messages replaces Terminal, Photos added][Summary end card]
White background (--background white)Portrait — a vertical Dock with labels alongside
[White variant][Portrait]

How it works

  • Records — an hourly background agent reads the Dock's own preferences (the pinned apps, up to and including System Settings). On each day the Dock changes it saves a snapshot: the app list, every icon in high resolution, and the current wallpaper. Optionally it keeps a cropped Dock screenshot too.
  • Renders — the videos are redrawn from that data: a glass Dock over your blurred wallpaper, spring animations, change labels (+ Linear, Cursor replaces Xcode), the date and day counter, and a progress bar scaled to real calendar time.
  • Previews on day one — preview invents a plausible past that ends with your real Dock, so you can see your video right away.

Requirements: macOS and uv. ffmpeg comes bundled.

Install

Command line

bash
uv tool install dock-timelapse
dock-timelapse install        # start recording (hourly agent, one snapshot per day of change)dock-timelapse preview        # see your video now, with an invented pastdock-timelapse render         # later: the real timelapse → ~/Movies/Dock Timelapse/

Claude Code

text
/plugin marketplace add bcldvd/dock-timelapse/plugin install dock-timelapse@dock-timelapse

The plugin brings the skill and the MCP server. Then just ask: "start recording my Dock", "make a timelapse of my Dock", "which apps did I add since June?"

Codex, Cursor, Gemini CLI, Copilot and other agents

The skill follows the open Agent Skills format:

bash
npx skills add bcldvd/dock-timelapse -y

MCP server (Claude Desktop, Codex, Cursor, VS Code, …)

json
{  "mcpServers": {    "dock-timelapse": {      "command": "uvx",      "args": ["dock-timelapse", "mcp"]    }  }}

Codex (~/.codex/config.toml):

toml
[mcp_servers.dock-timelapse]command = "uvx"args = ["dock-timelapse", "mcp"]

Tools: dock_status, current_dock, dock_history, install_recording, uninstall_recording, capture_now, render_timelapse, render_preview, render_frame.

Usage

bash
dock-timelapse status                                     # recording state + every snapshot and its changesdock-timelapse render --format portrait                   # landscape | portrait | both (default)dock-timelapse render --background white                  # wallpaper (default) | desktop (sharp) | whitedock-timelapse preview --demo                             # a generic demo Dockdock-timelapse still --t 2 5.5                            # single PNG framesdock-timelapse install --screenshots                      # also keep Dock screenshotsdock-timelapse uninstall                                  # stop recording, history stays

Screenshots use the Screen Recording permission: install --screenshots prints the Python path to add in System Settings → Privacy & Security → Screen & System Audio Recording. The videos only need the Dock data, so this step is optional.

Data lives in ~/Library/Application Support/dock-timelapse/ (snapshots.json, icons, wallpapers, and capture.log).

Development

bash
uv syncuv run pytest
modulerole
dockdata.pyparse Dock prefs → ordered apps, up to System Settings
diff.pyadded / removed / replaced / moved between two Docks
store.pysnapshots on disk, one per day of change
capture.py · visibility.py · macos.pyone capture attempt; Dock visibility; the macOS calls
agent.pythe launchd agent
timeline.py · layout.pypure animation model and geometry
render.py · video.pyPillow frames → ffmpeg H.264
poc.pyinvented histories for previews
mcp_server.pyMCP tools

License

MIT

Source: README.md at commit 9ccb093

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0LatestSep 26, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts