guten-morgen

A CLI for Morgen calendar and task management, designed for both humans and LLM agents.

All commands emit structured JSON, making it easy to pipe into scripts, jq, or feed directly to AI coding assistants like Claude Code.

Features

Unified task view — see tasks from Morgen, Linear, and Notion in one place
Calendar groups — filter events by work/personal/family with a single flag
Time-blocking — schedule tasks as calendar events with tasks schedule
Tag lifecycle — model task stages (Active, Waiting-On, Someday) with tags
LLM-friendly output — --json, --response-format concise, --jq, --fields for token-efficient responses
Smart caching — TTL-based cache with cache clear and cache stats
Bearer token auth — auto-detects Morgen desktop app for 5x higher rate limits

Installation

Requires Python 3.10+.

# Run without installing (uv)
uvx guten-morgen --help

# Install globally (uv — recommended)
uv tool install guten-morgen

# Install globally (pipx)
pipx install guten-morgen

# Install into current environment (pip)
pip install guten-morgen

# From source (development)
git clone https://github.com/tenfourty/guten-morgen.git
cd guten-morgen
uv sync --all-extras
uv run pre-commit install

All methods expose both gm (short) and guten-morgen (long) commands.

Setup

Get an API key from Morgen Platform (Settings > API Keys)

Create config (choose one):

# Interactive setup (recommended)
gm init

# Or manually: project-local config
cp config.toml.example guten-morgen.toml
# Edit guten-morgen.toml and add your api_key

Config discovery: $GM_CONFIG → guten-morgen.toml (walks up from CWD) → ~/.config/guten-morgen/config.toml

(Optional) Install Morgen desktop app for 5x higher API rate limits. gm auto-detects the desktop app's auth token and uses it when available. No configuration needed.
Verify it works:
```
gm accounts
gm today --json
```

Quick Start

# What's coming up?
gm next --json --response-format concise

# Full daily overview
gm today --json

# List overdue tasks across all sources
gm tasks list --status open --overdue --json --group-by-source

# Create and time-block a task
gm tasks create --title "Write design doc" --due 2026-02-20 --duration 90
gm tasks schedule <task-id> --start 2026-02-20T10:00:00

# Filter by tag
gm tasks list --tag "Active" --status open --json

Run gm --help for the full command reference.

Calendar Groups

Groups let you filter events by context. Configure in guten-morgen.toml:

default_group = "work"
active_only = true

[groups.work]
accounts = ["you@company.com:google"]
calendars = ["Work Calendar"]

[groups.personal]
accounts = ["you@personal.com:fastmail"]
calendars = ["Personal"]

Use --group personal to switch context, or --group all to see everything.

Global Options

Option	Description
`--format table\|json\|jsonl\|csv`	Output format (default: table)
`--json`	Shortcut for `--format json`
`--fields <list>`	Select specific fields
`--jq <expr>`	jq filtering on output
`--response-format concise`	~1/3 the tokens (great for LLMs)
`--short-ids`	Truncate IDs to 12 chars
`--group NAME`	Filter by calendar group
`--no-cache`	Bypass cache

Development

# Install dev dependencies
uv sync --all-extras
uv run pre-commit install

# Run tests
uv run pytest -x -q --cov

# Type checking
uv run mypy src/

# Lint
uv run ruff check .

Pre-commit hooks enforce ruff, mypy, bandit, pytest (90% coverage minimum), and ggshield secret scanning. To use ggshield, create a free account and set GITGUARDIAN_API_KEY.

Architecture

src/guten_morgen/
  cli.py        Click commands — boundary layer (model -> dict)
  client.py     MorgenClient — typed API wrapper (Pydantic models)
  models.py     Pydantic v2 models
  output.py     Render pipeline (table/json/jsonl/csv + fields + jq)
  errors.py     Exception hierarchy -> structured JSON on stderr
  config.py     XDG config discovery + API settings
  auth.py       Bearer token auth via Morgen desktop app
  time_utils.py Date range helpers
  cache.py      TTL-based request cache
  groups.py     Calendar group filtering from guten-morgen.toml
  retry.py      Rate-limit retry with dual-mode countdown

The boundary rule: client.py returns Pydantic models, cli.py converts with model_dump(), output.py only sees dicts.

Claude Code Integration

This project includes a CLAUDE.md with conventions and a .claude/ directory with hooks and skills for use with Claude Code. These are optional — the CLI works without them.

The .claude/skills/gm/ skill is portable. To use gm from any Claude Code session — not just this repo — symlink it into your user skills directory so it stays in sync on git pull:

mkdir -p ~/.claude/skills && ln -s "$(pwd)/.claude/skills/gm" ~/.claude/skills/gm

It documents the confirmation rule, timezone gotchas, and invocation recipes — deferring to gm --help for the command surface.

License

Apache 2.0

Metadata

Release files for guten-morgen 0.24.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for guten-morgen 0.24.0
File	Size	Uploaded
guten_morgen-0.24.0.tar.gz	326.6 kB	Jun 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for guten-morgen 0.24.0
File	Interpreter	ABI	Platform	Reset
guten_morgen-0.24.0-py3-none-any.whl 68.2 kB Jun 13, 2026	Python 3	none	any	Details

Total release size: 394.8 kB

Release files / guten_morgen-0.24.0.tar.gz

Download URL	guten_morgen-0.24.0.tar.gz
Size	326.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`8afe0c3dee9c9c6a97848de1ac36e382884155172add71f18d78ab9b5602235f`
BLAKE2b-256 checksum How to use checksums	`3a4608f6902879aee188699d24a44218de0c3b01b3ef5a571958aa5d931cbeb3`
Upload date	Jun 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/tenfourty/guten-morgen
Publishing commit: github.com/tenfourty/guten-morgen/tree/11926260bcca0f4c77a820826ab73597fb0f2d34

Workflow

Publishing configuration: github.com/tenfourty/guten-morgen/blob/11926260bcca0f4c77a820826ab73597fb0f2d34/.github/workflows/release.yml
Publishing logs: github.com/tenfourty/guten-morgen/actions/runs/27450579554/attempts/1

Artifact

Subject: guten_morgen-0.24.0.tar.gz
SHA-256 checksum: 8afe0c3dee9c9c6a97848de1ac36e382884155172add71f18d78ab9b5602235f Verifying attestations

Release files / guten_morgen-0.24.0-py3-none-any.whl

Download URL	guten_morgen-0.24.0-py3-none-any.whl
Size	68.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`046576c312026bb25e2b9ba5e5e454f4262dfa409b4e9c74d3e46867a5751548`
BLAKE2b-256 checksum How to use checksums	`dc9dfb02c4a974a623be66f0f782fee0651216afa02b11c5f76a587ed6a91539`
Upload date	Jun 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/tenfourty/guten-morgen
Publishing commit: github.com/tenfourty/guten-morgen/tree/11926260bcca0f4c77a820826ab73597fb0f2d34

Workflow

Publishing configuration: github.com/tenfourty/guten-morgen/blob/11926260bcca0f4c77a820826ab73597fb0f2d34/.github/workflows/release.yml
Publishing logs: github.com/tenfourty/guten-morgen/actions/runs/27450579554/attempts/1

Artifact

Subject: guten_morgen-0.24.0-py3-none-any.whl
SHA-256 checksum: 046576c312026bb25e2b9ba5e5e454f4262dfa409b4e9c74d3e46867a5751548 Verifying attestations