# Workshop
[](https://pypi.org/project/claude-workshop/)
[](https://github.com/zachswift615/workshop/actions/workflows/test.yml)
[](https://codecov.io/gh/zachswift615/workshop)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
**Give Claude long-term memory for your projects.**
Workshop is a persistent memory tool that lets Claude Code remember your decisions, preferences, and project context across sessions. Install it once, and Claude automatically maintains institutional knowledge about your codebase - no manual note-taking required.
**For developers using Claude Code** - your AI pair programmer will remember why you made architectural choices, what gotchas to avoid, and what you're working on, even weeks later.
## How It Works
1. **You install Workshop**: `pip install claude-workshop`
2. **You run setup once**: `workshop init`
3. **Claude does everything else**: Records decisions, maintains context, answers "why" questions
Claude automatically:
- 📝 Records architectural decisions with reasoning as you discuss them
- ⚠️ Documents gotchas and constraints as you discover them
- 🔄 Captures session summaries (files changed, commands run, what you worked on)
- 🧠 Answers "why did we choose X?" questions by searching past decisions
- 🎯 Tracks your current goals and next steps
- 🔍 Provides full-text search across all project knowledge
- 📥 **NEW:** Imports historical Claude Code sessions to backfill knowledge
## Installation
```bash
pip install claude-workshop
# Set up Claude Code integration (recommended)
workshop init
```
This sets up Claude Code integration:
- **Global**: Adds Workshop instructions to `~/.claude/settings.json` (Claude will use Workshop in all your projects)
- **Local**: Copies integration files to `.claude/` (auto-loads context at session start, captures session summaries at session end)
That's it! Start a new Claude Code session and Claude will automatically maintain your project's institutional knowledge.
### What Gets Set Up
The `workshop init` command configures Claude Code to:
- Load existing context at the start of each session
- Record decisions, gotchas, and preferences as you work
- Capture session summaries automatically when sessions end
- Answer "why" questions by searching past decisions
## What You Can Do (Optional)
While Claude handles most Workshop interactions automatically, you can also use the CLI directly:
```bash
# Query what Claude has learned
workshop why "using zustand" # Why did we make this choice?
workshop context # What's the current project state?
workshop sessions # What happened in past sessions?
workshop recent # What was recorded recently?
# Manually add entries (though Claude does this automatically)
workshop decision "Using PostgreSQL" -r "Need ACID guarantees for transactions"
workshop gotcha "API rate limit is 100 req/min"
workshop goal add "Implement caching layer"
```
**Most users never need to run these commands** - just let Claude manage everything!
### Import Historical Sessions (NEW in v0.2.0!)
Bootstrap Workshop with knowledge from past Claude Code sessions:
```bash
# Import current project's history
workshop import # Preview what would be imported
workshop import --execute # Actually import historical sessions
# Import specific files
workshop import session.jsonl --execute
# Interactive review
workshop import --interactive --execute
# Check what's been imported
workshop import-status
```
Workshop automatically:
- Extracts decisions, gotchas, and preferences from past conversations
- Tracks what's been imported to avoid duplicates
- Incrementally imports new sessions as they're created
- Uses pattern matching to identify valuable knowledge
### Export for Web Chat
Want to continue a conversation in Claude.ai web chat with full context from your Claude Code sessions?
```bash
workshop export # Export last month of context
workshop export --recent # Export last week only
workshop export --context # Export just current goals/state
workshop export --full # Export everything including notes
workshop export -o context.md # Save to file
```
Copy the output and paste it into a web chat to give Claude continuity between Code and web sessions!
### Web Admin Interface
Workshop includes a web-based admin interface for browsing and managing your knowledge base:
```bash
# Start the web server (requires Flask)
pip install "claude-workshop[web]"
workshop web
# Custom port
workshop web --port 8080
```
Then open http://localhost:5000 in your browser.
**Features:**
- **Dashboard**: Stats and recent entries
- **Browse**: Searchable, filterable list of all entries
- **View/Edit**: Click any entry to view details or make edits
- **Delete**: Remove outdated or incorrect entries
- **Settings**: View and edit your `~/.workshop/config.json`
The Settings page lets you:
- View/edit configuration with syntax highlighting
- Register new projects manually
- Validate configuration and test paths
- See auto-detected vs manually configured projects
## Data Storage
Workshop uses SQLite for fast, efficient storage:
### Database Locations
Workshop automatically finds the right database location using this priority order:
1. **Auto-detected** (default): `.workshop/workshop.db` at your git root
2. **Fallback**: `.workshop/workshop.db` in current directory
3. **Custom**: Configure via `~/.workshop/config.json` (see Configuration below)
### Claude Code Session Files (JSONL)
Claude Code stores conversation transcripts that Workshop can import:
**macOS & Linux:**
```
~/.claude/projects/<normalized-project-path>/*.jsonl
```
Example: `/Users/name/my-project` → `~/.claude/projects/-Users-name-my-project/*.jsonl`
**Windows:**
```
%USERPROFILE%\.claude\projects\<normalized-project-path>\*.jsonl
```
Example: `C:\Users\name\my-project` → `%USERPROFILE%\.claude\projects\C-Users-name-my-project\*.jsonl`
**Path Normalization:**
- Forward slashes (`/`) become hyphens (`-`)
- Underscores (`_`) become hyphens (`-`)
- Drive letters are preserved on Windows
### Configuration File
Workshop supports a global config file at `~/.workshop/config.json`:
```json
{
"version": "1.0",
"default_mode": "per-project",
"projects": {
"/Users/name/my-project": {
"database": "/Users/name/my-project/.workshop/workshop.db",
"jsonl_path": "~/.claude/projects/-Users-name-my-project",
"auto_import": true
}
},
"global": {
"database": "~/.workshop/workshop.db",
"enabled": false
}
}
```
The config file:
- Auto-registers projects when you first use Workshop in them
- Allows manual overrides for database and JSONL locations
- Can be edited via the Web UI (see Web Admin Interface below)
### 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 goal done <text>` - Mark a goal as completed
- `workshop goal clean` - Remove completed goals
- `workshop next add <text>` - Add a next step/TODO
- `workshop next done <text>` - Mark a next step as completed
- `workshop next clean` - Remove completed next steps
### Delete & Clean
- `workshop delete <id>` - Delete an entry by ID
- `workshop delete last` - Delete the most recent entry
- `workshop clean` - Interactively delete entries (last 7 days)
- `workshop clean --type <type>` - Clean only specific entry type
- `workshop clean --days <n>` - Clean entries from last N days
- `workshop clear <date>` - Delete all entries before date (e.g., "2025-01-01" or "30 days ago")
- `workshop clear <date> --type <type>` - Delete entries of specific type before date
### Import & Export
- `workshop import` - Import historical JSONL sessions (preview mode)
- `workshop import --execute` - Actually import sessions
- `workshop import <file.jsonl>` - Import specific file
- `workshop import --interactive` - Review each extraction
- `workshop import-status` - Show import history
- `workshop export` - Export context for web chat (with --recent, --context, --full options)
### 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
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-workshop",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "claude, claude-code, context, memory, notes, decisions, development-tools, cli",
"author": "Claude & Zach",
"author_email": "Claude & Zach Swift <zachswift615@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/76/4d/f4c4dda6e38b0235cd6843b883e7fbb4ca5062bc2ab8088ddb92982b220b/claude_workshop-2.2.9.tar.gz",
"platform": null,
"description": "# Workshop\n\n[](https://pypi.org/project/claude-workshop/)\n[](https://github.com/zachswift615/workshop/actions/workflows/test.yml)\n[](https://codecov.io/gh/zachswift615/workshop)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n**Give Claude long-term memory for your projects.**\n\nWorkshop is a persistent memory tool that lets Claude Code remember your decisions, preferences, and project context across sessions. Install it once, and Claude automatically maintains institutional knowledge about your codebase - no manual note-taking required.\n\n**For developers using Claude Code** - your AI pair programmer will remember why you made architectural choices, what gotchas to avoid, and what you're working on, even weeks later.\n\n## How It Works\n\n1. **You install Workshop**: `pip install claude-workshop`\n2. **You run setup once**: `workshop init`\n3. **Claude does everything else**: Records decisions, maintains context, answers \"why\" questions\n\nClaude automatically:\n- \ud83d\udcdd Records architectural decisions with reasoning as you discuss them\n- \u26a0\ufe0f Documents gotchas and constraints as you discover them\n- \ud83d\udd04 Captures session summaries (files changed, commands run, what you worked on)\n- \ud83e\udde0 Answers \"why did we choose X?\" questions by searching past decisions\n- \ud83c\udfaf Tracks your current goals and next steps\n- \ud83d\udd0d Provides full-text search across all project knowledge\n- \ud83d\udce5 **NEW:** Imports historical Claude Code sessions to backfill knowledge\n\n## Installation\n\n```bash\npip install claude-workshop\n\n# Set up Claude Code integration (recommended)\nworkshop init\n```\n\nThis sets up Claude Code integration:\n- **Global**: Adds Workshop instructions to `~/.claude/settings.json` (Claude will use Workshop in all your projects)\n- **Local**: Copies integration files to `.claude/` (auto-loads context at session start, captures session summaries at session end)\n\nThat's it! Start a new Claude Code session and Claude will automatically maintain your project's institutional knowledge.\n\n### What Gets Set Up\n\nThe `workshop init` command configures Claude Code to:\n- Load existing context at the start of each session\n- Record decisions, gotchas, and preferences as you work\n- Capture session summaries automatically when sessions end\n- Answer \"why\" questions by searching past decisions\n\n## What You Can Do (Optional)\n\nWhile Claude handles most Workshop interactions automatically, you can also use the CLI directly:\n\n```bash\n# Query what Claude has learned\nworkshop why \"using zustand\" # Why did we make this choice?\nworkshop context # What's the current project state?\nworkshop sessions # What happened in past sessions?\nworkshop recent # What was recorded recently?\n\n# Manually add entries (though Claude does this automatically)\nworkshop decision \"Using PostgreSQL\" -r \"Need ACID guarantees for transactions\"\nworkshop gotcha \"API rate limit is 100 req/min\"\nworkshop goal add \"Implement caching layer\"\n```\n\n**Most users never need to run these commands** - just let Claude manage everything!\n\n### Import Historical Sessions (NEW in v0.2.0!)\n\nBootstrap Workshop with knowledge from past Claude Code sessions:\n\n```bash\n# Import current project's history\nworkshop import # Preview what would be imported\nworkshop import --execute # Actually import historical sessions\n\n# Import specific files\nworkshop import session.jsonl --execute\n\n# Interactive review\nworkshop import --interactive --execute\n\n# Check what's been imported\nworkshop import-status\n```\n\nWorkshop automatically:\n- Extracts decisions, gotchas, and preferences from past conversations\n- Tracks what's been imported to avoid duplicates\n- Incrementally imports new sessions as they're created\n- Uses pattern matching to identify valuable knowledge\n\n### Export for Web Chat\n\nWant to continue a conversation in Claude.ai web chat with full context from your Claude Code sessions?\n\n```bash\nworkshop export # Export last month of context\nworkshop export --recent # Export last week only\nworkshop export --context # Export just current goals/state\nworkshop export --full # Export everything including notes\nworkshop export -o context.md # Save to file\n```\n\nCopy the output and paste it into a web chat to give Claude continuity between Code and web sessions!\n\n### Web Admin Interface\n\nWorkshop includes a web-based admin interface for browsing and managing your knowledge base:\n\n```bash\n# Start the web server (requires Flask)\npip install \"claude-workshop[web]\"\nworkshop web\n\n# Custom port\nworkshop web --port 8080\n```\n\nThen open http://localhost:5000 in your browser.\n\n**Features:**\n- **Dashboard**: Stats and recent entries\n- **Browse**: Searchable, filterable list of all entries\n- **View/Edit**: Click any entry to view details or make edits\n- **Delete**: Remove outdated or incorrect entries\n- **Settings**: View and edit your `~/.workshop/config.json`\n\nThe Settings page lets you:\n- View/edit configuration with syntax highlighting\n- Register new projects manually\n- Validate configuration and test paths\n- See auto-detected vs manually configured projects\n\n## Data Storage\n\nWorkshop uses SQLite for fast, efficient storage:\n\n### Database Locations\n\nWorkshop automatically finds the right database location using this priority order:\n\n1. **Auto-detected** (default): `.workshop/workshop.db` at your git root\n2. **Fallback**: `.workshop/workshop.db` in current directory\n3. **Custom**: Configure via `~/.workshop/config.json` (see Configuration below)\n\n### Claude Code Session Files (JSONL)\n\nClaude Code stores conversation transcripts that Workshop can import:\n\n**macOS & Linux:**\n```\n~/.claude/projects/<normalized-project-path>/*.jsonl\n```\nExample: `/Users/name/my-project` \u2192 `~/.claude/projects/-Users-name-my-project/*.jsonl`\n\n**Windows:**\n```\n%USERPROFILE%\\.claude\\projects\\<normalized-project-path>\\*.jsonl\n```\nExample: `C:\\Users\\name\\my-project` \u2192 `%USERPROFILE%\\.claude\\projects\\C-Users-name-my-project\\*.jsonl`\n\n**Path Normalization:**\n- Forward slashes (`/`) become hyphens (`-`)\n- Underscores (`_`) become hyphens (`-`)\n- Drive letters are preserved on Windows\n\n### Configuration File\n\nWorkshop supports a global config file at `~/.workshop/config.json`:\n\n```json\n{\n \"version\": \"1.0\",\n \"default_mode\": \"per-project\",\n \"projects\": {\n \"/Users/name/my-project\": {\n \"database\": \"/Users/name/my-project/.workshop/workshop.db\",\n \"jsonl_path\": \"~/.claude/projects/-Users-name-my-project\",\n \"auto_import\": true\n }\n },\n \"global\": {\n \"database\": \"~/.workshop/workshop.db\",\n \"enabled\": false\n }\n}\n```\n\nThe config file:\n- Auto-registers projects when you first use Workshop in them\n- Allows manual overrides for database and JSONL locations\n- Can be edited via the Web UI (see Web Admin Interface below)\n\n### Migration from JSON\n\nIf 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.\n\n## Claude Code Integration\n\nWorkshop integrates seamlessly with Claude Code to maintain context across sessions.\n\n### Global Setup (Recommended)\n\nAdd Workshop instructions to your global Claude Code settings so it's available in all projects:\n\n**Already done!** If you have `~/.claude/settings.json` configured, Claude will automatically:\n- Check for Workshop at session start\n- Use Workshop to record decisions, gotchas, and preferences\n- Query Workshop for historical context\n\n### Project-Specific Setup\n\nFor per-project integration with automatic context loading:\n\n1. Copy `.claude/` directory from this repo to your project\n2. The SessionStart hook will auto-load Workshop context\n3. Custom instructions will guide Claude's Workshop usage\n\nSee `.claude/README.md` for details.\n\n### How It Works\n\n- **Session Start**: Claude checks if Workshop is available\n- **During Session**: Claude records important information:\n - Architectural decisions with reasoning\n - Failed approaches and why\n - User preferences and coding style\n - Gotchas and constraints\n - Current goals and next steps\n- **Context Queries**: Claude searches Workshop when needing historical context\n\n### Benefits\n\n- **Continuity**: Pick up exactly where you left off\n- **Institutional Knowledge**: Never lose context about why things are the way they are\n- **Collaboration**: Share context with future sessions (and future you!)\n- **Efficiency**: Avoid re-discovering the same information\n\n\n## Commands Reference\n\n### Write Entries\n- `workshop note <text>` - Add a note\n- `workshop decision <text> -r <reasoning>` - Record a decision with reasoning \n- `workshop gotcha <text>` - Document a gotcha or constraint\n- `workshop preference <text>` - Save a user preference\n- `workshop antipattern <text>` - Record an antipattern to avoid\n\n### Query & Search\n- `workshop why <query>` - Smart search answering \"why did we do X?\"\n- `workshop search <query>` - Full-text search across all entries\n- `workshop context` - Show current session context summary\n- `workshop recent` - Show recent entries\n- `workshop read --type <type>` - Filter entries by type\n\n### Session History\n- `workshop sessions` - List recent sessions\n- `workshop session <id|last>` - View session details\n\n### State Management\n- `workshop goal add <text>` - Add a goal\n- `workshop goal list` - List active goals\n- `workshop goal done <text>` - Mark a goal as completed\n- `workshop goal clean` - Remove completed goals\n- `workshop next add <text>` - Add a next step/TODO\n- `workshop next done <text>` - Mark a next step as completed\n- `workshop next clean` - Remove completed next steps\n\n### Delete & Clean\n- `workshop delete <id>` - Delete an entry by ID\n- `workshop delete last` - Delete the most recent entry\n- `workshop clean` - Interactively delete entries (last 7 days)\n- `workshop clean --type <type>` - Clean only specific entry type\n- `workshop clean --days <n>` - Clean entries from last N days\n- `workshop clear <date>` - Delete all entries before date (e.g., \"2025-01-01\" or \"30 days ago\")\n- `workshop clear <date> --type <type>` - Delete entries of specific type before date\n\n### Import & Export\n- `workshop import` - Import historical JSONL sessions (preview mode)\n- `workshop import --execute` - Actually import sessions\n- `workshop import <file.jsonl>` - Import specific file\n- `workshop import --interactive` - Review each extraction\n- `workshop import-status` - Show import history\n- `workshop export` - Export context for web chat (with --recent, --context, --full options)\n\n### Utilities\n- `workshop info` - Show workspace information\n- `workshop init` - Set up Claude Code integration\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nIssues and pull requests welcome at https://github.com/zachswift615/workshop\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Persistent context and memory tool for Claude Code sessions",
"version": "2.2.9",
"project_urls": {
"Homepage": "https://github.com/zachswift615/workshop",
"Issues": "https://github.com/zachswift615/workshop/issues",
"Repository": "https://github.com/zachswift615/workshop"
},
"split_keywords": [
"claude",
" claude-code",
" context",
" memory",
" notes",
" decisions",
" development-tools",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "70441c91613e3bcc51580ca01f5832f60288fca09791b2be8e695e909b2c9ac8",
"md5": "42a69ff88fa832a8ffae2b630ba64f6d",
"sha256": "009f8b42bb3de1ccc281088d579679209e07929338a69608e2843c4565ed6c7c"
},
"downloads": -1,
"filename": "claude_workshop-2.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "42a69ff88fa832a8ffae2b630ba64f6d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 85731,
"upload_time": "2025-10-06T20:52:00",
"upload_time_iso_8601": "2025-10-06T20:52:00.833578Z",
"url": "https://files.pythonhosted.org/packages/70/44/1c91613e3bcc51580ca01f5832f60288fca09791b2be8e695e909b2c9ac8/claude_workshop-2.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "764df4c4dda6e38b0235cd6843b883e7fbb4ca5062bc2ab8088ddb92982b220b",
"md5": "7370cb9899b7d2a17cc3ff6969e7c2f3",
"sha256": "a58b3a4b74f21c73e4a01bd81b1042b4ea7d7b3e4f797f48dd42bc65e4f0f3af"
},
"downloads": -1,
"filename": "claude_workshop-2.2.9.tar.gz",
"has_sig": false,
"md5_digest": "7370cb9899b7d2a17cc3ff6969e7c2f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 86165,
"upload_time": "2025-10-06T20:52:02",
"upload_time_iso_8601": "2025-10-06T20:52:02.137386Z",
"url": "https://files.pythonhosted.org/packages/76/4d/f4c4dda6e38b0235cd6843b883e7fbb4ca5062bc2ab8088ddb92982b220b/claude_workshop-2.2.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 20:52:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zachswift615",
"github_project": "workshop",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claude-workshop"
}
JSON
