Costa OS User Guide

Installation

This guide walks you through the entire process from downloading Costa OS to landing on a working desktop. No Linux experience is required.

1. Welcome to Costa OS

What Is Costa OS?

Costa OS is a Linux distribution built on Arch Linux and the Hyprland Wayland compositor. Claude Code ships with full system access, so instead of memorizing commands, hunting through settings panels, or reading man pages, you describe what you want (by voice, by typing, or through keybinds) and the system does it. It knows your hardware, your running processes, your configs, and your project contexts.

Under the hood, Costa OS is a fully-featured Arch Linux installation with a tiling window manager, a curated set of development tools, and a custom Mediterranean-inspired theme called “Costa.” What makes it different is that Claude Code and local models are connected to every component. The clipboard watches what you copy and offers to debug errors. The screenshot tool analyzes images on capture. The music player, window manager, notification system, and status bar all feed into the same routing system.

Costa OS is powered by Claude Code in combination with a local model running on your GPU. Claude Code ships with full system access and handles complex tasks like code generation, debugging, system management, and multi-step workflows. The local model handles routine queries (system status, quick lookups, simple commands) with instant responses and no internet needed. Routing between them is automatic. When cloud models are used, your queries go directly to Anthropic. Costa OS has no servers in the middle, no telemetry, no analytics, and no accounts.

Philosophy

Costa OS is built on three principles:

1. Describe what you want, the system does it. Traditional operating systems force you to learn their language: command flags, config file syntax, menu hierarchies. Costa OS lets you skip that. Want to install a program? Say “install Blender.” Want to change a keybind? Say “bind Super+G to open GIMP.” Want to know why your build is slow? Ask, and the system checks your CPU load, running containers, swap usage, and compiler flags before answering.

2. Claude Code at the center, local models for speed. Claude Code is the primary intelligence. It can modify any config, install any package, write any script, and navigate graphical applications on your behalf. Local models running on your GPU handle routine queries with sub-second latency and zero internet dependency. The two work together: local for fast, everyday tasks; Claude for anything that requires real reasoning. Your data stays private regardless. Costa OS has no servers, no telemetry, and no accounts.

3. Maximum customization, zero gatekeeping. Costa OS is your machine. Every config file is documented, every tool is replaceable, and the entire codebase is open source under the Apache License 2.0. The AI makes customization effortless for beginners, and the underlying Arch Linux foundation means power users can go as deep as they want.

What Makes It Different

Most Linux distributions hand you a desktop and leave you to figure out the rest. Costa OS is different in several concrete ways:

• Claude Code is your system administrator. It ships as a first-class citizen with full system access, 30+ MCP tools, and a hardware-aware context file generated at first boot. It can modify any config, install any package, create any script, navigate graphical applications, and debug problems end-to-end.
• Your system context is always live. Every query is enriched with live data: running processes, GPU utilization, disk space, network state, audio routing, window layout. When a query is answered, it answers about your machine, not a generic one.
• Two tiers work together. Claude Code handles complex tasks: code generation, multi-file edits, architecture, debugging. Local models on your GPU handle routine queries with sub-second latency and zero internet dependency. Routing between them is automatic.
• Every component is connected. Copy an error message and the clipboard service offers to debug it with Claude. Take a screenshot and Claude reads and analyzes it. The voice assistant transcribes speech in 500 milliseconds. The desktop shell shows AI status, usage metrics, and processing indicators.
• It is still Arch Linux. Underneath all of this, this is a standard Arch installation. pacman works. systemctl works. You have full root access. Nothing is locked down, hidden, or “simplified” by removing functionality. Claude Code is an addition, not a restriction.

2. Getting Started

First Boot: What to Expect

When you boot the Costa OS ISO for the first time, you will see a graphical installer. This is a GTK4 application that walks you through disk partitioning, user account creation, and initial configuration. No terminal is required during installation.

After installation and reboot, the system runs a first-boot wizard that:

1. Sets up Claude Code: prompts you to authenticate with your Anthropic account (Claude Pro, Max, or API key).
2. Detects your GPU and installs the appropriate drivers (AMD, NVIDIA, or Intel)
3. Detects your monitors and generates a multi-monitor desktop shell layout
4. Generates a hardware-aware CLAUDE.md so Claude Code knows your exact setup
5. Detects optional hardware (IR camera for face auth, touchscreen for gestures)
6. Pulls the best local language model your GPU can handle from Ollama (for fast, offline queries)
7. Builds Whisper.cpp with GPU acceleration for voice transcription
8. Optionally sets up face authentication and touchscreen gestures

The full process takes a few minutes depending on your internet speed and GPU. When it finishes, you land on a fully configured desktop with the Costa theme, the hover-reveal shell on every monitor, a macOS-style dock, and both Claude Code and the local AI assistant ready to use.

The Installer Wizard

The ISO boots directly into a GTK4 graphical installer called costa-install-gui. It supports three partition modes:

The installer handles all of the low-level work: formatting, mounting, pacstrap, bootloader installation, and initial configuration. When it finishes, you remove the USB drive and reboot into your new system.

Your First Five Minutes

After the first-boot wizard completes, here is what to do:

1. Open a terminal. Press SUPER+Enter. This launches Ghostty, the GPU-accelerated terminal, pre-configured with the Costa theme and JetBrains Mono Nerd Font.
2. Open the app launcher. Press SUPER+Space. This opens Rofi, a fuzzy-search launcher. Start typing the name of any application and press Enter to launch it.
3. Try the assistant. In the terminal, type: costa-ai "what GPU do I have". The system will check your actual hardware and respond with the model name, driver version, and VRAM amount. This is a local query that never touches the internet.
4. Try voice input. Hold SUPER+ALT+V and speak a question. Release when you finish speaking. The audio is transcribed locally by Whisper, then sent to the router for a response.
5. Move between workspaces. Press SUPER+1 through SUPER+4 to switch between the four main workspaces on your primary monitor.
6. Open the settings hub. Press SUPER+I or click the gear icon in the desktop shell.

Essential Keybinds

These are the keybinds you will use most often. Costa OS uses vim-style navigation with the SUPER key as the primary modifier.

Applications

Window Focus and Movement

Window States

Workspaces

Voice and Commands

Media and Utilities

If you ever forget a keybind, ask: costa-ai "what is the keybind for fullscreen" or use the keybind configurator: costa-keybinds list.

Where Things Live

You do not need to memorize these paths. Claude Code knows all of them, and you can always ask: costa-ai "where is the shell config".

3. The AI Assistant

The assistant is built into every part of the system. It is not a chatbot bolted onto the side. It is deeply integrated into every part of the system, with access to live system state, 30+ structured tools, and the ability to execute safe commands automatically.

Three Ways to Interact

There are three input methods, and they all feed into the same intelligence layer:

1. Terminal (CLI)

The costa-ai command lets you ask questions and give commands directly from any terminal:

costa-ai "what services are using the most memory"
costa-ai "install htop"
costa-ai "why is my fan running so loud"
costa-ai "write me a Python HTTP server"

This is the most versatile method. It supports flags for JSON output, history browsing, usage stats, and more.

2. Voice (Push-to-Talk)

Hold SUPER+ALT+V and speak your question or command naturally. Release when you are done talking. The system records your audio, reduces background noise with DeepFilterNet, detects when you stop speaking with Silero VAD, transcribes your speech with Whisper on your GPU, and sends the text to the AI. The entire pipeline runs locally.

There is also a Type mode (SUPER+ALT+B) that transcribes your speech and types the resulting text directly into whatever window is focused, useful for dictation into text fields, documents, or chat apps.

3. Shell Widget (Text Input)

Left-click the Costa icon in the center of the desktop shell to open a Rofi text input box. Type your question and press Enter. Right-click the Costa icon to see the full text of the last response.

What It Can Do

The assistant is not limited to answering questions. It can take actions on your system, and it knows the difference between safe and dangerous operations.

Information queries: The system gathers live data before answering:

costa-ai "what is using my GPU right now"      # checks GPU utilization
costa-ai "is Docker running"                    # checks systemctl and docker ps
costa-ai "what Python packages are installed"   # queries pacman
costa-ai "what is my IP address"                # checks ip addr and curl ifconfig.me

System actions: Safe commands execute automatically:

costa-ai "turn up the volume to 80%"           # runs wpctl
costa-ai "skip this track"                      # runs playerctl
costa-ai "switch to workspace 3"                # runs hyprctl
costa-ai "set brightness to 50%"                # runs brightnessctl

Ask-first actions: Potentially destructive commands require your confirmation:

costa-ai "install Blender"                      # shows command, asks before running
costa-ai "restart the Ollama service"            # shows command, asks first
costa-ai "change my terminal font to Fira Code"  # shows config change, asks before applying

Blocked actions: Commands involving rm -rf, dd, mkfs, shutdown, and similar destructive operations are always flagged. The system will explain what the command would do and ask you to run it yourself.

Web-augmented queries: When local models cannot answer:

costa-ai "what is the latest Linux kernel version"
costa-ai "what is the weather in Boston"         # fetches from wttr.in
costa-ai "who won the game last night"

Code generation: Complex coding questions route to Claude Sonnet:

costa-ai "write a Rust function that parses CSV files"
costa-ai "debug this Python traceback: [paste error]"
costa-ai "explain what this regex does: ^(?:(?:25[0-5]|...))"

How Model Routing Works

When you ask a question, the router analyzes your query and picks the best model to answer it. You never need to think about this. It happens automatically.

Local models run on your GPU and process queries without any internet connection:

Cloud models are used when the local model cannot answer:

Auto-escalation is the key feature. If the local model responds with “I don't know” or similar uncertainty phrases, the router automatically re-sends your query to Claude Haiku with web search capability. You do not need to retry or specify a different model.

Neural Routing (ML Router)

Behind the pattern matching, Costa OS uses a lightweight PyTorch neural network to learn which model handles which queries best. This is a 3-layer MLP classifier (Input→64→32→7 classes) that runs in under 1ms on CPU.

How it works:

1. Your query is converted into a 29-dimension feature vector: query length, word count, question mark presence, action/code/web keyword detection, time of day, current VRAM tier, and 21 topic-pattern match flags.
2. The neural network predicts one of 7 route classes: local, local_will_escalate, haiku+web, sonnet, opus, file_search, or window_manager.
3. If confidence exceeds 65%, the ML prediction is used. Otherwise, the system falls back to regex pattern matching.
4. The model auto-retrains every 50 queries in the background, incorporating your real usage data (weighted 3x higher than synthetic training samples) alongside ~300+ synthetic labeled examples.

python3 ai-router/ml_router.py train              # generate data + train
python3 ai-router/ml_router.py eval               # train + evaluate + print report
python3 ai-router/ml_router.py predict "query"    # test prediction for a query

The trained model is saved to ~/.config/costa/ml_router.pt. It is small (a few KB) and loads instantly. If no trained model exists, the system falls back gracefully to regex-only routing.

Self-improving routing: Every query is logged with model used, escalation status, and timing. When you report a bad answer, the routing decision is marked incorrect. This feedback trains the next cycle, so the neural router learns from your corrections over time.

You can override routing when needed:

costa-ai --no-escalate "quick question"        # force local only
costa-ai --model opus "architecture review"     # force a specific cloud model
costa-ai --preset code "refactor this function"  # bias toward code routing
costa-ai --preset fast "what time is it"        # bias toward speed

The Costa Widget

The Costa widget in the desktop shell is the visual control center for the assistant.

Reporting Bad Answers

When you get a wrong answer, click the report icon in the desktop shell. This triggers a dual correction loop:

1. The failed query and response are sent to Claude Haiku, which identifies the problem and generates a knowledge file patch.
2. The patch is applied automatically to ~/.config/costa/knowledge/, so the local model has better reference material next time.
3. The routing decision is marked as incorrect in the database, feeding into the neural router's next training cycle so queries get sent to the right model.
4. A notification shows the corrected answer.

This means both the knowledge base and the routing classifier improve from every correction. The local model literally gets smarter over time.

costa-ai-report corrections    # review all corrections

Voice Push-to-Talk

The pipeline: hold key → DeepFilterNet noise reduction → Silero VAD auto-stop → Whisper GPU transcription (~500ms) → AI router → response in the desktop shell + Dunst notification.

Say “draft” or “hold” to review transcription before auto-submit.

Usage Tracking and Budgets

Every query is logged to a local SQLite database with model, latency, token counts, and cost estimates. Nothing is sent anywhere.

costa-ai --history                 # browse past queries
costa-ai --search "docker"         # full-text search history
costa-ai --usage                   # usage statistics
costa-ai --budget 5.00             # set daily spending limit
costa-ai --budget 30.00 month      # monthly cap

4. Desktop and Window Management

Costa OS uses Hyprland, a modern Wayland tiling compositor. Windows automatically arrange themselves to fill the screen, and you move between them with keyboard shortcuts.

Understanding Workspaces

Moving Windows

Or with natural language:

costa-ai "move firefox to the top monitor"
costa-ai "put the terminal on workspace 2"
costa-ai "tile the editor and terminal side by side"

Tiling, Floating, and Fullscreen

Tiled (default). Windows automatically arrange themselves. Floating: Detached from tiling, freely positioned (SUPER+SHIFT+F). Fullscreen: Takes the entire screen (SUPER+F).

To move or resize a floating window with the mouse, hold SUPER and drag with left (move) or right (resize) mouse button.

Natural Language Window Commands

costa-ai "move firefox to workspace 3"
costa-ai "put the terminal on the left monitor"
costa-ai "make VS Code fullscreen"
costa-ai "float the file manager"
costa-ai "close all terminals"

Multi-Monitor Setup

Costa OS auto-detects monitors during first boot. If you add or remove monitors later, open Settings Hub (SUPER+I) → Display → “Detect Monitors.”

Each monitor gets an appropriate shell layout: primary gets the full notch bar with all widgets, secondary monitors get a minimal status pill, and portrait monitors get a compact vertical bar.

Manual config in ~/.config/hypr/hyprland.conf:

monitor = DP-1, 2560x1440@165, 0x0, 1
monitor = HDMI-A-1, 1280x720, -720x0, 1, transform, 1
monitor = HDMI-A-2, 1920x1080@60, 320x-1080, 1

Window Rules

Rules go in ~/.config/hypr/hyprland.conf:

windowrule = float, class:^(rofi|pavucontrol)$
windowrule = opacity 0.9, class:^(ghostty)$
windowrule = workspace 2, class:^(firefox)$

Find window class names: hyprctl clients -j | jq '.[].class'

5. Development Environment

Pre-Installed Tools Overview

Language Managers

# Python (pyenv)
pyenv install 3.12 && pyenv global 3.12

# Node.js (nvm)
nvm install 24 && nvm alias default 24

# Java (SDKMAN)
sdk install java 21-open && sdk default java 21-open

# Rust (rustup)
rustup update && rustup default stable

Containers

docker compose up -d            # start services
lazydocker                      # TUI for Docker
k9s                             # TUI for Kubernetes

Claude Code Integration

Claude Code is a first-class citizen on Costa OS with deep system integration.

Custom slash commands: /check-system, /configure-shell, /install, /theme, /troubleshoot

MCP server: 30+ tools via the Costa OS MCP server for reading processes, managing windows, controlling media, taking screenshots, and reading/writing files.

Virtual monitor: Claude Code operates on an invisible headless monitor (HEADLESS-2, workspace 7, 1920x1080). It uses a proprietary MCP navigation system under development for screen reading, which is 112x cheaper in tokens than screenshot-based approaches.

Terminal: Ghostty and Zellij

Ghostty is GPU-accelerated and pre-configured with the Costa theme. Config: ~/.config/ghostty/config. Close and reopen to apply changes.

Zellij shortcuts: Ctrl+T (new tab), Ctrl+N (new pane), Ctrl+P (pane mode), Ctrl+O (session mode).

Git Workflow

Delta pager shows side-by-side diffs with syntax highlighting. lazygit for visual Git TUI. GitHub CLI (gh) for PRs, issues, and repos. SSH key at ~/.ssh/id_ed25519.

6. Customization

The Costa Theme

System-wide GTK theme: adw-gtk3-dark, icons: Papirus-Dark, cursor: Bibata-Modern-Ice, font: JetBrains Mono Nerd Font.

Changing the Wallpaper

Through Settings Hub (SUPER+I) → Display → Wallpaper. Costa OS ships with static Costa-themed wallpapers. Also supports videos (mpvpaper) and Wallpaper Engine scenes.

swww img /path/to/image.jpg               # static wallpaper
mpvpaper '*' /path/to/video.mp4 --fork    # video wallpaper

Video wallpapers include a smart pause feature: animation auto-pauses when windows cover >37.5% of the desktop.

Shell Widgets and Layout

The desktop shell is a hover-reveal glassmorphic bar built with AGS (Aylur's GTK Shell). Widgets include workspaces, git status, now playing, audio controls, PTT voice status, clock, and power menu. The shell config is TypeScript/TSX in ~/.config/ags/.

Or ask: costa-ai "add a CPU temperature widget to the shell"

Adding Keybinds

GUI: Click the keybind icon in the desktop shell, or run costa-keybinds-gui. Record key combos, detect conflicts, discover mouse buttons.

CLI:

costa-keybinds list
costa-keybinds add "SUPER" "F1" "exec" "firefox"
costa-keybinds remove "SUPER" "F1"

Manual: Edit ~/.config/hypr/hyprland.conf. Bind types: bind (single press), binde (repeats while held), bindm (mouse), bindl (works when locked), bindr (on release).

Changing Default Applications

Edit variables at the top of ~/.config/hypr/hyprland.conf:

$terminal = ghostty
$fileManager = thunar
$menu = rofi -show drun
$browser = firefox

xdg-settings set default-web-browser firefox.desktop
xdg-mime default thunar.desktop inode/directory

7. Music and Media

The Music Widget

A custom floating widget that controls any MPRIS-compatible player. Click the music icon in the desktop shell or run costa-music-widget.

Player Controls and Keybinds

Now-playing widget: left-click opens the music widget, middle-click play/pause, right-click next, scroll to seek.

Volume and Audio Output

wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.5       # set to 50%
wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+        # increase by 5%
wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle       # mute/unmute
pactl set-default-sink SINK_NAME                 # switch output device

For visual audio routing, use qpwgraph (GUI) or pavucontrol (mixer).

8. System Administration

Installing Packages

The easiest way: costa-ai "install Blender"

sudo pacman -S blender          # official repos
yay -S spotify-launcher         # AUR
pacman -Ss keyword              # search
sudo pacman -Rns package        # remove with deps

System Updates (costa-update)

Costa OS ships with an AI-assisted updater that pulls directly from the GitHub repo. It never pings or connects to Synoros servers. Run it on demand:

costa-update                    # AI-assisted update: pulls from GitHub,
                                # Claude reviews changes, fixes breakage
costa-update --check            # check for available updates without applying
costa-update --version          # show current version

How it works: costa-update fetches the latest release from GitHub, diffs it against your installed version, and hands the changelog to Claude. Claude reviews every change, applies it, and if anything breaks, rolls back and fixes the issue. You can also check your current version in the Settings Hub.

For manual package updates (not Costa OS-specific):

yay -Syu                        # update all system packages
sudo pacman -Rns $(pacman -Qtdq)  # remove orphans
paccache -rk2                   # clear package cache

Managing Services

systemctl status ollama                    # check status
sudo systemctl restart ollama              # restart
systemctl --user status costa-clipboard    # user-level service
journalctl -u ollama -f                    # follow live logs

Audio Configuration (PipeWire)

wpctl status                              # full audio graph
pw-top                                    # real-time audio activity
qpwgraph                                  # GUI graph editor
systemctl --user restart pipewire pipewire-pulse wireplumber  # restart audio

Network and WiFi

nmcli device wifi list                     # list networks
nmcli device wifi connect "MyNetwork" password "MyPassword"
nmtui                                      # interactive TUI
bandwhich                                  # live bandwidth monitor

Bluetooth

bluetoothctl power on
bluetoothctl scan on
bluetoothctl pair XX:XX:XX:XX:XX:XX
bluetoothctl trust XX:XX:XX:XX:XX:XX
bluetoothctl connect XX:XX:XX:XX:XX:XX

USB Drives and External Storage

USB drives auto-mount via udisks2 at /run/media/$USER/DRIVELABEL.

lsblk -f                                  # list drives with filesystems
udisksctl mount -b /dev/sdb1              # mount manually
udisksctl unmount -b /dev/sdb1            # safe eject

Display and Brightness

brightnessctl set 50%                      # set brightness
gammastep -O 4500                          # warm color temperature
hyprctl monitors                           # list monitors

Notifications

notify-send "Hello" "Test notification"    # send test
dunstctl close-all                         # dismiss all
dunstctl set-paused toggle                 # Do Not Disturb

9. Advanced Features

VRAM Manager

A background service that automatically keeps the best language model loaded in your GPU memory. Checks total VRAM, subtracts other apps and a 2GB headroom buffer, loads the largest model that fits.

cat /tmp/ollama-smart-model                # currently loaded model
cat /tmp/ollama-tier                       # current tier
ollama ps                                  # loaded models and VRAM usage

Workflows (costa-flow)

Automated multi-step tasks defined in YAML. Run shell commands, query the local model, branch on conditions, schedule on timers.

costa-flow list                            # list workflows
costa-flow run system-health               # run a workflow
costa-flow status                          # check running workflows

Built-in workflows: system-health, smart-update, backup-check, cleanup, docker-watch, morning-briefing, security-scan, log-digest, ollama-model-update, project-standup.

Create custom workflows in ~/.config/costa/workflows/ as YAML files with steps (shell, ai, condition) and optional cron schedule.

Project Management

Switch your entire workspace context with a single command:

costa-ai "switch to PARAGON"               # by name (fuzzy matching works)

This switches workspace, launches apps in configured positions, sets env vars, and runs setup commands. Create project configs in ~/.config/costa/projects/ as YAML.

AI Agents

Specialized personas with focused expertise and specific tool access. You or Claude choose the agent based on the task. The router picks the best model automatically: cloud for complex tasks, local when capable.

costa-agents run sysadmin "check disk usage"
costa-agents run architect "review the database schema"
costa-agents list                          # show all agents
costa-agents queue                         # show running tasks

Clipboard Intelligence

A background service that watches what you copy, classifies the content (errors, URLs, JSON, commands, code, file paths), and shows a notification with contextual actions.

Press SUPER+V for clipboard history in Rofi.

Screenshot AI

Face Authentication

Windows Hello-style face unlock using Howdy with your IR camera. Works at login (greetd), sudo, and screen lock (hyprlock). Password always works as fallback.

sudo howdy add                             # enroll face
sudo howdy test                            # test recognition
sudo howdy list                            # list enrolled models

Touchscreen Support

Auto-detected. Uses squeekboard (on-screen keyboard), hyprgrass (gestures), and libinput. 3-finger swipes for workspace navigation, app launcher, and window close.

Settings Hub

Central GTK4 application for all configuration. Open via SUPER+I, the gear icon in the desktop shell, or costa-settings. Sections: Display, Security, Input, AI Assistant, Development, System.

AI Navigation (costa-nav)

A proprietary MCP navigation system under development that lets Claude Code interact with graphical applications without taking screenshots. 112x cheaper in tokens than screenshot-based approaches.

MCP Servers

Costa OS ships with 6 MCP servers pre-configured for Claude Code:

Workflow Commands

Custom Claude Code slash commands ship with Costa OS for structured development workflows:

Document RAG

Index your own documents so the system can search and reference them:

costa-ai --index ~/projects/myapp/docs     # index a directory
costa-ai --index ~/notes                   # index personal notes

10. Troubleshooting

Common Issues and Fixes

# Hyprland config errors
hyprctl configerrors && hyprctl reload

# GPU not detected
source ~/.config/costa/gpu.conf && echo $GPU_NAME
lspci | grep VGA

# Audio issues
wpctl status
systemctl --user restart pipewire pipewire-pulse wireplumber

# Ollama not responding
systemctl restart ollama && ollama ps

# App won't close
hyprctl dispatch killactive
pkill -f processname

Where to Find Logs

How to Reset Configs

# Reset a specific component
cp /usr/share/costa/configs/hyprland.conf ~/.config/hypr/hyprland.conf
hyprctl reload

# Re-run first-boot setup
costa-firstboot --reconfigure

# Nuclear option (reset all Costa configs)
rm -rf ~/.config/costa/
costa-firstboot --reconfigure

Getting Help

Ask Claude Code: costa-ai "why is my fan running so loud". Or by voice: hold SUPER+ALT+V and describe your problem.

• GitHub: github.com/superninjv/costa-os
• Arch Wiki, the definitive Arch Linux resource
• Hyprland Wiki, compositor configuration reference

11. Privacy and Security

Data Collection Policy

Costa OS collects nothing. No analytics, no telemetry, no crash reports, no usage data. There are no accounts, no registration, and no Costa OS servers. The OS never phones home.

Where Your Data Lives

You can delete any of this data at any time. rm -rf ~/.config/costa/ removes everything Costa-specific.

API Key Management

API keys are stored locally in ~/.config/costa/env with restrictive permissions. They are sent directly from your machine to the provider's API. Never proxied through any Costa OS server.

Costa OS also works with Claude Pro/Max subscription tokens, no separate API billing required.

Face Auth Security

Howdy is a convenience feature, not a security-grade biometric system. It can be fooled by photos with regular webcams. IR cameras are significantly harder to spoof. Password is always the security baseline.

Voice Assistant Privacy

1. Recording: Only while you hold the push-to-talk key. No always-on listening.
2. Processing: DeepFilterNet + Whisper run locally on your hardware.
3. Deletion: Audio deleted immediately after transcription. Never uploaded.
4. Transcription: Text goes to local Ollama. Only text (never audio) sent to cloud if escalation triggers.

Network Connections Costa OS Makes

That is the complete list. There is no background telemetry, no analytics beacon, no heartbeat ping. There are no Costa OS servers.

12. Contributing

How to Contribute

Costa OS is open source under the Apache License 2.0. The repository is at github.com/superninjv/costa-os.

Development is managed by the Costa OS team. External contributions are not accepted via pull requests at this time. However, there are ways to help:

• Report bugs: File an issue on GitHub with steps to reproduce
• Suggest features: Open a feature request issue
• Test on hardware: Report compatibility results for different GPUs, monitors, and peripherals

The codebase is open source so you can read, fork, and learn from it, but the canonical repository is maintained exclusively by the team.

Project Structure

costa-os/
  ai-router/          Core intelligence layer
  packages/           Package lists by category
  configs/            Default config templates with Costa theme
  voice-assistant/    Push-to-talk voice assistant source
  scripts/            Automation and utility scripts
  branding/           Logo, wallpapers, boot splash images
  docs/               User guide, architecture docs, privacy policy
  knowledge/          Knowledge base files (shipped, injected into LLM)
  mcp-server/         Claude Code MCP server (system tools, screen reading)

Getting the Source

The Costa OS intelligence layer is open source:

git clone https://github.com/superninjv/costa-os.git

This gives you the router, knowledge base, MCP server, configs, and voice assistant source. You can use these components on any existing Arch Linux + Hyprland setup.

The installer and ISO are distributed as a download from synoros.io/costa-os.

Filing Issues

Include: what you expected, what actually happened, steps to reproduce, system info (GPU, monitors, package versions), and relevant logs. For AI-related issues, also include the query, model used, response received, and what the correct response should have been.