# Clockwork

> A macOS desktop app that schedules recurring AI agent jobs (Claude Code, Codex, OpenCode, Hermes) on a real calendar, runs them in sandboxed git worktrees, and files readable reports.

Clockwork is a macOS desktop application built by Vimox Shah that puts AI coding agents on a real calendar. You book a recurring job — picking an agent profile, a repository, a dollar budget, and a time — and Clockwork runs it unattended inside an OS-sandboxed git worktree, then delivers a structured report to your inbox covering what the agent did, what it skipped, and what it cost. Version 0.12.1 is the current release as of September 2026.

## What It Is

Clockwork sits in the category of agent scheduling and harness tooling for developer workflows. Its core job is to take the recurring, chore-like work that AI coding agents are well-suited for — dependency triage, flaky-test sweeps, docs-drift checks, security audits — and give that work a home on a calendar with hard budget caps, sandboxed execution, and human-readable output. It is a local-first macOS app: no account, no cloud component, no telemetry. All state lives in SQLite under `~/.clockwork`, and the daemon binds to loopback only.

## How Scheduling and Execution Work

Each task is booked with a profile, a repository, a dollar cap, a turn cap, a wall-clock timeout, and a schedule expressed as RRULE or cron in the user's own IANA time zone. Clockwork handles daylight-saving rules, missed-run policies (run late, skip, or ask), and a per-repository mutex so only one run executes against a repo at a time. Supported triggers include the calendar, HMAC-verified webhooks, and GitHub event sources.

When a run fires, Clockwork spawns a fresh git worktree and branch cut from the base branch, wraps it in a macOS Seatbelt sandbox profile, and drives whichever CLI engine the task is configured for — Claude Code, Codex CLI, OpenCode, or Hermes Agent — using the user's own subscription login. The sandbox denies reads of `.ssh`, `.aws`, `.gnupg`, shell history, and browser profiles, and blocks writes outside the run's worktree. Budget enforcement happens at the supervisor level, outside the model. Risky actions pause the run and wait for a human answer; unanswered asks fail closed.

## The Thirteen Built-In Agent Profiles

Clockwork ships thirteen specialist profiles, each defined as an operating contract with a mission, hard limits, and a fixed report shape:

- **Engineering:** Generalist, Dep Surgeon, Test Doctor, Bug Hunter, Code Reviewer, Refactor Engineer, Performance Engineer, Security Auditor, Release Engineer
- **Operations & Docs:** CI Investigator, Repo Health Monitor, Docs Scribe, Changelog Writer

Users can also write custom profiles in the app by specifying skills, a permission mode, budget defaults, and a system prompt.

## Agent Workforce Features

Beyond basic scheduling, Clockwork includes twelve "agent workforce" features: plan-then-execute approval gates (where a planning run must be approved before an execute run is created), shift-handoff memory that carries context between recurring occurrences, office-hours deferral for approval requests, sentinel-to-worker trigger pairs, repo-shipped job offers, run verdicts, an earned-autonomy ladder (where higher permission rungs are offered after accepted outcomes but never auto-granted), self-healing diagnostics, agent-proposed calendar events, timesheets, performance scorecards, and a portable proof-of-work export. The README notes that three of these twelve features actively enforce or refuse actions; the other nine are available but do not gate anything.

## Delivery and Reporting

Every run produces a structured report covering a summary, the branch and diffstat, cost against caps, approval decisions, and a full searchable transcript. Reports are delivered via macOS notifications, Telegram (which also carries approve/deny buttons), Slack, email, and an HMAC-signed outbound webhook. Credentials are masked before storage. The Inbox shows a morning digest of overnight runs, and each report ends with a next-action button.

## Update: v0.12.1

The current release is v0.12.1, published on September 10, 2026. The spec sheet on the project homepage lists this version as the baseline for all described features. Recent additions documented in the README include Telegram approval decisions, Slack and email delivery for approval requests, quiet-hours deferral with a working resume path (fixing a prior bug where deferred recurring schedules would stick), a retention settings card, outbound webhook URL in the task composer, a live run tail with mid-run catch-up, five bookable job templates, template export, a menu-bar item, and an accessibility sweep that runs in CI. The roadmap marks Docker execution as partially built (runner module exists, but no task-level dispatch or UI selector yet) and signed/notarized builds as pending an Apple Developer certificate.

## Features
- Real calendar scheduling with RRULE and cron support
- 13 built-in specialist agent profiles
- macOS Seatbelt sandbox per run with isolated git worktree
- Supports Claude Code, Codex CLI, OpenCode, and Hermes Agent
- Bring-your-own API keys stored in macOS Keychain
- Dollar cap, turn cap, and wall-clock timeout enforced by supervisor
- Human-in-the-loop approval gates that fail closed
- Agent chains: sequence agents with {{previous.report}} handoff
- Shift-handoff memory between recurring occurrences
- Plan-then-execute approval gate
- Office hours deferral for approval requests
- Sentinel-to-worker trigger pairs
- Earned autonomy ladder (offered, never auto-granted)
- Self-healing diagnostics (propose only, never self-apply)
- Timesheets and performance scorecards per agent profile
- Proof-of-work export as self-contained HTML
- Delivery via Telegram (with approve/deny buttons), Slack, email, webhook
- Full-text search across run history and transcripts
- HMAC-verified webhook and GitHub event triggers
- Local-first: SQLite in ~/.clockwork, loopback-only API, no telemetry
- Morning inbox digest of overnight runs
- Menu-bar item with approval badge
- Five bookable job templates included
- Command palette (⌘K) and keyboard shortcuts
- Cost and reliability analytics by task, provider, and day
- Repo-shipped job offers via .clockwork/jobs.json
- Live run tail with mid-run catch-up
- Ephemeral Docker execution (runner module exists, dispatch pending)

## Integrations
Claude Code, Codex CLI, OpenCode, Hermes Agent, Anthropic API, OpenAI API, Google AI, OpenRouter, xAI, Mistral, DeepSeek, Ollama, Telegram, Slack, GitHub (event triggers), macOS Keychain, Homebrew, launchd, Docker

## Platforms
WINDOWS, MACOS, WEB, API, CLI

## Pricing
Freemium — Free tier available with paid upgrades

## Version
0.12.1

## Links
- Website: https://vimoxshah.github.io/clockwork/
- Documentation: https://github.com/vimoxshah/clockwork/blob/main/docs/install.md
- Repository: https://github.com/vimoxshah/clockwork
- EveryDev.ai: https://www.everydev.ai/tools/clockwork-agent-scheduler