```
███████╗███████╗███████╗███████╗██╗ ██████╗ ███╗ ██╗███████╗
██╔════╝██╔════╝██╔════╝██╔════╝██║██╔═══██╗████╗ ██║██╔════╝
███████╗█████╗ ███████╗███████╗██║██║ ██║██╔██╗ ██║███████╗
╚════██║██╔══╝ ╚════██║╚════██║██║██║ ██║██║╚██╗██║╚════██║
███████║███████╗███████║███████║██║╚██████╔╝██║ ╚████║███████║
╚══════╝╚══════╝╚══════╝╚══════╝╚═╝ ╚═════╝ ╚═╝ ╚═══╝╚══════╝
```
<sub>_A public good brought to you by GWUDCAP and Three AIrrows Capital_</sub>
---
<br>
<div align="center">
##### ⚡ SHOCKING REPORT REVEALS ⚡
# **Vibe coding is shitty and confusing and produces garbage software that sucks to work on.**<br>
### _Claude Code makes it less shitty, but not by enough._
---
</div>
## 🔥 The Problem
<details>
<summary><strong>How you got here</strong> <em>(click to read the painful journey)</em></summary>
<br>
I'm going to guess how you got here and you can tell me if I get it right:
- 💭 The LLM programmer hype gave you a nerd chub
- 😬 The people hyping LLM programming made your nerd chub crawl back into your body <br> <sup>_(are you ready to 'scale your impact', dog?)_</sup>
- 🤮 You held your nose and downloaded Cursor/added Cline or Roo Code/npm installed Claude Code
At first this was obviously novel and interesting. Some things were shitty but mostly you were enjoying not having to write a context manager or even recognize that you needed one for your dumb client wrapper.
**You were _scaling_ your _impact_** _(whew)_.
But then Claude started doing some concerning things.
You asked it to add error handling to **one** function. It added error handling to **_every function in the file_**. And changed your error types. And your logging format. And somehow your indentation is different now?
The context window thing started getting annoying. You're explaining the same architecture for the fifth time today. Claude's like _'let me look for the database'_ **Brother. We've been using Postgres for six hours. You were just in there.**
Your CLAUDE.md is now longer than your actual code.
- `'NEVER use class components.'`
- `'ALWAYS use the existing auth middleware.'`
- `'DO NOT refactor unrelated code.'`
- `'REMEMBER we use PostgreSQL.'`
Claude reads the first line and then macrodoses window pane LSD for the rest.
You tried the subagents, but quickly realized that **you can't even talk to these things.** 10 minutes into a "code review" and the agent hits some kind of API error and returns to your main thread with no explanation of what it did or what it discovered.
Run it again, I guess?
_This fucking sucks_.
Now you're here. Your codebase is 'done' but you couldn't, in a million years, explain what that means or how it satisfies the definition.
There's three different global clients for the same database connection and two of them use hallucinated environment variables (the other just yeets your client secret into the service code).
You've got utility functions that are duplicated in four files because Claude kept forgetting they exist.
20% of your code lines are comments explaining why something *isn't* there and *is* somewhere else.
You don't even know exactly what's wrong and fixing it means understanding code you didn't write in patterns you don't recognize using approaches you wouldn't choose.
### **Are you scaling your impact yet?**
</details>
## 💊 The Solution
<details>
<summary><strong>What We Fixed</strong> <em>(what you get when you use cc-sessions)</em></summary>
<br>
So, now you're here. Since this is exclusively about Claude Code I'm going to assume that you are a CC user and you are looking to make that better. **Lit.**
Let's talk about Claude Code.
Of the major AI programming IDEs/scaffolds, Claude Code is probably the best and Claude models are probably the best _(though Google is kinda coming for that ass)_.
But, Claude Code is not without its **major faults, flaws, and flaccidity-inducing frustrations**.
For instance, **it would be nice if**:
- Claude had to talk to you before writing code so you didn't end up with 500 lines of implementation for a one-line change.
- you didn't lose everything when the context window died and Claude actually remembered what you were working on tomorrow.
- you didn't have to explain your entire architecture every. single. session. and Claude actually inherited understanding from previous work.
- Claude couldn't randomly refactor working code while you're trying to add a button.
- you didn't have to manually check which branch you're on in five different repos and Claude actually stopped you before you edited the wrong one.
- Claude followed the patterns in your codebase instead of inventing new ones every time it touches a file.
- you didn't have to write increasingly desperate rules in CLAUDE.md and Claude was actually forced to follow consistent behavior.
### **This is what Sessions does.**
It makes all of these nice things happen. Not through more rules or documentation or prompting techniques, but through **brute authoritarian rule over the agentic loop**.
</details>
## ⚙️ How It Works
**Sessions enforces discussion before implementation through hooks that Claude can't bypass.**
You install Sessions. Five minutes, one script. It sets up hooks that Claude can't bypass, state management that persists, and a task system that actually remembers things.
If you want to get acquainted you can read about individual features below:
<details>
<summary><strong>Claude waits for alignment</strong></summary>
<br>
Before Sessions, this was your life:
```
You: Add error handling to the auth flow
Claude: I'll add comprehensive error handling!
[IMMEDIATELY STARTS EDITING 15 FILES]
[ADDS TRY-CATCH TO EVERY FUNCTION]
[CHANGES YOUR ERROR MESSAGE FORMAT]
[REFACTORS YOUR LOGGING LIBRARY]
You: wait no stop STOP
Claude: I've updated the error handling across your entire codebase!
You: [muffled screaming]
```
With Sessions:
```
You: Add error handling to the auth flow
Claude: Let me analyze your current error patterns first...
[Claude reads auth code, examines existing error handling]
Claude: I found your error handling pattern:
- You're using custom AppError classes
- Errors bubble to middleware/errorHandler.ts
- Auth errors specifically use 401/403 status codes
- You log errors to Sentry in production
I'll add error handling to the login and refresh token endpoints
following your existing AppError pattern. Ready?
You: perfect, go ahead
Claude: [NOW edits exactly 2 files with correct patterns]
```
The hooks literally block Write/Edit tools until you approve. Claude HAS to discuss first. No exceptions. No workarounds. No surprise refactors.
</details>
<details>
<summary><strong>OP automatic compaction</strong></summary>
<br>
When Claude's context window hits 75%, a hook will tell Claude to start wrapping shid up. At 90%, the hook will be more aggressive about it.
When you okay (i.e. "let's compact"), Claude will use a protocol and several sub-agents to record all important info from your session to the current task file, along with next steps to begin immediately after you clear context.
You just type `/clear` and another hook will automatically yeet the current task file into Claude's context window and you can continue as if you never left.
```
[Friday, 4pm - deep in implementing a payment system]
Claude: ⚠️ Context at 75% - Consider wrapping up soon
You: I gotta run, lets compact and come back to this later.
Claude: Cool, running context-compaction.md protocol - first, let me call the logging agent to write our task log for the session...
You: [Close laptop, weekend happens]
[Monday, 9am]
You: /clear
You: lets continue
Claude: Welcome back! Resuming work on m-payment-integration.
Last session we:
- Integrated Stripe checkout flow
- Added webhook handlers for payment events
- Created payment status tracking
Current state: Testing webhook signatures
Next: Add retry logic for failed webhooks
Let's continue with the retry logic implementation.
```
Zero context rebuilding. Claude knows exactly where you left off.
</details>
<details>
<summary><strong>Better subagents</strong></summary>
<br>
There's no obvious way to get Claude to call subagents with all of the necessary context. There's also not great visiblity into how Claude prompts them, or even what the subagents do (or why they fail when they fail).
To deal with this, we've designated specific agents for specific tasks in the sessions system.
These are (currently):
- Context Gathering Agent | Digs through whole files at a time in your codebase to get all the right context for a task, then writes it to a context manifest in the task file so Claude doesn't have to re-learn it.
- Code Review Agent | Reviews code changes before they are committed to ensure they follow your patterns
- Logging Agent | Writes a log of what was done in a session to the task file
To make this a lot easier, the logging agent gets the entire conversation history - instead of relying on Claude to re-output everything important that happened in this session, the logging agent just branches off from your conversation, writes the logs, and passes it back to the main thread.
In the background, any call to a subagent copies the current conversation into a set of conversation history logs in a dedicated directory for the agent. If you ever want an agent to load the full conversation context before following their prompt, you can just adjust their agent prompt to tell them to read all of the files in .claude/state/{agent-name}/.
```
You: Lets start the caching upgrades e
Claude: No problem! Let me update current-task.json and then I'll use the context-gathering agent to analyze your caching system.
[Agent runs in separate context - doesn't pollute your main thread]
Agent results: I've created a comprehensive context manifest:
CACHING ARCHITECTURE:
- Redis for session cache (30min TTL)
- PostgreSQL materialized views for reports
- React Query for client-side caching (5min stale time)
- CDN caching for static assets
KEY PATTERNS:
- Cache keys use format: {service}:{entity}:{id}:{version}
- Invalidation happens through CacheManager.invalidate()
- All cache operations logged to cache_operations table
IMPLEMENTATION LOCATIONS:
- Server cache: /lib/cache/redis-cache.ts
- Client cache: /hooks/useQueryWithCache.ts
- Cache invalidation: /api/middleware/cache-invalidator.ts
[Full context manifest saved to task file - available forever]
```
The agent understood your patterns because it could analyze everything without worrying about preserving the context window.
</details>
<details>
<summary><strong>Tasks and Branches Is All You Need</strong></summary>
<br>
Every piece of work is a task. Every task has its own branch. Sessions enforces both.
```
You: Let's fix the payment webhooks
Claude: I'll create a task for that. What priority?
- h- (high): Critical/blocking issues
- m- (medium): Normal features/fixes
- l- (low): Nice-to-haves
- ?- (investigate): Not sure if needed
You: high priority
Claude: Creating h-fix-payment-webhooks
[Creates task file]
[Runs context-gathering agent]
[Sets up feature/fix-payment-webhooks branch]
Context manifest created:
- Stripe webhooks configured in /api/webhooks/stripe.ts
- Events: payment_intent.succeeded, charge.failed
- Current issue: signature verification failing
- Webhook secret in STRIPE_WEBHOOK_SECRET env var
Ready to start work on feature/fix-payment-webhooks?
```
Now your task has:
- **Permanent context** that survives session restarts
- **Its own branch** that Sessions enforces
- **Work logs** tracking everything done
- **Clear scope** preventing scope creep
When you come back tomorrow:
```
You: /clear
SessionStart: Loading task h-fix-payment-webhooks
Branch: feature/fix-payment-webhooks
Last work: Fixed signature verification
Next: Add retry logic for failed events
You: continue
Claude: Picking up where we left off - implementing retry logic for failed webhook events...
```
No context rebuilding. No confusion about what branch. No losing work.
</details>
<details>
<summary><strong>Ultrathink & API Mode</strong></summary>
<br>
Sessions automatically enables Claude's deep thinking mode on every message. But if you're paying per token, that gets expensive fast.
**Max Mode (Default):**
```
You: [any message]
[Claude automatically uses maximum thinking budget]
[2-3x more tokens but better reasoning]
[$20-200/month flat rate - use all you want]
```
**API Mode (Token Saver):**
```bash
# During installation:
"Enable API mode to save tokens? (y/n)"
# Or toggle later:
/api-mode
```
In API mode:
- Ultrathink disabled by default (saves ~50-67% tokens)
- You control when to use it: `[[ ultrathink ]] solve this hard problem`
- All other Sessions features still save tokens through context preservation
The truth? Sessions **saves** tokens for API users:
- Context persistence: -2000 tokens/task (no re-explaining)
- Auto-loading: -500 tokens/session (no "what are we doing?")
- DAIC enforcement: -1000 tokens/task (no failed attempts)
- Specialized agents: -3000 tokens (work in minimal contexts)
You lose ultrathink but gain token efficiency everywhere else.
</details>
<details>
<summary><strong>Branch Enforcement</strong></summary>
```
[Working on task m-fix-auth, supposed to be on feature/fix-auth branch]
You: update the login validation
Claude: I'll update the login validation. Let me look at the current implementation.
[Claude tries to edit src/auth/login.ts]
❌ BLOCKED: Branch mismatch!
- Task requires: feature/fix-auth
- You're on: main
Run this command:
git checkout feature/fix-auth
Claude: git checkout feature/fix-auth
Claude: [NOW can edit the file safely on the correct branch]
```
</details>
<details>
<summary><strong>Code Not Claude</strong></summary>
<br>
Before Sessions, your CLAUDE.md looked like this:
```markdown
# CLAUDE.md (1,247 lines)
## CRITICAL RULES (PLEASE FOLLOW)
### NEVER DO THESE THINGS
- NEVER use require() we use import
- NEVER use callbacks we use async/await
- NEVER use class components
- NEVER refactor working code
- NEVER change the database schema
- NEVER modify the auth middleware
- NEVER use var, always const/let
- NEVER commit directly to main
[... 200 more NEVER rules ...]
### ALWAYS DO THESE THINGS
- ALWAYS use the existing error handler
- ALWAYS follow our naming conventions
- ALWAYS use PostgreSQL not MySQL
- ALWAYS check if a utility exists first
[... 200 more ALWAYS rules ...]
### REMEMBER
- We use Tailwind not CSS modules
- The database is PostgreSQL
- Yes, still PostgreSQL
- I SAID POSTGRESQL
[... 500 lines of context ...]
```
Claude reads line 1 and forgets the rest.
With Sessions:
```markdown
# CLAUDE.md (< 100 lines)
## Project Overview
AI waifu platform. Node + React + PostgreSQL.
## Behavioral Rules
@CLAUDE.sessions.md
That's it. The rest is enforced by hooks.
```
Rules aren't suggestions anymore. They're **enforced by code**:
- Can't edit without permission? Hook blocks the tools
- Wrong branch? Hook blocks the edit
- Need to follow patterns? Context manifest has them documented
- Must remember PostgreSQL? It's in the task context that auto-loads
Your documentation describes your project. The hooks enforce behavior. Claude can't ignore hooks.
</details>
<details>
<summary><strong>Statusline keeping you informed</strong></summary>
```
[Bottom of your Claude Code window - two lines]
██████░░░░ 45.2% (72k/160k) | Task: m-payment-integration
DAIC: Discussion | ✎ 3 files | [4 open]
[After you say "go ahead"]
██████░░░░ 47.1% (75k/160k) | Task: m-payment-integration
DAIC: Implementation | ✎ 5 files | [4 open]
[When approaching context limit - bar turns red]
████████░░ 78.3% (125k/160k) | Task: m-payment-integration
DAIC: Discussion | ✎ 12 files | [4 open]
[When no task is active]
██░░░░░░░░ 12.1% (19k/160k) | Task: None
DAIC: Discussion | ✎ 0 files | [4 open]
```
Progress bar changes color: green < 50%, orange < 80%, red >= 80%.
</details>
This isn't complex. It's not heavy process. It's invisible rails that keep Claude from going off the cliff. You still describe what you want in natural language. Claude still writes code. But now it happens in a way that doesn't produce garbage.
You code at the same speed. You just don't spend the next three hours unfucking what Claude just did.
## 🚀 Installation
Alright, you're convinced. **Let's unfuck your workflow.**
### ✅ Requirements
You need:
- **Claude Code** _(you have this or you wouldn't be here)_
- **Python 3 + pip** _(for the hooks)_
- **Git** _(probably)_
- **5 minutes**
### 📦 Install
Pick your poison:
**NPM/NPX** (TypeScript Andys):
```bash
cd your-broken-project
npx cc-sessions # One-time install
# or
npm install -g cc-sessions # Global install
cc-sessions # Run in your project
```
**Pip/Pipx/UV** (Pythonistas):
```bash
pipx install cc-sessions # Isolated install (recommended)
cd your-broken-project
cc-sessions # Run the installer
# or
pip install cc-sessions # Regular pip
# or
uv pip install cc-sessions # UV package manager
```
**Direct Bash** ('build from source' gigachads):
```bash
git clone https://github.com/GWUDCAP/cc-sessions
cd your-broken-project
/path/to/cc-sessions/install.sh
```
The installer asks you:
- Your name (so Claude knows who it's disappointing)
- If you want the statusline (you do)
- What triggers implementation mode ('go ahead', 'ship it', whatever)
- Some other config shit (just hit enter)
That's it. Restart Claude Code. You're done.
### ✨ What Just Happened
You now have:
- Hooks that enforce discussion before implementation
- State that persists between sessions
- Task management that actually works
- Agents that aren't completely useless
- Git branch enforcement
- Token warnings before death
- A chance at maintaining this code in 6 months
### 🎯 Your First Task
Tell Claude:
```
Create a task for:
[EXPLAIN THE TASK]
```
Claude will:
- Create the task file with proper structure
- Use the context-gathering agent to gather everything they need to know to complete the task based on your existing codebase
- Build a context manifest so it never forgets what it learned
- Set up the task as your current focus
Then just say 'let's work on [task-name]' and watch Claude actually discuss before implementing.
### **Welcome to software development with guardrails.**
---
## 🔧 Customizing Sessions
Sessions is built to be modified. You can use Claude Code itself to improve Sessions or adapt it to your workflow.
<details>
<summary>How to customize Sessions</summary>
### Understanding the Structure
Sessions comes with knowledge files that explain its own architecture:
```
sessions/knowledge/claude-code/
├── hooks-reference.md # How hooks work and can be modified
├── subagents.md # Agent capabilities and customization
├── tool-permissions.md # Tool blocking configuration
└── slash-commands.md # Command system reference
```
### Modifying Behaviors
Tell Claude:
```
Using the hooks reference at @sessions/knowledge/claude-code/hooks-reference.md,
modify the DAIC enforcement to allow Bash commands in discussion mode
```
Claude can:
- Adjust trigger phrases in `sessions/sessions-config.json`
- Modify hook behaviors in `.claude/hooks/`
- Update protocols in `sessions/protocols/`
- Create new agents in `.claude/agents/`
- Customize task templates
### Common Customizations
**Change what tools are blocked:**
```json
// sessions/sessions-config.json
"blocked_tools": ["Edit", "Write"] // Remove MultiEdit to allow it
```
**Add your own trigger phrases:**
```json
"trigger_phrases": ["make it so", "ship it", "do the thing"]
```
**Modify agent prompts:**
Edit files in `.claude/agents/` to change how agents behave.
**Update workflows:**
Protocols in `sessions/protocols/` are just markdown - edit them to match your process.
### Pro Tips
1. Sessions has its own CLAUDE.md at `sessions/CLAUDE.md` for meta work
2. Use the knowledge files to understand the system deeply
3. Test changes in a separate branch first
4. The hooks are just Python - add logging if needed
5. Keep your customizations documented
Remember: You're not just using Sessions, you're evolving it. Make it yours.
</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/bf/f2/0a6657be578d40c01746d9b2060546b68a3bc8997bd3d67cd32c82092207/cc_sessions-0.2.3.tar.gz",
"platform": null,
"description": "```\n\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2557 \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\n\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\n\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\n\u255a\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u255a\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2551\u255a\u2588\u2588\u2557\u2588\u2588\u2551\u255a\u2550\u2550\u2550\u2550\u2588\u2588\u2551\n\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551\u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d\u2588\u2588\u2551 \u255a\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\n\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\n```\n\n<sub>_A public good brought to you by GWUDCAP and Three AIrrows Capital_</sub>\n\n---\n\n<br>\n<div align=\"center\">\n\n##### \u26a1 SHOCKING REPORT REVEALS \u26a1\n\n# **Vibe coding is shitty and confusing and produces garbage software that sucks to work on.**<br>\n\n### _Claude Code makes it less shitty, but not by enough._\n\n---\n\n</div>\n\n## \ud83d\udd25 The Problem\n\n<details>\n<summary><strong>How you got here</strong> <em>(click to read the painful journey)</em></summary>\n\n<br>\n\nI'm going to guess how you got here and you can tell me if I get it right:\n\n- \ud83d\udcad The LLM programmer hype gave you a nerd chub \n- \ud83d\ude2c The people hyping LLM programming made your nerd chub crawl back into your body <br> <sup>_(are you ready to 'scale your impact', dog?)_</sup> \n- \ud83e\udd2e You held your nose and downloaded Cursor/added Cline or Roo Code/npm installed Claude Code\n\nAt first this was obviously novel and interesting. Some things were shitty but mostly you were enjoying not having to write a context manager or even recognize that you needed one for your dumb client wrapper.\n\n**You were _scaling_ your _impact_** _(whew)_.\n\nBut then Claude started doing some concerning things. \n\nYou asked it to add error handling to **one** function. It added error handling to **_every function in the file_**. And changed your error types. And your logging format. And somehow your indentation is different now?\n\nThe context window thing started getting annoying. You're explaining the same architecture for the fifth time today. Claude's like _'let me look for the database'_ **Brother. We've been using Postgres for six hours. You were just in there.**\n\nYour CLAUDE.md is now longer than your actual code. \n- `'NEVER use class components.'` \n- `'ALWAYS use the existing auth middleware.'` \n- `'DO NOT refactor unrelated code.'` \n- `'REMEMBER we use PostgreSQL.'` \n\nClaude reads the first line and then macrodoses window pane LSD for the rest.\n\nYou tried the subagents, but quickly realized that **you can't even talk to these things.** 10 minutes into a \"code review\" and the agent hits some kind of API error and returns to your main thread with no explanation of what it did or what it discovered. \n\nRun it again, I guess? \n\n_This fucking sucks_.\n\nNow you're here. Your codebase is 'done' but you couldn't, in a million years, explain what that means or how it satisfies the definition. \n\nThere's three different global clients for the same database connection and two of them use hallucinated environment variables (the other just yeets your client secret into the service code). \n\nYou've got utility functions that are duplicated in four files because Claude kept forgetting they exist.\n\n20% of your code lines are comments explaining why something *isn't* there and *is* somewhere else.\n\nYou don't even know exactly what's wrong and fixing it means understanding code you didn't write in patterns you don't recognize using approaches you wouldn't choose.\n\n### **Are you scaling your impact yet?**\n\n</details>\n\n## \ud83d\udc8a The Solution\n\n<details>\n<summary><strong>What We Fixed</strong> <em>(what you get when you use cc-sessions)</em></summary>\n\n<br>\n\nSo, now you're here. Since this is exclusively about Claude Code I'm going to assume that you are a CC user and you are looking to make that better. **Lit.**\n\nLet's talk about Claude Code.\n\nOf the major AI programming IDEs/scaffolds, Claude Code is probably the best and Claude models are probably the best _(though Google is kinda coming for that ass)_.\n\nBut, Claude Code is not without its **major faults, flaws, and flaccidity-inducing frustrations**.\n\nFor instance, **it would be nice if**:\n\n- Claude had to talk to you before writing code so you didn't end up with 500 lines of implementation for a one-line change.\n\n- you didn't lose everything when the context window died and Claude actually remembered what you were working on tomorrow.\n\n- you didn't have to explain your entire architecture every. single. session. and Claude actually inherited understanding from previous work.\n\n- Claude couldn't randomly refactor working code while you're trying to add a button.\n\n- you didn't have to manually check which branch you're on in five different repos and Claude actually stopped you before you edited the wrong one.\n\n- Claude followed the patterns in your codebase instead of inventing new ones every time it touches a file.\n\n- you didn't have to write increasingly desperate rules in CLAUDE.md and Claude was actually forced to follow consistent behavior.\n\n### **This is what Sessions does.**\n\nIt makes all of these nice things happen. Not through more rules or documentation or prompting techniques, but through **brute authoritarian rule over the agentic loop**.\n\n</details>\n\n## \u2699\ufe0f How It Works\n\n**Sessions enforces discussion before implementation through hooks that Claude can't bypass.**\n\nYou install Sessions. Five minutes, one script. It sets up hooks that Claude can't bypass, state management that persists, and a task system that actually remembers things.\n\nIf you want to get acquainted you can read about individual features below:\n\n<details>\n<summary><strong>Claude waits for alignment</strong></summary>\n<br>\n\nBefore Sessions, this was your life:\n\n```\nYou: Add error handling to the auth flow\n\nClaude: I'll add comprehensive error handling!\n[IMMEDIATELY STARTS EDITING 15 FILES]\n[ADDS TRY-CATCH TO EVERY FUNCTION]\n[CHANGES YOUR ERROR MESSAGE FORMAT]\n[REFACTORS YOUR LOGGING LIBRARY]\n\nYou: wait no stop STOP\n\nClaude: I've updated the error handling across your entire codebase!\n\nYou: [muffled screaming]\n```\n\nWith Sessions:\n\n```\nYou: Add error handling to the auth flow\n\nClaude: Let me analyze your current error patterns first...\n\n[Claude reads auth code, examines existing error handling]\n\nClaude: I found your error handling pattern:\n- You're using custom AppError classes\n- Errors bubble to middleware/errorHandler.ts \n- Auth errors specifically use 401/403 status codes\n- You log errors to Sentry in production\n\nI'll add error handling to the login and refresh token endpoints\nfollowing your existing AppError pattern. Ready?\n\nYou: perfect, go ahead\n\nClaude: [NOW edits exactly 2 files with correct patterns]\n```\n\nThe hooks literally block Write/Edit tools until you approve. Claude HAS to discuss first. No exceptions. No workarounds. No surprise refactors.\n\n</details>\n\n<details>\n<summary><strong>OP automatic compaction</strong></summary>\n<br>\n\nWhen Claude's context window hits 75%, a hook will tell Claude to start wrapping shid up. At 90%, the hook will be more aggressive about it. \n\nWhen you okay (i.e. \"let's compact\"), Claude will use a protocol and several sub-agents to record all important info from your session to the current task file, along with next steps to begin immediately after you clear context.\n\nYou just type `/clear` and another hook will automatically yeet the current task file into Claude's context window and you can continue as if you never left.\n\n```\n[Friday, 4pm - deep in implementing a payment system]\n\nClaude: \u26a0\ufe0f Context at 75% - Consider wrapping up soon\n\nYou: I gotta run, lets compact and come back to this later.\n\nClaude: Cool, running context-compaction.md protocol - first, let me call the logging agent to write our task log for the session...\n\nYou: [Close laptop, weekend happens]\n\n[Monday, 9am]\n\nYou: /clear\n\nYou: lets continue\n\nClaude: Welcome back! Resuming work on m-payment-integration.\nLast session we:\n- Integrated Stripe checkout flow\n- Added webhook handlers for payment events \n- Created payment status tracking\n\nCurrent state: Testing webhook signatures\nNext: Add retry logic for failed webhooks\n\nLet's continue with the retry logic implementation.\n```\n\nZero context rebuilding. Claude knows exactly where you left off.\n\n</details>\n\n<details>\n<summary><strong>Better subagents</strong></summary>\n<br>\n\nThere's no obvious way to get Claude to call subagents with all of the necessary context. There's also not great visiblity into how Claude prompts them, or even what the subagents do (or why they fail when they fail).\n\nTo deal with this, we've designated specific agents for specific tasks in the sessions system.\n\nThese are (currently):\n - Context Gathering Agent | Digs through whole files at a time in your codebase to get all the right context for a task, then writes it to a context manifest in the task file so Claude doesn't have to re-learn it.\n - Code Review Agent | Reviews code changes before they are committed to ensure they follow your patterns\n - Logging Agent | Writes a log of what was done in a session to the task file\n\nTo make this a lot easier, the logging agent gets the entire conversation history - instead of relying on Claude to re-output everything important that happened in this session, the logging agent just branches off from your conversation, writes the logs, and passes it back to the main thread.\n\nIn the background, any call to a subagent copies the current conversation into a set of conversation history logs in a dedicated directory for the agent. If you ever want an agent to load the full conversation context before following their prompt, you can just adjust their agent prompt to tell them to read all of the files in .claude/state/{agent-name}/.\n \n```\nYou: Lets start the caching upgrades e\n\nClaude: No problem! Let me update current-task.json and then I'll use the context-gathering agent to analyze your caching system.\n\n[Agent runs in separate context - doesn't pollute your main thread]\n\nAgent results: I've created a comprehensive context manifest:\n\nCACHING ARCHITECTURE:\n- Redis for session cache (30min TTL)\n- PostgreSQL materialized views for reports \n- React Query for client-side caching (5min stale time)\n- CDN caching for static assets\n\nKEY PATTERNS:\n- Cache keys use format: {service}:{entity}:{id}:{version}\n- Invalidation happens through CacheManager.invalidate()\n- All cache operations logged to cache_operations table\n\nIMPLEMENTATION LOCATIONS:\n- Server cache: /lib/cache/redis-cache.ts\n- Client cache: /hooks/useQueryWithCache.ts\n- Cache invalidation: /api/middleware/cache-invalidator.ts\n\n[Full context manifest saved to task file - available forever]\n```\n\nThe agent understood your patterns because it could analyze everything without worrying about preserving the context window.\n\n</details>\n\n<details>\n<summary><strong>Tasks and Branches Is All You Need</strong></summary>\n<br>\n\nEvery piece of work is a task. Every task has its own branch. Sessions enforces both.\n\n```\nYou: Let's fix the payment webhooks\n\nClaude: I'll create a task for that. What priority?\n- h- (high): Critical/blocking issues\n- m- (medium): Normal features/fixes \n- l- (low): Nice-to-haves\n- ?- (investigate): Not sure if needed\n\nYou: high priority\n\nClaude: Creating h-fix-payment-webhooks\n[Creates task file]\n[Runs context-gathering agent]\n[Sets up feature/fix-payment-webhooks branch]\n\nContext manifest created:\n- Stripe webhooks configured in /api/webhooks/stripe.ts\n- Events: payment_intent.succeeded, charge.failed\n- Current issue: signature verification failing\n- Webhook secret in STRIPE_WEBHOOK_SECRET env var\n\nReady to start work on feature/fix-payment-webhooks?\n```\n\nNow your task has:\n- **Permanent context** that survives session restarts\n- **Its own branch** that Sessions enforces\n- **Work logs** tracking everything done\n- **Clear scope** preventing scope creep\n\nWhen you come back tomorrow:\n\n```\nYou: /clear\n\nSessionStart: Loading task h-fix-payment-webhooks\nBranch: feature/fix-payment-webhooks\nLast work: Fixed signature verification\nNext: Add retry logic for failed events\n\nYou: continue\n\nClaude: Picking up where we left off - implementing retry logic for failed webhook events...\n```\n\nNo context rebuilding. No confusion about what branch. No losing work.\n\n</details>\n\n<details>\n<summary><strong>Ultrathink & API Mode</strong></summary>\n<br>\n\nSessions automatically enables Claude's deep thinking mode on every message. But if you're paying per token, that gets expensive fast.\n\n**Max Mode (Default):**\n```\nYou: [any message]\n\n[Claude automatically uses maximum thinking budget]\n[2-3x more tokens but better reasoning]\n[$20-200/month flat rate - use all you want]\n```\n\n**API Mode (Token Saver):**\n```bash\n# During installation:\n\"Enable API mode to save tokens? (y/n)\"\n\n# Or toggle later:\n/api-mode\n```\n\nIn API mode:\n- Ultrathink disabled by default (saves ~50-67% tokens)\n- You control when to use it: `[[ ultrathink ]] solve this hard problem`\n- All other Sessions features still save tokens through context preservation\n\nThe truth? Sessions **saves** tokens for API users:\n- Context persistence: -2000 tokens/task (no re-explaining)\n- Auto-loading: -500 tokens/session (no \"what are we doing?\")\n- DAIC enforcement: -1000 tokens/task (no failed attempts)\n- Specialized agents: -3000 tokens (work in minimal contexts)\n\nYou lose ultrathink but gain token efficiency everywhere else.\n\n</details>\n\n<details>\n<summary><strong>Branch Enforcement</strong></summary>\n\n```\n[Working on task m-fix-auth, supposed to be on feature/fix-auth branch]\n\nYou: update the login validation\n\nClaude: I'll update the login validation. Let me look at the current implementation.\n\n[Claude tries to edit src/auth/login.ts]\n\n\u274c BLOCKED: Branch mismatch!\n- Task requires: feature/fix-auth \n- You're on: main\n\nRun this command:\ngit checkout feature/fix-auth\n\nClaude: git checkout feature/fix-auth\n\nClaude: [NOW can edit the file safely on the correct branch]\n```\n\n</details>\n\n<details>\n<summary><strong>Code Not Claude</strong></summary>\n<br>\n\nBefore Sessions, your CLAUDE.md looked like this:\n\n```markdown\n# CLAUDE.md (1,247 lines)\n\n## CRITICAL RULES (PLEASE FOLLOW)\n\n### NEVER DO THESE THINGS\n- NEVER use require() we use import\n- NEVER use callbacks we use async/await \n- NEVER use class components\n- NEVER refactor working code\n- NEVER change the database schema\n- NEVER modify the auth middleware\n- NEVER use var, always const/let\n- NEVER commit directly to main\n[... 200 more NEVER rules ...]\n\n### ALWAYS DO THESE THINGS \n- ALWAYS use the existing error handler\n- ALWAYS follow our naming conventions\n- ALWAYS use PostgreSQL not MySQL\n- ALWAYS check if a utility exists first\n[... 200 more ALWAYS rules ...]\n\n### REMEMBER\n- We use Tailwind not CSS modules\n- The database is PostgreSQL\n- Yes, still PostgreSQL\n- I SAID POSTGRESQL\n[... 500 lines of context ...]\n```\n\nClaude reads line 1 and forgets the rest.\n\nWith Sessions:\n\n```markdown\n# CLAUDE.md (< 100 lines)\n\n## Project Overview\nAI waifu platform. Node + React + PostgreSQL.\n\n## Behavioral Rules\n@CLAUDE.sessions.md\n\nThat's it. The rest is enforced by hooks.\n```\n\nRules aren't suggestions anymore. They're **enforced by code**:\n- Can't edit without permission? Hook blocks the tools\n- Wrong branch? Hook blocks the edit\n- Need to follow patterns? Context manifest has them documented\n- Must remember PostgreSQL? It's in the task context that auto-loads\n\nYour documentation describes your project. The hooks enforce behavior. Claude can't ignore hooks.\n\n</details>\n\n\n<details>\n<summary><strong>Statusline keeping you informed</strong></summary>\n\n```\n[Bottom of your Claude Code window - two lines]\n\n\u2588\u2588\u2588\u2588\u2588\u2588\u2591\u2591\u2591\u2591 45.2% (72k/160k) | Task: m-payment-integration\nDAIC: Discussion | \u270e 3 files | [4 open]\n\n[After you say \"go ahead\"]\n\n\u2588\u2588\u2588\u2588\u2588\u2588\u2591\u2591\u2591\u2591 47.1% (75k/160k) | Task: m-payment-integration \nDAIC: Implementation | \u270e 5 files | [4 open]\n\n[When approaching context limit - bar turns red]\n\n\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2591\u2591 78.3% (125k/160k) | Task: m-payment-integration\nDAIC: Discussion | \u270e 12 files | [4 open]\n\n[When no task is active]\n\n\u2588\u2588\u2591\u2591\u2591\u2591\u2591\u2591\u2591\u2591 12.1% (19k/160k) | Task: None\nDAIC: Discussion | \u270e 0 files | [4 open]\n```\n\nProgress bar changes color: green < 50%, orange < 80%, red >= 80%.\n\n</details>\n\nThis isn't complex. It's not heavy process. It's invisible rails that keep Claude from going off the cliff. You still describe what you want in natural language. Claude still writes code. But now it happens in a way that doesn't produce garbage.\n\nYou code at the same speed. You just don't spend the next three hours unfucking what Claude just did.\n\n## \ud83d\ude80 Installation\n\nAlright, you're convinced. **Let's unfuck your workflow.**\n\n### \u2705 Requirements\n\nYou need:\n- **Claude Code** _(you have this or you wouldn't be here)_\n- **Python 3 + pip** _(for the hooks)_\n- **Git** _(probably)_\n- **5 minutes**\n\n### \ud83d\udce6 Install\n\nPick your poison:\n\n**NPM/NPX** (TypeScript Andys):\n```bash\ncd your-broken-project\nnpx cc-sessions # One-time install\n# or\nnpm install -g cc-sessions # Global install\ncc-sessions # Run in your project\n```\n\n**Pip/Pipx/UV** (Pythonistas):\n```bash\npipx install cc-sessions # Isolated install (recommended)\ncd your-broken-project\ncc-sessions # Run the installer\n# or\npip install cc-sessions # Regular pip\n# or \nuv pip install cc-sessions # UV package manager\n```\n\n**Direct Bash** ('build from source' gigachads):\n```bash\ngit clone https://github.com/GWUDCAP/cc-sessions\ncd your-broken-project\n/path/to/cc-sessions/install.sh\n```\n\nThe installer asks you:\n- Your name (so Claude knows who it's disappointing)\n- If you want the statusline (you do)\n- What triggers implementation mode ('go ahead', 'ship it', whatever)\n- Some other config shit (just hit enter)\n\nThat's it. Restart Claude Code. You're done.\n\n### \u2728 What Just Happened\n\nYou now have:\n- Hooks that enforce discussion before implementation\n- State that persists between sessions\n- Task management that actually works\n- Agents that aren't completely useless\n- Git branch enforcement\n- Token warnings before death\n- A chance at maintaining this code in 6 months\n\n### \ud83c\udfaf Your First Task\n\nTell Claude:\n```\nCreate a task for: \n[EXPLAIN THE TASK]\n```\n\nClaude will:\n- Create the task file with proper structure\n- Use the context-gathering agent to gather everything they need to know to complete the task based on your existing codebase\n- Build a context manifest so it never forgets what it learned\n- Set up the task as your current focus\n\nThen just say 'let's work on [task-name]' and watch Claude actually discuss before implementing.\n\n### **Welcome to software development with guardrails.**\n\n---\n\n## \ud83d\udd27 Customizing Sessions\n\nSessions is built to be modified. You can use Claude Code itself to improve Sessions or adapt it to your workflow.\n\n<details>\n<summary>How to customize Sessions</summary>\n\n### Understanding the Structure\n\nSessions comes with knowledge files that explain its own architecture:\n```\nsessions/knowledge/claude-code/\n\u251c\u2500\u2500 hooks-reference.md # How hooks work and can be modified\n\u251c\u2500\u2500 subagents.md # Agent capabilities and customization\n\u251c\u2500\u2500 tool-permissions.md # Tool blocking configuration\n\u2514\u2500\u2500 slash-commands.md # Command system reference\n```\n\n### Modifying Behaviors\n\nTell Claude:\n```\nUsing the hooks reference at @sessions/knowledge/claude-code/hooks-reference.md, \nmodify the DAIC enforcement to allow Bash commands in discussion mode\n```\n\nClaude can:\n- Adjust trigger phrases in `sessions/sessions-config.json`\n- Modify hook behaviors in `.claude/hooks/`\n- Update protocols in `sessions/protocols/`\n- Create new agents in `.claude/agents/`\n- Customize task templates\n\n### Common Customizations\n\n**Change what tools are blocked:**\n```json\n// sessions/sessions-config.json\n\"blocked_tools\": [\"Edit\", \"Write\"] // Remove MultiEdit to allow it\n```\n\n**Add your own trigger phrases:**\n```json\n\"trigger_phrases\": [\"make it so\", \"ship it\", \"do the thing\"]\n```\n\n**Modify agent prompts:**\nEdit files in `.claude/agents/` to change how agents behave.\n\n**Update workflows:**\nProtocols in `sessions/protocols/` are just markdown - edit them to match your process.\n\n### Pro Tips\n\n1. Sessions has its own CLAUDE.md at `sessions/CLAUDE.md` for meta work\n2. Use the knowledge files to understand the system deeply\n3. Test changes in a separate branch first\n4. The hooks are just Python - add logging if needed\n5. Keep your customizations documented\n\nRemember: You're not just using Sessions, you're evolving it. Make it yours.\n\n</details>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Claude Code Sessions Framework - Enforced methodology for AI pair programming",
"version": "0.2.3",
"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": "93d5ab333fad74614d4deeb6cd26db71cddd389ff9db9055b836035e6098e963",
"md5": "3d66a53e46a5a52a562bd64659046927",
"sha256": "80ff2ac61b9ec20b5b6a761a4cdd2958776561e05355eec704ff373f146d92f5"
},
"downloads": -1,
"filename": "cc_sessions-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d66a53e46a5a52a562bd64659046927",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 75251,
"upload_time": "2025-08-28T17:31:46",
"upload_time_iso_8601": "2025-08-28T17:31:46.268828Z",
"url": "https://files.pythonhosted.org/packages/93/d5/ab333fad74614d4deeb6cd26db71cddd389ff9db9055b836035e6098e963/cc_sessions-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bff20a6657be578d40c01746d9b2060546b68a3bc8997bd3d67cd32c82092207",
"md5": "a318b59b463b2779a107a50a1a14f716",
"sha256": "6f7486be29dd3f071ea019f5ea6f24b491312f6cd09102b2206d60728a85777a"
},
"downloads": -1,
"filename": "cc_sessions-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "a318b59b463b2779a107a50a1a14f716",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 75808,
"upload_time": "2025-08-28T17:31:47",
"upload_time_iso_8601": "2025-08-28T17:31:47.156486Z",
"url": "https://files.pythonhosted.org/packages/bf/f2/0a6657be578d40c01746d9b2060546b68a3bc8997bd3d67cd32c82092207/cc_sessions-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 17:31:47",
"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
