@ofrusch/cadence

A velocity-aware daily-planner MCP server for Claude. Learns how much you actually get done in a day, so it can plan smarter ones over time.

Cadence lives inside Claude Desktop and Claude Code. It tracks today's plan, prior-day carryovers, and possibly-forgotten completions; learns patterns about how you work (which categories you finish, which sources of work tend to slip, where your estimates drift); and quietly surfaces what's useful when it's useful. The agent is the UI.

Install

Requires Node 20+ and either Claude Code or Claude Desktop.

curl -fsSL https://raw.githubusercontent.com/jebbit/cadence/main/install.sh | bash

That registers Cadence with whichever Claude clients you have installed, drops the slash commands into ~/.claude/commands/, and injects the proactive-behavior snippet into ~/.claude/CLAUDE.md. Restart Claude (Cmd+Q, then reopen). In any new session, type /cadence-plan-today to start.

To verify everything's wired up, run:

npx -y -p @ofrusch/cadence cadence-mcp doctor

Manual install

If you'd rather not pipe a script to bash:

# Claude Code:
claude mcp add cadence --scope user -- npx -y @ofrusch/cadence

# Claude Desktop:
npx -y -p @ofrusch/cadence cadence-mcp install-desktop

# Slash commands + CLAUDE.md snippet:
npx -y -p @ofrusch/cadence cadence-mcp install-skill

Slash commands

| Command | What it does | |---|---| | /cadence-plan-today | Interactive start-of-day flow. Surfaces forgotten check-offs, carryovers, and live external suggestions. | | /cadence-checkin | 3-line progress summary with a pace heuristic. | | /cadence-checkoff <task> | Mark a planned task done by fuzzy match. | | /cadence-wrap-up | End-of-day reflection. Runs the pattern extractor. | | /cadence-setup | Check which external integrations are wired up and walk through fixing any that aren't. |

External integrations

GitHub (gh CLI)

Cadence reads review requests via the GitHub CLI. Install gh and run gh auth login. If unavailable, the agent will mention it once and continue.

Jira (REST + API token)

Two options. Run /cadence-setup in any Claude session and it'll walk you through whichever you pick.

Recommended — env vars. The token never goes through your Claude transcript. Add to your shell rc:

export CADENCE_JIRA_BASE_URL="https://your-org.atlassian.net"
export CADENCE_JIRA_EMAIL="[email protected]"
export CADENCE_JIRA_TOKEN="<token from https://id.atlassian.com/manage-profile/security/api-tokens>"

Restart your shell, then run /cadence-setup to verify.

Conversational — paste in chat. /cadence-setup prompts for site URL, email, and an API token from id.atlassian.com, then writes them to ~/.cadence/config.json (mode 0600). Faster but the token lands in your Claude transcript.

Env vars take precedence over the config file, field by field.

Slack / Gmail / Calendar — compose with their MCPs

Cadence doesn't ship Slack, Gmail, or Calendar integrations directly. Install the relevant MCP server alongside Cadence:

claude mcp add slack  --scope user -- npx -y @modelcontextprotocol/server-slack
claude mcp add gmail  --scope user -- npx -y @modelcontextprotocol/server-gmail
# (substitute any Google MCP you prefer — Cadence doesn't care which)

When any of these are loaded, Claude does two things:

1. Adds new items as tasks. Slack followups, calendar prep, emails you owe replies to — the agent surfaces them and calls cadence_add_task with the right source.
2. Cross-references existing tasks. After cadence_start_day, the agent pulls recent items from the connected MCPs and links any that plausibly mention today's planned tasks via cadence_record_cross_reference. The user sees a single summary ("'finish OIDC migration' came up in 2 emails and your 2pm meeting").

Cadence also acts proactively (via the injected CLAUDE.md snippet): it greets you on first message of a session if you have unresolved tasks, offers to check things off when you mention finishing work, and nudges you toward /cadence-wrap-up when you signal you're logging off.

Tools

The MCP server exposes 22 cadence_* tools. Highlights:

• cadence_start_day — idempotent per local day. Returns carried_over, forgotten_check_offs, external_suggestions, top patterns, a yesterday summary, and unconfigured_sources.
• cadence_end_day — runs the pattern extractor; returns new_patterns_recorded.
• CRUD: add_task, check_off, carry_over, confirm_carried, confirm_completed, drop_task, update_task.
• Queries: get_today, get_progress, get_velocity, search_tasks.
• External (live): get_jira_assigned (REST), get_github_review_requests (gh CLI). Both return { configured, missing, items }.
• Setup: cadence_status, cadence_set_jira_credentials, cadence_clear_jira_credentials — drive the /cadence-setup conversational flow.
• Cross-reference: cadence_record_cross_reference, cadence_get_cross_references — let the agent link Gmail/Calendar/Slack items to planned tasks when those MCPs are loaded.
• Patterns: record_pattern, get_patterns.

Full tool reference and schemas: https://github.com/jebbit/cadence#tool-reference.

How the learning loop works

Every meaningful event becomes a signal in task_signals — estimates, completions, carries (with reasons), procrastination markers. end_day runs a rule-based extractor over the last 14 days:

• Category completion rate. ≥80% finished → velocity pattern; ≤30% → procrastination.
• Source carry rate. ≥50% of tasks from a source carried at least once → procrastination.
• Size drift. Mean size_actual differs from size_estimate by ≥0.5 buckets → estimate_bias.

Patterns supersede earlier same-key ones rather than accumulating. start_day surfaces the top 5 to the agent so the next plan is informed.

Configuration

Cadence keeps state in two files under ~/.cadence/:

| Path | What | |---|---| | ~/.cadence/cadence.db | SQLite database — tasks, patterns, signals. | | ~/.cadence/config.json | Persistent integration credentials (Jira). Mode 0600. Written by cadence_set_jira_credentials. |

Env vars (all optional):

| Env var | Default | What | |---|---|---| | CADENCE_DB_PATH | ~/.cadence/cadence.db | Override the SQLite path. | | CADENCE_CONFIG_PATH | ~/.cadence/config.json | Override the config-file path. | | CADENCE_TZ | system timezone | IANA timezone for "today" semantics. | | CADENCE_JIRA_BASE_URL | (from config.json) | Override the Atlassian site URL. | | CADENCE_JIRA_EMAIL | (from config.json) | Override the Atlassian email. | | CADENCE_JIRA_TOKEN | (from config.json) | Override the Jira API token. | | CADENCE_DISABLE_GH | unset | Set to 1 to suppress the gh subprocess. |

Env vars take precedence over the config file, field-by-field.

Privacy

Everything is local. The MCP server runs as a child process of your Claude client over stdio — there's no network traffic, no remote storage, no telemetry. Anthropic sees the tool calls and results just like any other MCP tool use; nothing else leaves your machine.

CLI

cadence-mcp                     Run the MCP server over stdio (default).
cadence-mcp serve               Same as above.
cadence-mcp install-skill       Install slash commands + inject CLAUDE.md snippet.
cadence-mcp install-desktop     Register the server in Claude Desktop's config.
cadence-mcp uninstall-desktop   Remove the Claude Desktop registration.
cadence-mcp doctor              Print a multi-section diagnostic report.
cadence-mcp help                Show usage.

Uninstall

claude mcp remove --scope user cadence
rm ~/.claude/commands/cadence-{plan-today,checkin,checkoff,wrap-up,setup}.md
# Then manually remove the <!-- BEGIN cadence --> block from ~/.claude/CLAUDE.md
# Optionally drop the database + config:
rm -rf ~/.cadence

Links

• Source & issues: https://github.com/jebbit/cadence
• Changelog: https://github.com/jebbit/cadence/blob/main/CHANGELOG.md

License

MIT — see LICENSE.