claude-session-tracker

KO | EN

gitlite — search

#python #ai #go #golang #android #machine-learning #deep-learning #linux #docker #nodejs #kubernetes #awesome-list #pytorch #open-source

claude-session-tracker

(★ 46)

Auto-save every Claude Code session to GitHub Projects. Never lose Prompt & Context again.

claude-session-tracker Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# claude-session-tracker
[![npm downloads](https://img.shields.io/npm/dm/claude-session-tracker)](https://www.npmjs.com/package/claude-session-tracker)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/ej31/claude-session-tracker/pulls)

[![npm version](https://img.shields.io/npm/v/claude-session-tracker)](https://www.npmjs.com/package/claude-session-tracker)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green?logo=node.js)](https://nodejs.org)
[![OS Compatibility](https://github.com/ej31/claude-session-tracker/actions/workflows/compat.yml/badge.svg)](https://github.com/ej31/claude-session-tracker/actions/workflows/compat.yml)
[![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-blueviolet)](https://claude.ai/code)

**Never lose a Claude Code conversation again.**

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

[Quick Start](#quick-start) • [What It Does](#what-it-does) • [How It Works](#how-it-works) • [Use Cases](#use-cases) • [Configuration](#configuration)

---
## What it does

One command, done. A private GitHub repo gets created, a Project board gets wired up, and every Claude Code session you run from now on is automatically logged as a GitHub Issue — prompts, responses, timestamps, everything.

No config files to write. No tokens to paste. Just run the installer and forget about it.

## Demo

<p>

</p>

## Quick Start

```bash
npx claude-session-tracker
```

The installer will offer to install the CLI globally so you can run commands like `claude-session-tracker pause` directly.

### What the installer does

Everything is automatic. You just pick a language and hit enter.

- Creates a private repo for your session issues
- Spins up a GitHub Project with all statuses pre-configured
- Adds date fields (`Session Created`, `Last Active`)
- Tags each issue with the project name as a label
- Installs Claude Code hooks globally
- Recovers gracefully if something fails mid-setup
- Protects session data if repository or project visibility changes (see [Privacy Protection](#privacy-protection))
- Marks the project board `ON_TRACK` on completion

Already installed? Re-running the installer just reuses your existing setup. No duplicates, no mess.

### CI / Non-interactive Install

Spinning up dev containers? Baking a dotfiles image? Onboarding 50 devs and _really_ don't want to answer the same prompts 50 times? That's what `--yes` is for. One flag, zero prompts, done.

Add `--yes` (or `-y`) to skip all interactive prompts. The installer also auto-detects CI environments (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `JENKINS_URL`, `CODEBUILD_BUILD_ID`, `TF_BUILD`) and non-TTY stdin — so if you're already in a pipeline, it just works.

```bash
# Recommended — pipe token via stdin (never appears in process listings)
echo "$TOKEN" | npx claude-session-tracker --yes --token-stdin

# Via environment variable
GITHUB_TOKEN=ghp_xxx npx claude-session-tracker --yes

# Via flag (less secure — visible in process listings)
npx claude-session-tracker --yes --token ghp_xxx

# If gh is already authenticated, no token needed
npx claude-session-tracker --yes
```

Use `--language` (or `-l`) to set the status label language. Valid values: `en`, `ko`, `ja`, `zh`. Defaults to `en`.

```bash
npx claude-session-tracker --yes --language ko
```

**Exit codes**

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Invalid usage (missing tool, bad language, no auth) |
| 3 | Authentication failure (invalid token or missing scopes) |

**CLI flags**

| Flag | Short | Description |
|------|-------|-------------|
| `--yes` | `-y` | Skip all prompts |
| `--ci` | | Force non-interactive mode |
| `--token <PAT>` | `-t` | GitHub Personal Access Token |
| `--token-stdin` | | Read token from stdin |
| `--language <code>` | `-l` | Status label language (`en`, `ko`, `ja`, `zh`) |
| `--version` | `-v` | Print version and exit |

---

### Key features

- One issue per session — your whole conversation in one place
- Prompts and responses saved automatically
- GitHub Projects board for at-a-glance status
- Searchable, shareable, permanent

## Custom date fields

The installer adds two date fields — `Created` (when a session starts) and `Last Active` (updated on every prompt).

GitHub's API can't modify project views, so you'll need to add these fields to your board manually. Go to your project, open any view, click `+` to add a field.

---

## What It Does

Every time you chat with Claude Code, the tracker kicks in —

- Creates a GitHub Issue for the session
- Logs every prompt and every response
- Issue title always reflects your most recent prompt — easy to scan at a glance
- Records which repository you were working in as a GitHub label (e.g. `ej31/my-app`)
- Tracks status — Registered, Responding, Waiting, Closed
- Auto-assigns issues to you
- Timestamps everything
- Auto-closes idle sessions (default 30 min)
- Health checks with `status` and `doctor` commands
- Pause/resume tracking whenever you want
- Auto-update notifications when a new version is available

Install once, then just use Claude Code like normal. That's literally it.

---

## Why?

Claude Code sessions vanish when they end.

Juggling multiple projects? Good luck remembering what you decided, what Claude suggested, or where you left off.

**claude-session-tracker** dumps your entire conversation history into GitHub Projects. Search it, share it, never lose it.

---

## 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 — zero slowdown.

### Features

**Session URL notification**

Session starts, you get a link —
```
This session is being tracked at https://github.com/you/repo/issues/42
```

**Smart title updates**

Every time you send a prompt, the issue title is replaced with that prompt text. The title always shows what you last asked, so scanning your issue list tells you exactly where each session left off.
```
Fix session resume bug
```

**Repository label**

The tracker detects the Git remote of your current workspace and attaches it as a GitHub label (e.g. `ej31/claude-session-tracker`). This keeps the issue title clean while still letting you filter sessions by repository on the Projects board.

**Resume without duplicates**

`claude --resume`? The tracker reuses the same issue. No duplicates.

**Git remote auto-detection**

Got a GitHub remote? The tracker picks up `owner/repo` automatically. No remote? Falls back to your storage repo.

**Zero blocking**

Hooks are async. Claude never waits on the tracker.

**Built-in recovery and health checks**

Setup died halfway? Just re-run it — the installer picks up where it left off. After install, check things with —

```bash
claude-session-tracker status
claude-session-tracker doctor
```

`status` for a quick local check, `doctor` for a deep GitHub-backed diagnosis.

**Pause / resume tracking**

Working on something sensitive? Kill the logging —

```bash
claude-session-tracker pause
claude-session-tracker resume
```

`pause` stops all logging and marks the project `INACTIVE`. `resume` flips it back to `ON_TRACK`.

Every state change gets recorded as a project status update — session ID, workspace path, issue URL, timestamp, IP address. Full audit trail.

If someone marks the card `INACTIVE` from the GitHub web UI, the hooks detect it and stop logging until it's switched back.

**Privacy protection**

Session data may contain sensitive information — API keys, file paths, internal logic. The tracker enforces private storage at every step.

If the repository or project board visibility is changed to public, the installer detects this on re-run and takes automatic action.

- Repository made public → switched back to private and archived, then a new private repository is created
- Project board made public → closed, then a new private project is created

The original data is never deleted. Archived repositories become read-only and closed projects stop receiving updates until explicitly reopened.

**Auto-update**

When a new version is published, the tracker shows a notification at the start of your next session. Update hook scripts in-place without re-running the full installer —

```bash
claude-session-tracker update
```

---

## Use Cases

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

**Team collaboration**
Share a Project with your team. Everyone sees what Claude is doing across all repos. Great for reviews and onboarding.

**Session handoff**
Left off yesterday? Resume tomorrow with full context. No duplicates.

**Audit trail**
Track everything Claude did, when, and why. Useful for reviews and figuring out what actually worked.

---

## Prerequisites

- Node.js 18+
- Python 3
- **GitHub CLI (`gh`)** — grab it from https://cli.github.com

```bash
  # macOS
  brew install gh

# Login with required scopes
  gh auth login --scopes "project,repo"
  ```

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

---

## Configuration

Re-run the installer or edit `~/.claude/hooks/config.env` directly —

```bash
npx claude-session-tracker
```

Config file format
```env
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/claude-session-storage
DONE_TIMEOUT_SECS=1800
CST_PROJECT_NAME_MODE=label
```

---

## Under the Hood

Files installed 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 hook
├── cst_session_end.py               # SessionEnd hook
├── cst_mark_done.py                 # Idle timeout handler
├── config.env                       # Your configuration
├── hooks.log                        # Execution logs
└── state/                           # Per-session state (JSON)
```

---

## Team Collaboration

Everyone installs under their own GitHub account. Want to share session visibility? Just invite teammates to your GitHub Project.

**How to invite**
1. Go to your GitHub Project page
2. Click **...** (menu) → **Settings**
3. Select **Manage access**
4. Click **Invite collaborators** and add people

Now the whole team can see session activity across all projects in one board.

---

## Uninstall

```bash
npx claude-session-tracker uninstall
```

Removes hooks, config, state files, and logs. Your GitHub repository and project board are not deleted — the repository is archived and the project is closed so your session history is preserved. Doesn't touch your other hooks.

---

## Known Issues

**Async hook completion messages showing up in Claude Code**

You might see this after every prompt/response —
```
⎿  Async hook UserPromptSubmit completed
⎿  Async hook Stop completed
```

That's Claude Code, not us. All hooks run with `async: true` so they don't block you, and Claude Code just doesn't have an option to hide these yet.

Tracked upstream — [anthropics/claude-code#32551](https://github.com/anthropics/claude-code/issues/32551)

---

## Contributing

Found a bug? Got an idea? PRs and issues are always welcome.

---

## License

MIT

claude-session-tracker

claude-session-tracker Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

claude-session-tracker

claude-session-tracker Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README