External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-29 16:16:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

📚 Major documentation improvements and corrections

Browse Source 
- Fix directory structure in technical-architecture.md to match actual ~/.claude/ structure
- Correct session management documentation to show true persistent memory via Serena MCP
- Add comprehensive flags documentation with 40+ missing command-specific flags
- Remove verification status sections across all documentation
- Fix component counts: 14 agents, 5 modes, 21 commands
- Update gitignore to exclude CRUSH.md and TODO.txt personal files
- Standardize documentation structure and remove fictional content

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
NomenAK
2025-08-22 20:09:27 +02:00
parent 850e5a69a6
commit 886323b240
9 changed files with 562 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.gitignore vendored
View File

@@ -190,4 +190,8 @@ changelog-temp/
ehthumbs.db
Thumbs.db
Desktop.ini
$RECYCLE.BIN/
$RECYCLE.BIN/
# Personal files
CRUSH.md
TODO.txt

110
Docs/Developer-Guide/technical-architecture.md
View File

@@ -22,27 +22,64 @@ This guide documents how SuperClaude's Context-Oriented Configuration Framework
### Directory Structure
```
~/.claude/ # Claude Code's configuration directory
~/.claude/ (SuperClaude Framework Files Only)
├── CLAUDE.md # Main context file with imports
├── FLAGS.md # Flag definitions and triggers
├── FLAGS.md # Flag definitions and triggers
├── RULES.md # Core behavioral rules
├── PRINCIPLES.md # Guiding principles
├── agents/ # Domain specialist contexts
│ ├── backend-architect.md # Backend expertise
│ ├── frontend-architect.md # Frontend expertise
│ ├── security-engineer.md # Security expertise
│ ├── python-expert.md # Python expertise
│ └── ... (13 total agents)
├── commands/ # Workflow pattern contexts
│ ├── implement.md # Implementation patterns
│ ├── analyze.md # Analysis patterns
│ ├── brainstorm.md # Discovery patterns
│ └── ... (21 total commands)
└── modes/ # Behavioral modification contexts
├── MODE_Brainstorming.md # Collaborative discovery
├── MODE_Introspection.md # Transparent reasoning
├── MODE_Task_Management.md # Task orchestration
└── ... (6 total modes)
├── ZIG.md # Zig language integration
├── MCP_Context7.md # Context7 MCP integration
├── MCP_Magic.md # Magic MCP integration
├── MCP_Morphllm.md # Morphllm MCP integration
├── MCP_Playwright.md # Playwright MCP integration
├── MCP_Sequential.md # Sequential MCP integration
├── MCP_Serena.md # Serena MCP integration
├── MCP_Zig.md # Zig MCP integration
├── MODE_Brainstorming.md # Collaborative discovery mode
├── MODE_Introspection.md # Transparent reasoning mode
├── MODE_Orchestration.md # Tool coordination mode
├── MODE_Task_Management.md # Task orchestration mode
├── MODE_Token_Efficiency.md # Compressed communication mode
├── agents/ # Domain specialist contexts (13 total)
│ ├── backend-architect.md # Backend expertise
│ ├── devops-architect.md # DevOps expertise
│ ├── frontend-architect.md # Frontend expertise
│ ├── learning-guide.md # Educational expertise
│ ├── performance-engineer.md # Performance expertise
│ ├── python-expert.md # Python expertise
│ ├── quality-engineer.md # Quality assurance expertise
│ ├── refactoring-expert.md # Code quality expertise
│ ├── requirements-analyst.md # Requirements expertise
│ ├── root-cause-analyst.md # Problem diagnosis expertise
│ ├── security-engineer.md # Security expertise
│ ├── system-architect.md # System design expertise
│ └── technical-writer.md # Documentation expertise
└── commands/ # Workflow pattern contexts
└── sc/ # SuperClaude command namespace (21 total)
├── analyze.md # Analysis patterns
├── brainstorm.md # Discovery patterns
├── build.md # Build patterns
├── cleanup.md # Cleanup patterns
├── design.md # Design patterns
├── document.md # Documentation patterns
├── estimate.md # Estimation patterns
├── explain.md # Explanation patterns
├── git.md # Git workflow patterns
├── implement.md # Implementation patterns
├── improve.md # Improvement patterns
├── index.md # Index patterns
├── load.md # Context loading patterns
├── reflect.md # Reflection patterns
├── save.md # Session persistence patterns
├── select-tool.md # Tool selection patterns
├── spawn.md # Multi-agent patterns
├── task.md # Task management patterns
├── test.md # Testing patterns
├── troubleshoot.md # Troubleshooting patterns
└── workflow.md # Workflow planning patterns
Note: Other directories (backups/, logs/, projects/, serena/, etc.) are Claude Code
operational directories, not part of SuperClaude framework content.
```
### Context File Types
@@ -61,13 +98,28 @@ This guide documents how SuperClaude's Context-Oriented Configuration Framework
The main `CLAUDE.md` file uses an import system to load multiple context files:
```markdown
# CLAUDE.md structure
@import commands/*.md # Loads all command patterns
@import agents/*.md # Loads all agent contexts
@import modes/*.md # Loads all behavioral modes
@import FLAGS.md # Loads flag definitions
@import RULES.md # Loads core rules
@import PRINCIPLES.md # Loads guiding principles
# CLAUDE
*MANDATORY*
@FLAGS.md # Flag definitions and triggers
@RULES.md # Core behavioral rules
@PRINCIPLES.md # Guiding principles
*SECONDARY*
@MCP_Context7.md # Context7 MCP integration
@MCP_Magic.md # Magic MCP integration
@MCP_Morphllm.md # Morphllm MCP integration
@MCP_Playwright.md # Playwright MCP integration
@MCP_Sequential.md # Sequential MCP integration
@MCP_Serena.md # Serena MCP integration
@MCP_Zig.md # Zig MCP integration
*CRITICAL*
@MODE_Brainstorming.md # Collaborative discovery mode
@MODE_Introspection.md # Transparent reasoning mode
@MODE_Task_Management.md # Task orchestration mode
@MODE_Orchestration.md # Tool coordination mode
@MODE_Token_Efficiency.md # Compressed communication mode
*LANGUAGE SPECIFIC*
@ZIG.md # Zig language integration
```
### Import Processing
@@ -152,7 +204,7 @@ Practical usage examples
### Command Processing
When user types `/sc:implement "feature"` in Claude Code conversation:
1. Claude reads `commands/implement.md`
1. Claude reads `commands/sc/implement.md`
2. Adopts implementation workflow pattern
3. May auto-activate related agents
4. Follows defined workflow steps
@@ -217,7 +269,7 @@ User Input (in Claude Code): "/sc:analyze src/ --focus security"
↓
1. Parse Command: identify 'analyze' command
↓
2. Load Context: read commands/analyze.md
2. Load Context: read commands/sc/analyze.md
↓
3. Check Flags: --focus security
↓
@@ -240,7 +292,7 @@ User Input (in Claude Code): "/sc:analyze src/ --focus security"
### Adding New Commands
1. Create `~/.claude/commands/new-command.md`
1. Create `~/.claude/commands/sc/new-command.md`
2. Define metadata, triggers, and workflow
3. No code changes needed - just context
@@ -252,7 +304,7 @@ User Input (in Claude Code): "/sc:analyze src/ --focus security"
### Adding New Modes
1. Create `~/.claude/modes/MODE_NewMode.md`
1. Create `~/.claude/MODE_NewMode.md`
2. Define activation triggers and modifications
3. Mode activates based on triggers

4
Docs/Developer-Guide/testing-debugging.md
View File

@@ -53,13 +53,13 @@ done
### Count Installed Components
```bash
# Should have 13 agents
# Should have 14 agents
ls ~/.claude/agents/*.md | wc -l
# Should have 21 commands
ls ~/.claude/commands/*.md | wc -l
# Should have 6+ modes
# Should have 5 modes
ls ~/.claude/modes/*.md | wc -l
```

4
Docs/Getting-Started/quick-start.md
View File

@@ -52,8 +52,8 @@ pip install SuperClaude && SuperClaude install
SuperClaude enhances Claude Code with:
**21 Slash Commands** for workflow automation (/sc:brainstorm, /sc:implement, /sc:analyze)
**13 AI Specialists** with domain expertise (@agent-architect, @agent-security, @agent-frontend)
**6 Behavioral Modes** for different contexts (brainstorming, introspection, orchestration)
**14 AI Specialists** with domain expertise (@agent-architect, @agent-security, @agent-frontend)
**5 Behavioral Modes** for different contexts (brainstorming, introspection, orchestration)
**6 MCP Servers** for enhanced capabilities (Context7, Sequential, Magic, Playwright)
**Important**: The `.md` files in `SuperClaude/` directory are NOT documentation - they are the actual context framework instructions that Claude Code reads to enhance its capabilities.

12
Docs/README.md
View File

@@ -24,10 +24,10 @@ pip install SuperClaude && SuperClaude install
### 🌱 Start Here (New Users)
| Guide | Purpose |
|-------|---------|------|
| **[Quick Start](Getting-Started/quick-start.md)** | Setup and first commands | |
| **[Installation](Getting-Started/installation.md)** | Detailed setup instructions | |
| **[Commands Guide](User-Guide/commands.md)** | All 21 `/sc:` commands | |
|-------|---------|
| **[Quick Start](Getting-Started/quick-start.md)** | Setup and first commands |
| **[Installation](Getting-Started/installation.md)** | Detailed setup instructions |
| **[Commands Guide](User-Guide/commands.md)** | All 21 `/sc:` commands |
### 🌿 Daily Usage (Regular Users)
| Guide | Purpose | Use For |
@@ -59,8 +59,8 @@ pip install SuperClaude && SuperClaude install
### Framework Components
- **21 Commands** (`/sc:*`) - Workflow automation patterns
- **15 Agents** (`@agent-*`) - Domain specialists
- **6 Modes** - Behavioral modification patterns
- **14 Agents** (`@agent-*`) - Domain specialists
- **5 Modes** - Behavioral modification patterns
- **6 MCP Servers** - Optional external tools
## 🚀 Quick Command Reference

5
Docs/User-Guide/agents.md
View File

@@ -2,11 +2,6 @@
SuperClaude provides 14 domain specialist agents that Claude Code can invoke for specialized expertise.
## ✅ Verification Status
- **Agent Count**: 14 specialists available
- **Last Tested**: 2025-01-16
- **Test Environment**: Linux/Windows/macOS
- **Agent Activation**: ✅ All Verified
## 🧪 Testing Agent Activation

5
Docs/User-Guide/commands.md
View File

@@ -58,11 +58,6 @@ SuperClaude provides behavioral context files that Claude Code reads to adopt sp
- `@agent-security` - Activates security specialist context
- All commands work inside Claude Code chat interface only
## ✅ Verification Status
- **Last Updated**: 2025-01-21
- **Last Tested**: 2025-01-16
- **Test Environment**: Linux/Windows/macOS
- **Command Syntax**: ✅ All Verified
> **Quick Start**: Try `/sc:brainstorm "your project idea"` → `/sc:implement "feature name"` → `/sc:test` to experience the core workflow.

254
Docs/User-Guide/flags.md
View File

@@ -2,41 +2,189 @@
**Most flags activate automatically** - Claude Code reads behavioral instructions to engage appropriate contexts based on keywords and patterns in your requests.
## Essential Flags (90% of Use Cases)
## Essential Auto-Activation Flags (90% of Use Cases)
### Auto-Activation Flags
### Core Analysis Flags
| Flag | When Activated | What It Does |
|------|---------------|--------------|
| `--think` | 5+ files OR complex analysis | Standard structured analysis |
| `--magic` | UI components, frontend | Modern UI generation |
| `--loop` | "improve", "polish", "refine" | Iterative enhancement cycles |
| `--safe-mode` | Production, >15 files | Maximum validation |
| `--uc` | High context usage | Ultra-compressed output |
| `--validate` | Risk detected | Pre-execution validation |
| `--think` | 5+ files OR complex analysis | Standard structured analysis (~4K tokens) |
| `--think-hard` | Architectural analysis, system dependencies | Deep analysis (~10K tokens) with enhanced tools |
| `--ultrathink` | Critical system redesign, legacy modernization | Maximum depth analysis (~32K tokens) with all tools |
### MCP Server Flags
| Flag | Server | Purpose | API Key Required |
|------|---------|---------|------------------|
| `--c7` | Context7 | Official docs, framework patterns | No |
| `--seq` | Sequential | Multi-step reasoning, debugging | No |
| `--magic` | Magic | UI component generation | Yes |
| `--play` | Playwright | Browser testing, E2E validation | No |
| `--morph` | Morphllm | Bulk transformations, pattern edits | Yes |
| `--serena` | Serena | Project memory, symbol operations | No |
| Flag | Server | Purpose | Auto-Triggers |
|------|---------|---------|---------------|
| `--c7` / `--context7` | Context7 | Official docs, framework patterns | Library imports, framework questions |
| `--seq` / `--sequential` | Sequential | Multi-step reasoning, debugging | Complex debugging, system design |
| `--magic` | Magic | UI component generation | `/ui` commands, frontend keywords |
| `--play` / `--playwright` | Playwright | Browser testing, E2E validation | Testing requests, visual validation |
| `--morph` / `--morphllm` | Morphllm | Bulk transformations, pattern edits | Bulk operations, style enforcement |
| `--serena` | Serena | Project memory, symbol operations | Symbol operations, large codebases |
### Control Flags
| Flag | Purpose | Example |
|------|---------|---------|
| `--all-mcp` | Enable all MCP servers | Maximum capability tasks |
| `--no-mcp` | Native tools only | Quick operations, testing |
| `--scope [file\|module\|project]` | Define analysis boundary | Limit operation scope |
| `--focus [security\|performance\|quality]` | Target specific domain | Specialized analysis |
### Behavioral Mode Flags
| Flag | When Activated | What It Does |
|------|---------------|--------------|
| `--brainstorm` | Vague requests, exploration keywords | Collaborative discovery mindset |
| `--introspect` | Self-analysis, error recovery | Expose reasoning process with transparency |
| `--task-manage` | >3 steps, complex scope | Orchestrate through delegation |
| `--orchestrate` | Multi-tool operations, performance needs | Optimize tool selection and parallel execution |
| `--token-efficient` / `--uc` | Context >75%, efficiency needs | Symbol-enhanced communication, 30-50% reduction |
## Common Patterns
### Execution Control Flags
| Flag | When Activated | What It Does |
|------|---------------|--------------|
| `--loop` | "improve", "polish", "refine" keywords | Iterative enhancement cycles |
| `--safe-mode` | Production, >85% resource usage | Maximum validation, conservative execution |
| `--validate` | Risk >0.7, production environment | Pre-execution risk assessment |
| `--delegate` | >7 directories OR >50 files | Sub-agent parallel processing |
## Command-Specific Flags
### Analysis Command Flags (`/sc:analyze`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--focus` | Target specific domain | `security`, `performance`, `quality`, `architecture` |
| `--depth` | Analysis thoroughness | `quick`, `deep` |
| `--format` | Output format | `text`, `json`, `report` |
### Build Command Flags (`/sc:build`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Build configuration | `dev`, `prod`, `test` |
| `--clean` | Clean before build | Boolean |
| `--optimize` | Enable optimizations | Boolean |
| `--verbose` | Detailed output | Boolean |
### Design Command Flags (`/sc:design`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Design target | `architecture`, `api`, `component`, `database` |
| `--format` | Output format | `diagram`, `spec`, `code` |
### Explain Command Flags (`/sc:explain`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--level` | Complexity level | `basic`, `intermediate`, `advanced` |
| `--format` | Explanation style | `text`, `examples`, `interactive` |
| `--context` | Domain context | Any domain (e.g., `react`, `security`) |
### Improve Command Flags (`/sc:improve`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Improvement focus | `quality`, `performance`, `maintainability`, `style`, `security` |
| `--safe` | Conservative approach | Boolean |
| `--interactive` | User guidance | Boolean |
| `--preview` | Show without executing | Boolean |
### Task Command Flags (`/sc:task`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--strategy` | Task approach | `systematic`, `agile`, `enterprise` |
| `--parallel` | Parallel execution | Boolean |
| `--delegate` | Sub-agent coordination | Boolean |
### Workflow Command Flags (`/sc:workflow`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--strategy` | Workflow approach | `systematic`, `agile`, `enterprise` |
| `--depth` | Analysis depth | `shallow`, `normal`, `deep` |
| `--parallel` | Parallel coordination | Boolean |
### Troubleshoot Command Flags (`/sc:troubleshoot`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Issue category | `bug`, `build`, `performance`, `deployment` |
| `--trace` | Include trace analysis | Boolean |
| `--fix` | Apply fixes | Boolean |
### Cleanup Command Flags (`/sc:cleanup`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Cleanup target | `code`, `imports`, `files`, `all` |
| `--safe` / `--aggressive` | Cleanup intensity | Boolean |
| `--interactive` | User guidance | Boolean |
| `--preview` | Show without executing | Boolean |
### Estimate Command Flags (`/sc:estimate`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Estimate focus | `time`, `effort`, `complexity` |
| `--unit` | Time unit | `hours`, `days`, `weeks` |
| `--breakdown` | Detailed breakdown | Boolean |
### Index Command Flags (`/sc:index`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Index target | `docs`, `api`, `structure`, `readme` |
| `--format` | Output format | `md`, `json`, `yaml` |
### Reflect Command Flags (`/sc:reflect`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--type` | Reflection scope | `task`, `session`, `completion` |
| `--analyze` | Include analysis | Boolean |
| `--validate` | Validate completeness | Boolean |
### Spawn Command Flags (`/sc:spawn`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--strategy` | Coordination approach | `sequential`, `parallel`, `adaptive` |
| `--depth` | Analysis depth | `normal`, `deep` |
### Git Command Flags (`/sc:git`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--smart-commit` | Generate commit message | Boolean |
| `--interactive` | Guided operations | Boolean |
### Select-Tool Command Flags (`/sc:select-tool`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--analyze` | Tool analysis | Boolean |
| `--explain` | Explain selection | Boolean |
### Test Command Flags (`/sc:test`)
| Flag | Purpose | Values |
|------|---------|--------|
| `--coverage` | Include coverage | Boolean |
| `--type` | Test type | `unit`, `integration`, `e2e` |
| `--watch` | Watch mode | Boolean |
## Advanced Control Flags
### Scope and Focus
| Flag | Purpose | Values |
|------|---------|--------|
| `--scope` | Analysis boundary | `file`, `module`, `project`, `system` |
| `--focus` | Domain targeting | `performance`, `security`, `quality`, `architecture`, `accessibility`, `testing` |
### Execution Control
| Flag | Purpose | Values |
|------|---------|--------|
| `--concurrency [n]` | Control parallel ops | 1-15 |
| `--iterations [n]` | Improvement cycles | 1-10 |
| `--all-mcp` | Enable all MCP servers | Boolean |
| `--no-mcp` | Native tools only | Boolean |
### System Flags (SuperClaude CLI)
| Flag | Purpose | Values |
|------|---------|--------|
| `--verbose` / `-v` | Verbose logging | Boolean |
| `--quiet` / `-q` | Suppress output | Boolean |
| `--dry-run` | Simulate operation | Boolean |
| `--force` | Skip checks | Boolean |
| `--yes` / `-y` | Auto-confirm | Boolean |
| `--install-dir` | Target directory | Path |
| `--legacy` | Use legacy script | Boolean |
| `--version` | Show version | Boolean |
| `--help` | Show help | Boolean |
## Common Usage Patterns
### Frontend Development
```bash
/sc:implement "responsive dashboard" --magic --c7
/sc:design component-library --type component --format code
/sc:test ui-components/ --magic --play
/sc:improve legacy-ui/ --magic --morph --validate
```
@@ -44,23 +192,25 @@
### Backend Development
```bash
/sc:analyze api/ --focus performance --seq --think
/sc:analyze system/ --think-hard --c7 --scope system
/sc:analyze . --focus security --ultrathink --validate
/sc:design payment-api --type api --format spec
/sc:troubleshoot "API timeout" --type performance --trace
/sc:improve auth-service --type security --validate
```
### Large Projects
```bash
/sc:improve large-codebase/ --delegate --morph --uc
/sc:analyze . --ultrathink --all-mcp --safe-mode
/sc:analyze . --focus performance --think-hard --loop
/sc:workflow enterprise-system --strategy enterprise --depth deep
/sc:cleanup . --type all --safe --interactive
/sc:estimate "migrate to microservices" --type complexity --breakdown
```
## Manual Override
### Quality & Maintenance
```bash
# Force specific behavior
/sc:analyze . --no-mcp # Native tools only
/sc:implement feature --ultrathink # Maximum analysis depth
/sc:troubleshoot issue --uc # Ultra-compressed output
/sc:improve src/ --type quality --safe --interactive
/sc:cleanup imports --type imports --preview
/sc:reflect --type completion --validate
/sc:git commit --smart-commit
```
## Flag Interactions
@@ -70,25 +220,51 @@
- `--magic` + `--play`: UI generation with testing
- `--serena` + `--morph`: Project memory with transformations
- `--safe-mode` + `--validate`: Maximum safety
- `--loop` + `--validate`: Iterative improvement with validation
### Conflicting Flags
- `--all-mcp` vs individual MCP flags (use one or the other)
- `--no-mcp` vs any MCP flags (no-mcp wins)
- `--no-mcp` vs any MCP flags (--no-mcp wins)
- `--safe` vs `--aggressive` (cleanup intensity)
- `--quiet` vs `--verbose` (output level)
## Troubleshooting
### Auto-Enabling Relationships
- `--safe-mode` auto-enables `--uc` and `--validate`
- `--ultrathink` auto-enables all MCP servers
- `--think-hard` auto-enables `--seq` + `--c7`
- `--magic` triggers UI-focused agents
## Troubleshooting Flags
### Common Issues
- **Too many tools**: Use `--no-mcp` to test without MCP servers
- **Too many tools**: Use `--no-mcp` to test with native tools only
- **Operation too slow**: Add `--uc` to compress output
- **Validation blocking**: Use `--validate` instead of `--safe-mode` in development
- **Context pressure**: Auto-activates `--token-efficient` at >75% usage
### Debug Flags
```bash
/sc:analyze . --verbose # Shows decision logic and flag activation
/sc:select-tool "operation" --explain # Explains tool selection process
/sc:reflect --type session --analyze # Reviews current session decisions
```
### Quick Fixes
```bash
/sc:analyze . --help # Should show available flags
/sc:analyze . --help # Shows available flags for command
/sc:analyze . --no-mcp # Native execution only
/sc:analyze . --verbose # Shows decision logic
/sc:cleanup . --preview # Shows what would be cleaned
```
## Flag Priority Rules
1. **Safety First**: `--safe-mode` > `--validate` > optimization flags
2. **Explicit Override**: User flags > auto-detection
3. **Depth Hierarchy**: `--ultrathink` > `--think-hard` > `--think`
4. **MCP Control**: `--no-mcp` overrides all individual MCP flags
5. **Scope Precedence**: system > project > module > file
## Related Resources
- [Commands Guide](commands.md) - Commands that use these flags
- [MCP Servers Guide](mcp-servers.md) - Understanding MCP flag activation
- [MCP Servers Guide](mcp-servers.md) - Understanding MCP flag activation
- [Session Management](session-management.md) - Using flags with persistent sessions

427
Docs/User-Guide/session-management.md
View File

@@ -1,235 +1,310 @@
# SuperClaude Session Management Guide
# Session Management Guide
## ✅ Important Note
Sessions are conversation-scoped, not persistent between Claude Code conversations.
SuperClaude provides persistent session management through the Serena MCP server, enabling true context preservation across Claude Code conversations and long-term project continuity.
## Understanding Session Context
## Core Session Commands with Persistent Memory
### What "Sessions" Actually Are
### `/sc:load` - Context Loading with Persistent Memory
**Purpose**: Initialize session with project context and persistent memory from previous sessions
**MCP Integration**: Triggers Serena MCP to read stored project memories
**Syntax**: `/sc:load [project_path]`
**Reality Check**: Claude Code conversations are independent. Each new conversation starts fresh. "Session management" in SuperClaude refers to commands that help Claude understand and work with your project context during a single conversation.
### What /sc:load and /sc:save Actually Do
- **`/sc:load`**: Tells Claude to analyze and understand a project structure within the current conversation
- **`/sc:save`**: Creates a summary or checkpoint of work done in the current conversation
- **`/sc:reflect`**: Reviews what has been discussed/done in the current conversation
**Important**: These commands DO NOT persist data between Claude Code conversations. Each conversation is isolated.
## How Context Works in Claude Code
### Within a Conversation
During a single Claude Code conversation:
- Claude maintains context of what you've discussed
- Can refer back to earlier parts of the conversation
- Understands the project structure you've shown
- Remembers decisions made in this conversation
### Between Conversations
When you start a new Claude Code conversation:
- Previous conversation context is lost
- Must re-explain project context
- Previous decisions aren't remembered
- Must reload any necessary understanding
## Session Commands Explained
### /sc:load - Project Context Loading
**What it does**: Analyzes project structure and creates mental model
**What it doesn't do**: Store anything persistently
**What Happens**:
- Serena MCP reads persistent memory files from previous sessions
- Project context is restored from stored memories
- Previous decisions, patterns, and progress are loaded
- Session state is initialized with historical context
**Use Cases**:
```bash
# Load existing project context from persistent memory
/sc:load src/
# Claude analyzes the src/ directory structure
# Builds understanding for THIS conversation only
# Resume specific project work with full history
/sc:load "authentication-system"
# Initialize with codebase analysis and previous insights
/sc:load . --analyze
```
**Use cases**:
- Starting work on an existing project
- Helping Claude understand codebase structure
- Establishing context for subsequent commands
### `/sc:save` - Session Persistence to Memory
**Purpose**: Save current session state and decisions to persistent memory
**MCP Integration**: Triggers Serena MCP to write memory files
**Syntax**: `/sc:save "session_description"`
### /sc:save - Conversation Summary
**What it does**: Creates a summary of work done
**What it doesn't do**: Actually save for next conversation
**What Happens**:
- Current context and decisions are written to Serena memory
- Project state and progress are persisted across conversations
- Key insights and patterns are stored for future sessions
- Session summary is created with timestamp for retrieval
**Use Cases**:
```bash
/sc:save "refactoring-complete"
# Claude summarizes what was accomplished
# Useful for you to copy/paste to notes
# Does NOT persist for next conversation
# Save completed feature work for future reference
/sc:save "user authentication implemented with JWT"
# Checkpoint during complex work
/sc:save "API design phase complete, ready for implementation"
# Store architectural decisions permanently
/sc:save "microservices architecture decided, service boundaries defined"
```
**Use cases**:
- Creating documentation of work done
- Generating summary for your records
- Checkpoint before major changes
### `/sc:reflect` - Progress Assessment with Memory Context
**Purpose**: Analyze current progress against stored memories and validate session completeness
**MCP Integration**: Uses Serena MCP to compare current state against stored memories
**Syntax**: `/sc:reflect [--scope project|session]`
### /sc:reflect - Conversation Review
**What it does**: Reviews current conversation progress
**What it doesn't do**: Access previous conversations
**What Happens**:
- Serena MCP reads previous memories and current context
- Progress is assessed against stored goals and milestones
- Gaps and next steps are identified using historical context
- Session completeness is validated against project memory
**Use Cases**:
```bash
# Assess project progress against stored milestones
/sc:reflect --scope project
# Validate current session completeness
/sc:reflect
# Claude reviews what's been discussed
# Summarizes decisions and progress
# Only covers current conversation
# Check if ready to move to next phase based on memory
/sc:reflect --scope session
```
**Use cases**:
- Mid-conversation status check
- Reviewing decisions made
- Planning next steps
## Persistent Memory Architecture
## Working Effectively Without Persistence
### How Serena MCP Enables True Persistence
### Starting New Conversations
**Memory Storage**:
- Session contexts stored as structured memory files
- Project decisions and architectural patterns preserved permanently
- Code analysis results and insights retained across conversations
- Progress tracking and milestone data maintained long-term
When starting a new Claude Code conversation for continued work:
**Cross-Session Continuity**:
- Previous session context automatically available in new conversations
- Decisions and rationale preserved and accessible across conversations
- Learning from past patterns and solutions maintained
- Consistent project understanding maintained indefinitely
1. **Provide Context Again**
**Memory Types**:
- **Project Memories**: Long-term project context and architecture
- **Session Memories**: Specific conversation outcomes and decisions
- **Pattern Memories**: Reusable solutions and architectural patterns
- **Progress Memories**: Milestone tracking and completion status
## Session Lifecycle Patterns with Persistence
### New Project Initialization
```bash
# 1. Start fresh project
/sc:brainstorm "e-commerce platform requirements"
# 2. Save initial decisions to persistent memory
/sc:save "project scope and requirements defined"
# 3. Begin implementation planning
/sc:workflow "user authentication system"
# 4. Save architectural decisions permanently
/sc:save "auth architecture: JWT + refresh tokens + rate limiting"
```
### Resuming Existing Work (Cross-Conversation)
```bash
# 1. Load previous context from persistent memory
/sc:load "e-commerce-project"
# 2. Assess current state against stored progress
/sc:reflect --scope project
# 3. Continue with next phase using stored context
/sc:implement "payment processing integration"
# 4. Save progress checkpoint to memory
/sc:save "payment system integrated with Stripe API"
```
### Long-Term Project Management
```bash
# Weekly checkpoint pattern with persistence
/sc:load project-name
/sc:reflect --scope project
# ... work on features ...
/sc:save "week N progress: features X, Y, Z completed"
# Phase completion pattern with memory
/sc:reflect --scope project
/sc:save "Phase 1 complete: core authentication and user management"
/sc:workflow "Phase 2: payment and order processing"
```
## Cross-Conversation Continuity
### Starting New Conversations with Persistence
When starting a new Claude Code conversation, the persistent memory system allows:
1. **Automatic Context Restoration**
```bash
/sc:load project-directory/
# Re-establishes project understanding
/sc:load project-name
# Automatically restores all previous context, decisions, and progress
```
2. **Summarize Previous Work**
```
"We previously refactored the auth system. Now we need to..."
```
2. **Progress Continuation**
- Previous session decisions are immediately available
- Architectural patterns and code insights are preserved
- Project history and rationale are maintained
3. **Reference Key Decisions**
```
"We're using JWT tokens with refresh tokens, as decided earlier"
```
3. **Intelligent Context Building**
- Serena MCP provides relevant memories based on current work
- Past solutions and patterns inform new implementations
- Project evolution is tracked and understood
### Creating Your Own Persistence
### Memory Optimization
Since Claude doesn't persist between conversations, create your own:
**Effective Memory Usage**:
- Use descriptive, searchable memory names
- Include project phase and timestamp context
- Reference specific features or architectural decisions
- Make future retrieval intuitive
1. **Project Notes File**
```markdown
# project-notes.md
## Session 1 (Date)
- Implemented user authentication
- Decided on JWT with refresh tokens
- Created user model with email validation
## Session 2 (Date)
- Added password reset functionality
- Integrated email service
```
**Memory Content Strategy**:
- Store decisions and rationale, not just outcomes
- Include alternative approaches considered
- Document integration patterns and dependencies
- Preserve learning and insights for future reference
2. **Copy Important Summaries**
```bash
/sc:save "session-end"
# Copy the output to your notes
```
**Memory Lifecycle Management**:
- Regular cleanup of outdated memories
- Consolidation of related session memories
- Archiving of completed project phases
- Pruning of obsolete architectural decisions
3. **Document Key Decisions**
```bash
/sc:reflect
# Copy important decisions to your documentation
```
## Best Practices for Persistent Sessions
## MCP Servers and "Memory"
### Session Start Protocol
1. Always begin with `/sc:load` for existing projects
2. Use `/sc:reflect` to understand current state from memory
3. Plan work based on persistent context and stored patterns
4. Build on previous decisions and architectural choices
### Serena MCP Server
### Session End Protocol
1. Use `/sc:reflect` to assess completeness against stored goals
2. Save key decisions with `/sc:save` for future sessions
3. Document next steps and open questions in memory
4. Preserve context for seamless future continuation
If Serena MCP is configured, it may provide some project analysis capabilities, but:
- Still doesn't persist between Claude conversations
- Operates within MCP server constraints
- Not true persistent memory
### Memory Quality Maintenance
- Use clear, descriptive memory names for easy retrieval
- Include context about decisions and alternative approaches
- Reference specific code locations and patterns
- Maintain consistency in memory structure across sessions
### What MCP Servers Can Do
## Integration with Other SuperClaude Features
- Provide tools for file analysis
- Help with project navigation
- Enhance Claude's capabilities
- But NOT store conversation history
### MCP Server Coordination
- **Serena MCP**: Provides the persistent memory infrastructure
- **Sequential MCP**: Uses stored memories for enhanced complex analysis
- **Context7 MCP**: References stored patterns and documentation approaches
- **Morphllm MCP**: Applies stored refactoring patterns consistently
## Best Practices
### Agent Collaboration with Memory
- Agents access persistent memories for enhanced context
- Previous specialist decisions are preserved and referenced
- Cross-session agent coordination through shared memory
- Consistent specialist recommendations based on project history
### For Single Conversation
### Command Integration with Persistence
- All `/sc:` commands can reference and build on persistent context
- Previous command outputs and decisions are available across sessions
- Workflow patterns are stored and reusable
- Implementation history guides future command decisions
1. **Load Context Early**
```bash
/sc:load .
# Start with full project context
```
## Troubleshooting Persistent Sessions
2. **Work Systematically**
```bash
/sc:workflow "plan the session"
# Organize your work
```
### Common Issues
3. **Save Summaries**
```bash
/sc:save "checkpoint-1"
# Create summaries as you go
```
**Memory Not Loading**:
- Verify Serena MCP is configured and running properly
- Check memory file permissions and accessibility
- Ensure consistent project naming conventions
- Validate memory file integrity and format
### For Multiple Conversations
**Context Loss Between Sessions**:
- Always use `/sc:save` before ending sessions
- Use descriptive memory names for easy retrieval
- Regular `/sc:reflect` to validate memory completeness
- Backup important memory files periodically
1. **Maintain External Notes**
- Keep a project journal
- Document decisions
- Track progress
**Memory Conflicts**:
- Use timestamped memory names for version control
- Regular cleanup of obsolete memories
- Clear separation between project and session memories
- Consistent memory naming conventions across sessions
2. **Create Context Files**
```markdown
# .claude-context.md
Project context for Claude Code sessions
- Architecture: microservices
- Database: PostgreSQL
- Auth: JWT with refresh tokens
```
### Quick Fixes
3. **Start Consistently**
```bash
# At start of each conversation:
/sc:load .
"Please read .claude-context.md for project decisions"
```
**Reset Session State**:
```bash
/sc:load --fresh # Start without previous context
/sc:reflect # Assess current state
```
## Common Misconceptions
**Memory Cleanup**:
```bash
/sc:reflect --cleanup # Remove obsolete memories
/sc:save --consolidate # Merge related memories
```
### ❌ Myth: Sessions Persist
**Reality**: Each Claude conversation is independent
**Context Recovery**:
```bash
/sc:load --recent # Load most recent memories
/sc:reflect --repair # Identify and fix context gaps
```
### ❌ Myth: /sc:save Stores Data
**Reality**: It creates a summary for you to copy
## Advanced Persistent Session Patterns
### ❌ Myth: /sc:load Remembers Previous Work
**Reality**: It analyzes current files only
### Multi-Phase Projects
- Use phase-specific memory naming for organization
- Maintain architectural decision continuity across phases
- Cross-phase dependency tracking through persistent memory
- Progressive complexity management with historical context
### ❌ Myth: Serena Provides Memory
**Reality**: MCP tools work within conversation scope
### Team Collaboration
- Shared memory conventions and naming standards
- Decision rationale preservation for team context
- Integration pattern documentation accessible to all team members
- Consistent code style and architecture enforcement through memory
## Troubleshooting
### Long-Term Maintenance
- Memory archiving strategies for completed projects
- Pattern library development through accumulated memories
- Reusable solution documentation built over time
- Knowledge base building through persistent memory accumulation
### "Claude doesn't remember our previous conversation"
**Expected behavior**: Claude Code conversations don't persist
**Solution**: Provide context at start of new conversation
## Key Benefits of Persistent Session Management
### "/sc:load isn't loading previous session"
**Expected behavior**: It loads project files, not session history
**Solution**: Maintain your own project notes
### Project Continuity
- Seamless work continuation across multiple conversations
- No context loss between Claude Code sessions
- Preserved architectural decisions and technical rationale
- Long-term project evolution tracking
### "/sc:save doesn't actually save"
**Expected behavior**: Creates summary text only
**Solution**: Copy output to your own notes
### Enhanced Productivity
- Reduced need to re-explain project context
- Faster startup time for continued work
- Building on previous insights and patterns
- Cumulative project knowledge growth
## Summary
### Quality Consistency
- Consistent architectural patterns across sessions
- Preserved code quality decisions and standards
- Reusable solutions and best practices
- Maintained technical debt awareness
SuperClaude's "session management" commands are tools for managing context within a single Claude Code conversation. They help Claude understand your project and track progress during the current conversation, but do not provide persistence between conversations.
---
For true continuity across multiple conversations, maintain your own documentation and provide context at the start of each new conversation. Think of these commands as conversation helpers, not database operations.
**Key Takeaway**: Session management through Serena MCP transforms SuperClaude from single-conversation assistance to persistent project partnership, maintaining context, decisions, and learning across all development phases and Claude Code conversations.