\n\n \n\n
` | `-l` | Status label language (`en`, `ko`, `ja`, `zh`) |\n| `--version` | `-v` | Print version and exit |\n\n---\n\n### Key features\n\n- One issue per session — your whole conversation in one place\n- Prompts and responses saved automatically\n- GitHub Projects board for at-a-glance status\n- Searchable, shareable, permanent\n\n## Custom date fields\n\nThe installer adds two date fields — `Created` (when a session starts) and `Last Active` (updated on every prompt).\n\nGitHub'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.\n\n![\"image\"](\"https://github.com/user-attachments/assets/c5cc4d4e-6f1f-4847-a901-9098af1db852\")
\n\n---\n\n## What It Does\n\nEvery time you chat with Claude Code, the tracker kicks in —\n\n- Creates a GitHub Issue for the session\n- Logs every prompt and every response\n- Issue title always reflects your most recent prompt — easy to scan at a glance\n- Records which repository you were working in as a GitHub label (e.g. `ej31/my-app`)\n- Tracks status — Registered, Responding, Waiting, Closed\n- Auto-assigns issues to you\n- Timestamps everything\n- Auto-closes idle sessions (default 30 min)\n- Health checks with `status` and `doctor` commands\n- Pause/resume tracking whenever you want\n- Auto-update notifications when a new version is available\n\nInstall once, then just use Claude Code like normal. That's literally it.\n\n---\n\n## Why?\n\nClaude Code sessions vanish when they end.\n\nJuggling multiple projects? Good luck remembering what you decided, what Claude suggested, or where you left off.\n\n**claude-session-tracker** dumps your entire conversation history into GitHub Projects. Search it, share it, never lose it.\n\n---\n\n## How It Works\n\n| Claude Code Event | GitHub Status | What Happens |\n|---|---|---|\n| Session starts | Registered | Issue created, added to Project |\n| You submit prompt | Responding | Prompt saved, title updated |\n| Claude responds | Waiting | Response saved, idle timer starts |\n| Timer expires | Closed | Session auto-closed |\n\nAll hooks run async — zero slowdown.\n\n### Features\n\n**Session URL notification**\n\nSession starts, you get a link —\n```\nThis session is being tracked at https://github.com/you/repo/issues/42\n```\n\n**Smart title updates**\n\nEvery 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.\n```\nFix session resume bug\n```\n\n**Repository label**\n\nThe 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.\n\n**Resume without duplicates**\n\n`claude --resume`? The tracker reuses the same issue. No duplicates.\n\n**Git remote auto-detection**\n\nGot a GitHub remote? The tracker picks up `owner/repo` automatically. No remote? Falls back to your storage repo.\n\n**Zero blocking**\n\nHooks are async. Claude never waits on the tracker.\n\n**Built-in recovery and health checks**\n\nSetup died halfway? Just re-run it — the installer picks up where it left off. After install, check things with —\n\n```bash\nclaude-session-tracker status\nclaude-session-tracker doctor\n```\n\n`status` for a quick local check, `doctor` for a deep GitHub-backed diagnosis.\n\n**Pause / resume tracking**\n\nWorking on something sensitive? Kill the logging —\n\n```bash\nclaude-session-tracker pause\nclaude-session-tracker resume\n```\n\n`pause` stops all logging and marks the project `INACTIVE`. `resume` flips it back to `ON_TRACK`.\n\nEvery state change gets recorded as a project status update — session ID, workspace path, issue URL, timestamp, IP address. Full audit trail.\n\nIf someone marks the card `INACTIVE` from the GitHub web UI, the hooks detect it and stop logging until it's switched back.\n\n**Privacy protection**\n\nSession data may contain sensitive information — API keys, file paths, internal logic. The tracker enforces private storage at every step.\n\nIf the repository or project board visibility is changed to public, the installer detects this on re-run and takes automatic action.\n\n- Repository made public → switched back to private and archived, then a new private repository is created\n- Project board made public → closed, then a new private project is created\n\nThe original data is never deleted. Archived repositories become read-only and closed projects stop receiving updates until explicitly reopened.\n\n**Auto-update**\n\nWhen 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 —\n\n```bash\nclaude-session-tracker update\n```\n\n---\n\n## Use Cases\n\n**Personal context log**\nNever forget what you discussed. Search GitHub Projects, find any session in seconds.\n\n**Team collaboration**\nShare a Project with your team. Everyone sees what Claude is doing across all repos. Great for reviews and onboarding.\n\n**Session handoff**\nLeft off yesterday? Resume tomorrow with full context. No duplicates.\n\n**Audit trail**\nTrack everything Claude did, when, and why. Useful for reviews and figuring out what actually worked.\n\n---\n\n## Prerequisites\n\n- Node.js 18+\n- Python 3\n- **GitHub CLI (`gh`)** — grab it from https://cli.github.com\n\n ```bash\n # macOS\n brew install gh\n\n # Login with required scopes\n gh auth login --scopes \"project,repo\"\n ```\n\n Needs `project` (read/write Projects) and `repo` (create issues, comments) scopes.\n\n---\n\n## Configuration\n\nRe-run the installer or edit `~/.claude/hooks/config.env` directly —\n\n```bash\nnpx claude-session-tracker\n```\n\nConfig file format\n```env\nGITHUB_PROJECT_OWNER=your-username\nGITHUB_PROJECT_NUMBER=1\nGITHUB_PROJECT_ID=PVT_...\nGITHUB_STATUS_FIELD_ID=PVTSSF_...\nGITHUB_STATUS_REGISTERED=...\nGITHUB_STATUS_RESPONDING=...\nGITHUB_STATUS_WAITING=...\nGITHUB_STATUS_CLOSED=...\nNOTES_REPO=your-username/claude-session-storage\nDONE_TIMEOUT_SECS=1800\nCST_PROJECT_NAME_MODE=label\n```\n\n---\n\n## Under the Hood\n\nFiles installed to `~/.claude/hooks/`\n```\n~/.claude/hooks/\n├── cst_github_utils.py # Shared utilities\n├── cst_session_start.py # SessionStart hook\n├── cst_prompt_to_github_projects.py # UserPromptSubmit hook\n├── cst_post_tool_use.py # PostToolUse hook\n├── cst_session_stop.py # Stop hook\n├── cst_session_end.py # SessionEnd hook\n├── cst_mark_done.py # Idle timeout handler\n├── config.env # Your configuration\n├── hooks.log # Execution logs\n└── state/ # Per-session state (JSON)\n```\n\n---\n\n## Team Collaboration\n\nEveryone installs under their own GitHub account. Want to share session visibility? Just invite teammates to your GitHub Project.\n\n**How to invite**\n1. Go to your GitHub Project page\n2. Click **...** (menu) → **Settings**\n3. Select **Manage access**\n4. Click **Invite collaborators** and add people\n\nNow the whole team can see session activity across all projects in one board.\n\n---\n\n## Uninstall\n\n```bash\nnpx claude-session-tracker uninstall\n```\n\nRemoves 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.\n\n---\n\n## Known Issues\n\n**Async hook completion messages showing up in Claude Code**\n\nYou might see this after every prompt/response —\n```\n⎿ Async hook UserPromptSubmit completed\n⎿ Async hook Stop completed\n```\n\nThat'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.\n\nTracked upstream — [anthropics/claude-code#32551](https://github.com/anthropics/claude-code/issues/32551)\n\n---\n\n## Contributing\n\nFound a bug? Got an idea? PRs and issues are always welcome.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}