Journals

Journals are AI-generated markdown summaries of quest sessions. They capture what was built, what was learned, and why decisions were made — turning ephemeral Claude Code conversations into durable documentation.

What journals contain

Each journal entry is a narrative markdown document generated by analyzing the full conversation history of a quest. A typical entry includes:

• A descriptive title summarizing what was accomplished.
• Key findings and decisions made during the session.
• What was built or changed and why.
• YAML frontmatter with metadata (date, project name, branch).

Entries are concise (roughly 200—500 words) and written in a readable narrative style, not a raw transcript.

Here is an example of what the frontmatter looks like:

---
date: 2026-03-18
project: my-app
branch: feat/auth-flow
---

Creating a journal entry

There are two ways to create a journal entry:

1. From the Journals section — click the + button in the Journals panel at the bottom of a project column. A modal appears listing all quests in the project. Select the quest you want to document.

2. From a quest’s context menu — right-click a quest and select the journal option. This skips the quest picker and starts generating immediately.

When you trigger creation, Sidequest:

graph LR
A[Quest .jsonl] -->|Extract text| B[Conversation]
B -->|Claude chronicler prompt| C[Title + Content JSON]
C -->|Write with frontmatter| D[Journal .md]

1. Locates the quest’s Claude Code conversation file (.jsonl) from the quest’s working directory.
2. Extracts the conversation text.
3. Sends it to Claude with a chronicler system prompt that instructs it to produce a structured JSON response with a title and content.
4. Writes the result as a markdown file with YAML frontmatter.

Generation takes a few seconds. The entry opens automatically in the viewer when complete.

Where journals are stored

By default, journal entries are saved to:

~/.sidequest/journal/{project-name}/

Each entry is a markdown file named with a slug derived from the generated title (e.g., implementing-oauth-flow.md). If a file with the same name already exists, a numeric suffix is appended.

Changing the journal directory

To use a custom location:

1. Expand the Journals section in the project column.
2. Click the gear icon to open journal settings.
3. Click Browse to choose a new directory.

To reset back to the default, click Reset to default in the settings dialog.

The custom path is stored per-project in the journal_path column on the projects table.

Viewing journal entries

Expand the Journals section to see a list of all entries for the project, sorted newest first. Click any entry to open it in the viewer modal, which renders the markdown with full formatting (headings, code blocks, tables, lists).

The viewer strips the YAML frontmatter for display and shows only the content.

Managing entries

Right-click an entry in the list (or use the buttons in the viewer) to access these actions:

• Rename — edit the entry’s display name. The filename on disk updates to match.
• Copy — copy the rendered markdown content to your clipboard (frontmatter excluded).
• Delete — remove the entry from disk. Requires confirmation.
• Commit to project — copy the file into your project repository and create a git commit.

Committing to your project

The commit workflow lets you promote a journal entry from the Sidequest journal directory into your actual codebase:

1. Select Commit to project from the context menu or viewer.
2. Browse to the target directory within your project (e.g., docs/journals/).
3. Click Commit. Sidequest copies the file, runs git add, and creates a commit with the message docs: add journal entry {name}.

The target directory must be within the project’s repository. If the commit fails (e.g., due to a git hook), the copied file is cleaned up automatically.

When journals are useful

Knowledge transfer. When handing off a feature branch to another developer, generate a journal entry so they understand the decisions and trade-offs without reading the full conversation.

Onboarding. New team members can read journal entries to understand how and why the codebase evolved, written in plain language rather than commit messages.

Audit trail. For compliance-sensitive projects, journals provide a narrative record of what the AI agent did and why, tied to specific branches and dates.

Personal reference. After a long quest spanning multiple sessions, a journal entry gives you a quick summary of where things stand and what was decided.