{"id":34226333,"url":"https://github.com/fgrehm/clotilde","last_synced_at":"2026-02-23T23:28:22.866Z","repository":{"id":327617947,"uuid":"1108354339","full_name":"fgrehm/clotilde","owner":"fgrehm","description":"A CLI for managing named Claude Code sessions, with support for forking.","archived":false,"fork":false,"pushed_at":"2025-12-04T17:18:26.000Z","size":143,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-08T01:28:36.473Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/fgrehm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","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-12-02T10:50:40.000Z","updated_at":"2025-12-05T07:08:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fgrehm/clotilde","commit_stats":null,"previous_names":["fgrehm/clotilde"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fgrehm/clotilde","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fclotilde","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fclotilde/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fclotilde/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fclotilde/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fgrehm","download_url":"https://codeload.github.com/fgrehm/clotilde/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgrehm%2Fclotilde/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28394270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: 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":[],"created_at":"2025-12-16T00:23:26.112Z","updated_at":"2026-02-23T23:28:22.859Z","avatar_url":"https://github.com/fgrehm.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clotilde\n\nNamed sessions, profiles, and context management for Claude Code.\n\n\u003e **Documentation**: For the latest stable release, see [Clotilde on the `stable` branch](https://github.com/fgrehm/clotilde/tree/stable). This `main` branch contains development changes and may include features not yet released.\n\n## About the Name\n\nA traditional Brazilian name - sometimes considered old-fashioned or humorous - which adds a light, unpretentious personality to the tool. Pronounced more or less like **KLOH-teel-dee** (Portuguese-ish).\n\n## Why?\n\nClaude Code is great for single conversations, but as you start juggling multiple parallel sessions in the same project, things get painful:\n\n- **Session naming is unreliable**: Claude Code has `/rename`, but names don't persist across resumes, can't be used with `--resume \u003cname\u003e`, and get overwritten by auto-generated slugs. There's no way to name a session at startup either.\n- **The resume picker doesn't scale**: Fine for 2-3 sessions, but with more it shows unhelpful text like \"This session is being continued from a previous conversation that ran out of context...\" Which one was your auth work again?\n- **No per-session configuration**: Want to use Haiku for a quick question and Opus for deep feature work? You have to change settings globally or pass flags every time.\n- **No persistent context injection**: There's no built-in way to feed the same background context (ticket info, project conventions, task goals) into every session automatically.\n- **Forking is low-level**: `--fork-session` and `/fork` exist but require knowing UUIDs, have no named fork tracking, and don't record parent/child relationships. There's no way to fork by name.\n\n## What Clotilde does\n\nClotilde is a thin wrapper around Claude Code that adds named sessions, profiles, context management, and user-friendly forking.\n\n```bash\n# Named sessions you can instantly switch between\nclotilde start auth-feature\nclotilde start bugfix-db-timeout\nclotilde resume auth-feature\n\n# Fork a session to explore a tangent\nclotilde fork auth-feature auth-alternative-approach\n\n# Incognito sessions that auto-delete on exit\nclotilde incognito quick-question\n\n# Profiles for different workflows\nclotilde start review --profile strict     # deny Bash/Write permissions\nclotilde start spike --profile quick       # use Haiku, bypass permissions\n```\n\nSession names are stored as external name-to-UUID mappings, so they work reliably regardless of Claude Code's internal naming behavior. Profiles let you define reusable presets (model, permissions, output style) in a single config file. Context files are automatically injected at session start via hooks.\n\n## How It Works\n\nClotilde never patches or modifies Claude Code.\n\n- Each session is a folder in `.claude/clotilde/sessions/\u003cname\u003e/` containing metadata, optional settings, and system prompt files\n- SessionStart hooks handle fork registration, `/clear` UUID tracking, and context injection\n- Claude Code is invoked with `--session-id`, `--resume`, `--settings`, and `--append-system-prompt-file` flags\n\n**Note on worktrees:** Since `.claude/clotilde/` lives in each worktree's `.claude/` directory, each worktree gets its own independent sessions and context. Use worktrees for major branches/features, use Clotilde for managing multiple conversations within each worktree.\n\n## Installation\n\n**Download binary** (recommended)\n\nDownload the latest release for your platform from [GitHub Releases](https://github.com/fgrehm/clotilde/releases).\n\n**Go install:**\n```bash\ngo install github.com/fgrehm/clotilde@latest\n```\n\n**Build from source:**\n```bash\ngit clone https://github.com/fgrehm/clotilde\ncd clotilde\nmake build\nmake install  # Installs to ~/.local/bin\n```\n\n## Quick Start\n\n```bash\n# Initialize in your project\nclotilde init\n\n# Start a new named session\nclotilde start auth-feature\n\n# Resume it later\nclotilde resume auth-feature\n\n# List all sessions\nclotilde list\n\n# Inspect a session\nclotilde inspect auth-feature\n\n# Fork a session to try something different\nclotilde fork auth-feature experiment\n\n# Delete when done\nclotilde delete experiment\n```\n\n## Incognito Sessions\n\nIncognito sessions automatically delete themselves when you exit. See [`clotilde incognito`](#clotilde-incognito-name-options) for usage.\n\n**Note:** Cleanup runs on normal exit (Ctrl+D, `/exit`). If the process crashes or is killed (SIGKILL), the session may persist. Use `clotilde delete \u003cname\u003e` to clean up manually.\n\n**Limitations:**\n- Cannot fork FROM incognito sessions (they'll auto-delete when you exit)\n- CAN fork TO incognito sessions (create an incognito fork of a regular session)\n\n## Session Context\n\nAttach context to a session so Claude knows what you're working on:\n\n```bash\n# Set context when starting a session\nclotilde start auth-feature --context \"working on ticket GH-123\"\n\n# Works with incognito and fork too\nclotilde incognito --fast --context \"quick spike on caching\"\nclotilde fork auth-feature experiment --context \"trying JWT instead of sessions\"\n\n# Update context when resuming\nclotilde resume auth-feature --context \"now on GH-456\"\n```\n\nContext is stored in session metadata and automatically injected into Claude at session start (alongside the session name). Forked sessions inherit context from the parent unless overridden with `--context`.\n\nUse `clotilde inspect \u003cname\u003e` to see a session's current context.\n\n## Shorthand Flags\n\nCommon permission modes and presets have short, memorable flags available on all session commands (`start`, `incognito`, `resume`, `fork`):\n\n```bash\n# Permission mode shortcuts\nclotilde start refactor --accept-edits    # auto-approve edits, ask for the rest\nclotilde incognito --yolo                 # bypass all permission checks\nclotilde start spike --plan               # plan mode\nclotilde resume my-session --dont-ask     # approve everything\n\n# Fast mode (haiku + low effort)\nclotilde start quick-check --fast\nclotilde incognito --fast --yolo          # quick throwaway, no prompts\n\n# Works on resume and fork too\nclotilde resume my-session --fast\nclotilde fork my-session experiment --accept-edits\n```\n\n**Permission shortcuts** (`--accept-edits`, `--yolo`, `--plan`, `--dont-ask`) are mutually exclusive with each other and with `--permission-mode`.\n\n**`--fast`** sets `--model haiku` and `--effort low`. Cannot be combined with `--model`.\n\n## Pass-Through Flags\n\nPass additional Claude Code flags directly using `--` separator:\n\n```bash\n# Debug mode\nclotilde start my-session -- --debug api,hooks\n\n# Verbose output\nclotilde resume my-session -- --verbose\n\n# Multiple flags\nclotilde incognito test -- --debug --permission-mode plan\n```\n\n**Common use cases:**\n- `--debug [filter]` - Debug specific categories (api, hooks, mcp, etc.)\n- `--verbose` - Verbose output\n- `--permission-mode \u003cmode\u003e` - Override permission mode (acceptEdits, plan, etc.)\n- `--dangerously-skip-permissions` - Bypass permissions (for sandboxed environments)\n- `--print` - Non-interactive output for scripting\n- `--output-format json` - JSON output\n\n**Note:** These flags are passed directly to Claude Code for that session only. To persist settings across sessions, use the `--model` flag or configure `settings.json`.\n\n## Session Profiles\n\nDefine named presets for common session configurations. Use `--profile \u003cname\u003e` when creating sessions to apply a profile's settings.\n\nProfiles can be defined in two locations:\n\n- **Global**: `~/.config/clotilde/config.json` (respects `$XDG_CONFIG_HOME`) - available in all projects\n- **Project**: `.claude/clotilde/config.json` - scoped to a single project\n\nWhen both define a profile with the same name, the project version wins.\n\n```json\n{\n  \"profiles\": {\n    \"quick\": {\n      \"model\": \"haiku\",\n      \"permissionMode\": \"bypassPermissions\"\n    },\n    \"strict\": {\n      \"permissions\": {\n        \"deny\": [\"Bash\", \"Write\"],\n        \"defaultMode\": \"ask\"\n      }\n    },\n    \"research\": {\n      \"model\": \"sonnet\",\n      \"outputStyle\": \"Explanatory\"\n    }\n  }\n}\n```\n\n**Profile fields:**\n- `model` - Claude model (haiku, sonnet, opus)\n- `permissionMode` - Permission mode (acceptEdits, bypassPermissions, default, dontAsk, plan)\n- `permissions` - Granular permissions:\n  - `allow` - Tools Claude can always use\n  - `deny` - Tools Claude cannot use\n  - `ask` - Tools that require approval\n  - `additionalDirectories` - Extra directories Claude can access\n  - `defaultMode` - Default action for tools not in allow/deny/ask (ask, allow, or deny)\n  - `disableBypassPermissionsMode` - Disable permission bypass (boolean)\n- `outputStyle` - Output style (built-in or custom name)\n\n**Usage examples:**\n\n```bash\n# Apply \"quick\" profile (haiku + bypass permissions)\nclotilde start spike --profile quick\n\n# Apply \"strict\" profile (deny Bash/Write, ask mode)\nclotilde start sandboxed --profile strict\n\n# Combine profiles with CLI flags (CLI flags win)\nclotilde start research --profile quick --model sonnet\n\n# Use profile on incognito sessions\nclotilde incognito --profile quick\n```\n\n**Precedence:** Global profile → project profile → CLI flags (each layer overrides the previous). For example, `--profile quick --model opus` uses the quick profile's settings but replaces its model with opus.\n\n## Output Styles\n\nCustomize how Claude communicates in each session using built-in or custom output styles:\n\n```bash\n# Built-in styles\nclotilde start myfeature --output-style default\nclotilde start myfeature --output-style Explanatory\nclotilde start myfeature --output-style Learning\n\n# Existing project/user styles (by name)\nclotilde start myfeature --output-style my-project-style\nclotilde start myfeature --output-style my-personal-style\n\n# Custom inline content (creates new session-specific style)\nclotilde start myfeature --output-style \"Be concise and use bullet points\"\n\n# Custom from file (creates new session-specific style)\nclotilde start myfeature --output-style-file ./my-style.md\n```\n\n**How `--output-style` flag works:**\n1. Checks if value matches existing style in `.claude/output-styles/` or `~/.claude/output-styles/`\n2. If found, uses that style (no new file created)\n3. Else checks if value is a built-in style (`default`, `Explanatory`, `Learning`)\n4. Otherwise treats value as inline content and creates `.claude/output-styles/clotilde/\u003csession-name\u003e.md`\n\n**Note:** Case sensitivity matters! `\"default\"` is lowercase, `\"Explanatory\"` and `\"Learning\"` are capitalized.\n\n**Storage:** Session-specific custom styles are stored in `.claude/output-styles/clotilde/\u003csession-name\u003e.md` and should be gitignored (much like `.claude/clotilde`, they're ephemeral per-user customizations). Team members can share output styles by placing them in `.claude/output-styles/` (without the `clotilde/` subdirectory) and committing them to git.\n\n## Commands\n\n### `clotilde init [--global]`\n\nInitialize clotilde in the current project. Creates `.claude/clotilde/` directory and configures hooks.\n\nBy default, hooks are installed in `.claude/settings.local.json` (local to your machine, not committed to git). Use `--global` to install hooks in `.claude/settings.json` instead (shared with team, committed to git).\n\n```bash\n# Initialize with local hooks (default - recommended for experimental use)\nclotilde init\n\n# Initialize with project-wide hooks (team shares clotilde setup)\nclotilde init --global\n```\n\n**Why settings.local.json by default?**\n- Clotilde is experimental - people can try it without affecting team members\n- `.local.json` files are typically gitignored, keeping your config private\n- Team members who don't use clotilde won't see the hooks in project settings\n\n**Note:** The `.claude/clotilde/` directory (containing session metadata, transcripts paths, and context) should be gitignored. This is intentional - sessions are ephemeral, per-user state that shouldn't be committed to the repository. Each developer maintains their own independent session list.\n\n### `clotilde start \u003cname\u003e [options]`\n\nStart a new named session.\n\n```bash\n# Basic usage\nclotilde start my-session\n\n# With profile\nclotilde start spike --profile quick\nclotilde start sandboxed --profile strict\n\n# With custom model\nclotilde start bugfix --model haiku\n\n# Profile + CLI flag override\nclotilde start research --profile quick --model sonnet\n\n# With custom system prompt (append to default)\nclotilde start refactoring --append-system-prompt-file prompts/architect.md\nclotilde start review --append-system-prompt \"Be critical and thorough\"\n\n# Replace Claude's default system prompt entirely\nclotilde start minimal --replace-system-prompt-file prompts/custom.md\nclotilde start focused --replace-system-prompt \"You are a focused coding assistant\"\n\n# Create incognito session\nclotilde start quick-test --incognito\n\n# With permissions\nclotilde start sandboxed --permission-mode plan \\\n  --allowed-tools \"Read,Bash(npm:*)\" \\\n  --disallowed-tools \"Write\" \\\n  --add-dir \"../docs\"\n\n# Combine options\nclotilde start research --model haiku --append-system-prompt \"Focus on exploration\"\n```\n\n**Options:**\n- `--profile \u003cname\u003e` - Named profile from config (applies model, permissions, and output style as baseline)\n- `--model \u003cmodel\u003e` - Model to use (haiku, sonnet, opus). CLI flag overrides profile.\n- `--fast` - Use haiku model with low effort for quick tasks\n- `--append-system-prompt \u003ctext\u003e` - Add system prompt text (appends to Claude's default)\n- `--append-system-prompt-file \u003cpath\u003e` - Add system prompt from file (appends to Claude's default)\n- `--replace-system-prompt \u003ctext\u003e` - Replace Claude's default system prompt entirely with custom text\n- `--replace-system-prompt-file \u003cpath\u003e` - Replace Claude's default system prompt entirely with file contents\n- `--context \u003ctext\u003e` - Session context (e.g. \"working on ticket GH-123\"). Injected into Claude at session start.\n- `--incognito` - Create incognito session (auto-deletes on exit)\n- `--accept-edits` - Shorthand for `--permission-mode acceptEdits`\n- `--yolo` - Shorthand for `--permission-mode bypassPermissions`\n- `--plan` - Shorthand for `--permission-mode plan`\n- `--dont-ask` - Shorthand for `--permission-mode dontAsk`\n- `--permission-mode \u003cmode\u003e` - Permission mode (acceptEdits, bypassPermissions, default, dontAsk, plan). CLI flag overrides profile.\n- `--allowed-tools \u003ctools\u003e` - Comma-separated list of allowed tools (e.g. `Bash(npm:*),Read`). CLI flag overrides profile.\n- `--disallowed-tools \u003ctools\u003e` - Comma-separated list of disallowed tools (e.g. `Write,Bash(git:*)`). CLI flag overrides profile.\n- `--add-dir \u003cdirectories\u003e` - Additional directories to allow tool access to. CLI flag overrides profile.\n- `--output-style \u003cstyle\u003e` - Output style: `default`, `Explanatory`, `Learning`, existing style name, or custom content. CLI flag overrides profile.\n- `--output-style-file \u003cpath\u003e` - Path to custom output style file. CLI flag overrides profile.\n\n### `clotilde incognito [name] [options]`\n\nStart a new incognito session that automatically deletes when you exit. If no name is provided, a random name like \"happy-fox\" or \"brave-wolf\" will be generated.\n\n```bash\n# Random name (e.g., \"clever-owl\")\nclotilde incognito\n\n# Explicit name\nclotilde incognito quick-test\n\n# With model and random name\nclotilde incognito --model haiku\n```\n\n**Options:** Same as `clotilde start` (except `--incognito` is implicit), including `--context`\n\n### `clotilde resume [name] [options]`\n\nResume a session by name. Shorthand flags are passed directly to Claude Code for that invocation.\n\n```bash\nclotilde resume auth-feature\nclotilde resume auth-feature --fast\nclotilde resume auth-feature --accept-edits\nclotilde resume auth-feature --context \"now on GH-456\"\n```\n\n**Options:**\n- `--context \u003ctext\u003e` - Update session context (e.g. \"now working on GH-456\")\n- `--accept-edits`, `--yolo`, `--plan`, `--dont-ask`, `--fast` (see [Shorthand Flags](#shorthand-flags))\n\n### `clotilde list`\n\nList all sessions with details (name, model, last used).\n\n### `clotilde inspect \u003cname\u003e`\n\nShow detailed session information including files, settings, context sources, and Claude Code data status.\n\n```bash\nclotilde inspect auth-feature\n```\n\n### `clotilde fork \u003cparent\u003e [name] [options]`\n\nFork a session to try different approaches without losing the original.\n\nIf no name is provided for incognito forks, a random name will be generated.\n\n```bash\nclotilde fork auth-feature auth-experiment\n\n# Create incognito fork with explicit name\nclotilde fork auth-feature temp-experiment --incognito\n\n# Create incognito fork with random name (e.g., \"clever-owl\")\nclotilde fork auth-feature --incognito\n```\n\n**Options:**\n- `--context \u003ctext\u003e` - Override context for the fork (inherits from parent if not specified)\n- `--incognito` - Create fork as incognito session (auto-deletes on exit)\n- `--accept-edits`, `--yolo`, `--plan`, `--dont-ask`, `--fast` - Shorthand flags (see [Shorthand Flags](#shorthand-flags))\n\n**Note:** You cannot fork FROM incognito sessions, but you can fork TO incognito sessions.\n\n### `clotilde delete \u003cname\u003e [--force]`\n\nDelete a session and all associated Claude Code data (transcripts, agent logs).\n\n**Options:**\n- `--force, -f` - Skip confirmation prompt\n\n### `clotilde completion \u003cshell\u003e`\n\nGenerate shell completion scripts (bash, zsh, fish, powershell). See `clotilde completion --help` for setup instructions.\n\n## Related Work\n\nClaude Code has a `/rename` command, but session names don't persist reliably across resumes, can't be used with `--resume \u003cname\u003e`, and there's no `--session-name` flag for naming at startup. Several open issues track these gaps:\n\n- [#25870](https://github.com/anthropics/claude-code/issues/25870) - `--session-name` flag for naming sessions at startup\n- [#26249](https://github.com/anthropics/claude-code/issues/26249) - `/rename` names not indexed, can't resume by name\n- [#26240](https://github.com/anthropics/claude-code/issues/26240) - Session names lost after resuming and continuing work\n- [#11408](https://github.com/anthropics/claude-code/issues/11408) - Named sessions for easier identification\n\n### Existing solutions\n\n- [**tweakcc**](https://github.com/Piebald-AI/tweakcc) - Patches Claude Code to add custom system prompts, toolsets, themes, and more\n- [**claude-code-session-name**](https://github.com/richardkmichael/claude-code-session-name) - Python wrapper adding `--session-name` flag, stores names in SQLite\n\nClotilde is different because:\n\n- Non-invasive (doesn't patch or modify Claude Code)\n- Native Go binary (no runtime dependencies)\n- Goes beyond naming: profiles, context injection, incognito sessions, forking\n- Built-in cleanup (deletes sessions + associated Claude Code data)\n\n## Development\n\n**Requirements:**\n- Go 1.25+\n- Make\n- golangci-lint v2.x (for linting - matches CI)\n\n**Setup golangci-lint:**\n```bash\n# Install golangci-lint v2.x (required for consistent linting with CI)\ncurl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin\n\n# Verify installation\ngolangci-lint --version  # Should show v2.x\n```\n\n**Configure git hooks** (recommended):\n```bash\nmake setup-hooks\n```\n\nThis enables pre-commit checks that automatically format and lint your code before committing, preventing CI failures.\n\n**Build \u0026 Test:**\n\n```bash\n# Build\nmake build\n\n# Run tests\nmake test\n\n# Run tests with coverage\nmake coverage\n\n# Run tests in watch mode\nmake test-watch\n\n# Format code\nmake fmt\n\n# Lint\nmake lint\n\n# Install locally to ~/.local/bin\nmake install\n```\n\n**Note:** The `make lint` command will warn you if your local golangci-lint version doesn't match CI (v2.x).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgrehm%2Fclotilde","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgrehm%2Fclotilde","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgrehm%2Fclotilde/lists"}