Metadata-Version: 2.4
Name: claude-workshop
Version: 0.1.0
Summary: Persistent context and memory tool for Claude Code sessions
Author: Claude & Zach
Author-email: Claude & Zach Swift <zachswift615@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/zachswift615/workshop
Project-URL: Repository, https://github.com/zachswift615/workshop
Project-URL: Issues, https://github.com/zachswift615/workshop/issues
Keywords: claude,claude-code,context,memory,notes,decisions,development-tools,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
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 :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# Workshop

**Persistent context and memory tool for Claude Code sessions.**

Workshop helps Claude remember decisions, gotchas, preferences, and context across sessions. Never lose track of why you made a choice or what you were working on.

## Features

- 🧠 **Smart Context Search** - Ask "why did we do X?" and get instant answers with reasoning
- 📝 **Decision Tracking** - Record architectural decisions with full reasoning
- ⚠️ **Gotcha Documentation** - Never forget edge cases and constraints
- 🔄 **Session Summaries** - Automatic capture of what happened in each session
- 🔍 **Full-Text Search** - Fast SQLite FTS5 search across all entries
- 🎯 **Goal & State Management** - Track what you're working on and what's next
- 🤖 **Claude Code Integration** - Seamless integration with automatic context loading

## Installation

```bash
pip install claude-workshop

# Set up Claude Code integration (recommended)
workshop init
```

This will:
- Add Workshop instructions to global Claude Code settings (`~/.claude/settings.json`)
- Copy integration files to local project (`.claude/` directory)
- Enable automatic context loading at session start

### Manual Installation Options

```bash
# Global only (Claude checks for Workshop in all projects)
workshop init --global

# Local only (auto-load context in current project)
workshop init --local
```

## Quick Start

```bash
# Write entries
workshop note "Implemented user authentication flow"
workshop decision "Using zustand for state management" --reasoning "Simpler API than Redux, better TypeScript support"
workshop gotcha "Stripe webhooks need raw body parser disabled"
workshop preference "User prefers verbose comments explaining the why"

# Query and search
workshop why "using zustand"        # Smart search - answers "why did we do X?"
workshop context                    # Show current session context
workshop search "authentication"    # Search all entries
workshop read --type decision       # Show all decisions
workshop recent                     # Show recent entries

# Manage state
workshop goal add "Implement payment processing"
workshop next "Add error boundaries for auth failures"
```

## Data Storage

Workshop uses SQLite for fast, efficient storage:
- **Project-specific**: `./.workshop/workshop.db` in your project root
- **Global**: `~/.workshop/workshop.db` for cross-project context
- **Custom location**: Set `WORKSHOP_DIR` environment variable

### Migration from JSON

If you're upgrading from an earlier version that used JSON storage, Workshop will automatically migrate your data to SQLite on first run and create a backup of your JSON file.

## Claude Code Integration

Workshop integrates seamlessly with Claude Code to maintain context across sessions.

### Global Setup (Recommended)

Add Workshop instructions to your global Claude Code settings so it's available in all projects:

**Already done!** If you have `~/.claude/settings.json` configured, Claude will automatically:
- Check for Workshop at session start
- Use Workshop to record decisions, gotchas, and preferences
- Query Workshop for historical context

### Project-Specific Setup

For per-project integration with automatic context loading:

1. Copy `.claude/` directory from this repo to your project
2. The SessionStart hook will auto-load Workshop context
3. Custom instructions will guide Claude's Workshop usage

See `.claude/README.md` for details.

### How It Works

- **Session Start**: Claude checks if Workshop is available
- **During Session**: Claude records important information:
  - Architectural decisions with reasoning
  - Failed approaches and why
  - User preferences and coding style
  - Gotchas and constraints
  - Current goals and next steps
- **Context Queries**: Claude searches Workshop when needing historical context

### Benefits

- **Continuity**: Pick up exactly where you left off
- **Institutional Knowledge**: Never lose context about why things are the way they are
- **Collaboration**: Share context with future sessions (and future you!)
- **Efficiency**: Avoid re-discovering the same information


## Commands Reference

### Write Entries
- `workshop note <text>` - Add a note
- `workshop decision <text> -r <reasoning>` - Record a decision with reasoning  
- `workshop gotcha <text>` - Document a gotcha or constraint
- `workshop preference <text>` - Save a user preference
- `workshop antipattern <text>` - Record an antipattern to avoid

### Query & Search
- `workshop why <query>` - Smart search answering "why did we do X?"
- `workshop search <query>` - Full-text search across all entries
- `workshop context` - Show current session context summary
- `workshop recent` - Show recent entries
- `workshop read --type <type>` - Filter entries by type

### Session History
- `workshop sessions` - List recent sessions
- `workshop session <id|last>` - View session details

### State Management
- `workshop goal add <text>` - Add a goal
- `workshop goal list` - List active goals
- `workshop next <text>` - Add a next step/TODO

### Utilities
- `workshop info` - Show workspace information
- `workshop init` - Set up Claude Code integration

## License

MIT License - see LICENSE file for details.

## Contributing

Issues and pull requests welcome at https://github.com/zachswift615/workshop

