jernel

jernel

A journal for your machine's soul. jernel gives your computer a voice by translating system metrics into personal journal entries using LLMs.

Installation

Quick install (macOS arm64, Linux amd64):

curl -sSL https://raw.githubusercontent.com/cldixon/jernel/main/install.sh | sh

Or download a binary directly from Releases.

Or install with Go:

go install github.com/cldixon/jernel@latest

Or build from source:

git clone https://github.com/cldixon/jernel.git
cd jernel
go build -o jernel .

Check your installed version:

jernel --version

Configuration

On first run, jernel creates a config directory at ~/.config/jernel/ with:

• config.yaml — model settings and defaults
• system_prompt.md — system prompt for the LLM
• message_prompt.md — customizable entry generation template
• personas/ — character definitions for journal entries

Set your Anthropic API key:

export ANTHROPIC_API_KEY=your-key-here

Quick Start

The easiest way to use jernel is through the interactive TUI:

jernel open

This opens a full-screen terminal interface where you can:

• Browse and read journal entries
• Generate new entries with persona selection
• Create and edit personas with the built-in editor
• Start/stop the daemon for automatic entry generation
• View settings and configuration paths

CLI Commands

Entries

# Create a new entry (uses default persona)
jernel entry create

# Create with a specific persona
jernel entry create --persona dramatic

# List recent entries
jernel entry list

# List entries for a specific persona
jernel entry list --persona dramatic

# Read the most recent entry
jernel entry read

# Read a specific entry by ID
jernel entry read 5

Personas

# List all personas
jernel persona list

# Create a new persona (opens template file)
jernel persona create my_persona

# Delete a persona (with option to delete associated entries)
jernel persona delete my_persona

Daemon

The daemon runs in the background and generates entries automatically at random intervals.

# Start the daemon (default: 3 entries per day)
jernel daemon start

# Start with custom rate
jernel daemon start --rate 5 --rate-period day

# Start with specific personas (randomly selected for each entry)
jernel daemon start --personas "dramatic,thoughtful,anxious"

# Check daemon status
jernel daemon status

# Stop the daemon
jernel daemon stop

Other Commands

# Open the interactive TUI
jernel open

# Delete all entries (with confirmation)
jernel reset

Personas

Personas define the voice and personality for journal entries. They are markdown files stored in ~/.config/jernel/personas/.

Create a new persona:

jernel persona create anxious

This creates a template file you can edit. Example persona:

---
name: anxious
---

A nervous computer who worries about everything. High CPU usage triggers panic,
low disk space causes existential dread. Always anticipating the next crash.
Speaks in short, worried sentences. Often trails off with "..."

Use it when creating entries:

jernel entry create --persona anxious

Or select it in the TUI when pressing n to create a new entry.

Context Continuity

jernel includes your most recent entries (default: 3) when generating new ones, allowing the LLM to maintain narrative continuity and build on previous themes. Configure this in config.yaml:

context_entries: 3  # number of previous entries to include

Set to 0 to disable context continuity.

Customization

Message Prompt

The ~/.config/jernel/message_prompt.md file controls how entries are generated. It's a Go template with access to:

• {{.Persona}} — the persona description
• {{.MachineType}} — laptop, desktop, server, etc.
• {{.TimeOfDay}} — morning, afternoon, evening, night
• {{.CPUPercent}}, {{.MemoryPercent}}, etc. — system metrics
• {{.PreviousEntries}} — recent entries for context

Power users can customize this template to change the entry format or add additional instructions.

System Prompt

The ~/.config/jernel/system_prompt.md file contains the system-level instructions for the LLM. Edit this to change the fundamental behavior of entry generation.

Development

Running Tests

go test ./...

With verbose output:

go test ./... -v

With race detection:

go test ./... -race

Building

go build -o jernel .

License

MIT