aider-desk: Instructions file for Codex

AGENTS.md

This file provides guidance to AiderDesk when working with code in this repository.

Common Commands

Development

• npm install - Install dependencies
• npm run dev - Run in development mode with hot reload
• npm run dev:no-hmr - Run in development mode without hot module replacement

Type Checking

• npm run typecheck - Run all TypeScript type checks
• npm run typecheck:node - Type check main process files (tsconfig.node.json)
• npm run typecheck:web - Type check renderer process files (tsconfig.web.json)

Linting and Formatting

• eslint --fix - Run ESLint with auto-fix and auto-format on specified file(s)

Testing

• npm run test - Run all tests (main + renderer)
• npm run test:node - Run main, preload, and common process tests
• npm run test:web - Run renderer process tests (React components)
• npm run test:watch - Run tests in watch mode for development
• npm run test:coverage - Generate coverage reports
• npm run test:ui - Open interactive test UI

Note for Agents: When running 'npm run test' script via power---bash, always append -- --no-color to the command (e.g., npm run test:node -- --no-color) to ensure clean, parseable output without ANSI escape codes. Other scripts can be run without this.

Building

• npm run build - Full build (includes type checking)
• npm run build:win - Build Windows executable
• npm run build:mac - Build macOS executable
• npm run build:linux - Build Linux executable
• npm run build:unpack - Build without packaging

Manual Type Checking (for verification)

• tsc --noEmit -p tsconfig.node.json - Check main process files
• tsc --noEmit -p tsconfig.web.json - Check renderer process files

Dependency Management

• All dependency versions in root package.json, packages/app/package.json, and packages/extensions/package.json are pinned to exact versions (no ^/~ ranges). npm strips package-lock.json from published tarballs, so any range would float at install time for consumers.
• packages/app/scripts/generate-package.mjs copies versions verbatim from root package.json into the published @aiderdesk/aiderdesk package — pinning root propagates to the published package on the next build.
• To bump a version, change the exact pin (or use the update-ai-sdk-dependencies.yml workflow, which writes exact pins) and run npm install to sync the lockfile. Never reintroduce ^/~ ranges.
• Exception: the ranged entries under overrides (@tootallnate/once, jsondiffpatch) are intentional — neither package exists in the lockfile, so there is no resolved version to pin.
• packages/extensions/package.json (also published, @aiderdesk/extensions) is pinned the same way, except its peerDependencies (zod) which stays a range — peers declare consumer compatibility and install nothing. Its resolved versions live in the root lockfile: prefer the nested packages/extensions/node_modules/<name> resolution when it differs from the hoisted one (e.g. chalk, commander, execa, ora have different hoisted majors at root).
• Remaining workspace packages (packages/common, packages/mcp-server, packages/tree-sitter-utils) are also published and still use ranges; they are not covered by this policy yet.