Journal

ctx journal¶

Browse and search AI session history from Claude Code and other tools.

ctx journal <subcommand>

ctx journal source¶

List all parsed sessions.

ctx journal source [flags]

Flags:

Sessions are sorted by date (newest first) and display slug, project, start time, duration, turn count, and token usage.

Example:

ctx journal source
ctx journal source --limit 5
ctx journal source --project ctx
ctx journal source --tool claude-code

ctx journal source --show¶

Show details of a specific session.

ctx journal source --show [session-id] [flags]

Flags:

The session ID can be a full UUID, partial match, or session slug name.

Example:

ctx journal source --show abc123
ctx journal source --show gleaming-wobbling-sutherland
ctx journal source --show --latest
ctx journal source --show --latest --full

ctx journal import¶

Import sessions to editable journal files in .context/journal/.

ctx journal import [session-id] [flags]

Flags:

Self-healing, no flags required. Import's unit of memory is the source transcript, not the output file. A sweep (--all) automatically:

• imports new sessions it has never seen;
• completes grown sessions — any whose transcript gained messages since the last import (for example, a session imported while it was still running) is re-rendered up to its current end. Claude Code transcripts are append-only, so "it grew" is detected from the file's size and mtime alone; a partial import is just an intermediate state the next sweep finishes;
• skips unchanged sessions, byte-for-byte, writing nothing.

So you never have to remember to re-import or time it: importing a live session mid-flight is safe and the next sweep heals it. That "no new flags" is the feature — it is why import is wired into /ctx-wrap-up and a SessionEnd hook, where it runs on the way out of every session (idempotent; one stat per session when there is nothing to do).

Your edits are never clobbered. Journal entries are meant to be edited (add notes, clean up the transcript). Before re-rendering a grown entry, import checks whether the file's body is still exactly what ctx last wrote; if you edited it, ctx leaves the file untouched and warns, pointing you at ctx journal lock (permanent protection) or an explicit --regenerate (deliberate discard). Locked entries are never rewritten under any flag.

--regenerate is an edge-case tool, not the routine path. Reach for it to (a) mass-re-render after a change to the render format, or (b) one-time heal a pre-self-heal entry that an old mid-session import truncated — its source will never grow again, so the automatic path cannot heal it, and --regenerate re-renders it from the full transcript. --keep-frontmatter=false additionally discards enriched frontmatter during that re-render.

Single-session import (ctx journal import <id>) always re-renders the targeted session without prompting, since you are explicitly targeting it.

The journal/ directory should be gitignored (like sessions/) since it contains raw conversation data.

Example:

ctx journal import abc123                 # Import (or re-render) one session
ctx journal import --all                  # Import new + complete grown sessions
ctx journal import --all --dry-run        # Preview what would be imported
ctx journal import --all --regenerate     # Edge case: force full re-render (prompts)
ctx journal import --all --regenerate -y  # Force full re-render without prompting
ctx journal import --all --regenerate --keep-frontmatter=false -y  # Discard frontmatter

ctx journal lock¶

Protect journal entries from being overwritten by import --regenerate or modified by enrichment skills (/ctx-journal-enrich, /ctx-journal-enrich-all).

ctx journal lock <pattern> [flags]

Flags:

The pattern matches filenames by slug, date, or short ID. Locking a multi-part entry locks all parts. The lock is recorded in .context/journal/.state.json and a locked: true line is added to the file's YAML frontmatter for visibility.

Example:

ctx journal lock abc12345
ctx journal lock 2026-01-21-session-abc12345.md
ctx journal lock --all

ctx journal unlock¶

Remove lock protection from journal entries.

ctx journal unlock <pattern> [flags]

Flags:

Example:

ctx journal unlock abc12345
ctx journal unlock --all

ctx journal sync¶

Sync lock state from journal frontmatter to .state.json.

ctx journal sync

Scans all journal markdowns and updates .state.json to match each file's frontmatter. Files with locked: true in frontmatter are marked locked in state; files without a locked: line have their lock cleared.

This is the inverse of ctx journal lock: instead of state driving frontmatter, frontmatter drives state. Useful after batch enrichment where you add locked: true to frontmatter manually.

Example:

# After enriching entries and adding locked: true to frontmatter
ctx journal sync

ctx journal¶

Analyze and synthesize imported session files.

ctx journal <subcommand>

ctx journal site¶

Generate a static site from journal entries in .context/journal/.

ctx journal site [flags]

Flags:

Creates a zensical-compatible site structure with an index page listing all sessions by date, and individual pages for each journal entry.

Requires zensical to be installed for --build or --serve:

pipx install zensical

Example:

ctx journal site                    # Generate in .context/journal-site/
ctx journal site --output ~/public  # Custom output directory
ctx journal site --build            # Generate and build HTML
ctx journal site --serve            # Generate and serve locally

ctx journal obsidian¶

Generate an Obsidian vault from journal entries in .context/journal/.

ctx journal obsidian [flags]

Flags:

Creates an Obsidian-compatible vault with:

• Wikilinks ([[target|display]]) for all internal navigation
• MOC pages (Map of Content) for topics, key files, and session types
• Related sessions footer linking entries that share topics
• Transformed frontmatter (topics → tags for Obsidian integration)
• Minimal .obsidian/ config enforcing wikilink mode

No external dependencies are required: Open the output directory as an Obsidian vault directly.

Example:

ctx journal obsidian                        # Generate in .context/journal-obsidian/
ctx journal obsidian --output ~/vaults/ctx  # Custom output directory

ctx journal schema check¶

Validate JSONL session files against the embedded schema and report drift.

ctx journal schema check [flags]

Flags:

Scans JSONL files for unknown fields, missing required fields, unknown record types, and unknown content block types. When drift is found, writes a Markdown report to .context/reports/schema-drift.md. When drift resolves, the report is automatically deleted.

Designed for interactive use, CI pipelines, and nightly cron jobs.

Example:

ctx journal schema check                    # Current project
ctx journal schema check --all-projects     # All projects
ctx journal schema check --quiet            # Exit code only
ctx journal schema check --dir /path/to     # Custom directory

ctx journal schema dump¶

Print the embedded JSONL schema definition.

ctx journal schema dump

Shows all known record types with their required and optional fields, and all recognized content block types with their parse status. Useful for inspecting what the schema validator expects.

Example:

ctx journal schema dump

ctx serve¶

Serve any zensical directory locally. This is a serve-only command: It does not generate or regenerate site content.

ctx serve [directory]

If no directory is specified, defaults to the journal site (.context/journal-site).

Requires zensical to be installed:

pipx install zensical

Example:

ctx serve                        # Serve journal site (no regeneration)
ctx serve .context/journal-site  # Same, explicit path
ctx serve ./site                 # Serve the docs site