LEXOIRE DOCS

Developer documentation.

Engineering reference for installing, running, packaging, and extending the voice layer for coding tools, CLI copilots, durable sessions, and provider handoffs.

Start here

Project overview

Lexoire is a voice-driven AI automation system for coordinating GitHub Copilot CLI sessions through a local-first interface. The product brings together voice input, session routing, resumable CLI work, task visibility, and durable state so one user can run multiple streams of AI-assisted work without losing the plot.

What the app exposes

Conversation panels, memory panels, project plans, terminal output, settings, and active session coordination.

What the backend manages

Socket.IO events, Copilot CLI execution, SQLite persistence, session state transitions, and cross-session context.

Good mental model

Treat Lexoire as a control plane for AI work. The frontend captures intent, the backend routes and persists it, and sessions remain durable enough to resume instead of starting over.

Start here

Local setup

The repo is a unified workspace. Install dependencies once, then choose whether you want the browser workflow or the packaged Electron flow.

npm run install:all
Command Use
npm run dev Runs frontend and backend together with hot reload.
npm run dev:frontend Runs only the Vite frontend.
npm run dev:backend Runs only the backend with nodemon + ts-node.
npm run electron:dev Builds then launches the Electron shell.
Start here

Build and run

Use the root scripts for the full workspace. The backend also has its own build and start scripts if you are working in isolation.

npm run build
npm start
  • Frontend build output: frontend/dist/
  • Backend build output: backend/dist/
  • Electron packages: generated from the root packaging scripts and written into dist/

Developer note

The Electron shell starts the backend automatically and uses a fixed environment port, while local backend development can scan ports 5000-5005 when needed.

Architecture

System architecture

The core runtime is easiest to understand as three connected processes plus a persistence layer.

Electron main.js
  └─ spawns backend
     └─ serves frontend and APIs

Frontend (React + Vite)
  └─ Socket.IO client

Backend (Express + Socket.IO)
  └─ Copilot CLI subprocesses
  └─ SQLite persistence

Frontend role

Render the interface, capture input, and display live session, plan, and terminal state.

Backend role

Serve state, execute commands, stream updates, persist records, and coordinate session behavior.

Architecture

Frontend

The primary app entry is frontend/src/AppClean.tsx. It ties together the visible dashboard, silence-based voice sending, socket events, and higher-level orchestration hooks.

Hooks worth knowing first

  • useSocket: manages the Socket.IO connection lifecycle.
  • useVoiceRecognition: handles Web Speech API recognition and silence detection.
  • useSessionRouter: parses voice commands and targets sessions.
  • useVoiceRouting: combines recognition and routing into a higher-level workflow.
  • useSpeechSynthesis: sends responses to browser speech or Electron IPC.

Frontend contribution sweet spot

If you want high-leverage product work, improve session clarity, reduce noisy UI states, and make voice/terminal feedback easier to trust at a glance.

Architecture

Backend

backend/src/server.ts is the runtime entry point. It wires Express routes, Socket.IO events, and the services that manage sessions, persistence, and Copilot CLI execution.

Important backend services

File Responsibility
backend/src/db/database.ts SQLite wrapper and schema creation.
backend/src/services/session-manager.ts Session CRUD, focus, and state transitions.
backend/src/services/session-messaging.ts Inter-session messages and context sharing.
backend/src/services/session-persistence.ts Archiving and history management.
backend/src/copilot/copilot-service.ts Copilot CLI execution and resumable session handling.
Architecture

Electron

Electron turns the project into a packaged desktop app. The shell launches the backend, opens the browser window, and exposes an IPC bridge for speech recognition and text-to-speech.

  • electron/main.js: backend startup and BrowserWindow creation.
  • electron/preload.js: safe IPC surface exposed as window.lexoire.
  • swift/LexoireSpeech: native macOS speech integration used by the desktop app.
npm run electron
npm run electron:build:mac
Architecture

Database

Lexoire uses SQLite for local-first persistence. The schema is created automatically, so there is no separate migration tool.

Table family Purpose
Sessions Track current sessions, archive state, and history.
Conversations + messages Persist chat history and execution context.
Memories Store extracted, searchable context.
Plans + steps Represent ongoing execution pipelines and status.
Runtime flows

Voice routing

Voice routing is what makes the app feel like orchestration instead of dictation. The router parses phrases like “switch to planning”, “tell backend to fix login bug”, or “broadcast to all: run tests” and converts them into concrete routing actions.

Supported command patterns

  • Switch: move active focus to another session.
  • Tell: send a command to a named session.
  • Broadcast: push one command to every active session.
  • Pause / resume: manage execution state by voice.
const { parseCommand, executeRoute, setActiveSession } = useSessionRouter(...)
Runtime flows

Session lifecycle

Lexoire treats sessions as durable workers rather than throwaway chats.

  1. Create a session from the UI or a command.
  2. Store the durable Copilot session identifier locally.
  3. Resume with the stored session id instead of starting over.
  4. Pause or archive when the work stream is complete.

Design goal

A contributor touching session code should preserve resumability and visibility first. If work disappears or active state becomes ambiguous, the product promise weakens quickly.

Runtime flows

Copilot integration

The backend spawns the Copilot CLI and streams output back to the frontend. The system is built around resumable sessions and real-time updates rather than one-shot request/response exchanges. 

const proc = spawn('copilot', ['--resume', SESSION_ID, '--output-format', 'json']);

Contributors working here should focus on reliability, clear surfaced errors, and preserving the link between backend runtime state and UI state.

Open source

Contributing

The repo already has a straightforward contribution flow. Keep changes focused, run the existing build, and make it obvious which surface you improved. 

git clone https://github.com/YOUR_USERNAME/Lexoire.git
cd Lexoire
npm run install:all
npm run dev
  • Create a feature branch for one coherent improvement.
  • Build with npm run build before opening a pull request.
  • Follow the existing TypeScript and project structure patterns.
  • Prefer improvements that increase clarity, reliability, and contributor legibility.
Open source

Publishing docs for free on GitHub Pages

This docs site is intentionally buildless. Everything under website/ is static and deploys through GitHub Actions, which keeps hosting free and easy to maintain. 

.github/workflows/deploy-website.yml
website/
  index.html
  developer-docs.html
  assets/
  • The workflow deploys on pushes to main or master.
  • The Pages artifact is the website/ directory.
  • No separate docs framework is required to publish updates.

What to do after merge

Once this branch is pushed to the default branch, GitHub Actions will publish the site. If Pages is not already configured, set the repository to deploy from GitHub Actions.