Calgent

Calgent is a terminal-first natural-language Google Calendar CLI.

Type an event in plain English, review the parsed result, and let Calgent create the event in Google Calendar after confirmation.

calgent lunch with damien tomorrow 6pm

Calgent uses Gemini for structured parsing, deterministic Python validation for safety, and the Google Calendar API for event creation.

Features

• Parse natural-language event requests from the terminal.
• Resolve relative dates like tomorrow using the current date, time, and system timezone.
• Ask clarification questions when the request is ambiguous.
• Confirm inferred recurrence before creating recurring events.
• Infer importance and map it to calendar colors.
• Create Google Calendar events through OAuth.
• Support dry runs for parser and workflow testing.

Requirements

• Python 3.12+
• uv for dependency and tool management
• A Gemini API key
• A Google Cloud OAuth desktop client with Google Calendar API enabled

Install For Local Development

Clone the repository:

git clone https://github.com/curtischang2510/calgent.git
cd calgent

Install dependencies:

uv sync --extra dev

Run checks:

uv run pytest
uv run ruff check .

Install the CLI globally with uv tool:

uv tool install --editable . --force

After that, calgent should work from any directory:

calgent --help

Gemini Setup

Create a local environment file:

cp .env.example .env

Edit .env and set:

GEMINI_API_KEY=your_gemini_api_key
CALGENT_MODEL=gemini-2.5-flash-lite
CALGENT_FALLBACK_MODELS=gemini-2.0-flash-lite,gemini-2.0-flash
CALGENT_GEMINI_TIMEOUT_SECONDS=30

Check that the key is present and formatted correctly:

calgent --check-gemini-key

This check does not make an API call.

Google Calendar Setup

1. Open Google Cloud Console.
2. Create or select a project.
3. Enable the Google Calendar API.
4. Configure the OAuth consent screen.
5. If the app is in testing mode, add your Google account as a test user.
6. Create an OAuth client ID.
7. Choose Desktop app as the application type.
8. Download the JSON credentials file.
9. Rename it to credentials.json.
10. Place it in the project root next to pyproject.toml.

credentials.example.json shows the expected shape, but it is not a real credential file.

The first real calendar write opens a browser OAuth flow and creates token.json. Both credentials.json and token.json are ignored by git.

Optional calendar target:

CALGENT_CALENDAR_NAME=primary

By default, Calgent writes to Google Calendar's primary calendar unless CALGENT_CALENDAR_NAME is set.

Usage

Dry run without creating a calendar event:

calgent lunch with damien tomorrow 6pm --dry-run

Create an event after confirmation:

calgent lunch with damien tomorrow 6pm

Skip the confirmation prompt:

calgent lunch with damien tomorrow 6pm --yes

More examples:

calgent CS3210 exam 26th June 2026 3-5pm
calgent anniversary 30th January recurring yearly
calgent anniversary 30th Jan
calgent pay bills on 30th of month

If Gemini infers recurrence that the user did not explicitly request, Calgent asks before accepting that recurrence:

Should this be a monthly recurring event?

How It Works

Calgent separates the workflow into testable harness boundaries:

terminal input -> Gemini parser -> deterministic validation -> clarification/confirmation -> Google Calendar writer

The model does not write to Google Calendar directly. It only returns structured event data. Python then validates the event, applies product rules, asks clarifying questions, and only calls Google Calendar after confirmation.

When a clarification is needed, Calgent keeps an in-memory transcript for the current command. Each Gemini call includes:

• the original request,
• the current date and time,
• the system timezone,
• the previous parsed event,
• and the clarification turns so far.

This keeps the interaction closer to a terminal assistant while still preserving deterministic safety checks around side effects.

Development

Run tests:

uv run pytest

Run lint:

uv run ruff check .

Run formatter:

uv run ruff format .

Refresh the globally installed CLI after dependency or metadata changes:

uv tool install --editable . --force

Security Notes

Never commit these files:

• .env
• credentials.json
• token.json

They are ignored by .gitignore.