cadence

Your daily rhythm, tracked.

A Telegram bot + structured markdown system for tracking goals, daily habits, and progress. Works standalone or supercharged with Claude Code AI.

Zero dependencies. One Python file. Clone and run.

---

Why cadence?

Most productivity systems fail because they live in apps you forget to open. cadence lives in Telegram — the app already on your phone. It nudges you every morning and evening, tracks your replies, and writes everything to plain markdown files you own forever.

Two modes:

• Personal — financial goals, side hustles, habit tracking, debt payoff
• Work — sprint goals, standups, project tracking, OKRs

Two levels:

• Human-only — Telegram bot + markdown files. No AI, no magic, just discipline.
• AI-enhanced — Add Claude Code for intelligent reviews, auto-planning, and goal coaching.

---

Features

• Morning briefing — priorities, metrics, day type, daily reminder
• Evening check-in — auto-detects progress from the day, asks what's missing
• Weekly review — prompts you to score priorities, set next week's 3
• Reply parsing — type spent 500 food or done task 1 and it updates your tracker
• Daily logs — auto-generated logs/YYYY-MM-DD.md files
• Goal hierarchy — annual → quarterly → monthly → weekly → daily
• 3-priority rule — never more than 3 weekly priorities. Focus wins.
• Cross-platform scheduling — Linux (cron), macOS (launchd), Windows (Task Scheduler)
• Claude Code integration — optional AI that reads your goals and helps plan

---

Quick Start

git clone https://github.com/YOUR_USERNAME/cadence.git
cd cadence
python3 setup.py              # Interactive wizard (30 seconds)
python3 cadence.py test       # Sends test message to your Telegram

Then start the listener:

python3 cadence.py listen     # Receives and responds to your messages

Install automatic scheduling:

python3 setup.py install-scheduler   # Detects your OS, sets up cron/launchd/Task Scheduler

Prerequisites

• Python 3.8+ (no pip install needed — stdlib only)
• Telegram account + a bot from @BotFather (setup guide)

---

Architecture

┌──────────────┐     ┌────────────────┐     ┌──────────────────┐
│   Telegram    │◄───►│   cadence.py   │◄───►│  Markdown Files  │
│   (You)       │     │   (Bot)        │     │  GOALS.md        │
└──────────────┘     └────────────────┘     │  CURRENT_TASKS.md│
                                             │  logs/YYYY-MM-DD │
┌──────────────┐                             │  SCHEDULE.md     │
│  Claude Code  │◄──────────────────────────►│  CLAUDE.md       │
│  (Optional)   │     reads/writes           └──────────────────┘
└──────────────┘     same files

No API coupling. The bot and Claude Code share state through markdown files. They never call each other. This means:

• The bot works perfectly without Claude Code
• Claude Code works perfectly without the bot
• Together, they create a loop: bot nudges you → you update → Claude reads updates → Claude helps plan → bot tracks the plan

---

How It Works

Morning (automatic, via scheduler)

☀️ MORNING BRIEFING — Tuesday, 17 Mar 2026

🎯 Day Type: DEEP WORK
Deep work session

📊 Metrics
• Income Target: $18,000/month
• Debt Total: $10,000

📋 This Week's Priorities
1. 🔲 Ship the auth module
2. 🔄 Write 3 blog posts
3. 🔲 Review PR backlog

📝 Don't forget: 1 blog post today!

Reply with updates anytime.

You reply naturally

spent 200 groceries, 50 coffee
done auth module
worked on PR review

Bot parses and logs

💸 Recorded: 200 groceries, 50 coffee = 250
✅ Marked done: Ship the auth module
📝 Work logged

Evening (automatic)

🌙 END OF DAY — Tuesday

💸 Spent today:
  • Spending: 200 groceries, 50 coffee (total: 250)

✅ Work done:
  • Work: worked on PR review

👆 That's what I have so far.
Anything to add or correct?

---

Configuration

All configuration lives in config.json (generated by setup.py). See config.example.json for all options.

Key sections:

Section	What it controls
user	Name, timezone
mode	"personal" or "work"
schedule	Morning/evening times, day types
goals	Primary goal, income target, debt, custom metrics
tracking	Reply parsing categories + custom fields
claude	Enable/disable Claude Code integration
messages	Customize greetings, reminders

Custom tracking fields

Add your own trackable fields in config.json:

"custom_fields": [
  {
    "name": "bank_savings",
    "pattern": "savings\\s+(\\d+)",
    "label": "Savings Balance"
  }
]

Now savings 50000 in Telegram gets parsed and logged automatically.

---

Commands

Command	What it does
python3 cadence.py morning	Send morning briefing
python3 cadence.py evening	Send evening check-in
python3 cadence.py weekly	Send weekly review
python3 cadence.py status	Send instant status
python3 cadence.py listen	Start reply listener (daemon)
python3 cadence.py test	Send test message

Telegram commands (when listener is running)

Command	Response
/status	Current status snapshot
/morning	Morning briefing (on-demand)
/evening	Evening check-in (on-demand)
/weekly	Weekly review (on-demand)

Reply syntax

You type	Bot does
spent 200 food	Logs spending, totals amount
earned 500 freelance	Logs income
done deploy feature	Marks task done in CURRENT_TASKS.md
worked on API refactor	Logs work entry
blocker: CI is broken	Logs blocker
skip	Logs "no update" for the day

---

Claude Code Integration (Optional)

If you enabled Claude Code during setup, cadence generates:

• CLAUDE.md — instructions that Claude reads at every session start
• .mcp.json — registers a datetime MCP server so Claude knows the current date/time

What Claude Code does with cadence:

1. Reads GOALS.md at session start → knows your priorities
2. Reads CURRENT_TASKS.md → knows what's blocked or in progress
3. Reads logs/ → knows what you did today
4. Helps plan, unblock, and review your week

Install the MCP server:

python3 mcp/install_mcp.py

See Claude Code Setup Guide for details.

---

Cross-Platform Scheduling

Linux (cron)

bash schedulers/install_cron.sh

macOS (launchd)

bash schedulers/install_launchd.sh

Windows (Task Scheduler)

python3 schedulers/install_task_scheduler.py

Or let the setup wizard handle it:

python3 setup.py install-scheduler

---

File Structure

After setup, your directory looks like:

your-project/
├── cadence.py              # The bot (don't need to edit this)
├── config.json             # Your configuration (edit anytime)
├── .env                    # Bot token (secret, gitignored)
├── GOALS.md                # Your goals (edit weekly)
├── CURRENT_TASKS.md        # Your tasks (edit daily)
├── WEEKLY_SCHEDULE.md      # Your schedule (edit monthly)
├── CLAUDE.md               # Claude Code instructions (if enabled)
├── logs/
│   ├── 2026-03-17.md       # Auto-generated daily logs
│   ├── 2026-03-18.md
│   └── ...
├── setup.py                # Re-run anytime to reconfigure
├── mcp/                    # Claude Code MCP server
├── schedulers/             # OS-specific scheduler installers
├── templates/              # Mode templates (reference)
└── docs/                   # Guides

---

Comparison

Feature	cadence	Obsidian Life OS	Telegram habit bots	Plain journaling
Mobile-first (Telegram)	Yes	No (desktop app)	Yes	No
Goal hierarchy (year→week)	Yes	Yes	No	Manual
Auto daily logs	Yes	Plugin needed	No	Manual
Reply parsing	Yes	No	Basic	No
AI integration	Claude Code	Plugin	No	No
Dependencies	None (stdlib)	Obsidian + plugins	Varies	None
Data ownership	Markdown files	Markdown files	Cloud DB	Markdown/paper
Cross-platform scheduler	Yes	No	N/A	No
Setup time	30 seconds	Hours	Minutes	N/A

---

Contributing

We welcome contributions from everyone! Whether it's a bug fix, new feature, documentation improvement, or just a suggestion — every contribution matters.

Ways to contribute:

• Bug reports — found something broken? Open an issue
• Feature requests — have an idea? Start a discussion
• Code contributions — fork, branch, code, PR. See CONTRIBUTING.md for guidelines.
• Documentation — typos, better examples, translations — all welcome
• Share your setup — using cadence? Show us your config in Discussions

Please read our Contributing Guide and Code of Conduct before submitting.

---

Cloud Deployment

Run cadence 24/7 — even when your laptop is off.

• Google Cloud Free Tier — free forever e2-micro VM, easy signup (recommended)
• Oracle Cloud Free Tier — free forever ARM VM (4 CPU, 24 GB RAM) — but signup can be difficult
• Docker — run anywhere with docker compose up -d

Note: Oracle Cloud often rejects signups due to card type, address mismatch, or region demand. If you can't create an Oracle account, Google Cloud's Always Free e2-micro instance is a reliable alternative with a smoother signup process.

# Cloud VM (Google Cloud or Oracle Cloud)
bash schedulers/install_systemd.sh

# Docker
docker compose up -d

---

Plugins

Add custom /commands by dropping .py files in commands/:

# commands/weather.py
def register():
    return {"/weather": handle_weather}

def handle_weather(text, config):
    return "Weather plugin not configured."

The bot auto-discovers plugins at startup. See commands/example.py.

---

Tracking Modules

Enable optional tracking modules in config.json:

"modules": {
  "finance": { "enabled": true },
  "habits":  { "enabled": true, "habits": ["exercise", "reading"] },
  "health":  { "enabled": true, "fields": ["weight", "food"] }
}

• Finance — bank-aware spending (spent 500 from SAVINGS on rent), auto-deduct from tracked accounts
• Habits — streak tracking (exercise → "Exercise logged! Streak: 5")
• Health — field logging (weight 72.5 → logged with timestamp)

See docs/CUSTOMIZATION.md for details.

---

Roadmap

• Plugin system for custom commands
• Tracking modules (finance, habits, health)
• Bank-aware spending with balance tracking
• Cloud deployment (Oracle Cloud Free Tier)
• Docker support
• systemd service installer
• Cross-platform PID check (Windows/macOS/Linux)
• Quarterly and yearly review prompts
• Multi-user support (team mode with shared goals)
• Telegram inline keyboard for quick replies
• Dashboard web UI (optional)
• Notion/Obsidian sync
• i18n (multi-language messages)

Have an idea? Open a feature request.

---

License

MIT — use it, fork it, build on it.

---

Built with discipline, prompt engineered with Claude Code and Telegram.