claude-session-tracker

Never lose a Claude Code conversation again.

Every prompt, every response, every decision — automatically saved to GitHub Projects.

Quick Start • What It Does • How It Works • Use Cases • Configuration

---

What it does

This tool automatically creates a dedicated GitHub repository for storing Claude Code sessions, then sets up GitHub Projects inside that repository.

Each Claude Code session is assigned to its own issue, making it easy to revisit and review past sessions at any time. Every issue stores both your prompts and Claude’s responses, so the full context of each session is preserved and searchable later.

Demo

Quick Start

npx claude-session-tracker

Note

Nightly builds are published to npm before the next stable release. Use npx claude-session-tracker@nightly to try the latest Context Operator changes early. For details, see the latest nightly release notes.

Auto Setup (Recommended)

Pick this if you don't already have a GitHub Project set up.

The installer creates everything for you automatically —

• A private repository for storing session issues
• A GitHub Project with all status options configured
• Custom date fields (Session Created, Last Active)
• Claude Code hooks, globally installed

All you do is pick a language and confirm. That's it.

---

Key features

• Automatically creates a dedicated repository for Claude Code session history
• Sets up GitHub Projects for structured session tracking
• Assigns one issue per Claude Code session
• Stores both user prompts and Claude responses
• Makes it easy to revisit, read, and manage past sessions whenever needed

Custom date fields

Auto setup creates two custom date fields in your project — Created (set when a session starts) and Last Active (updated on every prompt).

The GitHub API doesn't support modifying project views programmatically, so you'll need to manually add these fields to your board view. Go to your project → open any view → click + to add a field.

---

What It Does

When you chat with Claude Code, the tracker automatically

• Creates a GitHub Issue for your session
• Records every prompt you type
• Records every response Claude gives
• Updates the issue title with your latest prompt (so you can scan history at a glance)
• Tracks session status: Registered → Responding → Waiting → Closed
• Auto-assigns issues to you
• Saves timestamps for everything
• Auto-closes idle sessions (configurable)

No setup after install. Just use Claude Code like normal.

---

Why?

Claude Code sessions disappear when they end.

If you're juggling multiple tasks across projects, it's chaos. What did you decide? What was the discussion? Where did you leave off?

claude-session-tracker fixes this by making your entire conversation history searchable and shareable on GitHub Projects.

---

How It Works

Claude Code Event	GitHub Status	What Happens
Session starts	Registered	Issue created, added to Project
You submit prompt	Responding	Prompt saved, title updated
Claude responds	Waiting	Response saved, idle timer starts
Timer expires	Closed	Session auto-closed

All hooks run async — tracking never slows you down.

Features

Session URL notification

When a session starts, Claude tells you where it's tracked —

This session is being tracked at https://github.com/you/repo/issues/42

Smart title updates

Issue title auto-updates with your latest prompt —

[project-name] your latest prompt here...

Long project names get truncated at 20 chars.

Resume without duplicates

Resume a session with claude --resume? Tracker reuses the same GitHub Issue instead of creating a new one.

Git remote auto-detection

Has a GitHub remote? We use it for the issue title prefix. Issues always land in your configured storage repo.

Zero blocking

All hooks run async. Tracking never slows down Claude.

---

Use Cases

Personal context log Never forget what you discussed. Search your GitHub Projects and find any session in seconds.

Team collaboration Share a GitHub Project with your team. Everyone sees what Claude is working on across all your repos. Perfect for code reviews and onboarding.

Session handoff Paused work? Come back tomorrow and resume with full context. The tracker picks up where you left off, no duplicates.

Audit trail Track everything Claude did, when it did it, and why. Useful for reviews and learning what worked.

---

Prerequisites

• Node.js 18+

• Python 3

• GitHub CLI (gh) — REQUIRED. Install it from https://cli.github.com.

  # Install (macOS)
  brew install gh
  
  # Login and set required scopes
  gh auth login --scopes "project,repo"

  Needs project (read/write GitHub Projects) and repo (create issues, comments) scopes.

• A GitHub Project (v2) with a Status field (auto setup creates one for you)

---

Configuration

Edit ~/.claude/hooks/config.env directly, or just re-run the installer

npx claude-session-tracker

Config file format

GITHUB_PROJECT_OWNER=your-username
GITHUB_PROJECT_NUMBER=1
GITHUB_PROJECT_ID=PVT_...
GITHUB_STATUS_FIELD_ID=PVTSSF_...
GITHUB_STATUS_REGISTERED=...
GITHUB_STATUS_RESPONDING=...
GITHUB_STATUS_WAITING=...
GITHUB_STATUS_CLOSED=...
NOTES_REPO=your-username/dev-notes
DONE_TIMEOUT_SECS=1800

---

Under the Hood

Files we install to ~/.claude/hooks/

~/.claude/hooks/
├── cst_github_utils.py              # Shared utilities
├── cst_session_start.py             # SessionStart hook
├── cst_prompt_to_github_projects.py # UserPromptSubmit hook
├── cst_post_tool_use.py             # PostToolUse hook
├── cst_session_stop.py              # Stop / SessionEnd hook
├── cst_mark_done.py                 # Idle timeout handler
├── config.env                       # Your configuration
├── hooks.log                        # Execution logs
└── state/                           # Per-session state (JSON)

---

Manual Setup

Pick this if you already have a GitHub Project you want to use.

The wizard asks you ~6 questions —

1. GitHub Project Owner — your username or org
2. GitHub Project Number — grab it from your project URL
3. Status mapping — connect your Project's Status field to our lifecycle stages
4. Default repo — fallback when there's no git remote
5. Idle timeout — how long before we auto-close (default: 30 mins)
6. Scope — this project only, or go global

Then use Claude Code like normal. Everything flows to GitHub Projects automatically.

Uninstall

npx claude-session-tracker uninstall

Removes everything we installed — hook scripts, configuration, state files and logs. Doesn't touch your other hooks.

---

Known Issues

Async hook completion messages appearing in Claude Code

You may see messages like this after every prompt/response —

⎿  Async hook UserPromptSubmit completed
⎿  Async hook Stop completed

This is a Claude Code behavior, not a bug in this tool. All hooks run with async: true to avoid blocking your workflow, and Claude Code currently has no option to suppress these completion messages.

A feature request has been filed upstream: anthropics/claude-code#32551

---

Contributing

Found a bug? Have an idea? Contributions are always welcome.

Open an issue, submit a PR, or drop a feature request.

---

License

MIT