{"id":48825702,"url":"https://github.com/coreyrdean/clauck","last_synced_at":"2026-04-14T18:00:17.260Z","repository":{"id":351202813,"uuid":"1209907781","full_name":"CoreyRDean/clauck","owner":"CoreyRDean","description":"Cron-scheduled claude -p sessions on macOS. Event triggers, job library, auto-updates, natural-language management.","archived":false,"fork":false,"pushed_at":"2026-04-14T16:37:02.000Z","size":259,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T17:26:20.722Z","etag":null,"topics":["ai-agents","automation","claude","claude-code","cron","launchd","macos","mcp","scheduled-jobs"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CoreyRDean.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T22:47:24.000Z","updated_at":"2026-04-14T16:36:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CoreyRDean/clauck","commit_stats":null,"previous_names":["coreyrdean/open-claude-cron","coreyrdean/clauck"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/CoreyRDean/clauck","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoreyRDean%2Fclauck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoreyRDean%2Fclauck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoreyRDean%2Fclauck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoreyRDean%2Fclauck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CoreyRDean","download_url":"https://codeload.github.com/CoreyRDean/clauck/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CoreyRDean%2Fclauck/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31808518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude","claude-code","cron","launchd","macos","mcp","scheduled-jobs"],"created_at":"2026-04-14T18:00:15.464Z","updated_at":"2026-04-14T18:00:17.215Z","avatar_url":"https://github.com/CoreyRDean.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clauck — your agent, on the clock\n\n[![CI](https://github.com/CoreyRDean/clauck/actions/workflows/ci.yml/badge.svg)](https://github.com/CoreyRDean/clauck/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/CoreyRDean/clauck?include_prereleases)](https://github.com/CoreyRDean/clauck/releases/latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![macOS](https://img.shields.io/badge/platform-macOS-lightgrey)](https://github.com/CoreyRDean/clauck)\n[![Claude Code](https://img.shields.io/badge/powered_by-Claude_Code-orange)](https://claude.ai/code)\n\n\u003c!-- TODO: Replace with banner image at assets/banner.png or clauck.com hosted --\u003e\n\u003c!-- ![clauck](assets/banner.png) --\u003e\n\nWorkflow automation powered by AI agents. Schedule tasks, chain pipelines, react to events, and build automations that think — all from plain English.\n\n\u003e **Hey Claude, install clauck**\n\nPaste that into Claude Code. Done.\n\n```bash\n# Or one-liner:\ncurl -sSL https://raw.githubusercontent.com/CoreyRDean/clauck/main/install.sh | bash\n```\n\n```bash\n# Or manage from terminal:\nclauck list                          # what's running?\nclauck fire morning-brief            # trigger it now\nclauck every morning check my PRs    # plain English → scheduled job\nclauck doctor                        # diagnose issues\n```\n\n---\n\n## What people build with clauck\n\n| What they said | What clauck does |\n|---|---|\n| *\"Summarize my Slack and email before I sit down.\"* | Morning digest, 8am weekdays. ~$4/mo. |\n| *\"When a PDF lands in Downloads, tell me what it is.\"* | Event trigger. No schedule. ~$0.04/fire. |\n| *\"Pull Sentry errors → cross-ref with merged PRs → post to Slack.\"* | Chained pipeline. Three jobs, auto-composed. |\n| *\"Monitor health endpoints tonight during the deploy, then self-destruct.\"* | Temporal window. Auto-expires at 6am. |\n| *\"Prepare my standup 30 min before the meeting. Get better over time.\"* | Session persistence. Learns across runs. |\n| *\"Remind me to review the budget on Thursday.\"* | One-shot. Does the prep, not just the nudge. |\n| *\"Change my morning brief to also include Sentry.\"* | Modifies an existing job. One sentence. |\n| *\"Pause everything for the weekend.\"* | `clauck pause --all` or just tell Claude. |\n\n## Why this exists\n\nClaude Code is powerful. But you have to be there to use it. **clauck** makes your agent work when you're not — on schedules, in response to events, through multi-step pipelines, and with memory that carries across runs.\n\nIt's the difference between a tool you use and an agent that works for you.\n\n### Simple on the surface\n\n\u003e *\"Do this every morning: summarize my unread Slack messages.\"*\n\nClaude handles the cron expression, model selection, budget, prompt design, and installs it. You describe intent; clauck handles execution.\n\n### Powerful at depth\n\nBuild pipelines where jobs produce data for other jobs. React to filesystem changes, app launches, and arbitrary shell conditions. Configure per-job models, budgets, and tool surfaces. Create temporal workflows that activate, transition, decay, and expire on schedule. Debug jobs interactively. Let jobs learn from their own history through session persistence.\n\n### Beyond what native scheduling can do\n\n| | Claude Native | clauck |\n|---|---|---|\n| Event triggers (files, apps, shell) | No | 4 types, zero token cost |\n| Cross-run memory | Fresh session each time | Session persistence |\n| Chained pipelines (producers → consumers) | No | DAG execution with parallel resolution |\n| Temporal scheduling (one-shot, decay, windows) | One-shot only | Full set |\n| Per-job model/budget/MCP control | Partial | Per-job frontmatter |\n| Interactive debug + iterate | No | Opens Terminal to continue |\n| Job library + community | No | 7+ curated, extensible |\n| Self-healing diagnostics | No | `clauck doctor` |\n| CLI management | No | `clauck` binary with semantic fallthrough |\n| Works without Desktop app | Cloud only (no local) | launchd (OS-level) |\n\n## Install\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/CoreyRDean/clauck/main/install.sh | bash\n```\n\nThe installer shows you exactly what it will do and asks before proceeding. It installs the scheduler, skill, library, CLI, and a SessionStart hook — then fires the heartbeat job and shows proof the pipeline works.\n\n**Inspect first:** `curl -fsSL .../install.sh -o install.sh \u0026\u0026 less install.sh \u0026\u0026 bash install.sh`\n\n**Dry run:** `curl ... | bash -s -- --dry-run`\n\n**Non-interactive:** `curl ... | bash -s -- --yes`\n\n**Just tell Claude:** paste *\"Hey Claude, install clauck\"* into any Claude Code session.\n\n### Prerequisites\n\n| Dependency | Ships with macOS? | If missing |\n|---|---|---|\n| `/bin/zsh`, `/usr/bin/python3` | Yes | Always present |\n| `git` | Via Xcode CLT | `xcode-select --install` |\n| **`claude` CLI** | **No** | **[Install Claude Code](https://claude.ai/code)** — the only manual step |\n\n### Install from your own fork\n\n```bash\nCLAUCK_REPO=https://github.com/you/clauck bash \u003c(curl -fsSL .../install.sh)\n```\n\nUpdates check your fork. No backdoor from upstream.\n\n## The `clauck` CLI\n\nInstalled alongside `claude` at `~/.local/bin/clauck`. For quick management from the terminal:\n\n```bash\nclauck list                          # all jobs + status + next fire\nclauck status                        # system health overview\nclauck fire \u003cname\u003e                   # trigger a job now\nclauck edit \u003cname\u003e                   # open in your editor, validate on save\nclauck pause \u003cname\u003e / resume \u003cname\u003e  # toggle\nclauck logs \u003cname\u003e                   # recent runs with costs\nclauck library                       # browse pre-made jobs\nclauck install \u003cname\u003e                # install from library\nclauck doctor                        # diagnose system health\nclauck doctor -i                     # interactive diagnostic session\nclauck update --apply                # apply pending update\nclauck \u003canything else\u003e               # plain English → Claude executes it\nclauck work \u003ctext\u003e                   # explicit semantic (avoids subcommand conflicts)\n```\n\nThe semantic fallthrough means `clauck change heartbeat to every 2 hours` works the same as opening Claude and asking — but faster.\n\n## Job library\n\nShips with 7 curated jobs. Ask Claude *\"what's in the library?\"* or run `clauck library`:\n\n| Job | Schedule | Cost/mo | What it does |\n|---|---|---|---|\n| **morning-brief** | Weekdays 8am | ~$4 | Slack mentions + calendar + Jira in one digest |\n| **github-pr-digest** | Weekdays 9am | ~$3 | PRs needing review, stale drafts, merged |\n| **inbox-zero-assist** | Weekdays 5pm | ~$3 | Stale Gmail threads with suggested actions |\n| **daily-verify** | Daily | ~$6 | MCP health check (catches silent auth drift) |\n| **downloads-triage** | Event-driven | \u003c$1 | Categorize new downloads |\n| **workspace-cleanup** | Weekly | ~$0.16 | Stale/generic/large files on Desktop |\n| **git-commit-nudge** | Every 4h | ~$7 | Uncommitted/unpushed work across repos |\n\nAll report-only by default — they read and suggest, they don't send, delete, or modify.\n\n## Pipelines (producers and consumers)\n\nJobs can feed into each other. A **producer** delivers its output to the jobs that depend on it. A **consumer** receives output whenever its source runs.\n\n```yaml\n# Job A runs after B and C complete, with their outputs injected\nproducers:\n  - {name: job-b}\n  - {name: job-c}\n\n# Job A's output automatically triggers X and Y\nconsumers:\n  - job-x\n  - job-y\n```\n\nThe scheduler resolves the full dependency graph, runs roots in parallel, injects outputs up the tree, and handles failures. Each node sees an **oplog** of the full execution chain — who ran, what they produced, in what order.\n\nPipelines work with or without cron. An ad-hoc-only graph triggered by `clauck fire root-job` is a first-class use case.\n\n## External triggers\n\nReact to events, not just time:\n\n```yaml\nexternal_triggers:\n  - {type: file_added, path: ~/Downloads, glob: \"*.pdf\", quiet_seconds: 30}\n  - {type: process_starts, match: Obsidian}\n  - {type: file_changed, path: ~/Documents/inbox.md}\n  - {type: command_succeeds, run: \"curl -sf https://api.example.com/health\"}\n```\n\nAll four are evaluated every 60 seconds with zero token cost. Edge-triggered. Bootstrap-safe.\n\n## Temporal scheduling\n\nBeyond simple cron — express time-bounded intent:\n\n```yaml\nrun_once: true                    # fire once, auto-disable\nmax_runs: 5                       # fire 5 times, then stop\nvalid_after: \"2026-05-01\"         # don't start until May 1st\nexpires_after: \"2026-06-01\"       # auto-disable after June 1st\n```\n\nComplex requests decompose into phased jobs: *\"Every day for a week, then every other day for two weeks, then stop\"* becomes multiple jobs with staggered validity windows.\n\n## Trust and security\n\nThis system runs `claude -p --dangerously-skip-permissions` in a background LaunchAgent.\n\n**What we do:** every run is logged with full I/O. Auto-updates never apply without explicit opt-in. Fork users are completely isolated from upstream. The installer enumerates everything before acting and asks for confirmation.\n\n**What we don't do:** no telemetry, no phone-home, no shell config modification, no job overwriting.\n\nSee [SECURITY.md](SECURITY.md) for the full threat model.\n\n## Cost\n\n| Config | Per run (Haiku) | Monthly at hourly |\n|---|---|---|\n| Minimal (no MCPs, no plugins) | ~$0.04 | ~$29 |\n| MCP-using (no plugins) | ~$0.16 | ~$115 |\n| Full surface | ~$0.21 | ~$151 |\n\nBudget is per-job. The system never exceeds what you configure.\n\n## Architecture\n\n```\nlaunchd (60s tick) → scheduler.py\n  ├─ discovers jobs, parses frontmatter, writes manifest\n  ├─ evaluates cron + external triggers + temporal gates\n  ├─ resolves producer/consumer DAGs (cycle detection)\n  ├─ checks for updates (rate-limited)\n  └─ for matching jobs → run-job.sh (detached)\n       ├─ log created FIRST (preflight failures observable)\n       ├─ acquires lock (concurrency guard)\n       ├─ injects runtime context + producer outputs + oplog\n       └─ claude -p → log → exit_code tombstone\n```\n\nOne LaunchAgent. N jobs. Adding a job is dropping a Markdown file.\n\n## User stories\n\nThe [`stories/`](stories/) directory documents concrete use cases — from *\"morning catch-up\"* to *\"multi-phase project cadence\"* to *\"jobs that learn across runs.\"* 10 stories ship with the repo. Agents reference them when suggesting jobs; users browse them for inspiration; contributors submit new ones.\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md). Highlights: job chaining/DAG execution (v1.1), Linux support + alternative harnesses (v1.2), clauck.com dashboard (v2.0).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Library jobs and user stories are especially welcome.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoreyrdean%2Fclauck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoreyrdean%2Fclauck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoreyrdean%2Fclauck/lists"}