Work on something great!
npm install workon> Work on something great! š
A productivity CLI tool that helps developers quickly switch between projects with automatic environment setup. No more manually navigating to project directories, opening IDEs, or remembering project-specific commands.
⨠Smart Project Switching - Switch between projects in your current shell (no nested processes!)
š§ IDE Integration - Automatically open projects in VS Code, IntelliJ IDEA, or Atom
š Web Integration - Launch project websites and documentation
š³ Git Branch Support - Different configurations for different branches
š² Git Worktrees - Create, open, and manage git worktrees with tmux integration
š Auto Directory Change - Seamlessly cd into project directories
ā” Interactive Setup - Guided project configuration
š Backward Compatible - Legacy nested shell mode still available
- Node.js >= 20
``bashInstall globally
npm install -g workon
$3
`bash
Set up shell integration
echo 'eval "$(npx workon --init)"' >> ~/.zshrc # for zsh
echo 'eval "$(npx workon --init)"' >> ~/.bashrc # for bashReload your shell
source ~/.zshrc # or ~/.bashrc
`$3
`bash
workon --help
`Quick Start
1. Add your first project:
`bash
cd ~/code/myproject
workon add . # Register current directory as a project
`2. Or use interactive mode:
`bash
workon # Start interactive setup wizard
`3. Switch to a project:
`bash
workon myproject # Automatically cd + open IDE
`4. List available projects:
`bash
workon config list
`Project Configuration
Projects are configured with:
- Path: Where your project lives
- IDE: Which editor to open (
code, idea, atom)
- Events: What happens when switching to the project
- cwd: Change directory to project path
- ide: Open project in configured IDE
- web: Open project homepage/docs
- claude: Launch Claude Code (with optional tmux split)
- npm: Run npm scripts (with optional tmux pane)
- docker: Start Docker containers$3
Run
workon to start the interactive setup wizard:`bash
$ workon
8 v1.0.0-alpha.1
Yb db dP .d8b. 8d8b 8.dP .d8b. 8d8b.
YbdPYbdP 8' .8 8P 88b 8' .8 8P Y8
YP YP Y8P' 8 8 Yb Y8P' 8 8? What do you want to do?
⯠Start a new project
Open an existing project
Manage projects
Exit
`$3
`bash
Set base directory for all projects
workon config set project_defaults.base ~/codeAdd a project
workon config set projects.myapp.path myapp
workon config set projects.myapp.ide code
workon config set projects.myapp.events.cwd true
workon config set projects.myapp.events.ide true
`Usage Examples
$3
`bash
Add current directory as a project
cd ~/code/myproject
workon add .Add with a custom name
workon add . --name my-awesome-projectAdd with specific IDE
workon add . --ide ideaAdd a project from any path
workon add ~/code/another-project
`$3
`bash
Switch to project (changes directory + opens IDE)
workon myprojectShell mode - outputs commands instead of executing
workon myproject --shell
Output: cd "/path/to/myproject"
code "/path/to/myproject" &
`$3
Use the colon syntax to run only specific events for a project:
`bash
Run only the cwd event (just change directory)
workon myproject:cwdRun multiple specific events
workon myproject:cwd,ideShow available events for a project
workon myproject:help
`$3
`bash
Configure different settings for a git branch
workon myproject#feature-branch
`$3
Manage git worktrees with full tmux integration. There are two commands:
-
workon worktrees - Manage worktrees (run from the main repository)
- workon worktree - Operate on the current worktree you're inside#### Managing Worktrees (from main repo)
`bash
cd ~/code/myprojectShow interactive worktree menu
workon worktreesList worktrees
workon worktrees listCreate a new worktree
workon worktrees add feature-branchOpen workon session in a worktree (creates tmux session)
workon worktrees open feature-branchRemove a worktree
workon worktrees remove feature-branchMerge worktree branch and remove
workon worktrees merge feature-branchCreate branch from detached HEAD (for PR workflow)
workon worktrees branch my-worktree new-branch-name --push
`#### Operating on Current Worktree (from inside a worktree)
When you're inside a worktree, use
workon worktree (singular):`bash
cd ~/code/myproject/.worktrees/feature-branchShow status of current worktree
workon worktree
workon worktree statusMerge this worktree's branch into main/master
workon worktree mergeRemove this worktree (shows instructions to exit first)
workon worktree remove
`If you run
workon worktrees from inside a worktree, you'll get a helpful error directing you to use workon worktree instead.#### Notes
- If you run worktree commands from an unregistered git repository, workon will prompt you to register it first
- Worktrees created by workon are stored in
.worktrees/ inside the project
- External worktrees (created elsewhere) show as "(external)" in the list#### Post-Setup Hook
Create
.workon/worktree-setup.sh in your project to run commands after creating a worktree:`bash
#!/bin/bash
Install dependencies
[ -f "package.json" ] && npm installCopy environment file
[ -f "$PROJECT_PATH/.env" ] && cp "$PROJECT_PATH/.env" .env
`Environment variables available:
-
WORKTREE_PATH - Absolute path to the new worktree
- PROJECT_PATH - Absolute path to the main project$3
`bash
Use the old behavior if needed (spawns new shell)
workon myproject --no-shell # (this is the default)
`$3
`bash
List all configuration
workon config listSet a value
workon config set key valueRemove a value
workon config unset key
`Shell Integration Details
The modern shell integration works by:
1. Setup:
workon --init outputs a shell function
2. Usage: When you run workon myproject, the function:
- Calls workon myproject --shell to get commands
- Uses eval to execute them in your current shell
3. Result: No nested shells, seamless directory changes$3
If you prefer not to modify your shell config:
`bash
Get commands and execute manually
eval "$(workon myproject --shell)"Or see what commands would run
workon myproject --shell
`Advanced Usage
$3
workon automatically detects when you're in a configured project directory and shows relevant options.$3
Set up tab completion:
`bash
workon --completion
`$3
Troubleshoot with debug output:
`bash
workon myproject --debug
`Configuration Storage
conf package in your system's config directory:- macOS:
~/Library/Preferences/workon/
- Linux: ~/.config/workon/
- Windows: %APPDATA%/workon/Migration from Legacy Mode
If you've been using the nested shell mode, the new shell integration provides the same functionality without the shell nesting issues. Both modes continue to work:
- Legacy:
workon myproject (spawns new shell)
- Modern: workon myproject (with shell integration setup)Contributing
`bash
Install dependencies
pnpm installDevelopment
pnpm run dev # Run with tsx
pnpm run build # Build with tsup
pnpm run lint # Lint
pnpm run type-check # Type check
pnpm run test # Run tests
``Releases are automated via release-please.
MIT Ā© Israel Roldan