Session Start: Show Todos

Decisions

• Pending: Show full my-todos.md or only the “Now” section?

User Tasks

---

FR-013: Session Start — Show Todos

Summary

When starting a Claude Code session, automatically display next steps from vault/my-todos.md.

Problem / Motivation

Each session starts cold — Claude doesn’t know what the user was working on or plans to do. The user has to manually say “check my todos” or re-explain context. my-todos.md already tracks current focus, so this should be automatic.

Proposed Solution

A UserPromptSubmit hook that injects the contents of my-todos.md on the first prompt of each session. This gives Claude immediate context about priorities without the user having to ask.

Why UserPromptSubmit, not SessionStart?

Claude Code hooks don’t have a SessionStart event that can inject content into the conversation. UserPromptSubmit fires on every prompt — we use a state file to ensure injection only happens once per session.

Implementation

# .claude/hooks/session-start-todos.sh
LOCK="/tmp/claude-session-todos-$$"
 
# Only fire once per session (parent PID stays constant)
LOCK="/tmp/claude-session-todos-$PPID"
if [ -f "$LOCK" ]; then
  exit 0
fi
touch "$LOCK"
 
TODOS="$CLAUDE_PROJECT_DIR/vault/my-todos.md"
if [ -f "$TODOS" ]; then
  echo "--- Current Todos (from vault/my-todos.md) ---"
  cat "$TODOS"
  echo "---"
fi

Registration in .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-todos.sh\""
          }
        ]
      }
    ]
  }
}

---

Open Questions

1. Scope of display

Question: Show full file or only the “Now” section?

Option	Description
A) Full file	Simple, shows Now + Next + Backlog
B) Now section only	Parse out just the active items — less noise

Recommendation: Option A to start — file is short. Can filter later if it grows.

---

Phase Overview

Phase	Description	Status
Phase 1	Hook script + registration	—

---

Phase 1: Implement Hook —

Goal: Auto-show todos on first prompt of each session.

File / Feature	Details	Owner	Status
.claude/hooks/session-start-todos.sh	Hook script with once-per-session guard	opus	—
.claude/settings.json	Register UserPromptSubmit hook	opus	—
Test manually	Start new session, verify todos appear	mv	—

---

Test

Manual tests

Test	Expected	Owner	Actual	Last
Start new session, type anything	Todos injected into context	mv	pending	-
Second prompt in same session	No injection (once-per-session)	mv	pending	-
my-todos.md is empty	No output, no error	mv	pending	-

AI-verified tests

Scenario	Expected behavior	Verification method
…	…	…

E2E tests

Scenario	Assertion
…	…

Integration tests

Component	Coverage
…	…

Unit tests

Component	Tests	Coverage
…	…	…

---

History

Date	Event	Details
2026-03-12	Created	User wants automatic session context from todos

---

References

• FR-011 (Hook Scripts) — this is one specific hook implementation
• FR-004 (Session Start Recap) — complementary; recap shows git history, this shows user priorities