shep-ai/cli

Summary

Shep AI is a CLI tool that orchestrates AI coding agents (Claude Code, Cursor CLI, Gemini CLI) through a full software development lifecycle — from plain-English feature descriptions through PRD, research, planning, implementation, and PR creation. It runs a local daemon serving a Next.js web UI on port 4050, uses SQLite for persistence, and manages parallel feature work via git worktrees. Think of it as a conductor that wraps existing AI coding agents rather than being one itself.

Great for

people interested in building orchestration layers around AI coding agents — specifically the workflow management, approval gates, and multi-session coordination problems that arise when AI agents run long autonomous development tasks

Easy wins

• +The 34 open issues with only 'bug' and 'enhancement' labels — none are tagged 'good first issue' or 'help wanted', but the bug issues likely have scoped reproduction cases worth investigating
• +Adding Storybook stories for existing web components that are missing them (CLAUDE.md says commits are rejected without stories, implying some components may still lack them)
• +The competitors/ docs directory contains analysis of 12+ competing tools — contributing a missing competitor analysis (e.g. Amp, Devin 2.0) is low-risk documentation work that's explicitly part of the project's research culture
• +The POC JavaScript files in docs/poc/js/ (app.js, renderer.js) are vanilla JS with inline HTML strings — these are prototype artifacts that could be documented or formally deprecated to reduce confusion for new contributors

Red flags

• !docs/poc/js/app.js and renderer.js use direct innerHTML assignment with unsanitized interpolated values (e.g. `${actionDetails.question}`, `${decision.rationale}`) — these are prototype files but they're sitting in the repo with no clear deprecation notice, which could confuse contributors about acceptable patterns
• !commit_count: 1 and contributor_count: 1 in the metadata despite the README listing 4 contributors and 1127 npm versions — this suggests the repo was recently created or force-pushed, making it impossible to evaluate actual development velocity from git history
• !The CLAUDE.md rule 'You are the ONLY developer. Every test failure... is YOUR responsibility' is written for Claude Code as the primary contributor, not human collaborators — the contributing workflow is clearly designed around AI-assisted development, which may mean human contributor onboarding is an afterthought
• !No 'good first issue' or 'help wanted' labels on any of the 34 open issues, making it actively harder for new contributors to find entry points despite the 'PRs Welcome' badge

Code quality

The test sample (pr-sync-watcher.service.test.ts) is genuinely well-written — comprehensive mock factories, edge case coverage including the duplicate Maintain transition bug (#354), fake timers used correctly, and descriptive test names. The settings-page-client.tsx is dense but follows consistent patterns with good component decomposition (SettingsRow, SwitchRow, SettingsSection). The main concern is the docs/poc/js/ directory which contains thousands of lines of vanilla JS with string-interpolated HTML (classic XSS surface — `${actionDetails.question}` injected directly into innerHTML), but this appears to be a throwaway prototype, not production code. The clean architecture layering is consistently enforced based on the tsconfig path aliases.

What makes it unique

Most AI coding tools are either IDEs (Cursor, Windsurf), chat interfaces (Claude.ai), or single-shot code generators. Shep's differentiator is the multi-session orchestration layer — running 10 features in parallel each in their own git worktree, with configurable human approval gates at PRD/Plan/Merge phases. This is genuinely distinct from OpenHands or aider in that it's a coordinator of other agents rather than an agent itself. The competitors/ directory in the repo confirms the team has done serious competitive analysis. The risk is that this positioning depends entirely on Claude Code/Cursor CLI/Gemini CLI remaining CLI-invokable, making it somewhat fragile.