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.

Features

✨ 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

Requirements

- Node.js >= 20

Installation

$3

``bash

`Install globally`


npm install -g workon
Set up shell integration (one time setup)

echo 'eval "$(workon --init)"' >> ~/.zshrc    # for zsh
echo 'eval "$(workon --init)"' >> ~/.bashrc   # for bash
Reload your shell

source ~/.zshrc  # or ~/.bashrc

$3

`bash

`Set up shell integration`


echo 'eval "$(npx workon --init)"' >> ~/.zshrc    # for zsh
echo 'eval "$(npx workon --init)"' >> ~/.bashrc   # for bash
Reload 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 YPY8P' 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 ~/code
Add 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-project
Add with specific IDE

workon add . --ide idea
Add a project from any path

workon add ~/code/another-project

$3

bash
Switch to project (changes directory + opens IDE)

workon myproject
Shell 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:cwd
Run multiple specific events

workon myproject:cwd,ide
Show 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/myproject

`Show interactive worktree menu`


workon worktrees
List worktrees

workon worktrees list
Create a new worktree

workon worktrees add feature-branch
Open workon session in a worktree (creates tmux session)

workon worktrees open feature-branch
Remove a worktree

workon worktrees remove feature-branch
Merge worktree branch and remove

workon worktrees merge feature-branch
Create 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-branch

`Show status of current worktree`


workon worktree
workon worktree status
Merge this worktree's branch into main/master

workon worktree merge
Remove 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 install
Copy 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 list
Set a value

workon config set key value
Remove a value  

workon config unset key


Shell Integration Details
The modern shell integration works by:

1. Setup: workon --initoutputs a shell function 2. Usage: When you runworkon myproject, the function: - Callsworkon myproject --shellto get commands - Usesevalto 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`

Configuration is stored using the 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 install
Development

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.

License

MIT © Israel Roldan

workon

> Work on something great! 🚀

Features

Requirements

- Node.js >= 20

Installation

$3

``bash

`Install globally`


npm install -g workon
Set up shell integration (one time setup)

echo 'eval "$(workon --init)"' >> ~/.zshrc    # for zsh
echo 'eval "$(workon --init)"' >> ~/.bashrc   # for bash
Reload your shell

source ~/.zshrc  # or ~/.bashrc

$3

`bash

`Set up shell integration`


echo 'eval "$(npx workon --init)"' >> ~/.zshrc    # for zsh
echo 'eval "$(npx workon --init)"' >> ~/.bashrc   # for bash
Reload 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:

`$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 YPY8P' 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 ~/code
Add 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-project
Add with specific IDE

workon add . --ide idea
Add a project from any path

workon add ~/code/another-project

$3

bash
Switch to project (changes directory + opens IDE)

workon myproject
Shell 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:cwd
Run multiple specific events

workon myproject:cwd,ide
Show 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/myproject

`Show interactive worktree menu`


workon worktrees
List worktrees

workon worktrees list
Create a new worktree

workon worktrees add feature-branch
Open workon session in a worktree (creates tmux session)

workon worktrees open feature-branch
Remove a worktree

workon worktrees remove feature-branch
Merge worktree branch and remove

workon worktrees merge feature-branch
Create 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-branch

`Show status of current worktree`


workon worktree
workon worktree status
Merge this worktree's branch into main/master

workon worktree merge
Remove 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

#### 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 install
Copy 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 list
Set a value

workon config set key value
Remove a value  

workon config unset key


Shell Integration Details
The modern shell integration works by:

`$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`

Configuration is stored using the 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 install
Development

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.