Local Development Setup
Guide for setting up a local development environment.
Prerequisites
- pnpm - Package manager (required for workspaces)
- Bun - Backend runtime
- OpenCode TUI -
npm install -g @opencode/tui
Installation
# Clone the repository
git clone https://github.com/chriswritescode-dev/opencode-manager.git
cd opencode-manager
# Install dependencies
pnpm install
The pnpm dev command automatically runs scripts/setup-dev.sh first, which:
- Checks prerequisites (pnpm, bun, git, OpenCode TUI)
- Creates required workspace directories
- Copies .env.example to .env if missing
Then start development servers:
This starts:
- Backend on http://localhost:5003
- Frontend on http://localhost:5173 (with HMR)
Project Structure
opencode-manager/
├── backend/ # Bun + Hono API server
│ ├── src/
│ │ ├── routes/ # API route handlers
│ │ ├── services/ # Business logic
│ │ ├── db/ # Database migrations and queries
│ │ │ └── migrations/ # Numbered migration files
│ │ ├── types/ # TypeScript types
│ │ ├── utils/ # Utility functions
│ │ └── index.ts # Entry point
│ └── test/ # Backend tests
├── frontend/ # React + Vite SPA
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── pages/ # Page components
│ │ ├── hooks/ # Custom React hooks
│ │ ├── api/ # API client
│ │ ├── lib/ # Utilities
│ │ ├── stores/ # Zustand stores
│ │ └── contexts/ # React contexts
│ └── public/ # Static assets
├── shared/ # @opencode-manager/shared types and utilities
├── packages/memory/ # Memory plugin package
├── workspace/ # Runtime workspace for OpenCode
├── docs/ # Documentation
├── scripts/ # Build and utility scripts
├── Dockerfile # Docker image definition
└── docker-compose.yml # Docker Compose configuration
Available Scripts
Root Level
pnpm dev # Start both backend and frontend (runs setup-dev.sh first)
pnpm dev:backend # Start backend only
pnpm dev:frontend # Start frontend only
pnpm build # Build both packages
pnpm lint # Lint both packages
pnpm test # Run all tests
Backend
cd backend
bun --watch src/index.ts # Start with hot reload
pnpm test # Run tests (uses Vitest)
vitest <file> # Run single test file
vitest --ui # Test UI
vitest --coverage # Coverage report
eslint . --ext .ts # Lint
tsc --noEmit # TypeScript check
Frontend
cd frontend
pnpm dev # Start Vite dev server
pnpm build # Production build
pnpm lint # ESLint
pnpm typecheck # TypeScript check
Database
Using Bun's built-in SQLite (bun:sqlite) with numbered migrations.
Location
- Development:
./data/opencode.db - Docker:
/app/data/opencode.db
Schema Changes
- Add new migration file in
backend/src/db/migrations/(e.g.,007-new-feature.ts) - Export the migration in
backend/src/db/migrations/index.ts - Migrations run automatically on startup
Inspection
sqlite3 ./data/opencode.db
# Useful commands
.tables # List tables
.schema user # Show table schema
SELECT * FROM user; # View data
Testing
Running Tests
# All tests
cd backend && pnpm test
# Single file
cd backend && pnpm test src/services/repo.test.ts
# With UI
cd backend && pnpm test:ui
# With coverage
cd backend && pnpm test -- --coverage
Writing Tests
import { describe, it, expect } from 'vitest'
import { repoService } from '../src/services/repo'
describe('repoService', () => {
it('listAll returns repositories', async () => {
const repos = await repoService.listAll()
expect(Array.isArray(repos)).toBe(true)
})
})
Coverage Requirements
Minimum 80% coverage is enforced.
Debugging
Backend
Logs output to terminal when running pnpm dev. For verbose debug logging:
Frontend
- Open browser DevTools (F12)
- Check Console for errors
- Check Network tab for API calls
- Use React DevTools extension