CodeXomics Developer Guide¶

This guide summarizes the current CodeXomics development workflow and architecture. For agent-specific rules, read AI Assistant Guidelines and the canonical root Agents.md.

Prerequisites¶

• Node.js 20 or 22.
• npm 10 or newer.
• Git.
• Platform build tools required by Electron Builder for your operating system.

CodeXomics 0.722.0 uses Electron 41.7.1 for compatibility with the supported Node.js CI matrix.

Setup¶

git clone https://github.com/Scilence2022/CodeXomics.git
cd CodeXomics
npm install
npm start

Development mode:

npm run dev

Commands¶

Source Tree¶

CodeXomics/
├── src/
│   ├── main.js
│   ├── main/
│   ├── preload.js
│   ├── version.js
│   ├── mcp-server.js
│   ├── mcp-tools/
│   ├── bioinformatics-tools/
│   └── renderer/
│       ├── index.html
│       ├── renderer-modular.js
│       ├── css/
│       └── modules/
├── tools_registry/
├── packages/marketplace-server/
├── docs/
├── test/
├── scripts/
├── Agents.md
├── Memory.md
└── mkdocs.yml

Architecture¶

Electron Boundary¶

• src/main.js owns app lifecycle and BrowserWindow creation.
• src/main/ contains extracted main-process modules for windows, menus, MCP lifecycle, IPC, and project IPC.
• src/preload.js exposes safe APIs across the context bridge.
• Renderer code should not reach directly into Node APIs when a preload or IPC path exists.

Renderer Modules¶

Most app behavior lives in src/renderer/modules/.

High-impact modules:

• ChatManager.js - LLM orchestration and dynamic tool prompt assembly.
• MultiAgentSystem.js - agent scoring and routing.
• FileManager.js, MultiFileManager.js, ProjectManager.js - file and project workflows.
• TrackRenderer.js plus Canvas renderers - genome visualization.
• PluginManagerV2.js, PluginMarketplace.js, PluginFunctionCallsIntegrator.js - plugin lifecycle and AI-callable plugins.
• LLMConfigManager.js, MultiAgentSettingsManager.js - provider and agent settings.
• BenchmarkManager.js, BenchmarkUI.js, benchmark-suites/ - benchmark execution and reporting.

Chat Services¶

Tool execution is split into focused services under src/renderer/modules/chat/services/:

• ToolExecutionService.js
• LLMContextService.js
• IntentParserService.js
• TaskService.js
• FileOperationService.js
• AnnotationService.js
• ProteinService.js
• BlastService.js
• GenomeAnalysisService.js
• PrimerService.js
• RestrictionDigestService.js
• GelElectrophoresisService.js
• UIService.js

Use existing services before adding new ChatManager logic.

Dynamic Tool Registry¶

The registry is rooted at tools_registry/.

Important files:

• registry_manager.js loads and scores YAML tools.
• system_integration.js merges built-in, registry, MCP, and plugin tools.
• builtin_tools_integration.js maps local built-ins to ChatManager/service methods.
• tool_categories.yaml describes categories.

Current registry snapshot:

• 179 YAML tool schemas.
• 18 active YAML categories.
• 143 built-in ChatBox tools.
• 96 MCP tools in tools mode.

MCP Server¶

Entry point: src/mcp-server.js.

Tool modules live under src/mcp-tools/:

• navigation
• sequence
• protein
• database
• data
• pathway
• action
• utility
• file
• track
• primer
• annotation

Tools mode exposes the full MCP list. Agent mode exposes only codexomics_chat, list_genome_windows, and switch_active_window.

Plugin System¶

The plugin architecture is centered on:

• src/renderer/modules/core/ExtensionService.js
• src/renderer/modules/core/ExtensionHost.js
• src/renderer/modules/core/ContributionRegistry.js
• src/renderer/modules/core/CommandRegistry.js
• src/renderer/modules/PluginManagerV2.js
• src/renderer/modules/PluginSecurityValidator.js
• packages/marketplace-server/

Plugin API version is 2.0.0.

Adding A Tool¶

Use the complete checklist in root Agents.md. The short version:

1. Add a YAML schema in tools_registry/<category>/.
2. Add the built-in mapping if the app can execute it locally.
3. Add keyword relevance and intent matching.
4. Wire execution through an existing service or ChatManager fallback.
5. Add ToolNames.js constants.
6. Add FunctionCallsOrganizer categorization.
7. Add MCP parity if external clients need it.
8. Add an explicit policy in LLMContextService.shouldAllowToolExecution().
9. Add focused tests for registry, routing, and execution behavior.

Styling¶

CodeXomics uses vanilla CSS.

• Shared CSS lives in src/renderer/css/.
• Theme preset overrides live in src/renderer/css/themes/.
• Current preset CSS files: professional.css, minimal.css, pastel.css, elegant.css, midnight.css.
• Do not add TailwindCSS, Bootstrap, or atomic CSS frameworks unless explicitly requested.

Testing¶

Vitest is configured by vitest.config.mjs.

Test folders:

• test/unit/
• test/integration/
• test/mocks/

Common focused checks:

npm test
npm run lint
npm run version-validate

Documentation¶

MkDocs source lives in docs/ and is configured by mkdocs.yml.

Do:

• Update docs/index.md for public landing-page changes.
• Add user content under docs/user-guides/.
• Add implementation content under docs/developer-guides/.
• Add deep architecture content under docs/architecture/.
• Keep root README.md, Agents.md, and Memory.md accurate.
• Keep semantic version, compact display version, and MkDocs release label distinct and synchronized.

Do not:

• Edit generated site/ output directly.
• Point MkDocs nav at root-level files outside docs/.
• Hand-edit generated content on the gh-pages branch.

Run this before committing documentation or release metadata changes:

npm run docs:validate

Contribution Notes¶

• Keep changes scoped.
• Preserve user changes in the working tree.
• Use conventional commit messages.
• For docs-only changes, use docs(scope): summary.
• Run the most relevant checks before committing.