A local calendar service for development and repeatable tests. Build calendar
integrations without a real Google account, provider credentials, or an external
database.

Status: the documented scope is implemented locally. Includes user/calendar/event management,
Google-compatible event APIs and free/busy, local OAuth, watch notifications,
fixture/reset controls, and masked request history. Compatibility is intentionally
limited; unsupported features return explicit errors. See
compatibility.

https://github.com/user-attachments/assets/11db212a-89c9-4a04-8ff2-9711595e2f98

Quick start

Calendarpit 0.9.5 is available through Docker, Homebrew, and
GitHub Releases.

With Docker:

docker run --rm -p 127.0.0.1:4173:4173 -v calendarpit-data:/data ghcr.io/iktakahiro/calendarpit:0.9.5

Or Homebrew:

brew install iktakahiro/tap/calendarpit
calendarpit serve

Open http://127.0.0.1:4173. The API, local OAuth, and admin UI share one origin.
No Google credentials, environment file, or external database is needed.
See installation for Compose,
standalone downloads, networking, and updates.

Contributor setup, including the docs preview, lives in docs/.

Try a calendar integration

From a source checkout prepared using the development guide,
in another terminal:

bun run sample:dev

Open http://127.0.0.1:4175, connect a calendar, and approve a test user. Create an
event, inspect busy intervals, start a watch, update/delete events, and revoke and
reconnect. The default sample date is October 19, 2026. The admin UI shows
external changes as soon as the server saves them.

The built-in test client is sample-app / local-sample-secret, with callback
http://127.0.0.1:4175/callback. The sample overrides authorization, token, user-info,
Calendar API, and revocation endpoints and blocks real Google requests. See
Connect your app for consuming-app configuration.

Save the JSON example from Fixtures as
calendarpit.fixture.json, then start a temporary session from that directory:

calendarpit serve --database :memory: --config ./calendarpit.fixture.json

Relative fixture paths resolve from the directory where you start the CLI. Loading a fixture replaces
current data; reset always restores the startup fixture and clears credentials,
history and watch state. See Fixtures and Test control API.

Data storage

Homebrew and standalone CLI runs save changes to
.calendarpit/calendarpit.sqlite in the directory where you start Calendarpit.
Run from your project directory, or pass an explicit database path.
The startup log and Settings → Test data → Storage show the actual path.

# Temporary E2E session; no database files are written
calendarpit serve --database :memory: --port 0

# Choose a persistent workspace
calendarpit serve --database ./.calendarpit/manual.sqlite

Existing databases reopen their saved data, connections, tokens, watch channels,
and bounded history. A fixture seeds only a new database; reset restores that
original baseline even after restarting. Loading a fixture replaces current data
without changing the baseline. Each parallel worker must use :memory: or its own
file. See Storage and restarts.

Connect your application

Point your existing Google SDK and OAuth flow at Calendarpit. See the docs for
Local OAuth and
SDK examples in TypeScript/JavaScript, Python, Go, Java,
C#, and HTTP/curl, including calendar lists and FreeBusy queries.

Workspace

apps/
  calendarpit/          React admin UI, TanStack Start, Bun CLI
  docs/                 User documentation site (English and Japanese)
  sample/               Separate Bun app using the official Google SDK
packages/
  server/               Framework-independent API boundary and server logic
  typescript-config/    Shared strict TypeScript settings

Contributor documentation (architecture, testing, development workflow) lives in
docs/.

The UI uses React 19, TanStack Start/Router, Kumo, Tailwind CSS 4, and Gravity
UI Icons. TanStack Form manages the event editor. Bun provides the
runtime, package manager, type checker, test runner, and executable compiler.
Turborepo orchestrates workspace tasks; Oxlint and Oxfmt provide linting and
formatting. Direct dependency versions and bun.lock are pinned.

New dependency resolutions require a minimum release age of 48 hours via
bunfig.toml. npm-check-updates uses the matching two-day cooldown in
.ncurc.json. Existing locked versions are not re-evaluated by this policy.

Contributor commands

These commands require a source checkout and the development setup.

CLI and executable

After installing with Homebrew or placing a standalone executable on your PATH:

calendarpit --help
calendarpit --version
calendarpit serve --port 4173 --database :memory:

Homebrew and standalone downloads run the same embedded executable.
It includes the server, admin UI assets, and Bun runtime. No separate Node.js
or Bun installation is needed. Calendarpit is not distributed through npm.
Releases target macOS arm64/x64, Linux glibc arm64/x64, and Windows x64.
See installation for downloads,
checksums, and upgrades, and Run and configure
for all flags and environment variables.

The default bind address is 127.0.0.1. Use --host explicitly to change it.
CLI flags take precedence over CALENDARPIT_* environment variables. Port 0
requests an available port, which is printed on startup. The admin UI loads
Roboto Mono from Google Fonts with system-font fallbacks; Calendar and OAuth
operations remain local.

Docker Compose

Add this service to your project's compose.yaml:

services:
  calendarpit:
    image: ghcr.io/iktakahiro/calendarpit:0.9.5
    ports:
      - '127.0.0.1:4173:4173'
    volumes:
      - calendarpit-data:/data

volumes:
  calendarpit-data:

docker compose up -d calendarpit
docker compose logs calendarpit
docker compose down

The container binds 0.0.0.0 internally and runs as a non-root user. The host
port stays on loopback. The named volume preserves /data/calendarpit.sqlite;
docker compose down -v deletes it. Use CALENDARPIT_DATABASE=:memory: for
disposable tests. Browsers use http://127.0.0.1:4173; another Compose service
uses http://calendarpit:4173. See installation
for OAuth and webhook networking.

Development conventions

Use English for source, comments, documentation, issues, and commit messages.
Keep protocol behavior independent from UI components and application consumers.
Chronock is the first integration target; it contributes no application-specific
data or logic to Calendarpit. See AGENTS.md for repository guidance.

CI runs protocol/CLI and Google SDK HTTP integration tests. The separate release
workflow builds and tests distribution artifacts, then publishes version tags
to GHCR and GitHub Releases. Homebrew updates require tap credentials.
See Releasing for initial setup and publication status.