Witsy AI Assistant Development

Expert development workflow for Witsy - a cross-platform Electron-based desktop AI assistant that serves as a universal MCP (Model Context Protocol) client. Integrates multiple LLM providers with features including chat completion, image generation, speech processing, document search (RAG), and automation.

Project Architecture

Core Components

Build System (Electron Forge + Vite)

```bash

npm start # Development with hot reload

npm test # Vitest unit tests

npm run test:e2e # E2E tests (Playwright)

make mac-arm64 # Platform-specific builds

make win-x64

```

Configuration: `forge.config.ts` for Electron Forge, Vite configs for bundling.

Development Workflow

Follow this incremental approach for all implementation tasks:

1. **Break down tasks** into small, manageable pieces

2. **Code → Lint → Test** in small increments

3. **Verify tests pass** before moving to next task

4. **Confirm completion** with user before proceeding

5. **Never run** E2E tests, builds, or the full application during development

Linting

```bash

npm run lint # Check code + Vue type errors

npm run lint:css # Validate CSS variable references

```

Linting must produce zero output before running tests. CSS linter validates all `var(--...)` references against definitions in `css/variables.css` and `css/index.css`.

Testing

```bash

npm run test:ai -- <test-name-or-path> # Run specific tests

npm run test:ci # With coverage

```

**Testing Patterns:**

```typescript

import { useWindowMock } from '@tests/mocks/window'

// Use windowMock in beforeAll or beforeEach

```

Coverage Analysis

Identify files needing test coverage:

```bash

node tools/coverage_gaps.js # Top 20 files by uncovered lines

node tools/coverage_gaps.js --limit 10 # Top 10

node tools/coverage_gaps.js --filter src/components # Filter directory

node tools/coverage_gaps.js --show-lines # Show uncovered line ranges

```

Sorted by absolute uncovered lines (not percentage) to prioritize high-impact testing.

Key Patterns & Conventions

State Management

```typescript

import { store } from '@services/store'

```

Store is a Vue 3 reactive object holding application state (preferences, conversations, etc.).

Configuration

```typescript

// Centralized in src/types/config.ts with backwards compatibility

export type Configuration = {

engines: Record<string, EngineConfig>,

plugins: Record<string, PluginConfig>,

// ...

}

```

IPC Communication

```typescript

// Constants in src/ipc_consts.ts

export const CHAT = {

STREAM: 'chat-stream',

CANCEL: 'chat-cancel'

} as const

// Main handlers: src/main/ipc.ts

// Preload exposures: src/preload.ts

```

Event System

**IPC Events (main→renderer):**

```typescript

import useIpcListener from '@composables/ipc_listener'

const { onIpcEvent } = useIpcListener()

onIpcEvent('docrepo-modified', (data) => { /* handle */ })

```

Auto-cleaned on component unmount. Emit from main: `emitIpcEvent`/`emitIpcEventToAll`/`emitIpcEventToFocused`.

**Bus Events (renderer↔renderer):**

```typescript

import useEventBus from '@composables/event_bus'

const { onBusEvent, emitBusEvent } = useEventBus()

onBusEvent('fullscreen', (data) => { /* handle */ })

emitBusEvent('new-chat', payload)

```

Prefer Vue emit/provide-inject for parent-child communication.

Window API Types

If encountering `window.api.*` lint errors, add method signature to `declare global { interface Window {` in `src/types/index.ts`.

CSS Styling

Use **globally available CSS classes** only:

**Always use CSS variables** (`var(--variable-name)`) defined in `css/variables.css` and `css/index.css`. Do not create custom styles or hardcoded values.

Localization

```typescript

import { t } from '@services/i18n'

```

Translations in `./locales/*.json`. Only add English translations when creating features. To add other languages, run `./tools/i18n_check.ts --fix` (only when explicitly requested).

Guidelines

1. **Incremental development**: Small changes, continuous testing

2. **Test-first mindset**: Keep tests passing throughout

3. **Use established patterns**: Follow existing conventions for state, IPC, events

4. **Leverage global styles**: Use predefined CSS variables and classes

5. **Test like a user**: Trigger UI events, check observable state changes

6. **No premature execution**: Don't run builds, E2E tests, or full app during development