# Lettera


▗▖   ▗▄▄▄▖▗▄▄▄▖▗▄▄▄▖▗▄▄▄▖▗▄▄▖  ▗▄▖ 
▐▌   ▐▌     █    █  ▐▌   ▐▌ ▐▌▐▌ ▐▌
▐▌   ▐▛▀▀▘  █    █  ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌
▐▙▄▄▖▐▙▄▄▖  █    █  ▐▙▄▄▖▐▌ ▐▌▐▌ ▐▌
       

A typewriter-inspired journaling application that enforces forward-only writing to preserve raw thinking.

Named after the Olivetti Lettera series of portable typewriters—functional, beautiful, no-nonsense.

## Philosophy

- **The raw dump is the valuable artifact** — your unfiltered thoughts matter
- **Visible corrections reveal the thinking process** — strikethrough instead of delete
- **Closure is psychological, not enforced** — the ritual marks completion without forcing exit
- **Minimalism removes friction, not capability** — maximum content, minimum chrome

## Features

- **Typewriter mode** — No backspace, no delete. You can move the cursor freely and type over existing text (overtype mode), just like a real typewriter where you can move the carriage back and type over mistakes.
- **Strikethrough** — Move cursor to start position and press `Ctrl+X` to strike the next character through using Unicode combining characters (v̶i̶s̶i̶b̶l̶e̶ ̶i̶n̶ ̶p̶l̶a̶i̶n̶ ̶t̶e̶x̶t̶), one character at a time, until the end of the line.
- **Closure ritual** — Save and quit use distinct fade rituals: save is brief with `Saved`, quit is slower with `Bye`.
- **Manual save** — Press `Ctrl+S` to save your entry (also triggers the save ritual).
- **Archive** — Browse entries grouped by date with `Ctrl+O`; rows use `HH:MM - filename` for fast scanning.
- **Unsaved guards** — `Ctrl+N` and `Ctrl+Q` prompt before clearing or quitting when writing is unsaved.
- **Onboarding help** — First launch shows a shortcuts modal; reopen anytime with `Ctrl+K`.
- **Timestamped entries** — Each session creates a new markdown file (`YYYY-MM-DDTHH-mm-ss.md`).

## Interface Design

- Typewriter metaphor with intentional constraints.
- Start each session on a fresh page.
- Keyboard shortcuts shown in the footer.
- Minimal dark visual style with blue accent highlights.
- Header displays live time plus entry state (draft or locked, saved or unsaved, filename).

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Arrow keys` | Move cursor freely (overtype mode - typing replaces existing text) |
| `Ctrl+X` | Strike through text |
| `Ctrl+S` | Save the current file |
| `Ctrl+N` | New page (new timestamped file) |
| `Ctrl+O` | Open archive |
| `Ctrl+K` | Show shortcuts help |
| `Ctrl+Q` | Quit with closure ritual (fade animation) |
| `Esc` | Return from archive to editor |

Archive navigation note: date headers are non-selectable labels. Arrow keys move between entry rows.

## File I/O

File naming: `YYYY-MM-DDTHH-mm-ss.md` in the configured entries directory.

```
~/.lettera/
  config.json
  entries/
    2025-02-15T19-17-12.md
    2025-02-14T08-42-03.md
```

## Config file

~/.lettera/config.json

```
{
  "entriesDir": "path to entries",
  "helpSeen": true
}
```

## Installation

### Option A — Homebrew (recommended)

```bash
brew tap carlosolmos/lettera
brew install lettera
lettera
```

### Option B — Download the app (macOS, no terminal required)

1. Download `Lettera-<version>.zip` from the [Releases page](https://github.com/carlosolmos/lettera/releases)
2. Unzip and drag `Lettera.app` to `/Applications`
3. Double-click `Lettera.app` — it opens in Terminal automatically

> If `lettera` is not found, the app shows a dialog with the Homebrew install command.

### Option C — pip

```bash
pip install lettera
lettera
```

### From source (development)

```bash
git clone https://github.com/carlosolmos/lettera.git
cd lettera
make setup
make run
```

## Tech Stack

Python 3
Textual https://textual.textualize.io/



