[FEATURE] Session Notes — Add editable description/notes field (300 chars) with auto-generation for each session

Feature Request: Session Notes — Lightweight Annotations for Claude Code Sessions

For: Claude Code Desktop App & CLI (https://github.com/anthropics/claude-code)
Proposed By: Sumit — Founder, Antifragile Technologies (Dubai, UAE)
Date: 2026-03-09

---

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

---

Problem Statement

Current Limitation: Claude Code sessions have only a name — a short string that is either auto-generated from the first prompt or manually set via "Rename." There is no way to attach descriptive notes, context, or continuation instructions to a session.

Real-World Impact:

• Power users running 10-30+ sessions per project cannot distinguish sessions at a glance
• The "Rename" field is too short to capture meaningful context (what was done, what's pending, what to do next)
• Developers waste time clicking into session transcripts just to remember what a session was about
• There is no mechanism to leave "breadcrumbs" for yourself or teammates between sessions
• Session continuity depends entirely on memory or external note-taking tools

Example Scenario:

Monday:
Session "ACPN 17" → What did I do here? Click. Read. Scroll. Oh, header RTL fixes.
Session "ACPN 16" → And here? Click. Read. Scroll. Ah, footer component.
Session "ACPN 15" → Click. Read. Scroll...

Tuesday:
Developer has 20 ACPN sessions. Spends 15 minutes finding where they left off.

With Notes:
Session "ACPN 17" → "Completed header RTL. TODO: mobile nav breakpoints"
Session "ACPN 16" → "Footer component done. Waiting for client SVG assets"
Found it in 5 seconds. Back to coding.

Scale of the Problem: I have 300+ hours of Claude Code usage across multiple SaaS products (Nova Uptime, KitePin, FlipLink, ScreenShield, WordPress Max) and client projects (ACPN healthcare website — 400+ pages, 80+ clinicians). Managing sessions across these projects without notes is one of the most consistent friction points in my daily workflow. This is the single most impactful UX improvement I can suggest for power users.

---

Proposed Solution

Add a "Session Notes" field — a lightweight, editable text annotation (up to 300 characters) attached to each session.

Core Mechanism

.claude/sessions/{session-id}/note.md — A small markdown file storing the session annotation, or stored in existing session metadata.

Key Design Principles

1. Lightweight: Not a full handoff document — just 300 characters of context (like a git commit message for sessions)
2. UI-Native: Visible directly in the session sidebar, not buried in files
3. Zero-Friction: Auto-generation means you get notes without writing them
4. Non-Breaking: Completely optional, disabled-by-default sessions continue to work as before

---

Implementation Options

Option A: Desktop App Integration (Recommended)

Current UI — Session dropdown menu:

┌─────────────┐
│ ✏️ Rename    │
│ 📦 Archive   │
└─────────────┘

Proposed UI — Add "Notes" to dropdown:

┌──────────────────┐
│ ✏️ Rename         │
│ 📝 Notes          │
│ 📦 Archive        │
└──────────────────┘

Sidebar Display — Notes appear as a muted subtitle:

Current:

Today
  ○ ACPN 17
  ○ Wellness 3
  ○ Wellness 2
Yesterday
  ○ Fix return timestamp in audio processing
  ○ Build project from code prompt specifi...

With Notes:

Today
  ○ ACPN 17
    Header RTL fixes done. TODO: mobile nav breakpoints
  ○ Wellness 3
    Added meditation timer. Next: push notification system
  ○ Wellness 2
    Initial DB schema + auth flow. Ready for API routes
Yesterday
  ○ Fix return timestamp in audio processing
    Resolved UTC offset bug in ffprobe output parser
  ○ Build project from code prompt specifi...
    Created 12-phase spec. Waiting for client review

Interaction:

1. Click ∨ chevron on any session → Select "Notes"
2. Inline text field appears (300 char limit, with character counter)
3. Type note → Press Enter or click away to save
4. Note appears as subtitle in sidebar
5. Full note visible on hover tooltip if truncated

Option B: CLI Integration

# Set a note on current session
/note "Completed API routes for user auth. TODO: add rate limiting middleware"

# Set a note when starting a new session
claude --note "Starting rate limiter implementation"

# Auto-generate note for current session based on what was done
/note --auto

# View notes in session list when resuming
claude --resume
# Output:
# ┌─────┬────────────────────┬──────────────────────────────────────────────────┐
# │ No. │ Last Update        │ Summary                                          │
# ├─────┼────────────────────┼──────────────────────────────────────────────────┤
# │ 1   │ 2026-03-09 14:32   │ ACPN 17                                         │
# │     │                    │ 📝 Header RTL fixes done. TODO: mobile nav       │
# │ 2   │ 2026-03-09 09:15   │ Wellness 3                                      │
# │     │                    │ 📝 Added meditation timer. Next: notifications   │
# │ 3   │ 2026-03-08 16:45   │ Fix return timestamp                            │
# │     │                    │ 📝 Resolved UTC offset bug in ffprobe parser     │
# └─────┴────────────────────┴──────────────────────────────────────────────────┘

# Update note on a past session
claude --resume --session 1 --note "Updated: also fixed footer alignment"

Option C: Auto-Generation (Key Differentiator)

At session end, Claude Code auto-generates a concise note based on:

• Files modified during the session
• Tasks completed (successful tool calls, commits made)
• Errors encountered or tasks left incomplete
• Patterns in the conversation (TODOs mentioned, next steps discussed)

User Experience:

Session ending...

📝 Auto-generated note:
"Modified 4 files in src/components/. Completed: Header RTL fix, navbar responsive.
 Pending: mobile breakpoint at 768px. Error: SVG import failed for service icons."

[Accept] [Edit] [Discard]

Auto-generation makes this feature zero-friction — developers who don't want to manually annotate sessions still get useful notes.

Option D: Configuration Setting

{
  "sessionNotes": {
    // Enable/disable feature
    "enabled": true,

    // Maximum note length in characters
    "maxLength": 300,

    // Show notes in sidebar
    "showInSidebar": true,

    // Show notes in --resume list
    "showInResumeList": true,

    // Auto-generate notes at session end
    "autoGenerate": false,

    // Prompt before auto-saving note
    "promptBeforeSave": true,

    // Truncation length for sidebar display (full on hover)
    "sidebarTruncateLength": 80
  }
}

---

Benefits

For Individual Developers

• ✅ Instant session identification — Know what each session contains without opening it
• ✅ Reduced context switching cost — Find the right session in seconds, not minutes
• ✅ Built-in TODO tracking — "Next: implement middleware" right on the session
• ✅ Session history at a glance — Scroll through annotated sessions = mini project log
• ✅ Cognitive offload — Stop memorizing which session did what

For Teams

• ✅ Handoff context — "Session 12 note: Completed OAuth. Needs code review by Sarah"
• ✅ Debugging breadcrumbs — "Session 9 note: Changed DB schema, may have caused migration issue"
• ✅ Onboarding — New team member scans session notes to understand project progression
• ✅ Accountability — Notes show what was actually done vs. planned

For Claude Code Product

• ✅ Stickier UX — Users stay in Claude Code instead of switching to external note apps
• ✅ Power user retention — Addresses the #1 workflow friction for high-usage developers
• ✅ Differentiator — No competing AI coding tool (Cursor, Windsurf, Copilot) offers session annotations
• ✅ Foundation for future features — Notes data enables session search, project timelines, usage analytics

---

Proof of Concept

I've implemented a manual workaround across my projects and it validates the need:

Current Manual Workflow:

1. At the end of each session, I mentally note what was done
2. I use descriptive session names as a poor substitute: "ACPN 17 - RTL header fixes"
3. For complex projects, I maintain a separate session-log.md file outside Claude Code
4. When resuming, I open the log file, find the session, then --continue

Results from Manual Workaround:

• Works, but adds friction (context switching to external notes)
• Session names get unwieldy: "Fix return timestamp in audio processing and update ffprobe parser for UTC offset handling" — still truncated
• External log files get out of sync with actual sessions
• Team members can't see my notes without accessing the external file

What Native Notes Would Change:

• All context lives inside Claude Code — no external tools
• Notes are attached to the session object, always in sync
• Visible in sidebar without any extra clicks
• Auto-generation eliminates manual documentation

Validation: This request comes from 300+ hours of real-world Claude Code usage across 6+ active projects, where session management is a daily workflow challenge.

---

Use Cases

1. Multi-Project Development

Project: Nova Uptime (SaaS)
  ○ Session "API monitoring"
    📝 "Built /api/check endpoint. Next: add SSL cert monitoring + webhook alerts"

Project: ACPN Healthcare Website
  ○ Session "ACPN 17"
    📝 "Header RTL done. TODO: mobile nav at 768px breakpoint, test Arabic layout"

Project: KitePin (AI Support Agent)
  ○ Session "Dashboard v2"
    📝 "Converted React JSX to standalone HTML. Bug: mobile nav hamburger not toggling"

Developer switches between 3 projects daily. Notes tell them exactly where each project stands — instantly.

2. Debugging Across Sessions

Session "Auth Bug Hunt 1"
  📝 "Investigated JWT expiry. Not the issue. Suspect middleware."
Session "Auth Bug Hunt 2"
  📝 "Found it: CORS preflight stripping auth header. Fix deployed."
Session "Auth Bug Hunt 3"
  📝 "Regression test passed. Added integration test for CORS + JWT."

3 months later, similar bug appears. Developer searches notes → finds root cause in seconds.

3. Client Project Handoff

Freelancer finishing a project:
Session "Final Polish"
  📝 "All pages responsive. Client wants logo 10px larger. Invoice sent."

New developer picks up:
Reads notes → knows exactly what was done and what the client requested.

4. Daily Standup Reference

Manager: "What did you work on yesterday?"
Developer opens Claude Code sidebar:
  ○ "ACPN 17" — 📝 "Header RTL + mobile nav. 2 bugs fixed, 1 pending"
  ○ "Nova API" — 📝 "SSL monitoring endpoint. Tests passing. Ready for PR"

Standup answered in 10 seconds.

---

Alternatives Considered

| Approach | Limitation |
|----------|-----------|
| Long session names | Truncated in sidebar, no multi-line support, awkward UX |
| CLAUDE.md notes | Project-level, not session-level. Doesn't track per-session context |
| External note apps | Context switching, out of sync, not visible in Claude Code UI |
| Session handoff files (#11455) | Full markdown documents — great for continuity, but heavyweight. Notes are the lightweight complement |
| Git commit messages | Code-focused, not session-focused. Don't capture "what to do next" |
| Session naming (#2112) | Names only, no description field. 100 chars suggested — insufficient for context |

Key Distinction: This feature is the lightweight layer between a session name (too short) and a full handoff document (too heavy). Think of it as a git commit message for sessions — brief, descriptive, and always visible.

---

Security & Privacy Considerations

Data Storage: Notes stored locally in session metadata (same location as session transcripts)

No Cloud Sync by Default: Notes follow the same privacy model as session data

No Sensitive Data Guidance: Auto-generated notes should exclude:

• API keys, tokens, passwords
• File paths containing usernames
• Environment variables with secrets

GDPR/Privacy: Notes are user-generated annotations on their own sessions — no additional privacy concerns beyond existing session data

---

Migration Path

Phase 1 — MVP (Desktop App):

• Add "Notes" option to session dropdown menu
• Inline text field with 300 character limit
• Display as subtitle in sidebar (truncated with hover for full text)
• Notes stored in session metadata

Phase 2 — CLI Support:

• Add /note slash command for setting/viewing notes
• Add --note flag for claude --continue and claude --resume
• Display notes in --resume session list table

Phase 3 — Auto-Generation:

• At session end, offer auto-generated note based on session activity
• Accept/Edit/Discard prompt before saving
• Configurable via sessionNotes.autoGenerate setting

Phase 4 — Search & Discovery:

• Search sessions by note content (not just name)
• Filter sessions by keywords in notes
• Export session notes as project timeline

Backward Compatibility:

• Feature is additive — no changes to existing sessions
• Sessions without notes display exactly as they do today
• Auto-generation is opt-in, not default

---

Success Metrics

Adoption:

• % of sessions with notes (manual + auto-generated)
• % of users who enable auto-generation
• Frequency of note edits (indicates active use vs. set-and-forget)

Impact:

• Time to find correct session when resuming (before/after)
• Reduction in duplicate sessions (users creating new sessions because they can't find old ones)
• User satisfaction survey: "Can you find your sessions easily?"

Engagement:

• Correlation between note usage and session --continue rate
• Power user retention (users with 50+ sessions per month)

---

Related Issues (Different Scope)

| Issue | What It Requests | How This Differs |
|-------|-----------------|-----------------|
| #2112 | --session-name flag for naming sessions | Names only, no description/notes field |
| #3975 | Ability to name sessions for easier resume | Duplicate of naming, no notes concept |
| #11455 | Session handoff via .claude/handoff.md | Full markdown continuity documents — heavyweight. Notes are the lightweight complement |
| #18401 | Session linking to share context across sessions | Cross-session context transfer, not annotation |
| #10140 | Auto-create log files per session | Full logging, not user-facing annotations |
| #17188 | Expose session metadata via env vars | Developer tooling, not user-facing UX |

This feature fills the gap between naming (too short) and handoff documents (too heavy).

---

Technical Considerations

Storage:

• 300 characters per note ≈ 300 bytes per session
• Even with 10,000 sessions, total notes storage < 3MB
• Negligible impact on performance or disk usage

Data Model:

interface SessionMetadata {
  id: string;
  name: string;
  note?: string;        // NEW: up to 300 characters
  noteAutoGenerated?: boolean;  // NEW: flag for auto-generated notes
  noteUpdatedAt?: string;       // NEW: timestamp of last note edit
  createdAt: string;
  updatedAt: string;
  // ... existing fields
}

Auto-Generation Prompt (for Phase 3):

Based on this session's activity, generate a concise note (max 300 characters) covering:
1. What was accomplished (files changed, features built)
2. What's pending or errored
3. Suggested next step
Format: "[Completed]. [Pending/Next step]."

---

Conclusion

Session Notes is a small feature with outsized impact for developers who use Claude Code as their primary development tool.

The ask is simple: A 300-character text field on each session, visible in the sidebar, editable anytime, with optional auto-generation.

The impact is significant: Transforms the session list from "a list of names I have to click through" to "a scannable project log that tells me exactly where everything stands."

This request comes from 300+ hours of real Claude Code usage where session management friction is a daily reality. I believe this would benefit the entire Claude Code community, especially power users managing complex, multi-session projects.

---

Contact

Reporter: Sumit
Company: Antifragile Technologies (Dubai, UAE)
Role: Founder — building multiple SaaS products with Claude Code as primary development tool
Usage: 300+ hours across Nova Uptime, KitePin, FlipLink, ScreenShield, WordPress Max, ACPN healthcare website, and more

Willing to:

• Provide detailed workflow examples from real projects
• Test beta implementations and provide feedback
• Record screen captures of current workflow friction
• Collaborate on UX design for the notes interface

This feature request comes from daily development work where session management is the most consistent friction point. A lightweight notes field would eliminate context-switching overhead and make Claude Code the most developer-friendly AI coding tool available.