# Claudette
<img walt="Claudette" src="https://github.com/user-attachments/assets/ea21e509-2aa6-4ca6-b3e5-51248bef8395" />
Git worktree management for Apache Superset development, made simple. Fully loaded, concurrent dev environments, ready for Claude Code.
<img src="https://github.com/user-attachments/assets/eb809525-0783-4fa3-934b-cbbe740dd773" />
<img src="https://github.com/user-attachments/assets/8367ec7f-791f-49ad-89fd-e0dcd5169fa8" />
[](https://opensource.org/licenses/Apache-2.0)
## Get Started
```bash
# Install claudette
pip install git+https://github.com/mistercrunch/claudette-cli.git
# Initialize your environment (clones Superset and sets up base config)
claudette init
# See available commands
claudette --help
# Pro tip: Use 'clo' as a shorter alias for claudette!
clo --help
```
## Features
- 🌳 **Git Worktree Management** - Isolated branches in separate directories
- 🐍 **Automatic Python Environment** - Each project gets its own venv with dependencies
- 📦 **Node.js Isolation** - Separate node_modules per project
- 🐳 **Docker Integration** - Run containers on different ports per project
- 🎨 **Beautiful CLI** - Powered by Typer and Rich for a great experience
- 🔧 **Claude Code Integration** - Automatic environment setup for AI assistance
- ⚡ **Fast Setup** - Uses `uv` for blazing fast Python package installation
- 📝 **PROJECT.md Standard** - Persistent branch docs in `~/.claudette/projects/`, symlinked to worktrees
- 🔗 **Shared CLAUDE.local.md** - Single source of truth for Claude instructions across all projects
- 🎯 **Auto Port Assignment** - Automatically finds available ports when not specified
- 🧊 **Freeze/Thaw Projects** - Save ~3GB per project by removing dependencies when not in use
- 🔗 **GitHub PR Integration** - Track and quickly access pull requests associated with projects
## Installation
### From PyPI (coming soon)
```bash
pip install claudette
```
### From Source
```bash
git clone https://github.com/yourusername/claudette.git
cd claudette
pip install -e .
```
**Note:** Both `claudette` and `clo` commands will be available after installation. Use whichever you prefer!
### Prerequisites
1. **Initialize Claudette**:
```bash
claudette init
```
This will clone the Superset repository and set up your environment.
2. **Required Tools**:
- Python 3.8+
- Git with worktree support
- Docker and docker-compose
- Node.js and npm
- `uv` (will be installed automatically)
## Quick Start
```bash
# Initialize claudette environment
claudette init
# Create a new project (port auto-assigned)
clo add my-feature
# Or specify a port
clo add my-feature 9007
# Drop into Docker container for development
clo shell
# Or run a quick command
clo shell -- python --version
# Access the database directly
clo psql -- -c "\\dt"
# Start Docker containers
clo docker up
# Launch Claude with project context
clo claude code
# Link a GitHub PR to the project
clo pr link 12345
# Check project status
clo status
# List all projects
clo list
# Freeze inactive project to save space
clo freeze old-feature
# Thaw when ready to work again
clo thaw old-feature
# Clean up when done
clo remove my-feature
```
## Commands
All commands below can be run with either `claudette` or its shorter alias `clo`.
### `claudette init`
Initializes claudette environment:
- Clones Apache Superset base repository
- Creates configuration directory
- Sets up templates for CLAUDE.local.md and .claude_rc
### `claudette add <project> [port]`
Creates a new worktree project with:
- Git worktree branch (with conflict resolution)
- Python virtual environment with all dependencies
- Frontend node_modules
- Pre-commit hooks
- Docker configuration
- Auto-assigns port if not specified
### `claudette activate <project>` / `claudette shell`
- `activate`: Starts a new shell with Python venv activated and project environment
- `shell`: Drop into Docker container or run commands
- Interactive mode: `clo shell` enters bash shell
- Command mode: `clo shell -- <command>` runs command and exits
- Auto-starts containers if not running
- Examples:
- `clo shell -- python --version` - Check Python version
- `clo shell -- superset db upgrade` - Run database migrations
- `clo shell -- bash -c "ls -la | head"` - Complex commands
### `claudette list`
Shows all projects with their ports, Docker status, freeze state, and PRs:
```
┏━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━┓
┃ Project ┃ Port ┃ Path ┃ Status ┃ State ┃ PR ┃
┡━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━┩
│ my-feature │ 9007 │ code/superset-worktree/my-... │ 🟢 │ 🟢 │ #123 │
│ bug-fix │ 9008 │ code/superset-worktree/bug... │ ⚫ │ 🧊 │ ? │
└─────────────┴──────┴───────────────────────────────┴────────┴───────┴──────┘
```
### `claudette status [project]`
Shows detailed project status:
- Git branch and uncommitted changes
- Docker container status
- Python venv status
- Recent commits
### `claudette docker [args]`
Wrapper for docker-compose that automatically:
- Sets the correct NODE_PORT
- Uses the project name for container prefix
- Passes through all docker-compose commands
### `claudette claude [args]`
Launches claude CLI with project context:
- Sets working directory to project root
- Requires activated project (via $PROJECT)
- Passes through all arguments
### `claudette jest [args]` / `claudette pytest [args]`
Run tests with project context:
- `jest`: Frontend tests with all arguments passed to npm test
- `pytest`: Backend tests using Docker with automatic test database setup
### `claudette psql`
Direct PostgreSQL database access:
- Interactive mode: `clo psql` enters psql shell
- Command mode: `clo psql -- -c "SELECT..."` runs query and exits
- Auto-starts containers if not running
- Examples:
- `clo psql -- -c "\\dt"` - List all tables
- `clo psql -- -c "SELECT COUNT(*) FROM ab_user;"` - Run query
- `clo psql -- -f script.sql` - Execute SQL file
### `claudette nuke-db [project]`
Nukes the PostgreSQL database volume:
- Stops containers first
- Removes the Docker volume completely
- Useful for fresh database state
### `claudette remove <project>`
Cleanly removes a project:
- Stops Docker containers
- Removes git worktree
- Cleans up all project files
### `claudette sync [project]`
Syncs PROJECT.md content with claudette metadata:
- Updates project description from PROJECT.md
- Refreshes what shows in `claudette list`
- Run after editing PROJECT.md
### `claudette freeze <project>`
Freezes a project to save disk space (~3GB per project):
- Removes node_modules directory
- Removes Python .venv directory
- Project must be thawed before use
- Use `--force` to skip confirmation
### `claudette thaw <project>`
Thaws a frozen project to restore dependencies:
- Reinstalls npm packages with `npm ci`
- Recreates Python venv and installs packages
- Automatically triggered by commands that need dependencies
### `claudette pr <action> [pr_number] [project]`
Manage GitHub PR associations:
- `clo pr link <pr_number>` - Associate a PR with current/specified project
- `clo pr clear` - Remove PR association from current/specified project
- `clo pr open` - Open associated PR in browser
### `claudette nuke` (DANGEROUS!)
Completely removes claudette and all projects:
- Stops ALL Docker containers
- Removes ALL worktrees
- Deletes entire ~/.claudette directory
- Requires typing "NUKE" to confirm
## Configuration
### Environment Variables
- `CLAUDETTE_WORKTREE_BASE` - Base directory for worktrees (default: `~/code/superset-worktree`)
- `CLAUDETTE_PYTHON_VERSION` - Python version to use (default: `python3.11`)
### Files & Directories
#### Project Folder Structure
Each project gets a dedicated folder in `~/.claudette/projects/{project}/` containing:
- `.claudette` - Project metadata (port, path, description)
- `PROJECT.md` - Branch-specific documentation (symlinked to worktree)
- `.env.local` - Local environment variables (symlinked to worktree, future)
#### File Hierarchy
- `CLAUDE.md` - Repo-wide Superset development guidelines (in Superset repo)
- `CLAUDE.local.md` - Shared claudette configuration (symlinked to all worktrees)
- `PROJECT.md` - Branch-specific docs (lives in project folder, symlinked to worktree)
- `.claude_rc` - Central configuration referencing the PROJECT.md standard
### PROJECT.md Standard
Claudette uses PROJECT.md for branch-specific documentation:
- Lives in `~/.claudette/projects/{project}/PROJECT.md`
- Symlinked into worktree for easy editing
- Edit in your worktree → changes persist in project folder
- Survives worktree removal/recreation
- Use `--keep-docs` with `claudette remove` to preserve for later
- Claude loads PROJECT.md when present for branch context
### Extensible Architecture
The project folder structure is designed to be extensible. Files are managed via constants in the code, making it easy to add more symlinked files in the future (scripts, configs, etc.).
### Automatic Migration
Claudette automatically migrates older installations to the latest structure. A version file (`~/.claudette/.claudette.json`) tracks the schema version and ensures smooth upgrades without user intervention.
## Development Workflow
1. **Initialize claudette** (first time only):
```bash
claudette init
```
2. **Create a feature branch**:
```bash
claudette add new-feature # Auto-assigns port
```
3. **Activate the project**:
```bash
clo shell # Drop into Docker container (recommended)
# OR
clo activate new-feature # Activate Python venv in local shell
```
4. **Start services**:
```bash
claudette docker up
```
5. **Develop with AI assistance**:
```bash
claudette claude code # Opens Claude Code with project context
```
6. **Run tests**:
```bash
clo pytest tests/unit_tests/ # Backend tests via Docker
clo jest --watch # Frontend tests
pre-commit run --all-files # Code quality checks
```
7. **Check status**:
```bash
claudette status
```
8. **Clean up**:
```bash
exit # Leave Docker container (or Ctrl+D)
clo docker down # Stop containers
clo remove new-feature # Remove project
```
## Why Claudette?
Managing multiple Superset development environments is painful:
- Switching branches breaks your node_modules
- Frontend port conflicts when running multiple versions
- Python dependencies get mixed up
- Docker containers collide
Claudette solves this by giving each feature branch its own **complete** environment.
## How It Works
1. **Git Worktrees**: Each project is a separate git worktree, allowing multiple branches to be checked out simultaneously
2. **Isolated Environments**: Each project gets its own:
- Python virtual environment (`.venv`)
- Node modules (`node_modules`)
- Docker containers (prefixed by project name)
- Frontend port (9000-9999 range)
3. **Shared Configuration**: Common files like `CLAUDE.local.md` are symlinked to keep consistency
## Troubleshooting
### "Port already in use"
```bash
# Check what's using the port
lsof -i :9007
# Or just pick a different port
claudette add my-feature 9008
```
### "Git worktree already exists"
Claudette handles this automatically! When adding a project:
- Choose to reuse the existing branch
- Create a new branch with a different name
- Delete the existing branch and start fresh
Or use flags:
```bash
claudette add my-feature --reuse # Use existing branch
claudette add my-feature --force-new # Delete and recreate
claudette add my-feature --name alt-name # Use different branch name
```
### "Project is frozen"
Frozen projects have their dependencies removed to save space. When you try to use a frozen project:
```bash
# Either thaw it first
claudette thaw my-feature
# Or commands will prompt you to thaw automatically
claudette shell my-feature # Will ask to thaw first
```
### "Docker containers won't start"
```bash
# Check if containers are already running
docker ps
# Force remove old containers
claudette docker down
docker system prune
```
## Advanced Usage
### Custom Base Directory
```bash
export CLAUDETTE_WORKTREE_BASE=~/projects/superset
claudette add my-feature 9007
```
### Using with VS Code
```bash
# Open project in VS Code with correct Python interpreter
claudette shell my-feature
code . # VS Code will detect the activated venv
```
### Running Tests in Isolation
```bash
# Backend tests (using Docker with automatic test DB setup)
clo pytest tests/unit_tests/
clo pytest -x tests/ # Stop on first failure
clo pytest -v tests/unit_tests/ # Verbose output
clo pytest --nuke tests/ # Nuke and recreate test database
clo pytest -k test_charts # Run tests matching pattern
clo pytest --maxfail=3 tests/ # Stop after 3 failures
# Frontend tests
clo jest # Run all tests
clo jest --watch # Watch mode
clo jest --coverage # Coverage report
clo jest src/components/Button # Test specific directory
clo jest superset-frontend/src/components/Button # Auto-strips prefix
```
### Refreshing Database
```bash
# Completely wipe the PostgreSQL database
claudette nuke-db
claudette docker up # Starts fresh
```
### Managing Disk Space
```bash
# Freeze inactive projects to save ~3GB each
clo freeze old-project
clo freeze another-project --force # Skip confirmation
# List projects to see which are frozen
clo list # Frozen projects show 🧊 icon
# Thaw when ready to work
clo thaw old-project
```
### Working with GitHub PRs
```bash
# Link a PR to your project
clo pr link 12345
# View PR association
clo status # Shows PR number
clo list # Shows PR column
# Open PR in browser
clo pr open
# Clear PR association
clo pr clear
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### Development Setup
```bash
git clone https://github.com/yourusername/claudette.git
cd claudette
pip install -e ".[dev]"
```
## License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
## Credits
Built with:
- [Typer](https://typer.tiangolo.com/) - CLI framework
- [Rich](https://rich.readthedocs.io/) - Terminal formatting
- [uv](https://github.com/astral-sh/uv) - Fast Python package installer
Name inspired by Claude (Anthropic's AI assistant) + "-ette" (French diminutive suffix).
Raw data
{
"_id": null,
"home_page": null,
"name": "superset-claudette",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "development, git, superset, workflow, worktree",
"author": null,
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/37/37/70397bbd985a61d2425c74706c13fe17a7352b3e7d6616fbdccefb25cd85/superset_claudette-0.1.6.tar.gz",
"platform": null,
"description": "# Claudette\n\n<img walt=\"Claudette\" src=\"https://github.com/user-attachments/assets/ea21e509-2aa6-4ca6-b3e5-51248bef8395\" />\n\nGit worktree management for Apache Superset development, made simple. Fully loaded, concurrent dev environments, ready for Claude Code.\n\n<img src=\"https://github.com/user-attachments/assets/eb809525-0783-4fa3-934b-cbbe740dd773\" />\n<img src=\"https://github.com/user-attachments/assets/8367ec7f-791f-49ad-89fd-e0dcd5169fa8\" />\n\n\n[](https://opensource.org/licenses/Apache-2.0)\n\n## Get Started\n\n```bash\n# Install claudette\npip install git+https://github.com/mistercrunch/claudette-cli.git\n\n# Initialize your environment (clones Superset and sets up base config)\nclaudette init\n\n# See available commands\nclaudette --help\n\n# Pro tip: Use 'clo' as a shorter alias for claudette!\nclo --help\n```\n\n## Features\n\n- \ud83c\udf33 **Git Worktree Management** - Isolated branches in separate directories\n- \ud83d\udc0d **Automatic Python Environment** - Each project gets its own venv with dependencies\n- \ud83d\udce6 **Node.js Isolation** - Separate node_modules per project\n- \ud83d\udc33 **Docker Integration** - Run containers on different ports per project\n- \ud83c\udfa8 **Beautiful CLI** - Powered by Typer and Rich for a great experience\n- \ud83d\udd27 **Claude Code Integration** - Automatic environment setup for AI assistance\n- \u26a1 **Fast Setup** - Uses `uv` for blazing fast Python package installation\n- \ud83d\udcdd **PROJECT.md Standard** - Persistent branch docs in `~/.claudette/projects/`, symlinked to worktrees\n- \ud83d\udd17 **Shared CLAUDE.local.md** - Single source of truth for Claude instructions across all projects\n- \ud83c\udfaf **Auto Port Assignment** - Automatically finds available ports when not specified\n- \ud83e\uddca **Freeze/Thaw Projects** - Save ~3GB per project by removing dependencies when not in use\n- \ud83d\udd17 **GitHub PR Integration** - Track and quickly access pull requests associated with projects\n\n## Installation\n\n### From PyPI (coming soon)\n```bash\npip install claudette\n```\n\n### From Source\n```bash\ngit clone https://github.com/yourusername/claudette.git\ncd claudette\npip install -e .\n```\n\n**Note:** Both `claudette` and `clo` commands will be available after installation. Use whichever you prefer!\n\n### Prerequisites\n\n1. **Initialize Claudette**:\n ```bash\n claudette init\n ```\n This will clone the Superset repository and set up your environment.\n\n2. **Required Tools**:\n - Python 3.8+\n - Git with worktree support\n - Docker and docker-compose\n - Node.js and npm\n - `uv` (will be installed automatically)\n\n## Quick Start\n\n```bash\n# Initialize claudette environment\nclaudette init\n\n# Create a new project (port auto-assigned)\nclo add my-feature\n\n# Or specify a port\nclo add my-feature 9007\n\n# Drop into Docker container for development\nclo shell\n\n# Or run a quick command\nclo shell -- python --version\n\n# Access the database directly\nclo psql -- -c \"\\\\dt\"\n\n# Start Docker containers\nclo docker up\n\n# Launch Claude with project context\nclo claude code\n\n# Link a GitHub PR to the project\nclo pr link 12345\n\n# Check project status\nclo status\n\n# List all projects\nclo list\n\n# Freeze inactive project to save space\nclo freeze old-feature\n\n# Thaw when ready to work again\nclo thaw old-feature\n\n# Clean up when done\nclo remove my-feature\n```\n\n## Commands\n\nAll commands below can be run with either `claudette` or its shorter alias `clo`.\n\n### `claudette init`\nInitializes claudette environment:\n- Clones Apache Superset base repository\n- Creates configuration directory\n- Sets up templates for CLAUDE.local.md and .claude_rc\n\n### `claudette add <project> [port]`\nCreates a new worktree project with:\n- Git worktree branch (with conflict resolution)\n- Python virtual environment with all dependencies\n- Frontend node_modules\n- Pre-commit hooks\n- Docker configuration\n- Auto-assigns port if not specified\n\n### `claudette activate <project>` / `claudette shell`\n- `activate`: Starts a new shell with Python venv activated and project environment\n- `shell`: Drop into Docker container or run commands\n - Interactive mode: `clo shell` enters bash shell\n - Command mode: `clo shell -- <command>` runs command and exits\n - Auto-starts containers if not running\n - Examples:\n - `clo shell -- python --version` - Check Python version\n - `clo shell -- superset db upgrade` - Run database migrations\n - `clo shell -- bash -c \"ls -la | head\"` - Complex commands\n\n### `claudette list`\nShows all projects with their ports, Docker status, freeze state, and PRs:\n```\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Project \u2503 Port \u2503 Path \u2503 Status \u2503 State \u2503 PR \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 my-feature \u2502 9007 \u2502 code/superset-worktree/my-... \u2502 \ud83d\udfe2 \u2502 \ud83d\udfe2 \u2502 #123 \u2502\n\u2502 bug-fix \u2502 9008 \u2502 code/superset-worktree/bug... \u2502 \u26ab \u2502 \ud83e\uddca \u2502 ? \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### `claudette status [project]`\nShows detailed project status:\n- Git branch and uncommitted changes\n- Docker container status\n- Python venv status\n- Recent commits\n\n### `claudette docker [args]`\nWrapper for docker-compose that automatically:\n- Sets the correct NODE_PORT\n- Uses the project name for container prefix\n- Passes through all docker-compose commands\n\n### `claudette claude [args]`\nLaunches claude CLI with project context:\n- Sets working directory to project root\n- Requires activated project (via $PROJECT)\n- Passes through all arguments\n\n### `claudette jest [args]` / `claudette pytest [args]`\nRun tests with project context:\n- `jest`: Frontend tests with all arguments passed to npm test\n- `pytest`: Backend tests using Docker with automatic test database setup\n\n### `claudette psql`\nDirect PostgreSQL database access:\n- Interactive mode: `clo psql` enters psql shell\n- Command mode: `clo psql -- -c \"SELECT...\"` runs query and exits\n- Auto-starts containers if not running\n- Examples:\n - `clo psql -- -c \"\\\\dt\"` - List all tables\n - `clo psql -- -c \"SELECT COUNT(*) FROM ab_user;\"` - Run query\n - `clo psql -- -f script.sql` - Execute SQL file\n\n### `claudette nuke-db [project]`\nNukes the PostgreSQL database volume:\n- Stops containers first\n- Removes the Docker volume completely\n- Useful for fresh database state\n\n### `claudette remove <project>`\nCleanly removes a project:\n- Stops Docker containers\n- Removes git worktree\n- Cleans up all project files\n\n### `claudette sync [project]`\nSyncs PROJECT.md content with claudette metadata:\n- Updates project description from PROJECT.md\n- Refreshes what shows in `claudette list`\n- Run after editing PROJECT.md\n\n### `claudette freeze <project>`\nFreezes a project to save disk space (~3GB per project):\n- Removes node_modules directory\n- Removes Python .venv directory\n- Project must be thawed before use\n- Use `--force` to skip confirmation\n\n### `claudette thaw <project>`\nThaws a frozen project to restore dependencies:\n- Reinstalls npm packages with `npm ci`\n- Recreates Python venv and installs packages\n- Automatically triggered by commands that need dependencies\n\n### `claudette pr <action> [pr_number] [project]`\nManage GitHub PR associations:\n- `clo pr link <pr_number>` - Associate a PR with current/specified project\n- `clo pr clear` - Remove PR association from current/specified project\n- `clo pr open` - Open associated PR in browser\n\n### `claudette nuke` (DANGEROUS!)\nCompletely removes claudette and all projects:\n- Stops ALL Docker containers\n- Removes ALL worktrees\n- Deletes entire ~/.claudette directory\n- Requires typing \"NUKE\" to confirm\n\n## Configuration\n\n### Environment Variables\n- `CLAUDETTE_WORKTREE_BASE` - Base directory for worktrees (default: `~/code/superset-worktree`)\n- `CLAUDETTE_PYTHON_VERSION` - Python version to use (default: `python3.11`)\n\n### Files & Directories\n\n#### Project Folder Structure\nEach project gets a dedicated folder in `~/.claudette/projects/{project}/` containing:\n- `.claudette` - Project metadata (port, path, description)\n- `PROJECT.md` - Branch-specific documentation (symlinked to worktree)\n- `.env.local` - Local environment variables (symlinked to worktree, future)\n\n#### File Hierarchy\n- `CLAUDE.md` - Repo-wide Superset development guidelines (in Superset repo)\n- `CLAUDE.local.md` - Shared claudette configuration (symlinked to all worktrees)\n- `PROJECT.md` - Branch-specific docs (lives in project folder, symlinked to worktree)\n- `.claude_rc` - Central configuration referencing the PROJECT.md standard\n\n### PROJECT.md Standard\n\nClaudette uses PROJECT.md for branch-specific documentation:\n- Lives in `~/.claudette/projects/{project}/PROJECT.md`\n- Symlinked into worktree for easy editing\n- Edit in your worktree \u2192 changes persist in project folder\n- Survives worktree removal/recreation\n- Use `--keep-docs` with `claudette remove` to preserve for later\n- Claude loads PROJECT.md when present for branch context\n\n### Extensible Architecture\n\nThe project folder structure is designed to be extensible. Files are managed via constants in the code, making it easy to add more symlinked files in the future (scripts, configs, etc.).\n\n### Automatic Migration\n\nClaudette automatically migrates older installations to the latest structure. A version file (`~/.claudette/.claudette.json`) tracks the schema version and ensures smooth upgrades without user intervention.\n\n## Development Workflow\n\n1. **Initialize claudette** (first time only):\n ```bash\n claudette init\n ```\n\n2. **Create a feature branch**:\n ```bash\n claudette add new-feature # Auto-assigns port\n ```\n\n3. **Activate the project**:\n ```bash\n clo shell # Drop into Docker container (recommended)\n # OR\n clo activate new-feature # Activate Python venv in local shell\n ```\n\n4. **Start services**:\n ```bash\n claudette docker up\n ```\n\n5. **Develop with AI assistance**:\n ```bash\n claudette claude code # Opens Claude Code with project context\n ```\n\n6. **Run tests**:\n ```bash\n clo pytest tests/unit_tests/ # Backend tests via Docker\n clo jest --watch # Frontend tests\n pre-commit run --all-files # Code quality checks\n ```\n\n7. **Check status**:\n ```bash\n claudette status\n ```\n\n8. **Clean up**:\n ```bash\n exit # Leave Docker container (or Ctrl+D)\n clo docker down # Stop containers\n clo remove new-feature # Remove project\n ```\n\n## Why Claudette?\n\nManaging multiple Superset development environments is painful:\n- Switching branches breaks your node_modules\n- Frontend port conflicts when running multiple versions\n- Python dependencies get mixed up\n- Docker containers collide\n\nClaudette solves this by giving each feature branch its own **complete** environment.\n\n## How It Works\n\n1. **Git Worktrees**: Each project is a separate git worktree, allowing multiple branches to be checked out simultaneously\n2. **Isolated Environments**: Each project gets its own:\n - Python virtual environment (`.venv`)\n - Node modules (`node_modules`)\n - Docker containers (prefixed by project name)\n - Frontend port (9000-9999 range)\n3. **Shared Configuration**: Common files like `CLAUDE.local.md` are symlinked to keep consistency\n\n## Troubleshooting\n\n### \"Port already in use\"\n```bash\n# Check what's using the port\nlsof -i :9007\n\n# Or just pick a different port\nclaudette add my-feature 9008\n```\n\n### \"Git worktree already exists\"\nClaudette handles this automatically! When adding a project:\n- Choose to reuse the existing branch\n- Create a new branch with a different name\n- Delete the existing branch and start fresh\n\nOr use flags:\n```bash\nclaudette add my-feature --reuse # Use existing branch\nclaudette add my-feature --force-new # Delete and recreate\nclaudette add my-feature --name alt-name # Use different branch name\n```\n\n### \"Project is frozen\"\nFrozen projects have their dependencies removed to save space. When you try to use a frozen project:\n```bash\n# Either thaw it first\nclaudette thaw my-feature\n\n# Or commands will prompt you to thaw automatically\nclaudette shell my-feature # Will ask to thaw first\n```\n\n### \"Docker containers won't start\"\n```bash\n# Check if containers are already running\ndocker ps\n\n# Force remove old containers\nclaudette docker down\ndocker system prune\n```\n\n## Advanced Usage\n\n### Custom Base Directory\n```bash\nexport CLAUDETTE_WORKTREE_BASE=~/projects/superset\nclaudette add my-feature 9007\n```\n\n### Using with VS Code\n```bash\n# Open project in VS Code with correct Python interpreter\nclaudette shell my-feature\ncode . # VS Code will detect the activated venv\n```\n\n### Running Tests in Isolation\n```bash\n# Backend tests (using Docker with automatic test DB setup)\nclo pytest tests/unit_tests/\nclo pytest -x tests/ # Stop on first failure\nclo pytest -v tests/unit_tests/ # Verbose output\nclo pytest --nuke tests/ # Nuke and recreate test database\nclo pytest -k test_charts # Run tests matching pattern\nclo pytest --maxfail=3 tests/ # Stop after 3 failures\n\n# Frontend tests\nclo jest # Run all tests\nclo jest --watch # Watch mode\nclo jest --coverage # Coverage report\nclo jest src/components/Button # Test specific directory\nclo jest superset-frontend/src/components/Button # Auto-strips prefix\n```\n\n### Refreshing Database\n```bash\n# Completely wipe the PostgreSQL database\nclaudette nuke-db\nclaudette docker up # Starts fresh\n```\n\n### Managing Disk Space\n```bash\n# Freeze inactive projects to save ~3GB each\nclo freeze old-project\nclo freeze another-project --force # Skip confirmation\n\n# List projects to see which are frozen\nclo list # Frozen projects show \ud83e\uddca icon\n\n# Thaw when ready to work\nclo thaw old-project\n```\n\n### Working with GitHub PRs\n```bash\n# Link a PR to your project\nclo pr link 12345\n\n# View PR association\nclo status # Shows PR number\nclo list # Shows PR column\n\n# Open PR in browser\nclo pr open\n\n# Clear PR association\nclo pr clear\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development Setup\n```bash\ngit clone https://github.com/yourusername/claudette.git\ncd claudette\npip install -e \".[dev]\"\n```\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.\n\n## Credits\n\nBuilt with:\n- [Typer](https://typer.tiangolo.com/) - CLI framework\n- [Rich](https://rich.readthedocs.io/) - Terminal formatting\n- [uv](https://github.com/astral-sh/uv) - Fast Python package installer\n\nName inspired by Claude (Anthropic's AI assistant) + \"-ette\" (French diminutive suffix).\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Superset multi-environment workflow manager using git worktrees",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/yourusername/claudette",
"Issues": "https://github.com/yourusername/claudette/issues",
"Repository": "https://github.com/yourusername/claudette"
},
"split_keywords": [
"development",
" git",
" superset",
" workflow",
" worktree"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2baf0bdf44af899d8b77f91bfb55e4febc8657d8c5fc9993cb6da525829fcebb",
"md5": "8b2dfd2d2c3912e55ea0bd560e57cd51",
"sha256": "6ad66ccdf86616569a3ac0e26b53c30c170a3c3860974db6f69086a0af5eea83"
},
"downloads": -1,
"filename": "superset_claudette-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b2dfd2d2c3912e55ea0bd560e57cd51",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 41496,
"upload_time": "2025-09-08T19:52:00",
"upload_time_iso_8601": "2025-09-08T19:52:00.023851Z",
"url": "https://files.pythonhosted.org/packages/2b/af/0bdf44af899d8b77f91bfb55e4febc8657d8c5fc9993cb6da525829fcebb/superset_claudette-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "373770397bbd985a61d2425c74706c13fe17a7352b3e7d6616fbdccefb25cd85",
"md5": "b87ce4021801ba721c375b618bd9d39b",
"sha256": "1e5e09f9a09af240cdf301cadc7bc55e684dfd86f3d0da91ec89e20f087d1fca"
},
"downloads": -1,
"filename": "superset_claudette-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "b87ce4021801ba721c375b618bd9d39b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 40348,
"upload_time": "2025-09-08T19:52:01",
"upload_time_iso_8601": "2025-09-08T19:52:01.344767Z",
"url": "https://files.pythonhosted.org/packages/37/37/70397bbd985a61d2425c74706c13fe17a7352b3e7d6616fbdccefb25cd85/superset_claudette-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 19:52:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "claudette",
"github_not_found": true,
"lcname": "superset-claudette"
}
JSON
