<p align="center"><img src="sessions.png" alt="cc-sessions"></p>
<div align="center">An opinionated approach to productive development with Claude Code</div>
<div align="center"><sub><em>Public good brought to you by GWUDCAP and Three AIrrows Capital</em></sub></div>
<br>
<br>
<div align="center">
[](https://www.npmjs.com/package/cc-sessions)
[](https://www.npmjs.com/package/cc-sessions)
[](https://pypi.org/project/cc-sessions/)
[](https://pepy.tech/project/cc-sessions)
</div>
<div align="center">
[](https://opensource.org/licenses/MIT)
[](https://x.com/AgentofToastX)
[](https://dexscreener.com/solana/oy5mbertfqdytu8atyonycvcvu62fpmz3nkqoztrflq)
</div>
<div align="center"><img src="testimonial-1.png" alt="cc-sessions testimonial" width="60%"></div>
<div align="center"><img src="testimonial-2.png" alt="cc-sessions testimonial" width="60%" align="center"></div>
<br>
## latest updates
<details>
<summary>
latest release - v0.3.0
</summary>
i'm happy to present cc-sessions v0.3.0
<em>it's basically autopilot</em>
**major highlights:**
- **Dual Language Support**: Now available as both Python and Node.js packages with complete feature parity
- **Unified Sessions API**: Single `sessions` command replaces multiple slash commands
- **Natural Language Protocols**: Full workflow automation through trigger phrases (mek:, start^:, finito, squish)
- **Todo Validation System**: Approved todo lists are locked and tracked to prevent scope creep
- **Directory Tasks**: Multi-phase projects with subtasks on shared feature branches
- **Kickstart Tutorial**: Interactive onboarding teaches cc-sessions by using it
- **CI Environment Detection**: Auto-bypass DAIC in GitHub Actions (thanks @oppianmatt)
- **Enhanced Statusline**: Nerd Fonts + git tracking with ahead/behind indicators (thanks @dnviti)
- **Safe Uninstaller**: Interactive removal with automatic backups (thanks @gabelul)
See [CHANGELOG.md](CHANGELOG.md) for complete details.
</details>
<details>
<summary>
Claude Code version issue
</summary
**'ere meh now**: the recommended Claude Code version is **2.0.8** due to an upstream bug in newer versions of Claude Code.
Claude Code versions after 2.0.8 have a bug in their stderr aggregation system that causes 400 API errors when:
- Multiple tool calls execute in parallel (batched in one Claude response)
- Commands generate their own stderr output (e.g., curl progress meters)
- PostToolUse hooks also send stderr feedback (exit code 2)
This breaks cc-sessions' PostToolUse hooks that provide essential feedback like directory navigation confirmations and DAIC mode transitions.
**install the correct version**:
```bash
npm install -g @anthropic-ai/claude-code@2.0.8
```
**related**: [cc-sessions Issue #53](https://github.com/GWUDCAP/cc-sessions/issues/53)
</details>
## installing the extension
You install cc-sessions into a repo from the project root:
```bash
cd ~/my-git-repo && [npx|pipx run] cc-sessions
```
There are Python and Node packages - use whichever you have:
### Python
```bash
# Navigate to the repo you want to
# use cc-sessions in, then...
pipx run cc-sessions
```
### Node
```bash
# Navigate to the repo you want to
# use cc-sessions in, then...
npx cc-sessions
```
<details>
<summary>
### what gets installed
</summary>
The installer sets up:
- Hook files in `sessions/hooks/` for DAIC enforcement
- API commands in `sessions/api/` for state/config management
- Protocol templates in `sessions/protocols/` for workflow automation
- Specialized agents in `.claude/agents/` for heavy operations
- Sessions API wrapper slash command in `.claude/commands`
- Initial state in `sessions/sessions-state.json`
- Configuration in `sessions/sessions-config.json`
- Automatic `.gitignore` entries for runtime files
</details>
### updates and uninstalls/reinstalls
The system automatically preserves your work:
- Creates timestamped backups in `.claude/.backup-YYYYMMDD-HHMMSS/`
- Preserves all task files and agent customizations
- Preserves sessions-config.json
- Restores everything after installation completes
- State file regenerates fresh
<br>
## kickstart: interactive tutorial
You can select whether to take the interactive tutorial at the end of the installer. Its pretty quick and it will fully onboard you if you're new, using cc-sessions to teach you cc-sessions.
The system teaches itself through index-based progression, then cleans up its own onboarding files on graduation.
<br>
## quick start
<details><summary><em>Best way to get started is kickstart, but...</em></summary>
<br>
**After installation (and, optionally, kickstart), use trigger phrases to control workflows:**
```
You: "mek: add user authentication"
Claude: [Creates task with interactive prompts]
You: "start^: @sessions/tasks/h-implement-user-auth.md"
Claude: [Loads context, proposes implementation plan with specific todos]
You: "yert"
Claude: [Implements only the approved todos]
You: "finito"
Claude: [Completes task: commits, merges, cleans up]
```
**These trigger phrases are the defaults.** Add any trigger phrases you like:
```bash
# See current triggers
/sessions config triggers list
# Add your own phrase to any category
/sessions config triggers add go lets do this
# Categories: go, no, create, start, complete, compact
# Slash command API syntax: /sessions [subsystem] [command] [arguments]
# Context-aware help on failed commands - fail away
```
Check `sessions/sessions-config.json` to see all configuration options.
</details>
<br>
## why I made cc-sessions
<details><summary><em>I made cc-sessions to solve what I don't like about AI pair programming...</em></summary>
<br>
If you ask Claude a question he may just start writing code, especially if you are in the middle of a task.
Without additional scaffolding, you are often manually adding files to context for 20% of the context window and being perennially terrified of having to compact context.
The list of things you have to remember can get quite large:
- compact before you run out of tokens
- read every diff before approving
- write task files
- commit changes
- merge branches
- push to remote
- manage which tools Claude can use
- remember to run the right slash commands
The cognitive overhead balloons quickly.
Tasks don't survive restarts. Close Claude Code, reopen it, and you're explaining everything from scratch. No confidence that work will continue cleanly and no structure to how to handle working across context windows.
**You discover problems faster than you can solve them.** Without a standardized, friction-free way to capture tasks, these insights vanish.
When context does get compacted automatically, it doesn't preserve enough detail to inspire confidence.
Most have a CLAUDE.md file stuffed with behavioral rules, some of which are simple where others are complex branching conditional logic.
LLMs are terrible at following long instruction lists throughout an entire conversation. The guidance degrades as the conversation progresses.
Git workflow adds constant friction: creating branches, crafting commit messages, merging when complete, pushing to remote. More cognitive overhead.
**So, cc-sessions fixes all of this.**
</details>
<br>
## features summary
<details><summary><em>click to learn about features...</em></summary>
<br>
### Discussion-Alignment-Implementation-Check (DAIC)
Claude earns the right to write code. By default, Edit, Write, and MultiEdit tools are completely blocked. Before Claude can touch your codebase, he has to discuss his approach, explain his reasoning, and propose specific todos you explicitly approve with trigger phrases like "go ahead" or "make it so" (fully customizable).
Once you approve the plan, Claude loads those exact todos and can only work on what you agreed to. Try to change the plan mid-stream? The system detects it and throws him back to discussion mode. No scope creep. No surprise rewrites. Just the work you approved.
### Task Management That Survives Restarts
Tasks are markdown files with frontmatter that tracks status, branches, and success criteria. The system automatically creates matching git branches, enforces branch discipline (no committing to wrong branches or editing files off branch), and loads complete context when you restart a task days later.
Directory-based tasks support complex multi-phase work with subtask workflows. File-based tasks handle focused objectives. Task indexes let you filter by service area. Everything persists through session restarts.
### Specialized Agents for Heavy Lifting
Five specialized agents run in separate context windows to handle operations that would otherwise burn your main thread:
- **context-gathering** - Analyzes your codebase and creates comprehensive context manifests for each task you create
- **logging** - Consolidates work logs chronologically
- **code-review** - Reviews implementations for quality and patterns
- **context-refinement** - Updates task context based on session discoveries
- **service-documentation** - Maintains CLAUDE.md files for services
Each agent receives the full conversation transcript and returns structured results to your main session.
### Protocols That Automate Workflows
Pre-built protocol templates guide task creation, startup, completion, and context compaction. They adapt automatically based on your configuration—no manual decisions about submodules, commit styles, or git workflows. The protocols just know what you prefer and act accordingly.
All protocols use structured output formats (`[PROPOSAL]`, `[STATUS]`, `[PLAN]`) so you always know when Claude needs your input.
### Sessions API & Slash Commands
Unified `sessions` command provides programmatic access to state, configuration, and task management. Slash commands (`/sessions`) give you quick access through Claude Code's command palette.
Configure trigger phrases, manage git preferences, toggle features, inspect state—everything through a clean API with JSON output support for scripting.
### Interactive Kickstart Onboarding
First install drops you into interactive onboarding with two modes: Full (15-30 min walkthrough of every feature with hands-on exercises) or Subagents-only (5 min agent customization crash course). You learn by doing, not by reading docs.
The system teaches itself, then cleans up after graduation.
### Complete Configuration Control
Every behavior is configurable through `sessions/sessions-config.json`. Customize trigger phrases, blocked tools, git workflows (commit styles, auto-merge, auto-push), environment settings, feature toggles. The system respects your preferences automatically—protocols adapt, enforcement rules adjust, everything just works your way.
### Automatic State Preservation
The system backs up your work before updates, preserves task files and agent customizations during reinstalls, and maintains state across session restarts. Your `.gitignore` gets configured automatically to keep runtime state out of version control. Everything persists, nothing gets lost.
</details>
<br>
## contributing
We mostly inline contributions unless your PR is exceptionally solid - there are a lot of concerns to manage when updating this repo.
If your suggestion or PR is good and used, we'll credit you even if inlined.
<br>
## license
MIT License. It's a public good - use it, fork it, make it better.
See the [LICENSE](LICENSE) file for the legal details.
Raw data
{
"_id": null,
"home_page": null,
"name": "cc-sessions",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "claude, claude-code, ai, pair-programming, daic, workflow, development",
"author": null,
"author_email": "toast <toast_x@bytebot.site>",
"download_url": "https://files.pythonhosted.org/packages/46/48/b5195008020ca9a16d2a37009abd3d14701e5c2bab66708136716c9922d5/cc_sessions-0.3.4.tar.gz",
"platform": null,
"description": "<p align=\"center\"><img src=\"sessions.png\" alt=\"cc-sessions\"></p>\n<div align=\"center\">An opinionated approach to productive development with Claude Code</div>\n<div align=\"center\"><sub><em>Public good brought to you by GWUDCAP and Three AIrrows Capital</em></sub></div>\n<br>\n<br>\n<div align=\"center\">\n\n[](https://www.npmjs.com/package/cc-sessions)\n[](https://www.npmjs.com/package/cc-sessions)\n[](https://pypi.org/project/cc-sessions/)\n[](https://pepy.tech/project/cc-sessions)\n</div>\n<div align=\"center\">\n\n[](https://opensource.org/licenses/MIT)\n[](https://x.com/AgentofToastX)\n[](https://dexscreener.com/solana/oy5mbertfqdytu8atyonycvcvu62fpmz3nkqoztrflq)\n</div>\n\n<div align=\"center\"><img src=\"testimonial-1.png\" alt=\"cc-sessions testimonial\" width=\"60%\"></div>\n<div align=\"center\"><img src=\"testimonial-2.png\" alt=\"cc-sessions testimonial\" width=\"60%\" align=\"center\"></div>\n\n<br>\n\n## latest updates\n\n<details>\n<summary>\nlatest release - v0.3.0\n</summary>\n\ni'm happy to present cc-sessions v0.3.0\n<em>it's basically autopilot</em>\n\n**major highlights:**\n- **Dual Language Support**: Now available as both Python and Node.js packages with complete feature parity\n- **Unified Sessions API**: Single `sessions` command replaces multiple slash commands\n- **Natural Language Protocols**: Full workflow automation through trigger phrases (mek:, start^:, finito, squish)\n- **Todo Validation System**: Approved todo lists are locked and tracked to prevent scope creep\n- **Directory Tasks**: Multi-phase projects with subtasks on shared feature branches\n- **Kickstart Tutorial**: Interactive onboarding teaches cc-sessions by using it\n- **CI Environment Detection**: Auto-bypass DAIC in GitHub Actions (thanks @oppianmatt)\n- **Enhanced Statusline**: Nerd Fonts + git tracking with ahead/behind indicators (thanks @dnviti)\n- **Safe Uninstaller**: Interactive removal with automatic backups (thanks @gabelul)\n\nSee [CHANGELOG.md](CHANGELOG.md) for complete details.\n</details>\n\n<details>\n<summary>\nClaude Code version issue\n</summary\n \n**'ere meh now**: the recommended Claude Code version is **2.0.8** due to an upstream bug in newer versions of Claude Code.\n\nClaude Code versions after 2.0.8 have a bug in their stderr aggregation system that causes 400 API errors when:\n- Multiple tool calls execute in parallel (batched in one Claude response)\n- Commands generate their own stderr output (e.g., curl progress meters)\n- PostToolUse hooks also send stderr feedback (exit code 2)\n\nThis breaks cc-sessions' PostToolUse hooks that provide essential feedback like directory navigation confirmations and DAIC mode transitions.\n\n**install the correct version**:\n```bash\nnpm install -g @anthropic-ai/claude-code@2.0.8\n```\n\n**related**: [cc-sessions Issue #53](https://github.com/GWUDCAP/cc-sessions/issues/53)\n</details>\n\n## installing the extension\n\nYou install cc-sessions into a repo from the project root:\n\n```bash\ncd ~/my-git-repo && [npx|pipx run] cc-sessions\n```\n\nThere are Python and Node packages - use whichever you have:\n\n### Python\n\n```bash\n# Navigate to the repo you want to \n# use cc-sessions in, then...\npipx run cc-sessions\n```\n\n### Node\n\n```bash\n# Navigate to the repo you want to \n# use cc-sessions in, then...\nnpx cc-sessions\n```\n\n<details>\n<summary>\n\n### what gets installed\n</summary>\n\nThe installer sets up:\n- Hook files in `sessions/hooks/` for DAIC enforcement\n- API commands in `sessions/api/` for state/config management\n- Protocol templates in `sessions/protocols/` for workflow automation\n- Specialized agents in `.claude/agents/` for heavy operations\n- Sessions API wrapper slash command in `.claude/commands`\n- Initial state in `sessions/sessions-state.json`\n- Configuration in `sessions/sessions-config.json`\n- Automatic `.gitignore` entries for runtime files\n</details>\n\n### updates and uninstalls/reinstalls\n\nThe system automatically preserves your work:\n- Creates timestamped backups in `.claude/.backup-YYYYMMDD-HHMMSS/`\n- Preserves all task files and agent customizations\n- Preserves sessions-config.json\n- Restores everything after installation completes\n- State file regenerates fresh\n\n<br>\n\n## kickstart: interactive tutorial\n\nYou can select whether to take the interactive tutorial at the end of the installer. Its pretty quick and it will fully onboard you if you're new, using cc-sessions to teach you cc-sessions.\n\nThe system teaches itself through index-based progression, then cleans up its own onboarding files on graduation.\n\n<br>\n\n## quick start\n\n<details><summary><em>Best way to get started is kickstart, but...</em></summary>\n<br>\n\n**After installation (and, optionally, kickstart), use trigger phrases to control workflows:**\n\n```\nYou: \"mek: add user authentication\"\nClaude: [Creates task with interactive prompts]\n\nYou: \"start^: @sessions/tasks/h-implement-user-auth.md\"\nClaude: [Loads context, proposes implementation plan with specific todos]\n\nYou: \"yert\"\nClaude: [Implements only the approved todos]\n\nYou: \"finito\"\nClaude: [Completes task: commits, merges, cleans up]\n```\n\n**These trigger phrases are the defaults.** Add any trigger phrases you like:\n\n```bash\n# See current triggers\n/sessions config triggers list\n\n# Add your own phrase to any category\n/sessions config triggers add go lets do this\n\n# Categories: go, no, create, start, complete, compact\n# Slash command API syntax: /sessions [subsystem] [command] [arguments]\n# Context-aware help on failed commands - fail away\n```\n\nCheck `sessions/sessions-config.json` to see all configuration options.\n</details>\n\n<br>\n\n## why I made cc-sessions\n\n<details><summary><em>I made cc-sessions to solve what I don't like about AI pair programming...</em></summary>\n<br>\nIf you ask Claude a question he may just start writing code, especially if you are in the middle of a task.\n\nWithout additional scaffolding, you are often manually adding files to context for 20% of the context window and being perennially terrified of having to compact context.\n\nThe list of things you have to remember can get quite large: \n\n - compact before you run out of tokens \n - read every diff before approving\n - write task files\n - commit changes\n - merge branches\n - push to remote\n - manage which tools Claude can use\n - remember to run the right slash commands \n\nThe cognitive overhead balloons quickly.\n\nTasks don't survive restarts. Close Claude Code, reopen it, and you're explaining everything from scratch. No confidence that work will continue cleanly and no structure to how to handle working across context windows.\n\n**You discover problems faster than you can solve them.** Without a standardized, friction-free way to capture tasks, these insights vanish.\n\nWhen context does get compacted automatically, it doesn't preserve enough detail to inspire confidence. \n\nMost have a CLAUDE.md file stuffed with behavioral rules, some of which are simple where others are complex branching conditional logic. \n\nLLMs are terrible at following long instruction lists throughout an entire conversation. The guidance degrades as the conversation progresses.\n\nGit workflow adds constant friction: creating branches, crafting commit messages, merging when complete, pushing to remote. More cognitive overhead.\n\n**So, cc-sessions fixes all of this.**\n</details>\n\n<br>\n\n## features summary\n\n<details><summary><em>click to learn about features...</em></summary>\n<br>\n\n### Discussion-Alignment-Implementation-Check (DAIC)\n\nClaude earns the right to write code. By default, Edit, Write, and MultiEdit tools are completely blocked. Before Claude can touch your codebase, he has to discuss his approach, explain his reasoning, and propose specific todos you explicitly approve with trigger phrases like \"go ahead\" or \"make it so\" (fully customizable).\n\nOnce you approve the plan, Claude loads those exact todos and can only work on what you agreed to. Try to change the plan mid-stream? The system detects it and throws him back to discussion mode. No scope creep. No surprise rewrites. Just the work you approved.\n\n### Task Management That Survives Restarts\n\nTasks are markdown files with frontmatter that tracks status, branches, and success criteria. The system automatically creates matching git branches, enforces branch discipline (no committing to wrong branches or editing files off branch), and loads complete context when you restart a task days later.\n\nDirectory-based tasks support complex multi-phase work with subtask workflows. File-based tasks handle focused objectives. Task indexes let you filter by service area. Everything persists through session restarts.\n\n### Specialized Agents for Heavy Lifting\n\nFive specialized agents run in separate context windows to handle operations that would otherwise burn your main thread:\n\n- **context-gathering** - Analyzes your codebase and creates comprehensive context manifests for each task you create\n- **logging** - Consolidates work logs chronologically\n- **code-review** - Reviews implementations for quality and patterns\n- **context-refinement** - Updates task context based on session discoveries\n- **service-documentation** - Maintains CLAUDE.md files for services\n\nEach agent receives the full conversation transcript and returns structured results to your main session.\n\n### Protocols That Automate Workflows\n\nPre-built protocol templates guide task creation, startup, completion, and context compaction. They adapt automatically based on your configuration\u2014no manual decisions about submodules, commit styles, or git workflows. The protocols just know what you prefer and act accordingly.\n\nAll protocols use structured output formats (`[PROPOSAL]`, `[STATUS]`, `[PLAN]`) so you always know when Claude needs your input.\n\n### Sessions API & Slash Commands\n\nUnified `sessions` command provides programmatic access to state, configuration, and task management. Slash commands (`/sessions`) give you quick access through Claude Code's command palette.\n\nConfigure trigger phrases, manage git preferences, toggle features, inspect state\u2014everything through a clean API with JSON output support for scripting.\n\n### Interactive Kickstart Onboarding\n\nFirst install drops you into interactive onboarding with two modes: Full (15-30 min walkthrough of every feature with hands-on exercises) or Subagents-only (5 min agent customization crash course). You learn by doing, not by reading docs.\n\nThe system teaches itself, then cleans up after graduation.\n\n### Complete Configuration Control\n\nEvery behavior is configurable through `sessions/sessions-config.json`. Customize trigger phrases, blocked tools, git workflows (commit styles, auto-merge, auto-push), environment settings, feature toggles. The system respects your preferences automatically\u2014protocols adapt, enforcement rules adjust, everything just works your way.\n\n### Automatic State Preservation\n\nThe system backs up your work before updates, preserves task files and agent customizations during reinstalls, and maintains state across session restarts. Your `.gitignore` gets configured automatically to keep runtime state out of version control. Everything persists, nothing gets lost.\n</details>\n\n<br>\n\n## contributing\n\nWe mostly inline contributions unless your PR is exceptionally solid - there are a lot of concerns to manage when updating this repo. \n\nIf your suggestion or PR is good and used, we'll credit you even if inlined.\n\n<br>\n\n## license\n\nMIT License. It's a public good - use it, fork it, make it better.\n\nSee the [LICENSE](LICENSE) file for the legal details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "an opinionated approach to productive development with Claude Code",
"version": "0.3.4",
"project_urls": {
"Documentation": "https://github.com/GWUDCAP/cc-sessions#readme",
"Homepage": "https://github.com/GWUDCAP/cc-sessions",
"Issues": "https://github.com/GWUDCAP/cc-sessions/issues",
"Repository": "https://github.com/GWUDCAP/cc-sessions.git"
},
"split_keywords": [
"claude",
" claude-code",
" ai",
" pair-programming",
" daic",
" workflow",
" development"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e62d3e773c25f439ed562da1e4cf91dfaf0cb115dea90c46b3a446e95c35df2c",
"md5": "3e65376e28709b2b596640d638f6e5eb",
"sha256": "6d7b2cd4d98382878f1e229c9a8aa5cc8a3e6bc15ad4a7449cd82568a157a9dd"
},
"downloads": -1,
"filename": "cc_sessions-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3e65376e28709b2b596640d638f6e5eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 270749,
"upload_time": "2025-10-15T14:45:40",
"upload_time_iso_8601": "2025-10-15T14:45:40.477309Z",
"url": "https://files.pythonhosted.org/packages/e6/2d/3e773c25f439ed562da1e4cf91dfaf0cb115dea90c46b3a446e95c35df2c/cc_sessions-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4648b5195008020ca9a16d2a37009abd3d14701e5c2bab66708136716c9922d5",
"md5": "4c6ec47bf41ad5f26469bb674ec3df11",
"sha256": "82cd70c087afb2380ce5f410bd5acf048590145961111ef7e50576f669576005"
},
"downloads": -1,
"filename": "cc_sessions-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "4c6ec47bf41ad5f26469bb674ec3df11",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 237685,
"upload_time": "2025-10-15T14:45:41",
"upload_time_iso_8601": "2025-10-15T14:45:41.995124Z",
"url": "https://files.pythonhosted.org/packages/46/48/b5195008020ca9a16d2a37009abd3d14701e5c2bab66708136716c9922d5/cc_sessions-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-15 14:45:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GWUDCAP",
"github_project": "cc-sessions#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cc-sessions"
}
JSON
