Skip to Content
GuidesYour First Feature

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, cline

Using 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-app

2. Start Shep

shep

Shep starts in the background and opens localhost:4050 . The first time, the browser walks you through setup:

  1. Pick your agent — any of the agents on your machine.
  2. Pick its default model — on a new install this is Claude Opus 5.5 for Claude Code.
  3. Shep checks the agent is installed and signed in, and shows you the command to fix it if not.
  4. 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 --pr

Or 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.

The New Feature drawer with a description, the agent and model picker, the reasoning-effort menu, the Fast/Spec switch, and the Approve, Evidence, Skills and Git toggles

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.

The feature drawer's Agent status card reading "Needs you — waiting for your approval", with the next step "Approve or reject in its review tab"

  • 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 and shep 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 --pr

All three run in parallel. None of them touches your main checkout.

What’s next