Skip to content

Your First Plan

This tutorial walks you through erk's complete workflow: creating a plan, saving it to GitHub, implementing it, and landing the PR. You'll build a simple CLI chatbot and add features to it.

Prerequisites: Complete Installation and verify with erk doctor.

Step 1: Clone the Starter Project

Clone the tutorial starter repo using the GitHub CLI. This front-loads authentication—if there are any issues, you'll discover them now:

gh repo create say --template dagster-io/erk-tutorial --public --clone
cd say

If prompted to authenticate, follow the instructions.

The starter is a Python project using modern tools: uv, ruff, ty, pytest, and, of course, erk.

Verify the setup:

uv run say

You should see a > prompt. Type something and press Enter—it echoes back. Press Ctrl+C to exit.

Step 2: Plan Your First Feature

erk is built around a plan → implement cycle. We believe explicit planning is critical for agentic engineering: you get better outcomes, more precise control, and can perform larger units of work more confidently and autonomously.

We'll demonstrate this using Plan Mode in Claude Code to add a simple feature.

Start a new session:

claude

Ask Claude to plan adding a /quit command:

I want to add a /quit command that exits the loop gracefully with a "bye" message. Let's plan this.

Claude enters plan mode. You can also enter plan mode anytime by pressing Shift+Tab to cycle through modes (Auto → Plan → Auto).

You'll see Claude exploring the codebase—reading files, understanding the CLI structure, finding where the input loop lives, and identifying patterns to follow. When it finishes exploring, it presents a plan for your review.

Step 3: Develop the Plan

This is a simple feature, so the plan should be straightforward: modify the input loop to check for /quit, print "bye", and exit. Review what Claude proposes and continue when you're satisfied.

Step 4: Save the Plan to GitHub

When the plan is ready, Claude prompts you for next steps.

erk Extends Plan Mode

Standard Claude Code plan mode shows this menu when you approve:

○ Start implementation
○ Edit the plan

erk extends this with additional options:

○ Save the plan          # Save as GitHub issue, stop here
○ Implement              # Save to GitHub, then implement
○ Incremental            # Implement directly (for quick iterations)
○ View/Edit the plan

Choose Save the plan. Claude runs /erk:plan-save, which:

  1. Creates a GitHub issue with your plan
  2. Adds the erk-plan label
  3. Returns the issue number

You'll see output like:

Plan saved as issue #1

Why Save to GitHub?

When you develop a plan in Claude Code, it normally lives only in the conversation—easy to lose when you close the session. By saving as a GitHub issue:

  • The plan persists beyond your session
  • Anyone can implement it—you, a teammate, or a CI agent
  • Progress is tracked effortlessly through GitHub's issue system

Step 5: Implement the Plan

The standard erk workflow implements each plan in its own worktree.

What's a Worktree?

Git worktrees let you have multiple branches checked out simultaneously in separate directories. Instead of switching branches in your main directory, erk creates a new directory with the feature branch—completely isolated.

Prepare the Worktree

First, exit Claude Code:

/exit

Now prepare a worktree for your plan:

erk prepare 1

This creates a worktree with the plan's content. You'll see output like:

Created branch: P1-quit-command
✓ Assigned P1-quit-command to slot-1
Created .impl/ folder from issue #1

To activate and start implementation:
  source /Users/you/.erk/repos/say/worktrees/slot-1/.erk/bin/activate.sh && erk implement  (copied to clipboard)

Activate and Implement

The activation command is automatically copied to your clipboard. Just paste and run it:

source /path/to/slot-1/.erk/bin/activate.sh && erk implement

This does two things:

  1. Activates the worktree environment (changes directory, sets up venv, loads .env)
  2. Starts Claude Code with the plan loaded

Your plan is now implementing.

Work in Parallel

Open a new terminal and return to your main directory:

cd ~/say

From here, you can monitor progress with the erk dashboard:

erk dash

This launches an interactive TUI showing all your plans and their implementation status.

Step 6: Submit the PR

When the implementation finishes, you're already in the worktree. Submit the PR:

erk pr submit

This creates a pull request linked to the original issue.

Step 7: Land the PR

For this tutorial, merge your own PR:

erk pr land

This:

  1. Merges the PR
  2. Closes the linked issue
  3. Deletes the feature branch
  4. Frees the worktree for reuse

After landing, return to your main repo:

cd ~/say

What You've Learned

You've completed the full erk workflow:

Phase What Happened
Plan Created a detailed implementation plan with Claude
Save Stored the plan as a GitHub issue for tracking
Implement Executed the plan in an isolated worktree
Submit Created a PR linked to the original issue
Land Merged and cleaned up automatically

Quick Reference

Task Command
Start Claude claude
Save plan /erk:plan-save
Exit Claude /exit
Prepare worktree erk prepare <issue>
Activate + implement source .erk/bin/activate.sh && erk implement
Monitor plans erk dash
Submit PR erk pr submit
Land PR erk pr land

Next Steps