ChipOS ChipOS Docs
Back to ChipOS
OFFICIAL DOCUMENTATION

ChipOS Documentation

The complete guide to the AI Operating System for Hardware Design. Learn how to leverage world-leading RAG technology for semiconductor development.

Quick Start

Get up and running in 5 minutes

RAG Technology

Learn about our AI architecture

Commands

12 built-in slash commands

What is ChipOS?

ChipOS is a complete AI operating system designed specifically for semiconductor engineers. Built on top of VS Code, it provides a standalone development environment with integrated knowledge management, AI-powered assistance, and seamless integration with modern AI tools.

For Hardware Engineers

  • Store and search datasheets, RTL specs, and verification plans
  • Generate SystemVerilog and UVM testbenches with AI
  • Query your knowledge base using natural language

For AI/ML Engineers

  • Deploy and benchmark models on Metis hardware
  • Create inference pipelines with YAML configuration
  • Access SDK documentation through RAG-powered search

Installation

No conflicts with VS Code

ChipOS is a standalone application with its own data folder. It won't interfere with your existing VS Code installation.

1

Download the DMG

ChipOS-2025.12.1-macOS-arm64.dmg

Requires macOS 11+ • Apple Silicon

2

Open the DMG and drag to Applications

The app is notarized by Apple — no security warnings.

3

Launch ChipOS

Find it in your Applications folder or Spotlight.

Quick Start

Get ChipOS connected to your AI assistant in under 5 minutes.

1

Open a Workspace

In the Controls panel, click "Open Workspace" to select your project folder. ChipOS automatically installs 12 Voyager SDK commands to .claude/commands/

Controls → Open Workspace → Select Folder

2

Connect AI Provider

Click "Connect AI Provider" and select your preferred tool:

Claude Code

Cursor

Windsurf

Gemini

3

Open Dashboard (Optional)

Click "Open Dashboard" to access the full ChipOS UI with Knowledge Base, AI Chatbot, and more.

Start Using Commands

In Claude Code terminal, try your first command:

/voyager-help How do I create a detection pipeline?

Claude will query the ChipOS knowledge base and provide contextual answers!

Configuration

ChipOS settings can be configured through VS Code's settings UI or settings.json.

Setting Default Description
chipos.backend.mode "hosted" Backend mode: "hosted" (cloud) or "local" (Docker)
chipos.backend.hostedUrl https://chipos-server-*.run.app Cloud backend API URL
chipos.backend.apiUrl http://localhost:8181 Local backend API URL
chipos.showWelcomeOnStartup true Open dashboard on startup

Knowledge Base

The Knowledge Base is your central repository for hardware documentation. Store datasheets, RTL specifications, verification plans, and SDK documentation — all searchable with AI.

Web Crawling

Automatically crawl documentation websites using sitemap discovery.

  • Sitemap-first crawling
  • Recursive link following
  • HTML to markdown conversion

Repository Ingestion

Index entire GitHub repositories with AST-aware code parsing.

  • 25+ programming languages
  • Function/class extraction
  • Dependency graph building

Document Upload

Upload and index PDF datasheets and documentation.

  • PDF text extraction
  • DOCX support
  • Markdown/text files

Sidebar Browser

Browse all indexed sources directly in the sidebar.

  • Tree view navigation
  • Source filtering
  • Quick search

AI Chatbot

The built-in AI chatbot provides hardware-aware conversations with full syntax highlighting for code.

Supported Languages

Python SystemVerilog Verilog YAML JSON Bash
RAG-Connected

The chatbot automatically queries your knowledge base for hardware-specific questions, providing accurate, contextual answers.

MCP Server

The Model Context Protocol (MCP) server enables AI assistants to access your knowledge base. ChipOS runs a lightweight HTTP-based MCP server on port 8051.

Lightweight

HTTP-based protocol, no process spawning

Auto-Discovery

Tools automatically registered and documented

Rate-Limited

Built-in quota management for LLM APIs

Available MCP Tools

Tool Description
perform_rag_query Search the knowledge base with semantic understanding
get_available_sources List all indexed documentation sources
health_check Check backend service health status
session_info Get current session and user information

Claude Commands

When you open a workspace in ChipOS, 12 Voyager SDK slash commands are automatically installed to .claude/commands/. These work on macOS, Linux, and Windows.

Download All Commands (14 .md files)
/voyager-help

Get help from the ChipOS RAG knowledge base

/new-pipeline

Create a complete YAML pipeline configuration

/deploy

Compile and deploy a model for Metis hardware

/run

Run inference with various input sources

/bench

Benchmark model performance metrics

/new-app

Create a Python app using InferenceStream

/debug

Debug pipeline, model, or inference issues

/test

Run tests for SDK components

/build

Build native operators and examples

/add-model

Add a custom model to the model zoo

/list-models

List and search available models

ADVANCED TECHNOLOGY

RAG Technology

ChipOS features a proprietary Retrieval-Augmented Generation architecture designed specifically for the complexity of semiconductor design.

Multi-Embedding Strategy

Simultaneously uses 3 different embedding models for comprehensive coverage:

OpenAI — Linguistic understanding (1536-3072 dims)
UniXcoder — Code-specific semantics (768 dims)
Jina — Late-chunking context (1024 dims)

cAST Chunking

Context-aware Abstract Syntax Tree chunking preserves code structure:

Syntactically-aware chunk boundaries
Extracts imports, definitions, calls
Supports 25+ languages via tree-sitter
Research-backed (peer-reviewed paper)

Embedding Models

ChipOS supports multiple embedding providers with automatic fallback and no vendor lock-in.

Provider Model Dimensions Use Case
Voyage AI voyage-code-3 1024 Default — Code-optimized
OpenAI text-embedding-3-small 1536 General semantic search
OpenAI text-embedding-3-large 3072 High-precision retrieval
Google text-embedding-004 768 Alternative provider
Ollama nomic-embed-text 1024 Local/on-premise deployment
Batch Processing

Embeddings are generated in batches of 100 with automatic rate limiting and exponential backoff for API quota management.

Auto-Code Extraction

World-First Capability

ChipOS automatically identifies, extracts, and indexes code snippets from documentation — no manual tagging required.

When you ask "show me an example of a UVM sequence", ChipOS doesn't just find pages that mention sequences — it finds actual, runnable code examples.

Extracted Metadata

Imports

Definitions

Function Calls

Parent Scope

Node Types

Dependencies

Corrective RAG

ChipOS implements a 5-agent self-correcting RAG pipeline based on academic research.

Five-Agent Pipeline

Context Retrieval

Initial document search

Relevance Eval

Grade with confidence

Query Refine

Rewrite if poor results

External KB

Web search fallback

Synthesize

Generate answer

Iterative Refinement

Up to 2 query rewrites if initial results are poor

Confidence Scoring

LLM-based relevance grading with thresholds

External Fallback

Web search when internal KB is insufficient

Source Attribution

Full query history and citation tracking

Query Classification

ChipOS analyzes query intent using keyword patterns to route queries to the optimal search strategy.

Intent Keywords Strategy
Code Specific "function", "class", "def", "implementation" Prioritize code examples table
Conceptual "how to", "what is", "explain", "guide" Prioritize documentation + summaries
API Reference "api", "endpoint", "parameter", "schema" Prioritize API docs
Debugging "error", "bug", "fix", "exception" Search both code and docs

Context Expansion

When retrieving code chunks, ChipOS automatically includes surrounding chunks from the same file to provide full context.

Parent-Child Relationships

Each code chunk stores metadata about its position in the original file:

file_hash

Groups chunks from same file

chunk_index

Position in file (0-indexed)

total_chunks

Total chunks in file

file_path

Full path for context

How It Works

When a code chunk is retrieved, Context Expansion fetches adjacent chunks (before and after) to provide surrounding code, making it easier for AI assistants to understand the full context.

Cross-Encoder Reranking

Two-stage retrieval: first fetch candidates with vector search, then rerank with a CrossEncoder model for 15-20% better relevance.

Reranking Pipeline

Initial Search

Fetch 5× candidates

CrossEncoder

Score each candidate

Top Results

Return best N

Setting Default Description
USE_RERANKING true Enable/disable reranking
RERANKING_MODEL ms-marco-MiniLM-L-6-v2 CrossEncoder model (fast + accurate)
RERANK_CANDIDATE_MULTIPLIER 5 Fetch N× results for reranking
RERANK_MAX_CANDIDATES 100 Maximum candidates to rerank

RAG Health Monitoring

ChipOS automatically evaluates RAG quality after content is uploaded or crawled, detecting issues before they impact users.

Healthy

75-100% score

RAG working well

Degraded

50-74% score

Some issues detected

Unhealthy

<50% score

Critical problems

Health Score Algorithm

health_score = (
    retrieval_success_rate * 0.40 +    # Did queries return results?
    avg_relevance_score * 0.40 +       # How relevant were results?
    system_health * 0.20               # No API errors?
)

Voyage AI Integration

New Default Provider

Voyage AI's voyage-code-3 is now the default embedding model, offering 13-17% better code retrieval than OpenAI with 33% less memory usage.

Metric voyage-code-3 text-embedding-3-small
Code Retrieval 92.4% 79.2%
Dimensions 1024 1536
Memory/vector ~4KB ~6KB
MRL Support Yes No

Configuration

# Settings → RAG Settings → LLM Provider
LLM_PROVIDER=voyage
EMBEDDING_MODEL=voyage-code-3

# API Key (Settings → API Keys)
VOYAGE_API_KEY=pa-xxxx

System Architecture

ChipOS Desktop App VS Code Fork
Welcome Extension
Theme
AI Toolkit
Main Server

Port 8181 • FastAPI + Socket.IO

MCP Server

Port 8051 • HTTP-based MCP

Agents Service

Port 8052 • PydanticAI

Supabase PostgreSQL 15+ with pgvector
Crawled Pages
Code Examples
Embeddings
Relationships

Technology Stack

Component Technology Purpose
Desktop App VS Code (Electron) Cross-platform native app
UI Framework React + TypeScript + Vite Webview panels and sidebar
UI Components Radix UI + TanStack Query Accessible primitives + data fetching
Backend Python + FastAPI + uv High-performance API server
Vector DB PostgreSQL + pgvector HNSW indexes for similarity search
Code Parsing tree-sitter AST-aware chunking (25+ languages)
MCP Protocol FastMCP (HTTP) AI assistant integration
AI Agents PydanticAI Corrective RAG pipeline
Observability Logfire Distributed tracing and logging
Deployment Docker + Google Cloud Run Containerized microservices

Database Schema

ChipOS uses Supabase (PostgreSQL 15+) with the pgvector extension for efficient vector similarity search.

chipos_crawled_pages

Stores crawled documentation with embeddings

  • • embedding: vector(1536)
  • • bm25_tokens: tsvector
  • • url, title, content
  • • source_id, metadata

chipos_code_examples

Indexed code with multi-dimensional embeddings

  • • embedding: vector(1536)
  • • code_embedding: vector(768)
  • • late_embedding: vector(1024)
  • • definitions, calls, imports[]

chipos_sources

Registered documentation sources

  • • name, url, type
  • • status, last_crawled
  • • page_count, metadata

chipos_code_relationships

Code dependency graph

  • • source_id, target_id
  • • relationship_type
  • • weight, metadata

AI Integrations

ChipOS connects seamlessly with your favorite AI coding assistants through the MCP server.

Claude Code

Full integration with auto-installed slash commands

Fully Supported

Cursor

MCP server configuration for context injection

Fully Supported

Windsurf

Native MCP tool access for knowledge queries

Fully Supported

Commands Reference

/voyager-help <query>

Query the ChipOS knowledge base for hardware-related help.

/voyager-help How do I configure a detection pipeline with YOLOv8?
/new-pipeline <model> <options>

Create a complete YAML pipeline configuration for inference. 

/new-pipeline yolov8n --input camera --output display
/deploy <model> [--target <device>]

Compile and deploy a model to Metis hardware.

/deploy yolov8n --target m.2
/bench <model> [--iterations <n>]

Benchmark model performance metrics (latency, throughput, power).

/bench yolov8n --iterations 1000

API Reference

The ChipOS backend exposes REST and MCP APIs for integration.

REST Endpoints

Method Endpoint Description
GET /api/health Health check
POST /api/rag/query RAG query with context
GET /api/sources List indexed sources
POST /api/sources/crawl Start web crawl
POST /api/sources/ingest Ingest GitHub repository

Settings Overview

ChipOS provides extensive configuration options to customize RAG behavior, code extraction, and system performance.

Features

  • Dark Mode - Toggle light/dark theme
  • Projects - Enable task management
  • Logfire - Structured logging
  • Disconnect Screen - Server status display

API Keys

  • OpenAI - RAG queries & embeddings
  • Google - Alternative LLM provider
  • GitHub - Private repo crawling
  • Encrypted storage with show/hide toggle

RAG Settings

  • LLM Provider - OpenAI, Gemini, Ollama
  • Hybrid Search - Vector + keyword search
  • Agentic RAG - Code-aware retrieval
  • Reranking - Cross-encoder scoring
  • Crawling - Batch size, concurrency

Code Extraction

  • Block Length - Min/max characters
  • Language Patterns - Per-language detection
  • Prose Filtering - Remove non-code content
  • Code Summaries - AI-generated descriptions
Complete Settings Documentation

For detailed descriptions of all 50+ settings, recommended configurations, and troubleshooting tips.

Full Settings Guide

Troubleshooting

MCP Server Not Connecting

If Claude/Cursor can't find the MCP server:

  1. Verify the backend is running (check Controls panel)
  2. Ensure port 8051 is not blocked by firewall
  3. Try restarting ChipOS with Cmd+Shift+P → Restart Services

Slash Commands Not Working

If /voyager-help doesn't respond:

  1. Check that .claude/commands/ exists in your workspace
  2. Verify commands were auto-installed (12 .md files should exist)
  3. Restart Claude Code terminal session

Empty RAG Results

If queries return no results:

  1. Check that sources are indexed in the Knowledge Base sidebar
  2. Verify embeddings were generated (check server logs)
  3. Try a broader query to test the connection