CodeXomics User Guide¶

Table of Contents¶

1. Introduction
2. Installation
3. Getting Started
4. Core Features
5. AI Assistant
6. External Tools
7. Benchmark Testing
8. Advanced Features
9. Troubleshooting
10. FAQ

Introduction¶

CodeXomics is an AI-native genome browser that combines traditional genomic analysis tools with a multi-agent AI assistant you can talk to — one that drives the browser and runs analyses for you. This guide will help you get the most out of CodeXomics.

What Can CodeXomics Do?¶

• 🧬 Genome Visualization - Interactive visualization of genomes, genes, and annotations
• 🤖 AI-Powered Analysis - Natural language queries powered by multiple AI agents
• 🔬 Protein Analysis - Structure prediction, network analysis, and pathway visualization
• 📊 Data Management - Project-based organization with support for multiple file formats
• 🔌 Extensible Platform - Plugin system and external tool integration
• 📈 Benchmark Testing - Comprehensive AI performance evaluation

Installation¶

Pre-built Binaries¶

Download the latest available build from the GitHub Releases page.

macOS¶

1. Download the Intel or Apple Silicon DMG for the latest release
2. Open the DMG file
3. Drag CodeXomics to your Applications folder
4. Right-click and select "Open" the first time (macOS security)

Windows¶

1. Download the Windows installer or portable executable
2. Run the installer and follow the prompts
3. Launch from Start Menu or Desktop shortcut

Linux¶

1. Download the AppImage, Debian package, or Snap package
2. For AppImage: chmod +x CodeXomics-*.AppImage && ./CodeXomics-*.AppImage
3. For Debian: sudo dpkg -i codexomics_*_amd64.deb

Building from Source¶

Use Node.js 22.12 or newer in the 22.x line and npm 10 or newer. See Build Instructions.

# Clone the repository
git clone https://github.com/Scilence2022/CodeXomics.git
cd CodeXomics

# Install dependencies
npm install

# Launch the app
npm start

# Build for your platform
npm run build:mac     # macOS
npm run build:win     # Windows
npm run build:linux   # Linux

Getting Started¶

First Launch¶

When you first launch CodeXomics, you'll see the main interface with:

• Header Bar - File operations, tools menu, and settings
• Genome Viewer - Central visualization area
• ChatBox - AI assistant interface (right sidebar)
• Sidebar - Left panel with an icon rail that switches between four views: Display (track and feature-type toggles), Inspect (details of the selected gene, primer, read or variant), Explore (search results, operons, bookmarks) and Info (file information and statistics). Click a section header to collapse it; click the active rail icon to hide the sidebar.

Settings¶

Every preference lives in one Settings window. Open it with ⌘, on macOS or Ctrl+, on Windows and Linux, from Options → Settings… in the toolbar, or from the Options menu.

• The sidebar groups the sections: General (Appearance, Navigation, Features, Tabs), Genome View (Visualization, Tracks, Gene Details, Search), AI Assistant (Model Providers, ChatBox, Agents & Skills, MCP Servers, Literature), Tools (External Tools, BLAST+, Plugins) and System (Memory, Caching, Security, Import, Export & Backup, About).
• The search box at the top of the sidebar finds individual settings across every section, in English or by Chinese keywords. Use the arrow keys and Enter to open a result; the setting is highlighted in its section.
• The older entry points still work and open the matching section: the Options menu items, a track header's gear (opens Tracks for that track type), the ChatBox settings button, and the assistant's toggle_settings_modal tool.
• Sections that have a Save button keep the window open after saving. Close the window with its close button or Esc.
• Settings persist across restarts, including search options, track settings, agents, MCP servers, skills and external tools.
• System → Import, Export & Backup → Export All Settings writes every setting to a JSON file you can import on another computer. API keys, tokens and Authorization headers are never included, and importing keeps the keys already stored on the computer.

Quick Start Workflow¶

1. Configure AI Models (Essential)¶

Before using AI features, configure your LLM providers:

Settings → Model Providers      (⌘, on macOS, Ctrl+, on Windows and Linux)

Add API Keys:

• OpenAI: Get key from https://platform.openai.com/api-keys
• Anthropic: Get key from https://console.anthropic.com/
• Google: Get key from https://ai.google.dev/
• SiliconFlow: Get key from https://siliconflow.cn/

Provider keys use OS-backed credential storage. If that storage is unavailable, newly entered keys are available for the current session and the provider settings display a warning. Previously saved keys remain available when the OS store recovers.

Model Lists Stay Current:

• Each provider tab fetches its live model list once credentials are saved, so newly released models appear without an app update
• A successful refresh updates the provider tab to show the reported models. Other (specify below) remains available for custom model IDs
• The line under the dropdown shows how many models were reported and when the list was last updated
• Lists refresh automatically when you open a provider tab (cached for 6 hours) and immediately after you change an API key or endpoint; Refresh re-fetches on demand
• The built-in list is the fallback when a live list is unavailable

Configure Agent Settings:

• Mode — leave multi-agent mode off for a single assistant that plans and calls tools directly, or turn it on to route requests to the specialised agents; enable or disable individual agents here
• Generation — temperature, token limit, and the default thinking level, applied in both modes. The model itself is chosen from the picker beside the ChatBox input box; its Auto entry follows the default in Options → Configure LLM Providers
• Execution — function-call rounds, early completion, tool-repetition limits, and timeouts
• Context — system prompt composition and dynamic tool selection
• Memory and Skills — memory system and installed agent skills

Test Connection:

• Click "Test Connection" for each provider
• Verify successful connection before proceeding

2. Load Your First Genome¶

File → Load File → Genome File

The source checkout includes test_data/ECOLI.gbk as a sample genome. See the format table for reference and supporting files.

3. Start Exploring¶

Navigate the Genome:

• Use the overview ruler to pan or resize the viewport. Its display control cycles Full, Compact, and Minimal and saves the selected mode.
• Drag in the coordinate ruler to select a sequence range. Use Full or Compact to show this ruler.
• Enter coordinates in the position input or use the zoom and paging buttons in the toolbar.
• To save the visible range, open Explore → Bookmarks → Current View, enter a name, and save. Select the bookmark later to return to its coordinates.

Search for Genes:

• Type gene name in search box (e.g., "lacZ")
• Press Enter to jump to gene location
• View detailed information in the tabbed Gene Details sidebar (Left Panel)

Ask the AI:

• Type questions in ChatBox (e.g., "What does the lacZ gene do?")
• AI will use appropriate tools to answer
• View conversation history and AI reasoning process

Core Features¶

Genome Visualization¶

The genome browser combines a feature track, GC content and skew, multi-track WIG data, the gene details sidebar, and a protein/sequence view.

Tracks¶

Gene Track 🧬

• Shows annotated genes and features
• Color-coded by type (CDS, tRNA, rRNA, etc.)
• Directional arrows indicate strand
• Click to view detailed information

Sequence Track 🔤

• Displays DNA sequence
• Adaptive density based on zoom level
• Color-coded nucleotides (A, T, G, C)

GC Content & Skew Track 📊

• Dynamic SVG visualization
• Adaptive window sizing
• Shows GC percentage and skew values
• Useful for identifying genomic features

Variant Track 🔬

• Shows SNPs and mutations from VCF files
• Quality scores and annotations
• Filter by type and quality

Read Alignment Track 📋

• Visualizes BAM/SAM alignments
• BAM and SAM coverage display the mean number of aligned bases per reference position in each bin. Depth follows the mapping-quality and secondary/supplementary alignment settings and is calculated independently of read display sampling. Deletions and skipped reference intervals contribute zero depth.
• The coverage label identifies views that show read overlaps per bin, including sampled overlaps when only a sample is available.
• Mismatch highlighting

Base-level read pileup over a selected gene, with coverage depth shown above the aligned reads.

Coverage and base-resolution read tracks alongside gene references and operons in the side panel.

Protein Track ⚗️

• Translated sequences
• Protein features and domains
• Link to structure prediction

Primer Track 🧪

• Designed primers rendered directly on the sequence view
• Forward and reverse orientation indicated by arrow direction
• Click a primer to open its details

Designed primers (e.g. Test-P1) drawn over the sequence view, aligned to their target coordinates.

Track Controls¶

Resize Tracks:

• Click and drag track headers to adjust height
• Settings persist across sessions

Reorder Tracks:

• Drag track headers to reorder
• Customize your preferred layout

Toggle Tracks:

• Click eye icon to show/hide tracks
• Right-click for track-specific options

Gene Details Sidebar¶

The Gene Details sidebar provides a comprehensive, tabbed intelligence panel for exploring annotated genomic features.

Pinned Header¶

The header remains static, providing immediate access to core identifiers:

• Gene Identifiers: Displays the gene name, locus tag, and feature type (e.g., CDS, mRNA).
• Location Data: Shows exact genomic coordinates, strand orientation, and sequence length.
• Operon Integration: Displays a color-coded operon badge for genes that are part of a coordinated transcriptional unit.

Global Actions¶

These buttons are always accessible above the tabs:

• Edit Annotation: Modify gene metadata or structure.
• Zoom to: Center the genome viewer on the selected feature.
• Deep Research: Launch advanced AI analysis for functional discovery.
• Search PDB / AlphaFold: Search for 3D protein structures (experimental or AI-predicted).

Tabbed Information Architecture¶

• General Tab: Essential attributes, product descriptions, and unified literature citations.
• GO Tab: Dedicated Gene Ontology terms for functional classification.
• Pathways Tab: Metabolic context, including EC numbers, KEGG orthology (KO), and pathway maps.
• Sequence Tab: High-quality rendering of DNA, CDS, and Protein sequences with line numbering.
• Notes Tab: A workspace for user-defined qualitative notes.
• Resources Tab: External database cross-references (db_xref) and project attachments.

Project Management¶

Creating Projects¶

File → New Project

Project Structure:

Documents/GenomeExplorer Projects/
└── MyProject/
    ├── data/                    # Project data files
    ├── MyProject.prj.GAI        # Project configuration
    └── metadata.json            # Project metadata

Project Files Include:

• Genome sequences and annotations
• AI conversation history
• Custom annotations and features
• Visualization preferences
• Analysis results

Project View Modes¶

Grid View - Visual thumbnail layout List View - Compact file listing Details View - Full metadata display

Switch modes using: View → Grid/List/Details

File Operations¶

Loading Files¶

Choose the file role under File → Load File. To overlay reads, load the reference FASTA or GenBank first, then choose Reads File. Keep a BAM's .bai or .csi index beside it for indexed regional queries. For alignment troubleshooting, see Reads Track Is Empty.

Exporting Data¶

Export Sequences:

Tools → Export → FASTA/GenBank/Protein

Export Features:

Tools → Export → GFF/BED

Export Analysis Results:

• AI conversation logs
• Benchmark test results
• Network analysis data
• Pathway visualizations

Sequence Editing¶

Use Sequence Editing to queue operations on the loaded genome. Paste replaces an active selection or inserts at the sequence cursor. If neither is available, choose the destination range. Paste Reverse Complement reverse-complements the clipboard bases before pasting.

Review the operations in Edit Queue. Positions refer to the source genome. CodeXomics adjusts downstream positions during execution and stops if an earlier edit makes a later target ambiguous. Run Edit Queue writes the result to a separate GenBank file and opens it in a new window when available.

Session Checkpoints restore the pending queue, sequence clipboard and saved view for the loaded genome. To return to the original bases after a successful export, open the original genome file.

For compound GenBank features, the exporter preserves segment structure and checks CDS translation when an edit affects coding sequence. See GenBank feature preservation for review and export behavior.

AI Assistant¶

ChatBox Interface¶

The ChatBox is your interface to CodeXomics' multi-agent AI system.

The ChatBox can drive analyses such as AlphaFold structure lookup, opening an interactive 3D protein viewer for the selected gene.

Basic Queries¶

Gene Information:

"What does the lacZ gene do?"
"Find all DNA polymerase genes"
"Show me genes involved in DNA repair"

Sequence Analysis:

"Calculate GC content of this region"
"Find ORFs in this sequence"
"Analyze codon usage for lacZ"

Navigation:

"Jump to position 1000"
"Show me the lac operon region"
"Find genes between 1000 and 5000"

Advanced Multi-Agent Queries¶

Complex Analysis:

"Perform a comprehensive analysis of the lac operon including:
- Gene annotation
- Protein structure prediction
- Pathway integration
- Regulatory elements"

Comparative Analysis:

"Compare GC content across multiple genomic regions"
"Find similar genes in other organisms"

Workflow Automation:

"Load E. coli genome, find ribosomal genes, export to FASTA"
"Analyze all genes in region 1000-10000 and generate summary"

Long-Running Research¶

Some requests — Deep Gene Research above all — start a background task that runs for several minutes rather than answering in one turn. CodeXomics polls those tasks for you; you do not need to ask "is it done yet?", and the assistant is told not to poll them either.

While a run is active, a research progress dock sits between the conversation and the input box and never scrolls away:

• Gene and status — Queued, Researching, Completed, Failed, or Cancelled
• Progress bar and percentage — an animated indeterminate bar until the server reports a figure
• Current step — for example Gene search or Literature full text
• Elapsed time — a ticking clock, so a run whose percentage has not moved for a while is still visibly alive
• Actions — jump back to the run's full status message in the conversation, cancel the run, or dismiss the row

Click the dock header to collapse it to a single line; the summary still shows gene, percentage, and current step. Several runs can be tracked at once. Completed runs disappear on their own after a short pause; failed runs stay until you dismiss them, with the reason shown inline.

The conversation also keeps a detailed status message for each run, updated in place, which is where the final report, download links, and outcome are delivered when the run finishes.

Understanding AI Responses¶

Thinking Process:

• Click "Show Thinking" to see AI reasoning
• Understand tool selection decisions
• View intermediate steps

Tool Calls:

• AI automatically selects appropriate tools
• View which tools were used
• See tool parameters and results

Multi-Agent Coordination:

• Coordinator assigns tasks to specialized agents
• Workers execute specific analysis
• Results are integrated and presented

AI Configuration¶

Default Model:

• Set in the Default Model tab under Settings → Model Providers
• Used whenever the ChatBox model selector is set to Auto; the Auto entry shows which model that currently is
• Leave its Model on Auto to use the Provider default model chosen on that provider's tab
• The selector beside the ChatBox input box overrides it per conversation. It lists every enabled provider's models, including ones entered through "Other (specify below)"

Thinking Level:

• Set beside the model selector in the ChatBox, or as a default under Agent Settings → Generation
• Default leaves the model's own behaviour; Off, Low, Medium and High set how much it reasons before answering
• Adjustable for models with a thinking control: Claude, Gemini 2.5 and later, OpenAI reasoning models, DeepSeek (directly or through Zhongkeyu), Qwen3 hybrid models on SiliconFlow, and OpenRouter. Levels a model does not accept are greyed out — some models always think, so they have no Off
• For any other model the control reads Thinking: fixed and is disabled; hover it to see why
• Higher levels give better plans on multi-step requests at the cost of latency and tokens; the output limit is raised automatically while thinking is on

Temperature Settings:

• Lower (0.0-0.3): Precise, factual responses
• Medium (0.4-0.7): Balanced creativity and accuracy
• Higher (0.8-1.0): More creative, exploratory

Context Management:

• AI maintains conversation context
• Reference previous queries
• Build on earlier analysis

External Tools¶

For NVIDIA arc/evo2-40b sequence generation, see the Evo 2 DNA Generation guide. Open it from Tools → Evo 2 DNA Generation.

CodeXomics integrates with several powerful external tools.

ProGenFixer 🔧¶

Purpose: Protein engineering and sequence optimization

Access:

Tools → External Tools → ProGenFixer
Keyboard: Cmd/Ctrl+Shift+P

Use Cases:

• Optimize protein sequences
• Fix problematic sequences
• Predict stability
• Design mutations

Deep Gene Research 🧬¶

Purpose: Advanced gene analysis and research

Access:

Tools → External Tools → Deep Gene Research
Keyboard: Cmd/Ctrl+Shift+D

Features:

• Exact CDS target binding through locus/protein identifiers
• Identity-aware literature retrieval and citation filtering
• Separate direct abstract-supported findings from exact GeneID-linked contextual bibliography; contextual papers are never used as annotation claims
• Citation-bound proposal facts with exact PMID/DOI links and verified abstract spans
• Concise, evidence-linked annotation proposals for curator review
• Automatic storage of the completed full JSON report in the associated gene's Resources → Attachments list
• A built-in searchable JSON viewer that expands and pages large reports on demand
• Safe import of externally started DGR tasks through archive_annotation_research; CodeXomics re-derives and verifies the exact current CDS qualifier snapshot together with the task, citations, proposal, and target binding before allowing a ChangeSet

Research does not edit the genome directly. When direct literature evidence is available, the proposal includes a compact, citation-rich CDS Note that summarizes the report's key functional, pathway, regulatory, structural, and phenotype findings. Each literature sentence is bound to a verified PubMed abstract span. Review the proposed qualifier diff and its citations before approving a ChangeSet. The full report attachment is integrity checked each time it is opened.

While the research runs

A run typically takes several minutes. CodeXomics polls it for you and shows live progress in the ChatBox — see Long-Running Research for the progress dock, its status fields, and how to cancel a run.

When the research finishes

The run's status message in the ChatBox becomes the result summary: confidence, research time, source count, download links for the report and the detailed research data, and the proposed annotation terms.

CodeXomics then creates the annotation ChangeSet for you. You no longer have to ask for the proposal to be turned into a reviewable change — the completion message names the ChangeSet directly:

📋 Annotation ChangeSet: cs_… (awaiting_approval)
- Qualifiers: product, note, go_terms, EC_number, …
- Risk: medium

Research that cannot be turned into a safe change says so instead of proposing one. The completion message reports the reason, and nothing is written:

Re-running or re-checking a completed task returns the ChangeSet that already exists rather than adding a duplicate to your review queue.

CHOPCHOP 🔬¶

Purpose: CRISPR design and analysis

Access:

Tools → External Tools → CHOPCHOP
Keyboard: Cmd/Ctrl+Alt+H

Capabilities:

• sgRNA design
• Off-target prediction
• Primer design
• Validation

KGML Pathway Viewer 🛤️¶

Purpose: KEGG pathway visualization

Access:

Tools → KGML Pathway Viewer
Keyboard: Cmd/Ctrl+Shift+K

Features:

• Interactive pathway maps
• Gene highlighting
• Metabolite information
• Pathway export

STRING Networks 🔗¶

Purpose: Protein-protein interaction analysis

Access:

Tools → Bioinformatics Tools → STRING Networks

Analysis:

• Interaction networks
• Functional enrichment
• Cluster analysis
• Network export

Benchmark Testing¶

The benchmark runs ChatBox tool-calling cases and records their calls, arguments, and execution results.

Opening Benchmark Interface¶

Options → LLM Benchmark

Test Suites¶

Automatic Simple covers individual operations such as navigation, file import, and sequence analysis. Automatic Complex covers workflows such as restriction digest followed by gel simulation or changing and rechecking track visibility. Manual suites provide instructions and a verification checklist for human scoring.

Running Tests¶

1. Configure the ChatBox provider and model, then select the suites or cases to run.
2. For file-based cases, set Default File Directory to the folder containing the named fixtures. Check the case instructions for inputs or a genome that must already be loaded.
3. Choose Production parity to use the current ChatBox settings, or Oracle-assisted for the controlled run that stops when the expected calls have executed.
4. Select Start Benchmark. For manual cases, follow the checklist and submit your evaluation.

Viewing Results¶

Progress Tracking:

• Real-time progress bars
• Test status indicators
• Success/failure counts

Detailed Reports:

• Individual test results
• LLM interaction logs
• Performance metrics
• Error analysis

Export Options:

• CSV export
• JSON export
• HTML reports
• LLM conversation logs

Automatic pass/fail is based on structured evidence from the current request. Use the recorded harness mode when comparing runs. Benchmark Methods

Advanced Features¶

Conversation Evolution v2¶

Track AI reasoning and decision-making across conversations.

Features:

• Conversation state tracking
• Decision point analysis
• Tool usage patterns
• Performance metrics

Access:

Tools → Conversation Evolution

Plugin System¶

Extend CodeXomics with community plugins.

Plugin Marketplace:

Plugins → Marketplace

Available Plugins:

• Biological Networks
• Comparative Genomics
• Metabolic Pathways
• Structural Genomics
• Population Genomics

Installing Plugins:

1. Browse marketplace
2. Click "Install" on desired plugin
3. Plugin automatically integrates
4. Access through Tools menu

MCP Integration¶

Use the authenticated Electron MCP listener to let external clients call tools against the current workspace or send a prompt to the ChatBox. MCP Server Guide

Custom Annotations¶

Create your own genomic features.

Adding Features:

1. Select sequence region
2. Right-click → "Create Feature"
3. Enter feature details
4. Save to project

Feature Types:

• CDS (Coding Sequence)
• Gene
• Regulatory Element
• Repeat Region
• Custom Type

Troubleshooting¶

Common Issues¶

AI Not Responding¶

Symptoms: ChatBox doesn't respond to queries

Solutions:

1. Check API key configuration (Settings → Model Providers)
2. Verify internet connection
3. Test connection using "Test Connection" button
4. Check API quota/billing
5. Try a different model provider

File Won't Load¶

Symptoms: Error loading genome file

Solutions:

1. Verify file format is supported
2. Check file isn't corrupted (open in text editor)
3. Ensure file permissions allow reading
4. Try smaller file first
5. Check console for specific errors (View → Developer Tools)

Slow Performance¶

Symptoms: Interface feels sluggish

Solutions:

1. Reduce number of visible tracks
2. Close unused external tool windows
3. Clear conversation history
4. Restart application
5. Check system resources (RAM, CPU)

Benchmark Tests Failing¶

Symptoms: Tests don't complete or fail unexpectedly

Solutions:

1. Verify test data files are accessible
2. Check LLM configuration
3. Ensure working directory is correct
4. Review test logs for specific errors
5. Try individual tests instead of full suite

Getting Help¶

Check Documentation:

• This user guide
• Developer guide
• API reference
• Fix summaries in docs/

Report Issues:

• GitHub Issues: https://github.com/Scilence2022/CodeXomics/issues
• Include: Version, OS, steps to reproduce, error messages

Contact:

• Email: songlf@tib.cas.cn
• GitHub Discussions: https://github.com/Scilence2022/CodeXomics/discussions

FAQ¶

General Questions¶

Q: What file formats are supported?

A: FASTA, GenBank, GFF/GTF, BED, VCF, BAM/SAM, KGML, WIG, and .prj.GAI project files.

Q: Do I need an API key to use CodeXomics?

A: AI features require API keys from providers (OpenAI, Anthropic, etc.). Basic visualization and analysis tools work without API keys.

Q: Can I use local LLMs?

A: Yes! Configure a local LLM endpoint (e.g., Ollama) in LLM settings.

Q: Is my data sent to AI providers?

A: Only your queries and relevant context are sent to AI providers. Your genome data stays local unless explicitly requested in a query.

Technical Questions¶

Q: How much RAM do I need?

A: Minimum 6GB, recommended 12GB for large genomes and multi-agent mode.

Q: Can I run CodeXomics on older computers?

A: It depends on the genome size and features used. Try reducing active tracks and disabling multi-agent mode.

Q: How do I update CodeXomics?

A: Open Help → Check for Updates…. Installed release builds also check after startup and every six hours. The update window shows the available version and release notes. Choose Download Update to see progress; you can cancel or close the window and return through Help. When verification finishes, save your work in all windows and choose Restart and Install. On macOS, a staged update also applies on the next normal quit; on Windows and Linux, use the restart button.

Development builds, portable Windows editions and store-managed packages explain their update method in that window. If the release feed is unavailable, use the official releases page or your package manager. In-app updates require release metadata as well as the installer; not every historical release includes that metadata.

Q: Where are my projects saved?

A: By default in Documents/GenomeExplorer Projects/. You can change this in settings.

Feature Questions¶

Q: Can I compare multiple genomes?

A: Yes, through the Comparative Genomics plugin and multi-file loading.

Q: How do I export my analysis results?

A: Use Tools → Export or save the entire project (.prj.GAI format).

Q: Can I create my own plugins?

A: Yes! See the Developer Guide for plugin development instructions.

Q: How accurate is the AI analysis?

A: AI provides helpful insights but should be validated. Use benchmark tests to evaluate performance for your specific use cases.

Next Steps¶

Explore More:

• Developer Guide - Create plugins and contribute
• Developer Guide - Technical documentation
• Current Release Notes - What's new in the current release

Join the Community:

• GitHub Discussions
• Report bugs
• Request features
• Share your analysis workflows

Stay Updated:

• Star the repository
• Watch for releases
• Follow changelog

Made with ❤️ by the CodeXomics Team