Settings Guide
Complete configuration reference for ChipOS
Features
The Features section controls which functionality is enabled in ChipOS. Toggle these settings to customize your experience.
Dark Mode
Switch between light and dark color themes
| Default | Enabled (Dark) |
| Effect | Changes entire UI color scheme |
| When to Use | Personal preference; dark mode reduces eye strain in low light |
Projects
Enable Projects and Tasks functionality
| Default | Enabled |
| Effect | Shows Projects sidebar, allows task management |
| Requirements | archon_tasks.sql migration must be installed |
Note: If you see "Projects table not detected", run the database migration in Supabase SQL Editor.
Pydantic Logfire
Structured logging and observability platform
| Default | Disabled |
| Effect | Sends telemetry data to Pydantic Logfire for debugging |
| Requirements | LOGFIRE_TOKEN in environment |
API Keys
Manage credentials for external services. API keys power the AI features, embeddings, and external integrations.
Supported API Keys
| Key Name | Service | Purpose |
|---|---|---|
VOYAGE_API_KEY |
Voyage AI | Default embeddings (voyage-code-3) |
OPENAI_API_KEY |
OpenAI | RAG queries, embeddings, AI chat |
GOOGLE_API_KEY |
Google Gemini | Alternative LLM provider |
GITHUB_TOKEN |
GitHub | Crawling private repositories |
Key Features
Encryption
Click lock icon to encrypt sensitive values
Show/Hide
Click eye icon to reveal masked values
Add New
Add custom API keys as needed
Security Tip: Always encrypt API keys. Encrypted credentials are stored securely and cannot be viewed after saving.
RAG Settings
RAG (Retrieval-Augmented Generation) settings control how ChipOS retrieves and processes knowledge from your documentation.
Voyage AI's voyage-code-3 is now the
default embedding model, offering 13-17% better code retrieval than
OpenAI while using 33% less memory (1024 vs 1536 dimensions). Get your API key at voyage.ai.
LLM Provider & Models
| Provider | Recommended Chat Model | Embedding Model |
|---|---|---|
| Voyage AI (default) | gpt-4o-mini via OpenAI |
voyage-code-3 (1024 dims) |
| OpenAI | gpt-4o-mini, gpt-4o |
text-embedding-3-small |
| Google Gemini | gemini-1.5-flash |
text-embedding-004 |
| Ollama (local) | llama2, mistral |
nomic-embed-text |
RAG Strategy Toggles
Use Contextual Embeddings
Enhances embeddings with surrounding context for better retrieval
Default: Disabled | Workers: 1-10 (default 3)
Use Hybrid Search
Combines vector similarity with BM25 keyword search
Default: Enabled |
Better for exact identifiers like AXI_AWREADY
Use Agentic RAG
Enables code extraction and specialized search for technical content
Default: Enabled | Creates separate embeddings for code blocks
Use Reranking
Applies cross-encoder reranking to improve result relevance
Default: Enabled | Re-scores top results for better accuracy
Use Query Classification
Analyzes query intent and routes to the optimal search strategy
Default: Enabled | Distinguishes code queries from conceptual queries
Use Context Expansion
Retrieves surrounding chunks from the same file for better context
Default: Enabled | Essential for code queries to understand full context
Crawling Performance Settings
| Setting | Default | Range | Description |
|---|---|---|---|
| Batch Size | 50 | 10-100 | URLs to queue per crawl batch |
| Max Concurrent | 10 | 1-20 | Pages to crawl simultaneously |
| Wait Strategy | DOM Loaded | - | When to consider page loaded |
| Page Timeout | 60 sec | 5-120 | Max time to wait for page |
| Render Delay | 0.5 sec | 0.1-5 | Wait after load before extracting |
Wait Strategy Options
Storage Performance Settings
| Setting | Default | Range | Description |
|---|---|---|---|
| Document Batch Size | 50 | 10-100 | Chunks per database insert batch |
| Embedding Batch Size | 100 | 20-200 | Embeddings per API call |
| Code Extraction Workers | 3 | 1-10 | Parallel code summary workers |
| Enable Parallel Batches | Enabled | - | Process multiple batches simultaneously |
Code Extraction Settings
These settings control how code blocks are detected and extracted from crawled documents.
Code Block Length
| Setting | Default | Range | Description |
|---|---|---|---|
| Minimum Length | 250 chars | 50-2000 | Shortest code block to extract |
| Maximum Length | 5000 chars | 1000-20000 | Longest code block to extract |
Tip: Increase minimum for higher quality (fewer snippets). Decrease to capture short examples.
Detection Features
Complete Block Detection
Extend code blocks to natural boundaries (closing braces, etc.)
Language-Specific Patterns
Use specialized patterns for TypeScript, Python, Verilog, etc.
Contextual Length Adjustment
Adjust minimum length based on context (example, snippet, implementation)
Content Filtering
Filter Prose Content
Remove documentation text mistakenly wrapped in code blocks
Filter Diagram Languages
Exclude Mermaid, PlantUML, and other diagram formats
Generate Code Summaries
Use AI to create summaries and names for code examples
Recommended Configurations
Hardware Documentation
- Use Contextual Embeddings: Enabled
- Use Hybrid Search: Enabled
- Use Agentic RAG: Enabled
- Wait Strategy: DOM Loaded
- Generate Code Summaries: Enabled
Large Codebases
- Max Discovered Pages: 50,000
- Embedding Batch Size: 200
- Code Extraction Workers: 5
- Parallel Batches: Enabled
- Use path regex filters
Low-Resource Systems
- Use Contextual Embeddings: Disabled
- Batch Size: 25
- Max Concurrent: 3
- Parallel Batches: Disabled
API Cost Optimization
- Contextual Embeddings: Disabled
- Code Summaries: Disabled
- Embedding Batch Size: 50
- Model: gpt-4o-mini
Troubleshooting
"Failed to save settings"
- Check Supabase connection
- Verify using service_role key (NOT anon key)
- Check browser console for detailed error
"Projects table not detected"
- Run database migration:
migration/archon_tasks.sql - Restart the server after migration
Slow crawling
- Reduce Max Concurrent to 3-5
- Use "DOM Loaded" wait strategy
- Check network/server response times
Poor search results
- Enable Hybrid Search
- Enable Reranking
- Increase Context Window Size
- Re-crawl sources with updated settings