SuperCharged-Claude-Code-Upgrade/dexto/DEVELOPMENT.md

Development Guide

This guide covers development workflows for working on the Dexto codebase.

Table of Contents

• Project Structure
• Development Setup
• Development Workflows
• Build Commands
• Testing
• Code Quality
• Publishing

Project Structure

Dexto is a monorepo using pnpm workspaces with the following structure:

dexto/
├── packages/
│   ├── core/          # @dexto/core - Core business logic
│   ├── cli/           # dexto - CLI application
│   └── webui/         # @dexto/webui - Next.js web interface
├── scripts/           # Build and development scripts
├── agents/            # Agent configurations
└── docs/              # Documentation

Package Dependencies

• dexto (CLI) depends on @dexto/core
• @dexto/webui is embedded into CLI at build time
• All packages version together (fixed versioning)

Development Setup

Prerequisites

• Node.js >= 20.0.0
• pnpm (automatically managed via Corepack)

Initial Setup

# Clone the repository
git clone https://github.com/truffle-ai/dexto.git
cd dexto

# Enable Corepack (if not already enabled) - this picks pnpm version
corepack enable

# Install dependencies (Corepack will use the correct pnpm version)
pnpm install

# Build all packages
pnpm run build

Development Workflows

1. Hot Reload Development (Recommended)

Best for frontend development with automatic reload:

pnpm run dev

This command:

• Builds core and CLI packages
• Runs API server on port 3001 (from built dist)
• Runs WebUI dev server on port 3000 (with hot reload)
• Prefixes output with [API] and [UI] for clarity
• Automatically sets DEXTO_DEV_MODE=true to use repository agent configs

Access:

• API: http://localhost:3001
• WebUI: http://localhost:3000

2. Symlink Development

Best for CLI development with instant changes:

# Create global symlink (full build with WebUI)
pnpm run link-cli

# Create global symlink (fast, no WebUI)
pnpm run link-cli-fast

# Remove symlink
pnpm run unlink-cli

Now dexto command uses your local development code directly.

3. Production-like Testing

Test the actual installation experience:

# Install globally from local build (full)
pnpm run install-cli

# Install globally from local build (fast, no WebUI)
pnpm run install-cli-fast

This creates tarballs and installs them globally, simulating npm install -g dexto.

Switching Between Workflows

The link-cli and install-cli commands are mutually exclusive:

• Running link-cli removes any npm installation
• Running install-cli removes any pnpm symlink
• Use unlink-cli to remove everything

Build Commands

Complete Builds

# Full build with cleaning
pnpm run build

# Build all packages without cleaning
pnpm run build:all

# Build with type checking
pnpm run build:check

Package-Specific Builds

# Build individual packages
pnpm run build:core
pnpm run build:cli
pnpm run build:webui

# Build CLI and its dependencies only (no WebUI)
pnpm run build:cli-only

WebUI Embedding

The WebUI is embedded into the CLI's dist folder during build:

# Embed WebUI into CLI dist (run after building WebUI)
pnpm run embed-webui

Testing

Automated Tests

# Run all tests
pnpm test

# Run unit tests only
pnpm run test:unit

# Run integration tests only
pnpm run test:integ

# Run tests with coverage
pnpm run test:ci

Manual testing

1. Common commands

cd ~
dexto --help 
dexto "what is the current time"
dexto "list files in current directory"

# Test other model override in CLI
dexto -m gpt-5-mini "what is the current date"

# Test web mode
dexto

# Test discord bot mode (requires additional setup)
dexto --mode discord

# Test telegram bot mode (requires additional setup)
dexto --mode telegram

2. Execution contexts

Dexto CLI operates differently based on the directory you are running in.

• source context -> when Dexto CLI is run in the source repository
• global context -> when Dexto CLI is run outside the source repository
• project context -> when Dexto CLI is run in a project that consumes @dexto dependencies

Based on execution context, Dexto CLI will use defaults for log path, default agent/agent registry. Run the CLI in different places and see the console logs to understand this.

Test above commands in different execution contexts for manual testing coverage.

Developer Mode Environment Variable:

When running dexto from within this repository, it normally uses your dexto setup preferences and global ~/.dexto directory. To force isolated testing with repository files:

export DEXTO_DEV_MODE=true  # Use repo configs and local .dexto directory

DEXTO_DEV_MODE Behavior:

• Agent Config: Uses agents/coding-agent/coding-agent.yml from repo (instead of ~/.dexto/agents/)
• Logs/Database: Uses repo/.dexto/ (instead of ~/.dexto/)
• Preferences: Skips global setup validation
• Use Case: Isolated testing and development on Dexto itself

Note: pnpm run dev automatically sets DEXTO_DEV_MODE=true, so the development server always uses repository configs and local storage.

Code Quality

Type Checking

# Type check all packages
pnpm run typecheck

# Type check with file watching
pnpm run typecheck:watch

# Type check specific package
pnpm run typecheck:core

Linting

# Run linter
pnpm run lint

# Fix linting issues
pnpm run lint:fix

Pre-commit Checks

Before committing, always run:

pnpm run build:check  # Typecheck + build
pnpm test            # Run tests
pnpm run lint        # Check linting

Publishing

Changeset Workflow

We use Changesets for version management:

1. Create a changeset for your changes:

   pnpm changeset
   

2. Select packages affected by your change

3. Choose version bump (patch/minor/major)

4. Write summary of your changes

Version Strategy

• Fixed versioning: All packages version together
• @dexto/core and dexto always have the same version
• @dexto/webui is private and not published

Publishing Process

Publishing is automated via GitHub Actions:

1. Merge PR with changeset
2. Bot creates "Version Packages" PR
3. Merge version PR to trigger npm publish

Common Tasks

Clean Everything

# Clean all build artifacts and caches
pnpm run clean

# Clean storage only
pnpm run clean:storage

Start Production Server

# Start the CLI (requires build first)
pnpm start

Working with Turbo

Turbo commands run tasks across all packages:

pnpm run repo:build      # Build all packages with Turbo
pnpm run repo:test       # Test all packages with Turbo
pnpm run repo:lint       # Lint all packages with Turbo
pnpm run repo:typecheck  # Typecheck all packages with Turbo

Troubleshooting

Native Dependencies

If you see errors about missing bindings (e.g., better-sqlite3):

# Reinstall dependencies
pnpm install

# If that doesn't work, clean and reinstall
pnpm run clean
pnpm install

Port Conflicts

Default ports:

• API/Server: 3001
• WebUI Dev: 3000

Set environment variables to use different ports:

PORT=4000 API_PORT=4001 pnpm run dev

Global Command Not Found

If dexto command is not found after linking:

# Check global installations
pnpm list -g
npm list -g dexto --depth=0

# Verify PATH includes pnpm/npm global bin
echo $PATH

Questions?

• Check CONTRIBUTING.md for contribution guidelines
• Open an issue for bugs or feature requests
• Join our Discord for development discussions