ritual

README

Ritual

A terminal-based journaling app for daily startup and shutdown reflection rituals.

STARTUP RITUAL
● ○ ○ ○ ○ ○ ○ ○

What kind of day is this?

> Deep work
  Meetings
  Mixed
  Recovery

↑/↓ select  •  enter confirm  •  esc back

┌─────────────────────────┬────────────────────────────────────────┐
│      January 2026       │                                        │
│                         │  Jan 10  ☀ Startup    Energy: 7        │
│  Su  Mo  Tu  We  Th  Fr │          ☽ Shutdown   Stress: 4        │
│               1   2   3 │                                        │
│   4   5   6   7   8   9 │  Jan 9   ☀ Startup    Energy: 8        │
│ [10] 11  12  13  14  15 │                                        │
│  ...                    │  Jan 8   ☀ Startup    Energy: 6        │
│                         │          ☽ Shutdown   Stress: 5        │
│                         │                                        │
└─────────────────────────┴────────────────────────────────────────┘
tab switch  •  ↑/↓ navigate  •  enter open  •  q quit

About

Ritual helps developers maintain consistent morning startup and evening shutdown routines directly from the terminal. Answer structured reflection questions, build streaks, and track your daily intentions—all without leaving your workflow.

Key Features:

• Startup and shutdown rituals with research-backed questions
• Full (~5-7 min) and quick (~1-2 min) modes
• Streak tracking with milestone celebrations (7, 30, 100, 365 days)
• Keyboard-driven interface
• Local JSON storage (~/.ritual/entries/)
• Huh-style visual polish

Installation

Download Binary (Recommended)

Download the latest release for your platform from GitHub Releases.

macOS (Apple Silicon):

# Download from GitHub Releases page, then:
tar xzf ritual_*_darwin_arm64.tar.gz
sudo mv ritual /usr/local/bin/

macOS (Intel):

# Download from GitHub Releases page, then:
tar xzf ritual_*_darwin_amd64.tar.gz
sudo mv ritual /usr/local/bin/

Linux (x86_64):

# Download from GitHub Releases page, then:
tar xzf ritual_*_linux_amd64.tar.gz
sudo mv ritual /usr/local/bin/

From Source

Requires Go 1.24+:

go install github.com/johnoct/ritual/cmd/ritual@latest

Verify Installation

ritual version

Usage

# Morning startup ritual
ritual start

# Evening shutdown ritual
ritual end

# Auto-detect based on time of day (before noon = startup, after = shutdown)
ritual auto

# Browse past entries
ritual log

# View weekly summary
ritual summary

# Quick mode (3 questions)
ritual start -q
ritual end -q
ritual auto -q

Commands

Command	Alias	Description
ritual start	s	Morning startup ritual
ritual end	e	Evening shutdown ritual
ritual auto	a	Auto-detect mode based on time of day
ritual log	l	Browse past entries
ritual summary	w	Weekly summary with wins, learnings, and trends
ritual config init	-	Create config file with defaults

Configuration

Ritual can be customized via ~/.ritual/config.yaml. Generate a default config:

ritual config init

Options

# Where entries are stored
storage:
  directory: ~/.ritual/entries

# Default modes (full or quick)
defaults:
  startup: full
  shutdown: full

# Auto-detection settings
auto:
  cutoff_hour: 12  # Hour (0-23) separating startup from shutdown

The -q flag always overrides the config default.

Keybindings

Ritual Mode:

Key	Action
Tab / Enter	Next question
Shift+Tab / Esc	Previous question
↑ / ↓	Navigate select options
← / →	Adjust rating value
Ctrl+S	Save and exit
Ctrl+C	Quit without saving

Log Browser:

Key	Action
Tab	Switch between calendar and list
↑ / ↓ / ← / →	Navigate calendar or list
Page Up / Page Down	Change month
Enter	Open entry full-screen
s	Open weekly summary
Esc	Return to split view
q	Quit log browser

Weekly Summary:

Key	Action
e	Edit/add reflection
Enter	Save reflection
Esc	Cancel editing / Return to log browser
q	Quit

The Questions

Ritual's questions are designed around research from Cal Newport (Deep Work), Carol Dweck (Growth Mindset), Anders Ericsson (Deliberate Practice), and others.

Startup Ritual

1. What kind of day is this? (Deep work / Meetings / Mixed / Recovery)
2. Energy level right now? (1-10)
3. If today went well, what would be true?
4. What are the 1-2 outcomes that matter most?
5. What is the very first concrete action?
6. What new approach or strategy will I try today?
7. What one thing am I deliberately practicing?
8. What tells me it's time to start?

Shutdown Ritual

1. What must I remember for tomorrow so I can let go?
2. What is one small win from today?
3. What did I learn or see more clearly?
4. What worked? What didn't?
5. Where did I choose effort over comfort?
6. What's one small adjustment for tomorrow?
7. Stress level now? (1-10)
8. What tells my brain work is done?

Data Storage

Entries are stored locally as JSON:

~/.ritual/
└── entries/
    ├── 2026-01-07.json
    ├── 2026-01-08.json
    └── ...

Each day can contain multiple entries (startup + shutdown).

Development

Project Status

• Basic TUI shell with navigation
• Startup/shutdown flows (8 questions each)
• JSON storage layer
• Huh-style visual polish
• Dot-based progress indicator
• Log browsing (ritual log)
• Quick/emergency modes
• Time-based auto-detection (ritual auto)
• Streak tracking
• Weekly summaries (ritual summary)

Building

go build -o ritual ./cmd/ritual

Testing

go test ./...
go vet ./...
golint ./...

Project Structure

ritual/
├── cmd/ritual/          # CLI entry point
├── internal/
│   ├── tui/             # Bubble Tea components
│   │   ├── app.go       # Main ritual model
│   │   ├── log.go       # Log browser
│   │   ├── calendar.go  # Calendar component
│   │   ├── entrylist.go # Entry list component
│   │   ├── entryview.go # Entry viewer
│   │   ├── summary.go   # Weekly summary view
│   │   └── styles.go    # Lip Gloss styles
│   ├── ritual/          # Question definitions
│   ├── storage/         # JSON persistence
│   ├── streak/          # Streak calculation
│   ├── summary/         # Weekly summary computation
│   └── config/          # Configuration loading
├── docs/plans/          # Design documents
├── PRD.md               # Product specification
└── README.md

Roadmap

• Phase 1 (Complete): Basic startup/shutdown rituals with JSON storage
• Phase 2 (Complete): Quick mode, styling, log browsing, auto-detection, streak tracking, weekly summaries
• Phase 3 (In Progress): Configuration (complete), export (planned)
• Future: Git commit integration, custom questions, sync

Built With

• Bubble Tea - TUI framework
• Lip Gloss - Styling
• Cobra - CLI framework
• Viper - Configuration

License

MIT