How do I use the session journal?

Question
Answer
2026-06-02 09:34 — Clarify versioning strategy
Conventions
See also

Question

How do I record what I am working on so that after a restart I know where I left off, and so that other Claude instances can detect overlap before picking up a new story?

Answer

Each worktree has a .journal.org file in its root directory — machine-local, gitignored, never committed. Use compass task start to clock on whenever you pick up a task (new or existing). The journal then answers two questions: compass journal where ("where was I?") and compass fleet ("what is every worktree doing?").

Clocking on to a task

# New task or resuming an existing task — all three cases:
./projects/ores.compass/compass.sh task start <task-slug>

This switches to the task's branch, flips the state from BACKLOG to STARTED if needed, and appends a timestamped entry to .journal.org. It is the required first step in both Start work on a new story and Work a task through to merged PR.

Restart recovery

# What was I working on? (last entry in this worktree)
./projects/ores.compass/compass.sh journal where

Then clock back on:

./projects/ores.compass/compass.sh task start <slug-from-where-output>

Viewing the session history

Newest first by default (git log semantics); -n N clips to the N most recent entries and --chronological restores oldest-first for reading history as a narrative:

./projects/ores.compass/compass.sh journal log -n 5
./projects/ores.compass/compass.sh journal log --chronological

Overlap detection before picking up a story

./projects/ores.compass/compass.sh fleet

Shows every worktree's current story, task, branch, and PR. Check this before starting new work to avoid touching the same area as another environment.

Updating the journal manually

For cases not covered by compass task start (e.g. recording a PR number or a DONE state):

./projects/ores.compass/compass.sh journal update \
  --story <UUID> --task <UUID> \
  --branch <branch> --state DONE --pr <N>

Entry format

#+begin_example

2026-06-02 09:34 — Clarify versioning strategy

Task: Create milestones infrastructure
State: STARTED
Branch: feature/clarify-versioning-strategy
PR: none

#+end_example

Field	Description
Heading timestamp	ISO date + time of clock-on
Story link	org-roam `[[id:UUID][Title]]` of the parent story
`Task ::`	org-roam `[[id:UUID][Title]]` of the specific task
`State ::`	`STARTED`, `DONE`, `BLOCKED`, etc.
`Branch ::`	Current git branch
`PR ::`	GitHub PR number or `none`

Conventions

Clock on with compass task start at the start of every task pickup, including after restarts. Do not rely on creation commands to do it.
One entry per task pickup, not per commit.
Org-roam links are preferred — entries are navigable from Emacs and stable when titles change.
The file grows indefinitely; do not prune it.
.journal.org is never committed to git.