Skip to main content

Development Setup

Everything you need to build DotAgents from source.

Prerequisites​

RequirementVersionPurpose
Node.js24.x recommended (min: 20.19.4)Runtime
pnpm9.xPackage manager (required)
RustLatest stableNative keyboard/input binary
XcodeLatest (macOS only)Code signing

pnpm is required. Using npm or yarn will cause installation issues.

corepack enable
corepack prepare pnpm@9 --activate

Quick Start​

git clone https://github.com/aj47/dotagents-mono.git
cd dotagents-mono
nvm use
pnpm install
pnpm --filter @dotagents/desktop build-rs    # Build Rust native binary
pnpm dev         # Start development server

Build Commands​

CommandDescription
pnpm devStart development server (desktop)
pnpm dev:mobileStart development server (mobile, Expo)
pnpm buildProduction build for current platform
pnpm --filter @dotagents/desktop build:macmacOS build (Apple Silicon + Intel universal)
pnpm --filter @dotagents/desktop build:winWindows build (x64)
pnpm --filter @dotagents/desktop build:linuxLinux build for host architecture
pnpm --filter @dotagents/desktop build:linux:x64Linux x64 build
pnpm --filter @dotagents/desktop build:linux:arm64Linux ARM64 build
pnpm --filter @dotagents/desktop build-rsBuild Rust native binary
pnpm testRun test suite
pnpm test:runRun tests once (CI mode)
pnpm test:coverageRun tests with coverage
pnpm typecheckTypeScript type checking
pnpm lintESLint across all packages

For signing, release packaging, GitHub Actions artifacts, docs builds, and web deployments, see Build, Release, Deploy.

Debug Mode​

pnpm dev d               # ALL debug logging
pnpm dev debug-llm       # LLM calls and responses
pnpm dev debug-tools     # MCP tool execution
pnpm dev debug-ui        # UI state changes

See Debug Reference for details.

Docker​

Build Linux packages in a consistent environment:

docker compose run --rm build-linux         # Build Linux packages
docker compose run --rm --build build-linux # Rebuild after code changes
docker compose run --rm shell               # Interactive dev shell

Linux Architecture-Specific Builds​

pnpm --filter @dotagents/desktop build:linux:x64
pnpm --filter @dotagents/desktop build:linux:arm64

Override packaging targets:

DOTAGENTS_LINUX_TARGETS=AppImage,deb pnpm --filter @dotagents/desktop build:linux:arm64

Mobile Development​

pnpm --filter @dotagents/mobile start    # Start Metro bundler
pnpm --filter @dotagents/mobile ios      # iOS (requires Xcode)
pnpm --filter @dotagents/mobile android  # Android (requires Android Studio)
pnpm --filter @dotagents/mobile web      # Web

Testing​

pnpm test                    # Watch mode
pnpm test:run                # Single run (CI)
pnpm test:coverage           # With coverage report

Tests use Vitest and are located alongside source files as *.test.ts and *.test.tsx.

Troubleshooting​

"Electron uninstall" error​

rm -rf node_modules && pnpm install

Multiple lock files​

rm -f package-lock.json bun.lock
rm -rf node_modules && pnpm install

Windows: "not a valid Win32 application"​

pnpm install --ignore-scripts
pnpm.cmd -C apps/desktop exec electron-builder install-app-deps

Node version mismatch​

nvm use    # Uses the repository .nvmrc

Next Steps​