Skip to content
Back to search

calends

The settlement day for everything you subscribe to — a self-hosted, AI-native subscription ledger with multi-currency, shared plans, reminders and a built-in MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/imetn/calends with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/imetn/calends'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/imetn--calends/badge.svg)](/listings/imetn--calends)

HTML

<a href="/listings/imetn--calends"><img src="/api/listings/imetn--calends/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

[Try the live demo](https://demo.calends.date) to explore before deploying. It is shared by all visitors and resets daily; external notifications are disabled.

Open Calends at `/` and sign in at `/login`. After signing in, `/` redirects to your configured start page, defaulting to `/overview`. Public sharing is optional: enable it in Settings to make the read-only page available at `/public`. See [routes and login redirects](ARCHITECTURE.md#web-requests-and-state) for details.

Cloudflare Workers

Use [one-click deployment](https://deploy.workers.cloudflare.com/?url=https://github.com/imetn/calends) with Workers and D1, or deploy from source:

git clone https://github.com/imetn/calends
cd calends
npm ci
npx wrangler login
node scripts/wrangler.mjs secret put SETUP_TOKEN
npm run deploy

Use a long random string for `SETUP_TOKEN`. The deploy command builds the app, provisions D1 on first deployment and applies migrations. Open `https://<your-worker>.workers.dev/`, enter the token on the login page and set your password.

Docker

Run the prebuilt image directly:

docker run -d --name calends -p 8787:8787 -v calends-data:/data xizozhe/calends:latest
docker logs calends

Open `http://localhost:8787/` and use the setup token printed in the logs on the login page. The named volume `calends-data` persists SQLite data at `/data`. You can also use `ghcr.io/imetn/calends:latest`. For production, pin a version tag such as `1.8.0` instead of `latest`.

Alternatively, build from source with Compose. From a source checkout, Compose (in `docker/`) builds the included [Dockerfile](docker/Dockerfile) and starts the app:

cd docker
docker compose up -d --build
docker compose logs calends

The [Compose configuration](docker/docker-compose.yml) persists SQLite data in a named volume mounted at `/data`. Building locally does not require a published Calends image or a Cloudflare account. See the [Docker guide](docs/self-hosting.md#using-prebuilt-images) for image registries, upgrades and Compose options.

For public access, enable HTTPS through a reverse proxy and set `TRUST_PROXY=1`. Add a passkey after setup in **Settings → Security**.

See the [self-hosting guide](docs/self-hosting.md) for custom domains, configuration, email reminders, subpath deployment and a prompt to delegate deployment to your AI agent.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 121 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="app/public/icons/logo.svg" width="96" height="96" alt="Calends logo" />
  3. </p>
  4. <h1 align="center">Calends</h1>
  5. <p align="center">
  6. Track subscription charges, shared payments and prepaid balances on your own server.
  7. </p>
  8. <p align="center">
  9. <a href="https://calends.date">Website</a> ·
  10. <a href="https://demo.calends.date">Live demo</a> ·
  11. <a href="#quick-start">Quick start</a> ·
  12. <a href="#ai--mcp">AI &amp; MCP</a> ·
  13. <a href="README.zh-CN.md">简体中文</a>
  14. </p>
  15. <p align="center">
  16. <img src="docs/screenshots/overview.png" alt="Calends overview" width="49%" />
  17. <img src="docs/screenshots/timeline.png" alt="Calends subscription timeline with billing periods, plan changes and payment methods" width="49%" />
  18. </p>
  19. <p align="center"><sub>Overview and subscription timeline · Fictional demo data</sub></p>
  20. ---
  21. ## Billing and payment history
  22. Track what you pay, when it renews, and who owes you. Calends brings subscriptions, shared plans and prepaid balances into one private, single-owner ledger, with an optional read-only public page and AI access through MCP.
  23. - **Flexible billing** — monthly, yearly, custom cycles and lifetime purchases, with optional contract terms and renewal notices independent of billing, trials, intro prices, bonus periods, pauses, postpaid billing, separate bill/payment tracking, advance charging and cancellation deadlines.
  24. - **Usage meters** — track per-period usage or cumulative readings in any unit, with shared meters across subscriptions, usage metrics, aligned charts and usage in charge records.
  25. - **Billing history** — keep price, plan and region changes, gaps and overlapping subscriptions; upgrades can credit the unused part of the old plan. See total spent, actual monthly cost and every charge.
  26. - **Transfers and split payments** — count second-hand takeovers and resales in net cost, and split a charge across multiple payment methods.
  27. - **Multiple currencies** — historical exchange rates for past charges, current rates for forecasts, and your choice of display currency.
  28. - **Balances and shared plans** — track prepaid credit and gift cards, estimate when balances run out, and manage payments for friends. Shared plans have dated collection rules, member overrides, per-period receipts with skipped-period collection, prepayments and waivers, overdue tracking and exit refunds; the member sheet uses a monthly period grid with receipt details on click, prepayments and waivers, while people have private avatars, custom colors and a separate account for each plan.
  29. - **Reports and calendar** — spending trends, a daily heatmap with optional 3D bars, cash vs. accrual, funding flows, region and category profiles, prepaid value, cancellation savings, subscription checkups and a shareable year in review. Includes month/year calendars and a private ICS feed.
  30. - **Search** — find Chinese names by full pinyin, initials or mixed syllables in the subscription list, command palette and pickers.
  31. - **Renewal reminders** — email, Telegram, Lark/Feishu, DingTalk, WeCom, Slack, Discord, Bark, ntfy, ServerChan and custom webhooks.
  32. - **AI access** — query and update your ledger from an MCP-compatible assistant, with scoped tokens and previews for write operations.
  33. - **Import external ledgers** — preview and import CSV files, ZIP backups and databases from Wallos and other services in your browser.
  34. - **Public page editor** — arrange widgets on a grid canvas and customize the header of your read-only public page.
  35. - **Automatic encrypted backups** — back up to S3-compatible storage or WebDAV with passphrase-based encryption, rolling retention and a safety backup before restoring or replacing a ledger.
  36. - **Storage and access** — password and passkey sign-in, remote device sign-out, optional public sharing with server-side masking, JSON backup/restore and CSV import/export. Available in 14 languages, with Australian English regional formatting.
  37. ## Quick start
  38. Want a look first? [Try the live demo](https://demo.calends.date).
  39. ### Cloudflare
  40. [Deploy to Cloudflare](https://deploy.workers.cloudflare.com/?url=https://github.com/imetn/calends), add a long random `SETUP_TOKEN` secret to the Worker, then open its URL, enter the token and set your password. To deploy from source, see the [Cloudflare guide](docs/self-hosting.md#cloudflare-from-source).
  41. ### Docker
  42. ```bash
  43. curl -fsSL https://raw.githubusercontent.com/imetn/calends/main/docker/compose.prebuilt.yml -o compose.yml
  44. docker compose up -d
  45. docker compose logs calends
  46. ```
  47. Open `http://localhost:8787/`, enter the setup token from the logs and set your password.
  48. ### One-line install
  49. On Debian or Ubuntu with systemd:
  50. ```bash
  51. curl -fsSL https://calends.date/install.sh | sudo bash
  52. ```
  53. Calends starts on `127.0.0.1:8787`; point your own reverse proxy at it. Run the same command to upgrade.
  54. For upgrades, HTTPS, configuration and other options, see the [self-hosting guide](docs/self-hosting.md).
  55. ## AI & MCP
  56. Ask “What renews next week?”, “How much did I spend this year?” or “Netflix went up to $17.99 from today.” Calends provides 36 tools over a stateless [MCP](https://modelcontextprotocol.io) endpoint at `/mcp` using Streamable HTTP.
  57. On the **AI access** page (`/connect`), create a read-only or read/write token, then connect your client. Opening `/mcp` in a browser takes you to this page; MCP clients use the `/mcp` endpoint:
  58. **Claude Code**
  59. ```bash
  60. claude mcp add --transport http calends https://your-domain/mcp --header "Authorization: Bearer <token>"
  61. ```
  62. **Codex**
  63. ```bash
  64. export CALENDS_TOKEN='<token>'
  65. codex mcp add calends --url https://your-domain/mcp --bearer-token-env-var CALENDS_TOKEN
  66. ```
  67. Keep `CALENDS_TOKEN` available in the environment that launches Codex. Tools cover subscriptions, spending, trends, receivables and insights, plus changes to prices, plans, status and payments. Every write tool supports `dry_run`; AI access can be turned off in Settings.
  68. ## Privacy
  69. Calends sends anonymous usage statistics once a day to [telemetry.calends.date](https://telemetry.calends.date): a random install ID, the app version, how it runs (Cloudflare, Docker/Node or the installer), the interface language and daily counts of app opens, page views, assistant messages and MCP tool calls. It never sends subscription names, prices, payments, notes, account details or anything you type. The counts are sent by your own server; the browser only reports page views to it.
  70. Turn it off under Settings → Anonymous usage stats, or set `CALENDS_TELEMETRY=0` (or `DO_NOT_TRACK=1`) when deploying, which also locks the setting off. Development builds never send.
  71. ## Contributing
  72. Bug reports, translations and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, checks and contribution guidelines.
  73. Start with the [architecture](ARCHITECTURE.md) and [code standards](docs/code-standards.md) before changing a subsystem. Coding agents use [AGENTS.md](AGENTS.md); `CLAUDE.md` imports the same instructions.
  74. Built with React 19, Vite, HeroUI / React Aria, shadcn/ui and Cloudflare Workers + D1 (SQLite). Billing, exchange rates and other domain logic are shared between the browser and Worker in `shared/`.
  75. Translations live in `shared/locales/<locale>/<namespace>.json`, with English and Simplified Chinese as the source languages.
  76. ## About the name
  77. _Calends_ were the first day of every Roman month, when accounts were settled and debts called in. It is also where the word _calendar_ comes from.
  78. ## License
  79. Calends is open source under the MIT License; see [LICENSE](LICENSE). You may use, modify and redistribute it, including commercially, provided you retain the copyright and license notices in copies or substantial portions of the software. If you fork Calends, please use a distinct name and credit Calends as the upstream source so users can distinguish your version from this project.
  80. The Latin letters and numerals use Xiaomi's [MiSans Latin](https://hyperos.mi.com/font/en/), bundled unmodified in `app/public/fonts/` under the [MiSans license](https://hyperos.mi.com/font/en/download/); it is not covered by the MIT License and may not be modified or redistributed on its own.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.