:timer_clock: Comodoro

CLI to manage timers

One server owns a timer, any number of clients drive it and watch it. This project is composed of 3 feature-gated layers:

• Low-level contract: the pure timer state machine and the JSON-RPC 2.0 method surface, no_std-compatible and free of any I/O
• Mid-level client and server: a blocking client over one connection, and a server owning the timer behind the listeners it binds
• High-level CLI: the client and the server behind a flat command grammar, a TOML configuration and per-event hooks

Table of contents

• Features
• Installation
• Configuration
• Usage
• AI policy
• License
• Social
• Contributing
• Sponsoring

Features

• Shared timer: one server owns it, any number of clients drive it.
• Push notifications: comodoro watch subscribes, the server pushes, nothing polls.
• Local socket and TCP: either transport, or both at once.
• Standard protocol: plain JSON-RPC 2.0, drivable from any language.
• Pomodoro-style cycles: any named durations, looping forever or a fixed number of times.
• Per-event hooks: a shell command, a desktop notification or both on any timer event, given the cycle name and its remaining time as variables.
• Status-bar friendly: second, minute or hour precision, plus --json for scripts, its schema given by comodoro json-schema.
• Session: comodoro repl answers commands over stdin, one per line.
• MCP server: an agent reads the timer through comodoro mcp, and drives it with --allow-write.

[!TIP] Comodoro is written in Rust and uses cargo features to gate its layers. The default feature set is declared in Cargo.toml.

Installation

Pre-built binary

Comodoro can be installed with the install.sh installer:

As root:

curl -sSL https://raw.githubusercontent.com/pimalaya/comodoro/master/install.sh | sudo sh

As a regular user:

curl -sSL https://raw.githubusercontent.com/pimalaya/comodoro/master/install.sh | PREFIX=~/.local sh

These commands install the latest binary from the GitHub releases section.

For a more up-to-date version than the latest release, check out the releases GitHub workflow and look for the Artifacts section. These pre-built binaries are built from the master branch.

[!NOTE] Such binaries are built with the default cargo features. If you need specific features, please use another installation method.

Cargo

cargo install comodoro --locked

For a more up-to-date version than the latest release:

cargo install --locked --git https://github.com/pimalaya/comodoro.git

Without desktop notifications, which drops the D-Bus system dependency:

cargo install comodoro --locked \
  --no-default-features \
  --features cli

Nix

If you have the Flakes feature enabled:

nix profile install github:pimalaya/comodoro

Or run without installing:

nix run github:pimalaya/comodoro

Sources

git clone https://github.com/pimalaya/comodoro
cd comodoro
nix run

Configuration

Comodoro writes no configuration: start from config.sample.toml, which the first-run welcome copies from share/doc/comodoro/ when the package ships it, uncomment one of its cycle presets (Pomodoro, 52/17 or 112/26), then the options you need.

A configuration is loaded from every existing path among $XDG_CONFIG_HOME/comodoro/config.toml, $HOME/.config/comodoro/config.toml and $HOME/.comodororc, each deep-merged on top of the ones before. -c <PATH> replaces them, repeated once per file: the first is the base and the next ones merge on top. Run without a configuration, Comodoro prints the commands creating one from the sample.

An account only needs its cycles. Everything else defaults: a socket under $XDG_RUNTIME_DIR, TCP on loopback port 9999, an endless loop, a precision of one minute.

Which transport a server binds is what comodoro server start [TRANSPORTS] says, and which one a client talks over is what socket.default or tcp.default says. The TCP listener is unauthenticated, so keep it on loopback unless you mean otherwise.

Usage

Start the server, which owns the timer and stays in the foreground:

comodoro server start

Then drive the timer from anywhere:

comodoro start
comodoro get
comodoro pause
comodoro resume
comodoro set 300
comodoro stop

Feed a status bar without polling, which prints the timer once and then on every change until interrupted:

comodoro watch

Every command prints the timer, the controls as it is after their change. With --json it prints the timer object instead, watch --json one object per line as each change happens:

comodoro watch --json | jq -r --unbuffered '"\(.cycle.name) \(.cycle.duration)s"'

Every command takes an optional transport, socket or tcp, and falls back to the one the configuration marks as default. The server takes the list of transports to bind, and binds the default one when given none:

comodoro server start socket tcp
comodoro get tcp

Every command and every flag is documented behind --help. The library API is documented on docs.rs, and complete runnable programs live in ./examples.

Logs go to stderr, so they can be redirected to a file while the command output stays on stdout:

comodoro server start --log-level debug 2>/tmp/comodoro.log

Use --log-file <PATH> to append them to a file directly. When --log-level is omitted the RUST_LOG environment variable is consulted, and RUST_BACKTRACE=1 adds the full error backtrace.

REPL

comodoro repl holds one account and answers commands, one per line, until exit or EOF. Each line connects to the server on its own:

$ comodoro repl
comodoro> start
comodoro> set 300
comodoro> get
comodoro> exit

Non-interactively, a program spawns comodoro repl --json and talks to it over stdio: it writes one command per line on stdin and reads one JSON value per line on stdout, failures included. watch and server start run until interrupted, so they are refused inside a session.

MCP

comodoro mcp also talks over stdio, but speaks the Model Context Protocol so an agent can read the timer with the get tool. The controls (start, pause, resume, set and stop) need --allow-write. The timer still belongs to a comodoro server start process.

MCP clients start the servers declared in their configuration, most of them under an mcpServers object:

{
  "mcpServers": {
    "comodoro": {
      "command": "comodoro",
      "args": ["mcp", "--allow-write"]
    }
  }
}

License

This project is licensed under either of:

• MIT license
• Apache License, Version 2.0

Social

• Chat on Matrix
• News on Mastodon or RSS
• Mail at [email protected]

Sponsoring

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

• 2022 → 2023: NGI Assure
• 2023 → 2024: NGI Zero Entrust
• 2024 → 2026: NGI Zero Core
• 2026 → 2027: NGI Zero Commons Fund

This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider sponsoring its development: