Guide to using Shep’s browser-based interface.
The web UI provides a visual interface for:
| Component | Technology | Purpose |
|---|---|---|
| Framework | Next.js 16+ | App Router, Server Components, Turbopack |
| React | React 19 | UI framework |
| Styling | Tailwind CSS 4 | Utility-first CSS with design tokens |
| UI Components | shadcn/ui | Radix primitives + Tailwind CSS |
| Design System | Storybook | Component documentation and testing |
| E2E Testing | Playwright | Browser-based automated tests |
The Web UI is built with modern React patterns:
Start the web UI server:
shep ui
Default URL: http://localhost:4050/
To use a custom port:
shep ui --port 8080
┌─────────────────────────────────────────────────────────────────────────┐
│ [Logo] Shep AI [Settings] [?] │
├──────────────────────┬─────────────────────────────────────────────────┤
│ │ │
│ FEATURES │ │
│ ──────────────── │ MAIN CONTENT AREA │
│ □ Feature 1 │ │
│ □ Feature 2 │ │
│ □ Feature 3 │ │
│ │ │
│ [+ New Feature] │ │
│ │ │
├──────────────────────┴─────────────────────────────────────────────────┤
│ Status: Ready | Analysis: Up to date | Server: Running │
└─────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────┐
│ New Feature │
├────────────────────────────────────────────────┤
│ │
│ Based on your codebase, here are some │
│ suggestions: │
│ │
│ ○ Add user authentication │
│ ○ Implement API caching │
│ ○ Add comprehensive testing │
│ ○ Other: [________________] │
│ │
├────────────────────────────────────────────────┤
│ [Cancel] [Continue] │
└────────────────────────────────────────────────┘
The chat interface guides you through requirements:
┌─────────────────────────────────────────────────────────┐
│ Feature: User Authentication | Phase: Requirements │
├─────────────────────────────────────────────────────────┤
│ │
│ Shep: What authentication method would you like? │
│ │
│ Options: │
│ ○ Email/password │
│ ○ OAuth - Google, GitHub │
│ ○ Magic links │
│ ○ Multiple methods │
│ │
│ You: [Type or select...] │
│ │
├─────────────────────────────────────────────────────────┤
│ Requirements gathered: 3 │
│ [Save Draft] [Done] │
└─────────────────────────────────────────────────────────┘
Chat features:
After requirements, view the generated plan:
┌──────────────────────────────────────────────────────────────────┐
│ User Authentication [Requirements] Preview │
├──────────────────────────────────────────────────────────────────┤
│ │
│ EPIC: 5 stories - 25 subtasks │
│ │
│ ┌─ Implement OAuth Authentication ────────────────────────────┐ │
│ │ Introduce OAuth support with Google and GitHub... │ │
│ │ │ │
│ │ ▼ STORY: Setup OAuth Provider Config - 3 tasks │ │
│ │ □ Create provider configuration file │ │
│ │ □ Add environment variable handling │ │
│ │ □ Implement provider factory │ │
│ │ │ │
│ │ ▼ STORY: Implement Callback Handlers - 4 tasks │ │
│ │ □ Create OAuth callback route │ │
│ │ □ Implement token exchange │ │
│ │ □ Handle user creation/linking │ │
│ │ □ Add error handling │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────┤
│ TICKETS 25 | DOCUMENTATION 3 | REQUIREMENTS 8 │
└──────────────────────────────────────────────────────────────────┘
| Tab | Content |
|---|---|
| TICKETS | Tasks and action items |
| DOCUMENTATION | Generated artifacts (PRD, RFC, etc.) |
| REQUIREMENTS | Gathered requirements list |
During implementation, track progress:
┌────────────────────────────────────────────────────────────┐
│ User Authentication │
│ Phase: Implementation | Progress: 40% │
├────────────────────────────────────────────────────────────┤
│ │
│ Progress: [================....................] 10/25 │
│ │
│ Currently Executing: │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ TASK: Implement token exchange │ │
│ │ Creating src/services/oauth.ts │ │
│ │ Adding exchangeToken function... │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ Recent Activity: │
│ ✓ Completed: Created src/routes/auth.ts │
│ ✓ Completed: Added OAuth callback route │
│ ✓ Completed: Configured environment variables │
│ │
├────────────────────────────────────────────────────────────┤
│ [Pause] [View Changes] [Cancel] │
└────────────────────────────────────────────────────────────┘
| Button | Action |
|---|---|
| Pause | Pause execution after current task |
| View Changes | Open diff viewer |
| Cancel | Stop execution (requires confirmation) |
View and edit generated documentation:
┌───────────────────────────────────────────────────────────┐
│ Product Requirements Document │
├───────────────────────────────────────────────────────────┤
│ │
│ # PRD: User Authentication │
│ │
│ Problem Statement │
│ ─────────────────── │
│ Users currently cannot securely access their accounts... │
│ │
│ User Stories │
│ ────────────── │
│ As a user, I want to log in with Google so that... │
│ As a user, I want to link my GitHub account... │
│ │
│ Acceptance Criteria │
│ ────────────────────── │
│ [ ] Users can sign in with Google OAuth │
│ [ ] Users can sign in with GitHub OAuth │
│ [ ] Users can link multiple providers │
│ │
├───────────────────────────────────────────────────────────┤
│ [Edit] [Export] [Regenerate] │
└───────────────────────────────────────────────────────────┘
Features:
Access via gear icon:
┌──────────────────────────────────────────────────┐
│ Settings [x] │
├──────────────────────────────────────────────────┤
│ │
│ Theme │
│ ○ Light ○ Dark ● System │
│ │
│ Implementation │
│ [x] Require approval before each task │
│ [ ] Auto-commit changes │
│ │
│ Server │
│ Port: [4050] │
│ │
│ Advanced │
│ [View Logs] [Clear Cache] [Reset Config] │
│ │
├──────────────────────────────────────────────────┤
│ [Cancel] [Save] │
└──────────────────────────────────────────────────┘
| Shortcut | Action |
|---|---|
Ctrl/Cmd + N |
New feature |
Ctrl/Cmd + S |
Save current |
Ctrl/Cmd + Enter |
Submit in chat |
Escape |
Close modal/cancel |
? |
Show all shortcuts |
The UI adapts to screen size:
# Start the web UI in development mode
pnpm dev:web
# Build for production
pnpm build:web
# Run E2E tests
pnpm test:e2e
View and develop components in isolation:
# Start Storybook dev server
pnpm dev:storybook
# Build Storybook for deployment
pnpm build:storybook
Storybook includes:
Note: Stories are colocated with components (e.g., button.stories.tsx next to button.tsx).
The web UI uses a four-tier component architecture with strict dependency direction.
src/presentation/web/
├── app/ # Next.js App Router
│ ├── layout.tsx # Root layout (uses AppShell)
│ ├── page.tsx # Home page
│ └── version/
│ └── page.tsx # Version info page
├── components/
│ ├── ui/ # Tier 0: shadcn/ui primitives
│ │ ├── button.tsx
│ │ ├── card.tsx
│ │ └── ...
│ ├── common/ # Tier 1: Cross-feature composed components
│ │ ├── theme-toggle/
│ │ ├── page-header/
│ │ ├── empty-state/
│ │ └── loading-skeleton/
│ ├── layouts/ # Tier 2: Page shells, structural wrappers
│ │ ├── sidebar/
│ │ ├── header/
│ │ ├── dashboard-layout/
│ │ └── app-shell/
│ └── features/ # Tier 3: Domain-specific UI bound to routes
│ ├── version/
│ └── settings/
├── docs/ # Design system MDX documentation
├── hooks/ # Custom React hooks
│ └── useTheme.ts
├── lib/ # Utilities
│ └── utils.ts
└── types/ # TypeScript types
└── theme.ts
For detailed architecture documentation, see UI Architecture.
Update when:
Related docs: