clauck is a local agent runtime for macOS. Build Clauck Cycles — think "clock cycles" — agents that execute on schedules, react to events, chain through pipelines, and automate work that thinks. All from plain English. Runs as you, on your Mac, with your permissions. No cloud. No sandbox. No permission-gated runtime.
The contract that governs this project lives in INTENT.md.
Hey Claude, install clauck
In Claude Code, that triggers the curl install.sh below. In Claude Desktop, paste "Create a new CoWork plugin from https://github.com/CoreyRDean/clauck" instead — Desktop handles plugin creation natively. Then run the installer once in a Mac terminal for the runtime binary.
# Runtime install (required on your Mac either way):
curl -sSL https://raw.githubusercontent.com/CoreyRDean/clauck/main/install.sh | bash# Or manage from terminal:
clauck list # what's running?
clauck fire morning-brief # trigger it now
clauck every morning check my PRs # plain English → scheduled job
clauck doctor # diagnose issues| What they said | What clauck does |
|---|---|
| "Summarize my Slack and email before I sit down." | Morning digest, 8am weekdays. ~$4/mo. |
| "When a PDF lands in Downloads, tell me what it is." | Event trigger. No schedule. ~$0.04/fire. |
| "Pull Sentry errors → cross-ref with merged PRs → post to Slack." | Chained pipeline. Three jobs, auto-composed. |
| "Monitor health endpoints tonight during the deploy, then self-destruct." | Temporal window. Auto-expires at 6am. |
| "Prepare my standup 30 min before the meeting. Get better over time." | Session persistence. Learns across runs. |
| "Remind me to review the budget on Thursday." | One-shot. Does the prep, not just the nudge. |
| "Change my morning brief to also include Sentry." | Modifies an existing job. One sentence. |
| "Pause everything for the weekend." | clauck pause --all or just tell Claude. |
Claude 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.
It's the difference between a tool you use and an agent that works for you.
The permission model is the wedge. clauck runs as you, on your machine, with your permissions. Every competitor runs sandboxed. That's the reason clauck exists and the reason you'd pick it over alternatives. Logs over guardrails. Trust earned via inspectability — every execution logged, every state change visible, every intent traceable. If you don't understand --dangerously-skip-permissions, clauck is not for you. If you do, it's designed for you.
"Do this every morning: summarize my unread Slack messages."
Claude handles the cron expression, model selection, budget, prompt design, and installs it. You describe intent; clauck handles execution.
Build 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.
| Claude Native | clauck | |
|---|---|---|
| Event triggers (files, apps, shell) | No | 4 types, zero token cost |
| Cross-run memory | Fresh session each time | Session persistence |
| Chained pipelines (producers → consumers) | No | DAG execution with parallel resolution |
| Temporal scheduling (one-shot, decay, windows) | One-shot only | Full set |
| Per-job model/budget/MCP control | Partial | Per-job frontmatter |
| Interactive debug + iterate | No | Opens Terminal to continue |
| Cycle marketplace + community | No | 7+ curated, extensible |
| Self-healing diagnostics | No | clauck doctor |
| CLI management | No | clauck binary with semantic fallthrough |
| Works without Desktop app | Cloud only (no local) | launchd (OS-level) |
curl -sSL https://raw.githubusercontent.com/CoreyRDean/clauck/main/install.sh | bashOne command. The installer places the runtime (scheduler, LaunchAgent, CLI at ~/.local/bin/clauck), caches the job marketplace, and registers the clauck plugin with Claude Code — the plugin delivers the skill (/clauck:clauck), the SessionStart hook, and the MCP server in one shot. Fires the heartbeat job at the end as proof.
Inspect first: curl -fsSL .../install.sh -o install.sh && less install.sh && bash install.sh
Dry run: curl ... | bash -s -- --dry-run
Non-interactive: curl ... | bash -s -- --yes
Just tell Claude: paste "Hey Claude, install clauck" in Claude Code — the agent runs the curl install.sh above. In Claude Desktop, paste "Create a new CoWork plugin from https://github.com/CoreyRDean/clauck" for the Desktop side (and run install.sh in a Mac terminal separately for the runtime binary).
Two things:
-
Paste this to Claude Desktop (CoWork or chat) to create the plugin:
Create a new CoWork plugin from
https://github.com/CoreyRDean/clauck.Desktop handles the rest natively — skill, hook, and MCP server get wired in. See docs/desktop-plugin-setup.md for the full reference.
-
Run the install.sh one-liner in a Mac terminal to place the runtime binary. The plugin wraps
~/.local/bin/clauck; without the binary the MCP server can't start. This step is a no-op if you've already installed.
| Dependency | Ships with macOS? | If missing |
|---|---|---|
/bin/zsh, /usr/bin/python3 |
Yes | Always present |
git |
Via Xcode CLT | xcode-select --install |
claude CLI |
No | Install Claude Code — the only manual step |
CLAUCK_REPO=https://github.com/you/clauck bash <(curl -fsSL .../install.sh)Updates check your fork. No backdoor from upstream.
Installed alongside claude at ~/.local/bin/clauck. For quick management from the terminal:
clauck list # all jobs + status + next fire
clauck status # system health overview
clauck fire <name> # trigger a job now
clauck edit <name> # open in your editor, validate on save
clauck pause <name> / resume <name> # toggle
clauck logs <name> # recent runs with costs
clauck marketplace # browse pre-made jobs
clauck install <name> # install from marketplace
clauck doctor # diagnose system health
clauck doctor -i # interactive diagnostic session
clauck update --apply # apply pending update
clauck <anything else> # plain English → Claude executes it
clauck work <text> # explicit semantic (avoids subcommand conflicts)The semantic fallthrough means clauck change heartbeat to every 2 hours works the same as opening Claude and asking — but faster.
Ships with 7 curated Cycles. Ask Claude "what's in the marketplace?" or run clauck marketplace:
| Cycle | Schedule | Cost/mo | What it does |
|---|---|---|---|
| morning-brief | Weekdays 8am | ~$4 | Slack mentions + calendar + Jira in one digest |
| github-pr-digest | Weekdays 9am | ~$3 | PRs needing review, stale drafts, merged |
| inbox-zero-assist | Weekdays 5pm | ~$3 | Stale Gmail threads with suggested actions |
| daily-verify | Daily | ~$6 | MCP health check (catches silent auth drift) |
| downloads-triage | Event-driven | <$1 | Categorize new downloads |
| workspace-cleanup | Weekly | ~$0.16 | Stale/generic/large files on Desktop |
| git-commit-nudge | Every 4h | ~$7 | Uncommitted/unpushed work across repos |
All report-only by default — they read and suggest, they don't send, delete, or modify.
Jobs 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.
# Job A runs after B and C complete, with their outputs injected
producers:
- {name: job-b}
- {name: job-c}
# Job A's output automatically triggers X and Y
consumers:
- job-x
- job-yThe 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.
Pipelines work with or without cron. An ad-hoc-only graph triggered by clauck fire root-job is a first-class use case.
React to events, not just time:
external_triggers:
- {type: file_added, path: ~/Downloads, glob: "*.pdf", quiet_seconds: 30}
- {type: process_starts, match: Obsidian}
- {type: file_changed, path: ~/Documents/inbox.md}
- {type: command_succeeds, run: "curl -sf https://api.example.com/health"}All four are evaluated every 60 seconds with zero token cost. Edge-triggered. Bootstrap-safe.
Beyond simple cron — express time-bounded intent:
run_once: true # fire once, auto-disable
max_runs: 5 # fire 5 times, then stop
valid_after: "2026-05-01" # don't start until May 1st
expires_after: "2026-06-01" # auto-disable after June 1stComplex 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.
This system runs claude -p --dangerously-skip-permissions in a background LaunchAgent.
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.
What we don't do: no telemetry, no phone-home, no shell config modification, no job overwriting.
See SECURITY.md for the full threat model.
Cost is a first-class transparent policy. Every Claude session — scheduled jobs, doctor invocations, natural-language commands — derives its sizing from a single formula keyed on a declared complexity scale (0.0–1.0). The formula lives in one inspectable file (lib/sizing.py), the knobs live in one config file (~/.clauck/.clauck.config.json, under doctor), and the math is printable with clauck size <scale>.
Declaring a job's cost — prefer complexity: 0.25 in frontmatter over raw max_turns/max_budget_usd. The scheduler derives the four parameters at fire time. Explicit fields still work as per-field overrides when you need to pin something. clauck inspect <job> shows the resolved values with provenance.
Auto-tuning — clauck doctor tracks a scale_skew offset. On budget truncation it bumps the skew; on clean runs it decays. Self-balancing safety net.
Typical per-run costs at derived sizing:
| Config | Per run (Haiku) | Monthly at hourly |
|---|---|---|
| Minimal (no MCPs, no plugins) | ~$0.04 | ~$29 |
| MCP-using (no plugins) | ~$0.16 | ~$115 |
| Full surface | ~$0.21 | ~$151 |
Budget is per-job. The system never exceeds what you configure.
launchd (60s tick) → scheduler.py
├─ discovers jobs, parses frontmatter, writes manifest
├─ evaluates cron + external triggers + temporal gates
├─ resolves producer/consumer DAGs (cycle detection)
├─ checks for updates (rate-limited)
└─ for matching jobs → run-job.sh (detached)
├─ log created FIRST (preflight failures observable)
├─ acquires lock (concurrency guard)
├─ injects runtime context + producer outputs + oplog
└─ claude -p → log → exit_code tombstone
One LaunchAgent. N jobs. Adding a job is dropping a Markdown file.
The 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.
See CONTRIBUTING.md. Marketplace jobs and user stories are especially welcome.