Skip to main content

Documentation Index

Fetch the complete documentation index at: https://aiwithapex.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Development Guide

​
Local Environment

​
Required Tools

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

​
Port Mappings

ServicePortURL
Gateway18789http://localhost:18789
Control UI3000http://localhost:3000

​
Setup

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

pnpm install
pnpm build

​
Dev Scripts

CommandPurpose
pnpm devRun CLI in dev mode
pnpm crocbot <cmd>Run CLI commands via tsx
pnpm gateway:watchGateway with auto-reload
pnpm gateway:devGateway in dev mode (skip channels)
pnpm buildProduction build (tsdown bundler, ~5s)
pnpm checkType-check + lint + format (no emit)
pnpm lintLint with oxlint (134 type-aware rules)
pnpm formatFormat check with oxfmt
pnpm testRun tests with Vitest
pnpm test:coverageTests with coverage report
pnpm ui:devControl UI dev server
pnpm ui:buildBuild 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