An optional enhancement that provides seamless cd behavior when switching worktrees.
No. Erk works out-of-the-box without shell integration.
When you run worktree-entering commands like erk implement or erk wt checkout, erk spawns a subshell in the target directory. Type exit when you're done to return to your previous directory.
Shell integration changes this behavior: instead of spawning a subshell, erk changes your current shell's directory (like cd). Some users prefer this workflow.
| Behavior | Without Shell Integration | With Shell Integration |
|---|---|---|
| Directory change | Subshell (use exit to return) |
In-place cd |
| Shell history | Separate per subshell | Continuous |
| Environment variables | Fresh in each subshell | Preserved |
You might want shell integration if you:
- Switch between worktrees frequently and dislike typing
exit - Want a single continuous shell history
- Prefer
cdsemantics over subshell semantics
You probably don't need it if you:
- Only occasionally switch worktrees
- Like the isolation of subshells (fresh environment each time)
- Are just getting started with erk
Run erk init --shell to see the setup instructions for your shell:
erk init --shellThis will:
- Detect your current shell (bash, zsh, or fish)
- Show the code to add to your shell configuration file
Add the following to your ~/.zshrc:
# Erk shell integration
eval "$(erk init --shell)"Then reload your shell:
source ~/.zshrcAdd the following to your ~/.bashrc:
# Erk shell integration
eval "$(erk init --shell)"Then reload your shell:
source ~/.bashrcAdd the following to your ~/.config/fish/config.fish:
# Erk shell integration
erk init --shell | sourceThen reload your shell:
source ~/.config/fish/config.fishAfter setting up, verify it's working:
# Should show the shell function, not just the binary path
type erkYou should see something like:
erk is a shell function from /path/to/your/config
If you see only erk is /path/to/erk, shell integration isn't loaded.
These commands change directories when shell integration is enabled:
erk implement/erk impl- Start implementing a planerk wt checkout/erk wt co- Switch to a worktreeerk wt create- Create and enter a new worktreeerk branch checkout/erk br co- Switch to a branch's worktreeerk pr checkout/erk pr co- Check out a PRerk land/erk branch land- Land a PR and navigate to the next worktreeerk up/erk down- Navigate the worktree stack
Without shell integration, these commands spawn subshells instead.
Some prompts cache the current directory. After switching worktrees, try:
cd .Or check if your prompt has a refresh command.
Make sure you sourced your shell config file:
source ~/.zshrc # or ~/.bashrc for bashOr start a new terminal session.
Check that the eval line is in the correct config file for your shell. Interactive shells load:
- Zsh:
~/.zshrc - Bash:
~/.bashrc - Fish:
~/.config/fish/config.fish
You can run the raw command without shell integration by using command:
command erk wt checkout my-featureThis bypasses the shell function and spawns a subshell as usual.
- Shell Integration Troubleshooting - Detailed problem solving
- Installation - Initial erk setup