A minimalist command-line journaling system for tracking daily activities, metrics, and insights.

Chronicle is a lightweight tool that helps you systematically log and analyze your daily life using simple, human-readable text files. It emphasizes privacy by storing all data locally while maintaining flexibility in how you record and review your information.

• Chronicle uses a simple text format: you can use any text editor with our .chr file format.
• It is privacy-first: all data stored locally on your machine.
• You can track multiple metrics:
  • daily activities and events,
  • health and fitness metrics,
  • tasks and goals,
  • sleep patterns,
  • custom metrics.
• Chronicle allows you to generate insights: analyze patterns and create summaries.
• .chr files have a flexible syntax: intuitive format for quick entries.

Chronicle uses plain text files with the .chr extension. The syntax is designed to be both human-readable and machine-parseable.

Each line in the file is a separate record, that can be an event (or a task), an object definition, a special command, or a comment.

Events are activities that have occurred, while tasks are planned future events.

-- Comments start with `--`.

-- Completed events.
podcast @inner_french e147 00:00/45:00
19:00/19:30 run 5.2km

-- Tasks (prefixed with [ ] or [x]).
[x] do the dishes
[ ] clean @bathroom

-- Future events (prefixed with >>>).
>>> 20:00/ concert @radiohead

Define reusable objects to simplify your entries:

podcast @innerfrench = Inner French Podcast .fr
book @dune = Dune by Frank Herbert

Date entries help organize your journal chronologically:

2024-01-01 -- Sets the current date.

book @dune = Dune by Frank Herbert .en /fiction 896p
podcast @inner_french = Inner French Podcast .fr

2000-01-01

00:00/08:00 sleep
09:00/09:30 run 5.2km

read @dune 120/140p
podcast @inner_french e50 45:00

>>> 20:00/ concert Radiohead

[x] buy milk
[ ] pay for internet 15usd

Objects:

• Book Dune by Frank Herbert, 896 pages, in English, fiction.
• Podcast Inner French Podcast in French.

1 January 2000.

• Events:
  • 00:00—08:00 Sleep.
  • 09:00—09:30 Run 5.2 km.
  • Read Dune from page 120 to 140.
  • Listen to Inner French Podcast episode 50 for 45 minutes.
• Planned:
  • 20:00 Concert Radiohead.
• Tasks:
  • Buy milk.
  • Pay for internet $15.

chronicle --input <files> view [--style <style>] [--colors light|dark|no] <subcommand>

chronicle --input <files> view language \
    [--form table|plot] \
    [--file <output file>] \
    [--period day|week|month|year] \
    [--smooth <days>] \
    [--interval <days>] \
    [--plot-type fill|stack|bar|percent] \
    [--margin <hours>] \
    [--exclude-languages <lang> ...] \
    [--services <service> ...] \
    [--cumulative]

chronicle --input <files> view travel [--svg-output <file>]

chronicle --input <files> view books [--year <year>] [--title <title>] [--finished]

chronicle --input <files> view podcasts [--title <title>]

chronicle --input <files> view sport

chronicle --input <files> view objects

• Python 3.12+.

pip install .

For the most detailed help, run:

chronicle --help

Common usage:

chronicle \
    --input <input Chronicle files> \
    <import options> \
    <command>

Example:

chronicle \
    --input timeline.chr \
    --import-wikimedia User1@en.wikipedia.org User2@wikidata.org \
    --import-memrise memrise.html \
    view language --form table

• --import-memrise: exported Memrise .html files. File can be requested at Memrise settings by "Download Personal Data" button.
• --import-duome: exported Duome .txt files.
• --import-wikimedia: import contributions from Wikimedia projects. Argument format is <username>@<url>, e.g. User1@en.wikipedia.org or User2@wikidata.org.

Chronicle can generate a Vim syntax file for .chr files that highlights event types, object definitions, timestamps, tags, languages, and other values.

Every time chronicle runs it writes a generated syntax file to syntax/chronicle.vim in the repository and, if ~/.vim/syntax/ exists, also to ~/.vim/syntax/chronicle.vim. The generated file is built from the static header syntax/chronicle_header.vim with auto-generated rules for every known event and object type appended.

1. Associate the .chr extension with the chronicle filetype. Add this line to your ~/.vimrc or ~/.config/nvim/init.vim:

   au BufRead,BufNewFile *.chr set filetype=chronicle

2. Copy the pre-generated syntax file into your Vim syntax directory:

   cp syntax/chronicle.vim ~/.vim/syntax/chronicle.vim

   After that, re-running chronicle will keep ~/.vim/syntax/chronicle.vim up to date automatically.

Chronicle provides a Lua script (scripts/chronicle.lua) for Neovim to help manage tasks directly within your .chr files. This script adds convenient commands and key mappings for working with tasks in your journal.

• :ChronicleStart or Space s

  • Changes the event start time to the current time.

• :ChronicleDone or Space d

  • Marks the current task as done (completes the task under the cursor).
  • Changes the event end time to the current time.
  • If the task is recurring (e.g., contains !every_day), it will automatically schedule the next occurrence on the appropriate date.

• :ChroniclePause or Space p

  • Marks the current task as done and creates a new identical task.

These commands are available after sourcing the script in Neovim:

:source <path to Chronicle>/scripts/chronicle.lua

1. Place your cursor on a task line in a .chr file.
2. Press Space d to mark it as done, or Space s to start the task.
3. If the task is recurring, the script will automatically insert the next occurrence on the correct date.