{"id":37342247,"url":"https://github.com/hex/claude-sessions","last_synced_at":"2026-04-04T21:05:42.135Z","repository":{"id":325922572,"uuid":"1102933015","full_name":"hex/claude-sessions","owner":"hex","description":"Session manager for Claude Code with automatic documentation and artifact tracking","archived":false,"fork":false,"pushed_at":"2026-01-20T08:22:46.000Z","size":181,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-20T18:10:15.860Z","etag":null,"topics":["anthropic","anthropic-claude","claude","claude-ai","claude-code","cli","developer-tools","documentation","session-manager","terminal","terminal-app","workflow"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-24T08:19:11.000Z","updated_at":"2026-01-20T08:22:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hex/claude-sessions","commit_stats":null,"previous_names":["hex/claude-sessions"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hex/claude-sessions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex%2Fclaude-sessions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex%2Fclaude-sessions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex%2Fclaude-sessions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex%2Fclaude-sessions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hex","download_url":"https://codeload.github.com/hex/claude-sessions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hex%2Fclaude-sessions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28635123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T14:50:40.221Z","status":"ssl_error","status_checked_at":"2026-01-21T14:48:59.225Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","anthropic-claude","claude","claude-ai","claude-code","cli","developer-tools","documentation","session-manager","terminal","terminal-app","workflow"],"created_at":"2026-01-16T03:52:04.506Z","updated_at":"2026-04-04T21:05:42.116Z","avatar_url":"https://github.com/hex.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cs - Claude Code Session Manager\n\nA session manager for [Claude Code](https://github.com/anthropics/claude-code) that creates isolated workspaces with automatic documentation and artifact tracking.\n\n![cs session demo](assets/screenshot.png)\n\n## Why cs?\n\nClaude Code doesn't require a project. You can spin up an instance to debug an API, troubleshoot home automation, research a hardware problem, or explore any idea that comes to mind.\n\nBut conversations get lost. You discover key insights, create useful scripts, figure out a tricky configuration - then the session ends and it's gone.\n\n**cs gives every task a home:**\n\n```bash\ncs debug-api          # Investigate that flaky endpoint\ncs homeassistant      # Fix your smart home setup\ncs router-config      # Document your network settings\ncs research-llms      # Explore a topic, keep your notes\n```\n\nEach session is a persistent workspace - documentation, artifacts, and secrets that survive across conversations and sync across machines.\n\nNo git repo required. No project structure needed. Just a name for what you're working on.\n\n## Features\n\n- **Isolated session workspaces** - Each session has its own directory with structured documentation\n- **Automatic artifact tracking** - Scripts and configs are auto-saved to `artifacts/`\n- **Secure secrets handling** - Sensitive data auto-detected and stored in OS keychain; sync across machines with [age](https://github.com/FiloSottile/age) public-key encryption\n- **Documentation templates** - Pre-configured markdown files for discoveries and changes\n- **Discoveries archival** - Automatic rotation of large discovery files before context compaction, with LLM-powered condensation via `/compact-discoveries`\n- **Automatic git version control** - Every session gets local git history; discovery edits are autosaved to a shadow ref for crash safety, session end creates one clean commit; optionally sync to remote\n- **Session locking** - PID-based lock prevents the same session from being opened in two terminals simultaneously; use `--force` to override\n- **Remote sessions** - Run sessions on remote machines via `et` or `ssh` + `tmux`; `cs` handles connection, stubbing, and session tracking\n- **CLI command capture** - Interesting commands auto-tracked to `.cs/commands.md` with secret scrubbing; frequently used commands can be promoted to reusable skills via `/skillify`\n- **Cross-session search** - `cs -search \u003cquery\u003e` greps across all sessions' discoveries, memory, README, and changes\n- **Bash command audit trail** - Every Bash command Claude runs is logged to `.cs/logs/session.log` with timestamps\n- **Update notifications** - Checks for updates and notifies when new versions are available\n- **Verified updates** - Updates are downloaded from GitHub Releases and verified with SHA-256 checksums; additionally verified with [minisign](https://jedisct1.github.io/minisign/) signatures when available\n\n## Installation\n\n### Bash (macOS/Linux)\n\n```bash\nbash -c \"$(curl -fsSL https://raw.githubusercontent.com/hex/claude-sessions/main/install.sh)\"\n```\n\nOr clone and run `./install.sh`.\n\n\u003e :warning: Always review [install.sh](install.sh) before running scripts from the internet.\n\nThe installer:\n- Adds `cs`, `cs-secrets`, and `cs-tui` to `~/.local/bin/`\n- Installs twelve [hooks](docs/hooks.md) to `~/.claude/hooks/` for session tracking\n- Adds `/summary`, `/compact-discoveries`, and `/skillify` commands, and `store-secret` skill to `~/.claude/`\n- Installs shell completions for bash and zsh\n- Configures hook entries in `~/.claude/settings.json`\n\n## Usage\n\n```bash\ncs                          # Interactive session manager (TUI)\ncs \u003csession-name\u003e           # Create or resume a session\ncs \u003csession-name\u003e --force   # Override active session lock\ncs -adopt \u003cname\u003e            # Adopt current directory as a session\ncs -remote \u003ccmd\u003e            # Manage remote hosts\ncs -search \u003cquery\u003e          # Search across all sessions\ncs -list, -ls               # List all sessions\ncs -remove, -rm \u003cname\u003e      # Remove a session\ncs -update                  # Update to latest version\ncs -uninstall               # Uninstall cs\ncs -help, -h                # Show help message\ncs -version, -v             # Show version\n```\n\n### Interactive Session Manager\n\nRunning `cs` with no arguments launches an interactive TUI for browsing and managing sessions:\n\n- **Navigate** with `j`/`k` or arrow keys; `g`/`G` for first/last; mouse scroll and click supported\n- **Sort** by column with `1`-`6` (toggles ascending/descending)\n- **Fuzzy search** with `/` — matches characters in order with highlighting; Enter commits the filter\n- **Time-based sections** — sessions grouped under Today, Yesterday, This Week, This Month, Older when sorted by date\n- **Action bar** with `Enter` — inline bar shows available actions with shortcut keys\n- **Preview pane** — appears automatically on wide terminals (\u003e120 cols); toggle with `p`\n- **Expand row** with `Tab` — shows session objective, discoveries, and artifact count inline\n- **Create session** with `n` — opens inline dialog to create a new session\n- **Delete** with `d` (confirmation required)\n- **Batch operations** — mark sessions with `Space`, then `D` to batch delete\n- **Rename** with `r`\n- **Move to remote** with `m` (local sessions only)\n- **Manage secrets** with `s` (view values with `v`, auto-redacts after 5 seconds)\n- **Async sync** with `P` (push), `L` (pull), `S` (status) — runs in background with spinner; `Esc` to cancel\n- **Quit** with `q` or `Esc`\n\nThe TUI requires `cs-tui` (an ~817 KB Rust binary). Build from source: `cd tui \u0026\u0026 cargo build --release`.\n\n### Session Commands\n\n```bash\ncs \u003csession\u003e -sync, -s \u003ccmd\u003e  # Sync with git remote\ncs \u003csession\u003e -secrets \u003ccmd\u003e   # Manage secrets\ncs \u003csession\u003e --on \u003chost\u003e      # Run on remote host\ncs \u003csession\u003e --move-to \u003chost\u003e # Move session to remote host\ncs \u003csession\u003e --force          # Override active session lock\n```\n\n### Examples\n\n```bash\ncs debug-api                # Create/resume 'debug-api' session\ncs fix-auth -sync remote \u003curl\u003e # Initialize sync for session\ncs my-project -secrets list # List secrets for session\n```\n\n### Adopting Existing Projects\n\nAlready working in a project directory with Claude Code? Use `-adopt` to add cs session management without moving anything:\n\n```bash\ncd ~/my-project\ncs -adopt my-project\n```\n\nThis converts the current directory into a cs session in place:\n- Creates the `.cs/` metadata structure in the current directory\n- Symlinks `~/.claude-sessions/\u003cname\u003e` to the current directory\n- Merges session protocol into existing `CLAUDE.md` if one exists\n- Initializes a git repo if one doesn't exist (preserves existing repos)\n- Since the working directory doesn't change, `claude --continue` picks up previous conversations\n\n### Remote Sessions\n\nRun sessions on a remote machine (e.g., a Mac Mini build server) while keeping `cs SESSION_NAME` as your single entry point. The remote machine needs `cs` and Claude Code installed independently.\n\n**Register a remote host (one-time):**\n\n```bash\ncs -remote add mini hex@mac-mini.local\ncs -remote list\ncs -remote remove mini\n```\n\n**Create or connect to a remote session:**\n\n```bash\ncs my-session --on mini                # using registered name\ncs my-session --on hex@mac-mini.local # inline, no registration needed\ncs hex@mac-mini.local:my-session      # host:session syntax (auto-remembered)\n```\n\nAfter the first connection, `cs my-session` automatically reconnects to the remote host.\n\n**Move an existing local session to remote:**\n\n```bash\ncs my-session --move-to mini\n```\n\nThis rsyncs the session to the remote host and creates a local stub so future `cs my-session` calls connect remotely.\n\n**Transport:** Prefers [Eternal Terminal](https://eternalterminal.dev/) (`et`) when available, falls back to `ssh`. Sessions are wrapped in `tmux` on the remote side.\n\n**Listing:** `cs -ls` shows a LOCATION column when remote sessions exist.\n\n**Note:** `-sync` and `-secrets` commands are not available on remote sessions. Connect to the remote session first, then run them from within.\n\n## Session Structure\n\n```\n~/.claude-sessions/\u003csession-name\u003e/\n├── .cs/                    # Session metadata\n│   ├── README.md           # Objective, environment, outcome\n│   ├── discoveries.md      # Recent findings and observations\n│   ├── discoveries.archive.md  # Archived historical entries\n│   ├── discoveries.compact.md  # LLM-condensed archive summary\n│   ├── changes.md          # Auto-logged file modifications\n│   ├── sync.conf           # Sync configuration\n│   ├── remote.conf         # Remote host (if remote session)\n│   ├── memory/             # Claude Code auto memory (synced)\n│   ├── plans/              # Claude Code plans (synced)\n│   ├── commands.md         # Auto-discovered CLI commands\n│   ├── artifacts/          # Auto-tracked scripts and configs\n│   └── logs/session.log    # Bash command audit trail + session log\n├── .claude/\n│   └── settings.local.json # Redirects auto memory into .cs/memory\n├── CLAUDE.md               # Session instructions for Claude\n└── [your project files]    # Clean workspace\n```\n\nClaude Code's [auto memory](https://code.claude.com/docs/en/memory) is redirected into `.cs/memory/` via `CLAUDE_CODE_AUTO_MEMORY_PATH` env var (set at launch) and `.claude/settings.local.json` (for future compatibility). This means auto memory is synced across machines with `cs -sync` and cleaned up with `cs -rm`.\n\n## Configuration\n\nAdd to `~/.bashrc` or `~/.zshrc`:\n\n```bash\n# Sessions directory (default: ~/.claude-sessions)\nexport CS_SESSIONS_ROOT=\"/path/to/sessions\"\n\n# Git sync prefix for shorter commands\nexport CS_SYNC_PREFIX=\"git@github.com:youruser/\"\n\n# Legacy password for secrets sync (age encryption preferred - see docs/secrets.md)\nexport CS_SECRETS_PASSWORD=\"your-secure-password\"\n\n# Override secrets backend (keychain or encrypted)\nexport CS_SECRETS_BACKEND=\"keychain\"\n\n# Override Claude Code binary (default: claude)\nexport CLAUDE_CODE_BIN=\"claude\"\n\n# Use Nerd Font icons (requires a Nerd Font in your terminal)\nexport CS_NERD_FONTS=\"1\"\n\n# Disable colors (see https://no-color.org)\nexport NO_COLOR=\"1\"\n```\n\nThe following environment variables are set automatically when you start a session:\n\n- `CLAUDE_SESSION_NAME` - The session name (e.g., `myproject`)\n- `CLAUDE_SESSION_DIR` - Full path to the session directory (workspace root)\n- `CLAUDE_SESSION_META_DIR` - Path to the `.cs/` metadata directory\n- `CLAUDE_ARTIFACT_DIR` - Path to the artifacts subdirectory (`.cs/artifacts`)\n- `CLAUDE_CODE_TASK_LIST_ID` - Set to the session name for task list persistence\n\n## Shell Completion\n\nTab completion for session names and commands is installed automatically. To enable it:\n\n**Bash** - Add to `~/.bashrc`:\n```bash\n[[ -f ~/.bash_completion.d/cs.bash ]] \u0026\u0026 source ~/.bash_completion.d/cs.bash\n```\n\n**Zsh** - Add to `~/.zshrc` (before `compinit`):\n```bash\nfpath=(~/.zsh/completions $fpath)\nautoload -Uz compinit \u0026\u0026 compinit\n```\n\nThen restart your shell or run `source ~/.bashrc` / `source ~/.zshrc`.\n\nCompletions support:\n- Session names: `cs home\u003cTAB\u003e` → `cs homeassistant`\n- Global flags: `cs -\u003cTAB\u003e` → `-list`, `-sync`, `-secrets`, etc.\n- Sync commands: `cs session -sync \u003cTAB\u003e` → `remote`, `push`, `pull`, etc.\n- Secrets commands: `cs session -secrets \u003cTAB\u003e` → `set`, `get`, `list`, etc.\n\n## Documentation\n\n- **[Hooks](docs/hooks.md)** - How the Claude Code hooks work\n- **[Secrets](docs/secrets.md)** - Secure secrets handling and storage backends\n- **[Sync](docs/sync.md)** - Git-based session sync across machines\n\n## Requirements\n\n- [Claude Code](https://github.com/anthropics/claude-code)\n- Bash 4.0+\n- `jq` for hook configuration\n- `git` for session sync\n\n## Uninstalling\n\n```bash\ncs -uninstall\n```\n\n## See also\n\n- [iTerm2-dimmer](https://github.com/hex/iTerm2-dimmer) -- dims noisy hook output (TASKMASTER, discoveries) in iTerm2 so it doesn't clutter the screen\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please open an issue or PR.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhex%2Fclaude-sessions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhex%2Fclaude-sessions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhex%2Fclaude-sessions/lists"}