Chronicle

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.

Features

• 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.

Data Format

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 and Tasks

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

Objects

Define reusable objects to simplify your entries:

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

Special Commands

Date entries help organize your journal chronologically:

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

Example

Chronicle file

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

Text representation

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.

Requirements

• Python 3.12+.

Installation

pip install .

Usage

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

Importing Data

• --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.

Neovim Integration

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.

Available Neovim Task Commands

• :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

Example Usage

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.