Development Setup

June 29, 2026 · View on GitHub

Complete guide to setting up a development environment for Shep AI CLI.

Prerequisites

Required

ToolVersionPurpose
Node.js18+Runtime
pnpm8+Package management
Git2.30+Version control

Install pnpm: npm install -g pnpm

ToolPurpose
VS CodeIDE with TypeScript support
SQLite BrowserDatabase inspection
Playwright VS Code ExtensionE2E test debugging
HTTPie/curlAPI testing

Initial Setup

1. Clone the Repository

git clone https://github.com/shep-ai/shep.git
cd cli

2. Install Dependencies

pnpm install

This installs all dependencies including dev dependencies.

If you previously built or exported Shep through Docker in the same checkout, do not reuse the copied runtime bundle or Linux-built node_modules for local development. Reset the workspace first:

pnpm reset:dev

That removes node_modules, dist, web, and Next.js build output, then reinstalls a clean host-native dependency tree.

3. Verify Setup

# Run type check
pnpm typecheck

# Run tests
pnpm test

# Build
pnpm build

# Start Storybook (design system)
pnpm dev:storybook

Project Structure

cli/
├── packages/core/src/
│   ├── domain/           # Business logic (no deps)
│   │   ├── entities/
│   │   ├── value-objects/
│   │   └── services/
│   ├── application/      # Use cases and ports
│   │   ├── use-cases/
│   │   ├── ports/
│   │   └── services/
│   └── infrastructure/   # External implementations
│       ├── repositories/
│       ├── agents/
│       ├── persistence/
│       └── services/
├── src/
│   └── presentation/     # UI layers
│       ├── cli/          # Commander-based CLI
│       ├── tui/          # @inquirer/prompts interactive wizards
│       └── web/          # Next.js + shadcn/ui
│           ├── app/      # Next.js App Router
│           ├── components/
│           │   ├── ui/   # shadcn/ui components
│           │   └── ...   # Feature components
│           └── stories/  # Storybook stories
├── tests/
│   ├── unit/             # Vitest unit tests
│   ├── integration/      # Vitest integration tests
│   └── e2e/              # Playwright e2e tests
├── docs/                 # Documentation
├── scripts/              # Build/dev scripts
├── .storybook/           # Storybook config
└── dist/                 # Build output

IDE Configuration

VS Code

Recommended extensions:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next"
  ]
}

Settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.preferences.importModuleSpecifier": "relative"
}

Debug configuration (.vscode/launch.json):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug CLI",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/presentation/cli/index.ts",
      "runtimeArgs": ["-r", "ts-node/register"],
      "console": "integratedTerminal"
    },
    {
      "name": "Debug Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/vitest",
      "args": ["run", "--reporter=verbose"],
      "console": "integratedTerminal"
    }
  ]
}

Development Commands

Starting Development

# Run CLI directly (tsx)
pnpm dev:cli

# Start Web UI (same as `pnpm dev`)
pnpm dev:web

# Shortcut for local web development
pnpm dev

# Start Storybook (Design System)
pnpm dev:storybook

Testing Locally

# Link package globally
pnpm link --global

# Now 'shep' command is available
shep --help

# Unlink when done
pnpm unlink --global @shepai/cli

Database Development

Development database location: ~/.shep/repos/...

Database migrations run automatically via the user_version pragma when the CLI bootstraps. To inspect the database manually:

# Using sqlite3 CLI
sqlite3 ~/.shep/repos/<encoded-path>/data

# Common queries
.tables
SELECT * FROM features;

Working with Tests (TDD)

This project uses Test-Driven Development. See tdd-guide.md for the full TDD workflow.

Running Tests

# TDD watch mode (recommended for development)
pnpm test:watch

# All tests
pnpm test

# Unit tests only
pnpm test:unit

# Integration tests only
pnpm test:int

# E2E tests (Playwright)
pnpm test:e2e

# Specific file
pnpm test:single tests/unit/domain/entities/feature.test.ts

Test Database

Tests use in-memory SQLite:

// tests/helpers/db.ts
export function createTestDatabase(): Database {
  return new Database(':memory:');
}

Debugging

Enable Debug Logging

# Via environment variable
DEBUG=shep:* pnpm dev:cli

# Or specific modules
DEBUG=shep:agents:* pnpm dev:cli

# Enable deployment service logging (dev server start/stop, port detection)
DEBUG=1 pnpm dev:cli

For web UI client-side debug logging, add to src/presentation/web/.env.local:

NEXT_PUBLIC_DEBUG=1

Debug Agent Execution

// Add to agent config
{
  "agents": {
    "logging": {
      "level": "debug",
      "includeMessages": true,
      "includePayloads": true
    }
  }
}

Inspect SQLite Database

# Using sqlite3 CLI
sqlite3 ~/.shep/repos/<encoded-path>/data

# Common queries
.tables
SELECT * FROM features;
SELECT * FROM tasks WHERE feature_id = 'xxx';

Common Issues

Node Version Mismatch

# Check version
node --version

# Use nvm to switch
nvm use 20

Build Errors After Pull

# Clean install
rm -rf node_modules
pnpm install

# Rebuild
pnpm build

Tests Failing on CI But Not Locally

Check for:

  • Environment variable differences
  • File system timing issues
  • Hardcoded paths

SQLite Issues

# Rebuild native modules
pnpm rebuild better-sqlite3

Playwright Issues

# Install browsers
pnpm exec playwright install

# Run with debug
pnpm test:e2e --debug

Maintaining This Document

Update when:

  • Prerequisites change
  • Project structure changes
  • New tooling is adopted
  • Common issues are discovered

Related docs: