Metadata-Version: 2.4
Name: cc-sessions
Version: 0.1.6
Summary: Claude Code Sessions Framework - Enforced methodology for AI pair programming
Author-email: toast <toast_x@bytebot.site>
License: MIT
Project-URL: Homepage, https://github.com/GWUDCAP/cc-sessions
Project-URL: Documentation, https://github.com/GWUDCAP/cc-sessions#readme
Project-URL: Repository, https://github.com/GWUDCAP/cc-sessions.git
Project-URL: Issues, https://github.com/GWUDCAP/cc-sessions/issues
Keywords: claude,claude-code,ai,pair-programming,daic,workflow,development
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: tiktoken>=0.5.0

```
███████╗███████╗███████╗███████╗██╗ ██████╗ ███╗   ██╗███████╗
██╔════╝██╔════╝██╔════╝██╔════╝██║██╔═══██╗████╗  ██║██╔════╝
███████╗█████╗  ███████╗███████╗██║██║   ██║██╔██╗ ██║███████╗
╚════██║██╔══╝  ╚════██║╚════██║██║██║   ██║██║╚██╗██║╚════██║
███████║███████╗███████║███████║██║╚██████╔╝██║ ╚████║███████║
╚══════╝╚══════╝╚══════╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝
```

<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 boner  
- 😬 The people hyping LLM programming made your boner crawl back into your body <br> <sub>_(are you ready to 'scale your impact', dog?)_</sub> 
- 🤮 You held your nose and downloaded Cursor/added Cline or Roo Code/npm installed Claude Code <br> <sub>_(after regretfully installing Node.js jk typescripters don't cry is just joke)_</sub>

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?

You learned to be more specific. `'ONLY change lines 45-52.'` Claude changes lines 45-52. **Also lines 1-44.** Also creates a new file you didn't ask for. Also helpful reminder that you should add TypeScript types _(you're writing Python)_.

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 state management patterns. 

Your auth flow has several functions that are hard coded to give everyone the keys to your whole server. 

You've got utility functions that are duplicated in four files because Claude kept forgetting they exist.

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.

### **You're not a programmer anymore. You're a prompt engineer with a production system that makes you want to slam your genitalia in a drawer.**

</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.**

<details>
<summary><strong>The DAIC workflow explained</strong> <em>(see how it actually works)</em></summary>

<br>

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.

Now when you start working, Claude is in Discussion Mode by default. It can read files, search code, analyze patterns. But it can't edit anything. Can't write. Can't even create a file. It HAS to talk to you first.

You: 'Add error handling to the auth flow'
Claude: *reads the auth code, understands the patterns, explains what it found and what it plans to do*
You: 'go ahead'
Claude: *NOW it can edit*

That's it. That's the whole DAIC thing. Discussion, Alignment, Implementation, Check. Claude can't skip ahead. The hooks literally block the tools.

</details>

<details>
<summary>**See it in action**</summary>

```
You: add user search to the dashboard

Claude: I'll help add user search to the dashboard. Let me first examine the current implementation.

[reads dashboard components, existing search patterns, API structure]

Looking at your codebase:
- Dashboard uses /components/Dashboard/index.tsx
- You have a SearchBar component already in /components/common/
- API has a users.search endpoint that's not being used
- Your other searches use debouncing with 300ms delay

I can add user search by:
1. Importing the existing SearchBar component
2. Adding state management with your existing useQueryState hook
3. Connecting to the users.search endpoint
4. Following your debounce pattern from products search

Should I implement this?

You: yep go ahead

Claude: [NOW Claude can edit - implements exactly what was discussed]
```

Without Sessions? Claude would've created a new search component, ignored your API endpoint, and used a different state pattern.

</details>

<details>
<summary><strong>Key features in detail</strong> <em>(persistent context, agents, enforcement)</em></summary>

<br>

When your context window hits 75%, you get a warning. Not after it dies. Before. You wrap up clean, save your work, start fresh. The task file has everything - what you're building, what you've done, what's next. Claude reads it and continues exactly where you left off.

<details>
<summary>Context persistence demo</summary>

```
[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: 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>

Those subagents that were useless? Now they get the entire context of your conversation so far (unless you dont need them to have it). They have strict instructions to record their findings in the appropriate sessions/ files and communicate with your main Claude Code thread when they are done. 

The code review agent knows your patterns. The context gathering agent knows your stack. The logging agent is basically a copy of your current conversation. They run in separate threads so your main context stays clean. They come back with actual useful information instead of random shit they guessed.

<details>
<summary>Agents that actually work</summary>

```
You: Lets start the caching upgrades 

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>

Your tasks aren't todos that disappear. They're persistent files with context manifests that explain how everything works, work logs that track what's been done, and success criteria that define done. Forever. You can leave for a month and come back to perfect context.

Branch enforcement means Claude checks what branch you're on before every edit. Wrong branch? Blocked. Here's the command to fix it. No more accidentally editing main. No more git archaeology.

<details>
<summary>Branch enforcement in action</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>

Your CLAUDE.md stays under 100 lines because Claude Code no longer needs 1000 rules to try to prevent it from American Psycho-ing your server's file system. A few key behavioral rules in CLAUDE.sessions.md and the rest is enforced by programmatic hooks - not suggestions Claude might follow. Actual enforcement that can't be ignored.

The statusline shows you everything in real-time. Current task. DAIC mode. Token usage. Number of edited files to go in staging. Number of open tasks that need to be addressed. You always know what's happening.

<details>
<summary>Statusline keeping you informed</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>

When Claude is done implementing, it's reminded to run 'daic' to return to discussion mode. Can't edit anything until you explicitly allow it again. No more runaway implementations. No more surprise refactors.

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.

</details>

## 🚀 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>
