Your First Feature
This is a step-by-step walkthrough from “I have a git repo” to “I have a merged PR” — Shep handles the branch, commits, PR and CI; your agent does the coding.
Before you start
Make sure your prerequisites are in place. See Getting Started for the list.
You’re ready when these return without errors:
node --version # v22 or higher
git --version
gh auth status # logged in
claude --version # or: kimi, codex, copilot, cursor-agent, gemini, clineUsing OpenRouter, Together AI, Ollama or an LLM proxy instead? You don’t need a CLI — you’ll enter the key or URL during setup. See Agents.
1. Pick a repo
Any git repo works. For your first run, pick a project where you can open a draft PR safely — your own playground repo is ideal.
cd ~/projects/my-app2. Start Shep
shepShep starts in the background and opens localhost:4050 . The first time, the browser walks you through setup:
- Pick your agent — any of the agents on your machine.
- Pick its default model — on a new install this is Claude Opus 5.5 for Claude Code.
- Shep checks the agent is installed and signed in, and shows you the command to fix it if not.
- Add this folder as a project.
Prefer the terminal? shep settings runs the same setup as a wizard, plus your IDE and default workflow.
3. Describe what you want built
Pick something small and concrete for your first run:
"add a /health endpoint that returns uptime and version""add a 'Last updated' timestamp to the user profile page""convert the README quick-start section into a markdown table"
Specific is better. The agent does its best work when the prompt names the file or behavior clearly.
4. Run it
From the terminal:
shep feat new "add a /health endpoint that returns uptime and version" --push --prOr in the browser: click + New on your repository in the Control Center, type the same description, switch on Push and PR under Git, and click Create Feature. You can also just ask for it in Chat.

5. Watch it work
The feature appears on the Control Center canvas and in the session tree. Click it to open the feature drawer:
- Overview — description, branch, pinned agent and model, and an Agent status card that says what the agent is doing and what comes next. Notify me pings you when it needs you.
- Activity — how long each phase took, and its cost.
- Log — the agent’s live output.
- Merge Review — the diff and PR status, once there is something to review.
- Chat — talk to the agent about this feature.
- Checkpoints — a snapshot after each step, which you can diff or restore.
Prefer the terminal? Run shep tui for a live console of every feature, or shep feat logs <id> -f to follow one. See Terminal console.
You can keep coding on main while this happens. The agent works in its own worktree under ~/.shep/repos/.
6. Review the PR
When the agent finishes, Shep pushes the branch, opens a draft PR and watches CI. If a check fails, the agent reads the logs and pushes a fix. The PR link shows in the drawer and in shep feat show <id>.
Open the PR and review it like any other: read the code, check the tests, leave comments.
7. Approve and merge
When the work is ready, the feature stops at the merge gate and shows Needs you.

- Merge it: approve in the Merge Review tab or run
shep feat approve <id>. Shep merges the PR for you. - Ask for changes: reject with feedback —
shep feat reject <id> --reason "also handle the missing VERSION env var"— and the agent goes back to work with your notes. - Answer review comments: after you or a teammate comment on the PR, run
shep feat comments <id>to see them andshep feat address-comments <id>to have the agent fix them, push, and reply on each thread. See PR review comments. - Take over manually: the worktree is a normal git checkout. Open it with
shep ide <id>, make changes, commit and push.
Next time, pass --allow-merge if you want Shep to merge on its own once CI is green.
What you just experienced
From one description you got:
- A feature branch, named for what it does.
- Commits, a push and a draft PR with code and tests.
- CI watched for you, with automatic fixes on failure.
- A checkpoint after every step, and a worktree you can take over at any point.
Now scale it. Try three at once:
shep feat new "add a 404 page" --push --pr
shep feat new "fix the broken footer link" --push --pr
shep feat new "switch the homepage banner to use the brand color" --push --prAll three run in parallel. None of them touches your main checkout.
What’s next
- From zero to a merged PR — the same flow as a tutorial, with a recording and checkpoints.
- Terminal console — approve, reject and follow features from the keyboard.
- Chat — start and steer features in a conversation.
- Web Dashboard — every page and panel explained.
- CI Watch & Auto-Fix — what happens after the PR opens.
- Configuration — set defaults so you stop typing the same flags.