Configuration

Your Siya, Your Way

Siya is highly customizable, allowing you to tailor every aspect of the experience to your needs. From UI preferences to model selection, tool configurations to custom workflows - make Siya work exactly how you want it to.

Configuration Overview

Siya's hierarchical configuration system provides flexibility at every level

Configuration Files

Global Config
Desktop Config
Project Config
SIYA.md

~/.siya/config.json

System-wide settings that apply to all Siya instances

{
  "defaultModel": "claude-opus-4",
  "theme": "dark",
  "editor": {
    "fontSize": 14,
    "fontFamily": "JetBrains Mono",
    "tabSize": 2,
    "wordWrap": true
  },
  "notifications": {
    "sound": true,
    "desktop": true,
    "email": false
  },
  "telemetry": {
    "enabled": false,
    "level": "errors"
  },
  "experimental": {
    "betaFeatures": true,
    "debugMode": false
  }
}

Setting Categories

Core Settings

Default model selection
UI theme preferences
Language settings
Timezone configuration

Developer Settings

Editor preferences
Code formatting
Syntax highlighting
Debug options

Privacy Settings

Telemetry control
Data retention
Logging levels
Analytics opt-out

Advanced Settings

Experimental features
Beta access
Performance tuning
Custom endpoints

~/.siya/siya-desktop-config.json

Desktop application specific settings including MCP servers

{
  "window": {
    "width": 1200,
    "height": 800,
    "alwaysOnTop": false,
    "transparency": 0.95
  },
  "shortcuts": {
    "toggleWindow": "Cmd+Shift+S",
    "newChat": "Cmd+N",
    "clearMemory": "Cmd+K",
    "openSettings": "Cmd+,"
  },
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["context7"],
      "autoStart": true
    },
    "stock-market": {
      "command": "node",
      "args": ["/path/to/stock-mcp/index.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  },
  "startup": {
    "launchAtLogin": true,
    "minimizeToTray": true,
    "checkUpdates": true
  }
}

Desktop configuration is automatically watched - changes take effect immediately without restart

./siya.config.json

Project-specific settings that override global defaults

{
  "project": {
    "name": "My Awesome App",
    "type": "web",
    "framework": "react",
    "language": "typescript"
  },
  "conventions": {
    "componentStyle": "functional",
    "stateManagement": "zustand",
    "styling": "tailwind",
    "testing": "vitest"
  },
  "tools": {
    "linter": "npm run lint",
    "typecheck": "npm run typecheck",
    "test": "npm test",
    "build": "npm run build"
  },
  "siya": {
    "autoRunChecks": true,
    "suggestTests": true,
    "enforceTypes": true,
    "documentCode": false
  }
}

Create a siya.config.json in your project root to maintain consistent behavior across team members

Project Context File

Natural language project documentation for Siya’s understanding

# Project Context for Siya

## Overview
This is an e-commerce platform built with Next.js and Supabase.

## Architecture
- Frontend: Next.js 14 with App Router
- Backend: Supabase (PostgreSQL + Auth)
- Styling: Tailwind CSS with custom design system
- State: Zustand for client state

## Conventions
- Use functional components with TypeScript
- Follow Airbnb style guide
- Test with Vitest and React Testing Library
- Commit messages: conventional commits

## Important Context
- The checkout flow has custom business logic in `lib/checkout.ts`
- We use a custom authentication wrapper in `components/auth`
- Database migrations are in `supabase/migrations`

## Common Tasks
- Run `npm run dev` to start development
- Run `npm run db:push` to apply migrations
- Run `npm run test:e2e` before deploying

SIYA.md provides human-readable context that helps Siya understand your project better

Model Configuration

Choose Your AI Model

Select from cutting-edge AI models or run locally with complete privacy

Cloud Models
Local Models

Available Models

Claude Models

Claude Opus 4

Most capable model
Best for complex tasks
Superior reasoning

Claude Sonnet 4

Balanced performance
Faster responses
Cost-effective

OpenAI Models

GPT-5

Latest generation
Multimodal capable
Extended context

GPT-4 Turbo

Production ready
Reliable performance
Good value

Google Models

Gemini 2.5 Pro

Massive context window
Multimodal native
Fast inference

Gemini 2.5 Flash

Lightning fast
Cost optimized
Good for simple tasks

Specialized Models

DeepSeek Coder

Code specialized
Technical tasks
Open weights

Qwen 2.5

Multilingual
Strong reasoning
Efficient

Model Selection Strategy

API Configuration

# Claude API
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI API
export OPENAI_API_KEY="sk-..."

# Google API
export GOOGLE_API_KEY="AIza..."

# Custom Endpoints
export LLM_GATEWAY_URL="https://your-gateway.com"

{
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}",
        "baseURL": "https://api.anthropic.com",
        "defaultModel": "claude-opus-4"
      },
      "openai": {
        "apiKey": "${OPENAI_API_KEY}",
        "organization": "org-...",
        "defaultModel": "gpt-5"
      }
    }
  }
}

Run Models Locally

Complete privacy and control with local model execution

Download Model

Choose and download a llamafile from supported models

Place in Directory

Move the file to ~/.siya/local-models/

Make Executable

Run chmod +x model-name.llamafile

Select in Siya

Choose the local model from Siya’s model selector

Supported Local Models

Performance Optimization

Hardware Acceleration

# Enable GPU acceleration
export CUDA_VISIBLE_DEVICES=0
export LLAMAFILE_GPU=1

# Metal acceleration (macOS)
export LLAMAFILE_USE_METAL=1

Memory Settings

# Adjust context size
export LLAMAFILE_CTX=8192

# Set thread count
export LLAMAFILE_THREADS=8

Tool Configuration

Power Up Your Tools

Configure tools to match your development workflow perfectly

File System Tools

{
  "tools": {
    "fileSystem": {
      "defaultPermissions": "conservative",
      "autoBackup": true,
      "excludePatterns": [
        "node_modules/**",
        ".git/**",
        "*.log",
        "dist/**"
      ],
      "watchPatterns": [
        "src/**/*.{ts,tsx,js,jsx}",
        "*.config.{js,ts}"
      ],
      "encoding": "utf-8",
      "lineEndings": "auto"
    }
  }
}

Safety Features

Automatic backups
Permission checks
Destructive warnings
Undo capability

Performance

Smart caching
Batch operations
Async I/O
Memory mapping

Integration

Git awareness
Build tool hooks
IDE sync
File watchers

Code Analysis Tools

{
  "tools": {
    "codeAnalysis": {
      "ast": {
        "enabled": true,
        "languages": ["typescript", "javascript", "python"],
        "maxFileSize": "10MB"
      },
      "linting": {
        "autoFix": false,
        "showSuggestions": true,
        "severity": "warning"
      },
      "typeChecking": {
        "strict": true,
        "incremental": true,
        "skipLibCheck": false
      }
    }
  }
}

Code analysis tools help Siya understand your codebase structure and maintain quality

Search Tools

Grep Configuration
Semantic Search

{
  "tools": {
    "grep": {
      "engine": "ripgrep",
      "defaultFlags": ["--smart-case", "--hidden"],
      "ignoreFile": ".gitignore",
      "maxResults": 1000,
      "contextLines": 2
    }
  }
}

{
  "tools": {
    "semanticSearch": {
      "enabled": true,
      "indexing": {
        "automatic": true,
        "schedule": "on-change",
        "languages": ["all"]
      },
      "embedding": {
        "model": "text-embedding-3-large",
        "dimensions": 1536
      }
    }
  }
}

Execution Tools

{
  "tools": {
    "execution": {
      "shell": "/bin/zsh",
      "timeout": 120000,
      "sandbox": {
        "enabled": true,
        "networking": false,
        "filesystem": "read-only"
      },
      "environment": {
        "NODE_ENV": "development",
        "PYTHONPATH": "./src"
      }
    }
  }
}

Sandbox mode restricts network and filesystem access for safety

MCP Server Configuration

Extend with MCP Servers

Connect specialized tools and services through Model Context Protocol

MCP servers extend Siya's capabilities with domain-specific tools

Quick Setup
Manual Setup
Available Servers

Ask Siya

Simply tell Siya: “Configure the stock-market MCP server”

Automatic Configuration

Siya will handle the installation and configuration

Start Using

The server’s tools are immediately available

Siya can configure any MCP server from a GitHub URL or npm package name

{
  "mcpServers": {
    "myServer": {
      "command": "node",
      "args": ["./mcp-server/index.js"]
    }
  }
}

{
  "mcpServers": {
    "myServer": {
      "command": "npx",
      "args": ["@mycompany/mcp-server", "--port", "3000"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "LOG_LEVEL": "debug"
      },
      "autoStart": true,
      "restartOnFailure": true,
      "healthCheck": {
        "interval": 30000,
        "timeout": 5000
      }
    }
  }
}

Hooks Configuration

Automate Your Workflow

Create powerful automations that trigger on Siya’s actions

Hooks enable event-driven automation within Siya

Creating Hooks
Hook Events
Hook Examples

Natural Language

Tell Siya: “Create a hook that runs tests whenever I modify a test file”

Siya Generates

Siya creates the appropriate hook configuration

Automatic Activation

Hook starts working immediately

{
  "hooks": [
    {
      "name": "Auto-test on change",
      "event": "file:modified",
      "pattern": "**/*.test.{js,ts}",
      "command": "npm test -- ${file}",
      "enabled": true
    }
  ]
}

{
  "hooks": [
    {
      "name": "Deploy on main",
      "event": "git:push",
      "condition": "branch === 'main'",
      "commands": [
        "npm run build",
        "npm run test",
        "npm run deploy"
      ],
      "notifications": {
        "success": "desktop",
        "failure": "desktop,email"
      }
    }
  ]
}

File Events

Git Events

Commit Events

git:commit - After commit
git:push - After push
git:pull - After pull
git:merge - After merge

Branch Events

git:branch:create - New branch
git:branch:switch - Change branch
git:branch:delete - Remove branch

Siya Events

Development Hooks

{
  "hooks": [
    {
      "name": "Format on save",
      "event": "file:modified",
      "pattern": "**/*.{js,ts,jsx,tsx}",
      "command": "prettier --write ${file}"
    },
    {
      "name": "Lint on save",
      "event": "file:modified",
      "pattern": "src/**/*.{js,ts}",
      "command": "eslint --fix ${file}"
    },
    {
      "name": "Type check",
      "event": "file:modified",
      "pattern": "**/*.{ts,tsx}",
      "command": "tsc --noEmit",
      "debounce": 1000
    }
  ]
}

CI/CD Hooks

{
  "hooks": [
    {
      "name": "Pre-commit checks",
      "event": "git:commit",
      "commands": [
        "npm run lint",
        "npm run typecheck",
        "npm test"
      ],
      "blocking": true
    },
    {
      "name": "Deploy staging",
      "event": "git:push",
      "condition": "branch.startsWith('feature/')",
      "command": "npm run deploy:staging"
    }
  ]
}

Notification Hooks

{
  "hooks": [
    {
      "name": "Task completion",
      "event": "siya:task:complete",
      "command": "osascript -e 'display notification \"${task}\" with title \"Task Completed\"'"
    },
    {
      "name": "Error alert",
      "event": "siya:error",
      "condition": "error.severity === 'high'",
      "command": "curl -X POST https://api.slack.com/webhook -d '{\"text\":\"Error: ${error.message}\"}'",
      "environment": {
        "SLACK_WEBHOOK": "${SLACK_WEBHOOK_URL}"
      }
    }
  ]
}

Advanced Configuration

Fine-Tune Every Detail

Advanced settings for power users who want complete control

Performance Tuning

Memory Optimization
Network Settings
Concurrency

{
  "performance": {
    "memory": {
      "maxHeapSize": "4096MB",
      "gcInterval": 300000,
      "cacheSize": "1GB",
      "compressionLevel": 6
    }
  }
}

Heap Settings

Initial: 512MB
Maximum: 4GB
Growth: Adaptive
GC: Incremental

Cache Strategy

LRU eviction
TTL: 1 hour
Compression: zstd
Persistence: optional

{
  "network": {
    "timeout": 30000,
    "retries": 3,
    "proxy": {
      "http": "http://proxy.company.com:8080",
      "https": "https://proxy.company.com:8080",
      "bypass": ["localhost", "*.internal.com"]
    },
    "ssl": {
      "rejectUnauthorized": true,
      "ca": "/path/to/ca.pem"
    }
  }
}

{
  "concurrency": {
    "maxParallelTasks": 4,
    "fileOperations": 10,
    "networkRequests": 5,
    "shellCommands": 2,
    "queueStrategy": "priority"
  }
}

Adjust concurrency based on your system resources

Security Settings

Access Control

{
  "security": {
    "fileAccess": {
      "whitelist": ["~/projects", "/tmp"],
      "blacklist": ["~/.ssh", "/etc"],
      "readOnly": ["~/Documents"]
    }
  }
}

Secrets Management

{
  "security": {
    "secrets": {
      "provider": "keychain",
      "encryption": "aes-256-gcm",
      "autoLock": 300
    }
  }
}

Never commit sensitive configuration to version control

Logging & Debugging

{
  "logging": {
    "level": "info",
    "outputs": ["console", "file"],
    "file": {
      "path": "~/.siya/logs",
      "maxSize": "100MB",
      "maxFiles": 5,
      "compress": true
    },
    "filters": {
      "exclude": ["password", "token", "key"],
      "include": ["error", "warning"]
    }
  },
  "debugging": {
    "enabled": false,
    "verboseTools": ["bash", "mcp"],
    "traceRequests": false,
    "profileMemory": false
  }
}

Enable debugging temporarily with: siya --debug

Configuration Best Practices

Configuration Excellence

Follow these practices for maintainable and effective configurations

Layer Appropriately

Use global for preferences, project for code style, session for experiments

Version Control

Commit project configs, exclude personal preferences and secrets

Document Settings

Add comments explaining non-obvious configuration choices

Regular Review

Periodically review and clean up unused configurations

Team Alignment

Share project configurations to ensure consistency

Troubleshooting Configuration

Common Issues

Reset Configuration

# Backup current config
cp ~/.siya/config.json ~/.siya/config.backup.json

# Reset to defaults
rm ~/.siya/config.json

# Siya will recreate with defaults
siya

# Check syntax
siya config validate

# Show effective config
siya config show --effective

# Test specific setting
siya config get tools.fileSystem.autoBackup

Summary

Configuration Mastery Achieved

You now have complete control over Siya’s behavior. From simple preferences to complex automations, every aspect can be tailored to your workflow. Use configurations wisely to create a development environment that feels like a natural extension of your thought process.

Next: MCP Integration

Extend Siya with powerful MCP servers

Explore Hooks

Create powerful workflow automations

Configure once. Work efficiently forever.

Your Siya, Your Way

​Configuration Overview

​Configuration Files

~/.siya/config.json

Core Settings

Developer Settings

Privacy Settings

Advanced Settings

~/.siya/siya-desktop-config.json

./siya.config.json

Project Context File

​Model Configuration

Choose Your AI Model

Claude Models

OpenAI Models

Google Models

Specialized Models

Run Models Locally

Hardware Acceleration

Memory Settings

​Tool Configuration

Power Up Your Tools

Safety Features

Performance

Integration

​MCP Server Configuration

Extend with MCP Servers

context7

stock-market

​Hooks Configuration

Automate Your Workflow

Commit Events

Branch Events

​Advanced Configuration

Fine-Tune Every Detail

Heap Settings

Cache Strategy

Access Control

Secrets Management

​Configuration Best Practices

Configuration Excellence

​Troubleshooting Configuration

​Summary

Configuration Mastery Achieved

Next: MCP Integration

Explore Hooks

Configuration Overview

Configuration Files

Model Configuration

Tool Configuration

MCP Server Configuration

Hooks Configuration

Advanced Configuration

Configuration Best Practices

Troubleshooting Configuration

Summary