Development

Development Guide

Local Environment

Required Tools

• Node.js 22+ (runtime baseline)
• pnpm (package management)
• Bun (optional, for TypeScript execution)

Port Mappings

Service	Port	URL
Gateway	18789	http://localhost:18789
Control UI	3000	http://localhost:3000

Setup

git clone https://github.com/moshehbenavraham/crocbot.git
cd crocbot

pnpm install
pnpm build

Dev Scripts

Command	Purpose
pnpm dev	Run CLI in dev mode
pnpm crocbot <cmd>	Run CLI commands via tsx
pnpm gateway:watch	Gateway with auto-reload
pnpm gateway:dev	Gateway in dev mode (skip channels)
pnpm build	Production build (tsdown bundler, ~5s)
pnpm check	Type-check + lint + format (no emit)
pnpm lint	Lint with oxlint (134 type-aware rules)
pnpm format	Format check with oxfmt
pnpm test	Run tests with Vitest
pnpm test:coverage	Tests with coverage report
pnpm ui:dev	Control UI dev server
pnpm ui:build	Build Control UI

Development Workflow

1. Pull latest from main
2. Create feature branch: git checkout -b feature/my-feature
3. Make changes with clear commits
4. Run lint/build/test: pnpm lint && pnpm build && pnpm test
5. Open PR with description

Testing

# Run all tests
pnpm test

# Run specific test file
pnpm vitest run src/telegram/network-errors.test.ts

# Run with coverage
pnpm test:coverage

# Run in watch mode
pnpm test:watch

# Live tests (requires real API keys)
CROCBOT_LIVE_TEST=1 pnpm test:live

Test Coverage

Coverage thresholds (enforced via Vitest):

• Lines: 70%
• Branches: 70%
• Functions: 70%
• Statements: 70%

Code Style

• Language: TypeScript (ESM, strict mode)
• Linting: oxlint
• Formatting: oxfmt
• Comments: Add brief comments for tricky logic
• File size: Aim for under 500 LOC

Run before commits:

pnpm check

Pre-commit Hooks

Install pre-commit hooks:

prek install

This runs the same checks as CI before each commit.

Debugging

Gateway Issues

# Check gateway status
crocbot gateway status

# Run with verbose logging
crocbot gateway --verbose

# Check health endpoint
curl http://localhost:18789/health

Telegram Connection Issues

# Check channel status
crocbot channels status --probe

# View gateway logs (systemd)
journalctl --user -u crocbot-gateway --since "1 hour ago"

Test Failures

# Run specific test file in watch mode
pnpm vitest src/path/to/file.test.ts

# Run with more verbose output
pnpm vitest run --reporter=verbose

Project Structure

src/
  agents/           # Pi agent runtime, tools, session repair
  alerting/         # Error reporting and alerting
  auto-reply/       # Message dispatch
  cli/              # CLI commands
  config/           # Configuration
  cron/             # Scheduled jobs
  gateway/          # Gateway server
  hooks/            # Hook system
  infra/            # Infrastructure (exec, net/SSRF, utilities)
  logging/          # Structured logging (tslog)
  media/            # Media processing
  memory/           # Memory management
  metrics/          # Metrics and monitoring
  plugins/          # Plugin runtime
  plugin-sdk/       # Plugin SDK
  providers/        # LLM provider integrations
  telegram/         # Telegram channel (grammY)

docs/               # Documentation (Mintlify)
scripts/            # Build and dev scripts
test/               # Shared and e2e tests
ui/                 # Control UI
dist/               # Built output