README
¶
Compa is a personal AI assistant that runs on your computer. You chat with it in your browser, on WhatsApp or on Slack, pick the models it uses, and it works with files, runs commands and searches the web for you. "Compa" is Mexican Spanish slang for pal.
Install
Windows (PowerShell):
irm https://github.com/kayiik/compa/releases/latest/download/install.ps1 | iex
macOS and Linux:
curl -fsSL https://github.com/kayiik/compa/releases/latest/download/install.sh | sh
Compa runs on Windows 10 or later, macOS 12 or later and Linux. More in docs/install.md.
Your first chat
- The installer starts Compa, which opens its setup page in your browser. Set a password. If you closed the page, choose Open Console in Compa's tray menu.
- Go to Models. Press Try free providers, or connect a provider with an API key or a model server on your computer.
- Go to Chat and ask something.
What it does
- Tools: files in its workspace folder, shell commands, web search and web pages, scheduled jobs, MCP servers.
- Models: API-key providers such as OpenAI, Anthropic, Google Gemini, OpenRouter, Groq and Mistral AI; local servers such as Ollama, LM Studio and LocalAI; any OpenAI- or Anthropic-compatible endpoint; free keyless providers; and more through an extension app. A route tries a list of models in order until one answers.
- Voice: dictation and spoken replies, push-to-talk or hands-free.
- Chat apps: WhatsApp, as a linked device of your account, and a Slack bot. Compa answers only you. Slack and Teams webhooks receive its notifications.
- Compitas: agents that keep working beside Compa, each with its own workspace and chat, on this computer or on other machines you add. Off until you turn them on.
- Skills and modules: instructions for particular tasks, and programs that add capabilities.
- Private by default: settings, chats and keys stay in
~/.compa; messages go only to the model providers you choose. The web UI is password-protected and listens only on this computer unless you turn on LAN access. - The web UI is in English, Czech, Brazilian Portuguese, Simplified Chinese and Bengali.
Documentation
- Install: installers, updates, uninstalling, ports, LAN access, building from source.
- Use Compa: models, chat, tools, approvals, voice, chat apps, skills, modules.
- Compitas: agents that work beside Compa, on this computer or on other machines.
- Troubleshooting, privacy and security
- Command line
- Gateway interface, for programs that run the gateway.
- Embed the Go runtime
Contributing: CONTRIBUTING.md. Security reports: SECURITY.md. Changes: CHANGELOG.md.
License
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var OnboardWorkspace embed.FS
OnboardWorkspace embeds the default onboarding workspace template.
Keeping this embed at the module root lets us source files directly from the tracked `workspace/` tree, instead of relying on a generated copy inside `cmd/...` that may be absent in clean checkouts and CI lint runs.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
compa-kernel
command
Module lifecycle commands.
|
Module lifecycle commands. |
|
compa-kernel/internal/cliui
Package cliui renders human-oriented CLI output: bordered panels and columns on wide interactive terminals.
|
Package cliui renders human-oriented CLI output: bordered panels and columns on wide interactive terminals. |
|
compa-kernel/internal/evolution
Package evolution holds the `compa-kernel evolution` commands: the human review step for the skill drafts evolution writes.
|
Package evolution holds the `compa-kernel evolution` commands: the human review step for the skill drafts evolution writes. |
|
compa-kernel/internal/jsonout
Package jsonout lets a command print its result as one JSON document on stdout, for programs that run compa-kernel: the command's --json flag.
|
Package jsonout lets a command print its result as one JSON document on stdout, for programs that run compa-kernel: the command's --json flag. |
|
fakemodule
command
Command fakemodule is a deterministic module used to test the host's module boundary without involving a real module, a network, or a paid provider.
|
Command fakemodule is a deterministic module used to test the host's module boundary without involving a real module, a network, or a paid provider. |
|
genfixtures
command
Command genfixtures writes the canonical host-side protocol fixtures.
|
Command genfixtures writes the canonical host-side protocol fixtures. |
|
notices
command
Command notices writes the THIRD_PARTY_NOTICES file of a release archive: the license texts of the third-party code compiled into the programs given (Go modules and the Go standard library) and bundled into compa's web UI (npm packages), with where to get each one's source.
|
Command notices writes the THIRD_PARTY_NOTICES file of a release archive: the license texts of the third-party code compiled into the programs given (Go modules and the Go standard library) and bundled into compa's web UI (npm packages), with where to get each one's source. |
|
internal
|
|
|
module
Package module executes detached module processes on behalf of the host.
|
Package module executes detached module processes on behalf of the host. |
|
moduletools
Package moduletools adapts detached module capabilities into agent tools.
|
Package moduletools adapts detached module capabilities into agent tools. |
|
approval
Package approval is the one policy that decides each tool call: whether it runs, waits for an approval, is refused, or whether the tool is not offered to the agent at all.
|
Package approval is the one policy that decides each tool call: whether it runs, waits for an approval, is refused, or whether the tool is not offered to the agent at all. |
|
audio/voice
Package voice runs speech-to-text and text-to-speech for a voice target "instance-id/model-id" on the llmgw-core provider of the target's instance: transcription is an Invoke on the audio_transcriptions surface with the OpenAI multipart transcription body, synthesis one on audio_speech with the OpenAI speech JSON.
|
Package voice runs speech-to-text and text-to-speech for a voice target "instance-id/model-id" on the llmgw-core provider of the target's instance: transcription is an Invoke on the audio_transcriptions surface with the OpenAI multipart transcription body, synthesis one on audio_speech with the OpenAI speech JSON. |
|
channels/whatsapp
Package whatsapp is the WhatsApp channel: Compa as a linked device of a WhatsApp account (whatsmeow).
|
Package whatsapp is the WhatsApp channel: Compa as a linked device of a WhatsApp account (whatsmeow). |
|
compute
Package compute is the control-plane state for Compitas: the computes a Compa can run agents on, and the Compitas placed on them.
|
Package compute is the control-plane state for Compitas: the computes a Compa can run agents on, and the Compitas placed on them. |
|
config
Package config defines Compa's configuration and loads and saves it.
|
Package config defines Compa's configuration and loads and saves it. |
|
constants
Package constants provides shared constants across the codebase.
|
Package constants provides shared constants across the codebase. |
|
contractv2
Package contractv2 declares the identity of the frozen kayiik.module/v2 behavioural Target Contract and the exact-pin check that gates it.
|
Package contractv2 declares the identity of the frozen kayiik.module/v2 behavioural Target Contract and the exact-pin check that gates it. |
|
credential
Package credential resolves secret values in the config, such as channel tokens and tool API keys.
|
Package credential resolves secret values in the config, such as channel tokens and tool API keys. |
|
events
Package events provides the process-local runtime event bus used to observe Compa components without coupling them to agent-specific event envelopes.
|
Package events provides the process-local runtime event bus used to observe Compa components without coupling them to agent-specific event envelopes. |
|
fileutil
Package fileutil provides file manipulation utilities.
|
Package fileutil provides file manipulation utilities. |
|
identity
Package identity provides unified user identity utilities for Compa.
|
Package identity provides unified user identity utilities for Compa. |
|
modproto
Package modproto defines the Compa detached-module protocol: the wire contract between the host and locally installed module executables.
|
Package modproto defines the Compa detached-module protocol: the wire contract between the host and locally installed module executables. |
|
modprotov2
Package modprotov2 is the wire representation of the frozen kayiik.module/v2 behavioural contract.
|
Package modprotov2 is the wire representation of the frozen kayiik.module/v2 behavioural contract. |
|
pairing
Package pairing keeps the direct messages a channel received while its allow_from listed no account.
|
Package pairing keeps the direct messages a channel received while its allow_from listed no account. |
|
pathlink
Package pathlink resolves a filesystem path to its true location, following every kind of link the host supports.
|
Package pathlink resolves a filesystem path to its true location, following every kind of link the host supports. |
|
providers/common
Package common provides shared utilities used by multiple LLM provider implementations (openai_compat, azure, etc.).
|
Package common provides shared utilities used by multiple LLM provider implementations (openai_compat, azure, etc.). |
|
providers/coretransport
Package coretransport hands the surface requests Compa's chat client makes to an llmgw-core provider.
|
Package coretransport hands the surface requests Compa's chat client makes to an llmgw-core provider. |
|
session/history
Package history reads the web chat's sessions from a workspace's session store: the list of sessions and each one's transcript, as the launcher's /api/sessions and the gateway's /web/sessions serve them.
|
Package history reads the web chat's sessions from a workspace's session store: the list of sessions and each one's transcript, as the launcher's /api/sessions and the gateway's /web/sessions serve them. |
|
updater
Package updater installs releases of Compa published on github.com/kayiik/compa.
|
Package updater installs releases of Compa published on github.com/kayiik/compa. |
|
updater/updatertest
Package updatertest serves fake GitHub releases of kayiik/compa, shaped like the ones the release workflow publishes, for tests of the updater and of the endpoints built on it.
|
Package updatertest serves fake GitHub releases of kayiik/compa, shaped like the ones the release workflow publishes, for tests of the updater and of the endpoints built on it. |
|
utils
Package utils provides shared, reusable algorithms.
|
Package utils provides shared, reusable algorithms. |
|
view
Package view defines shared declarative product-view definitions and rendering primitives for Compa and its consumer products.
|
Package view defines shared declarative product-view definitions and rendering primitives for Compa and its consumer products. |
|
web
|
|
|
backend
command
|
|
|
backend/dashboardauth
Package dashboardauth provides a bcrypt-backed SQLite store for the launcher dashboard password.
|
Package dashboardauth provides a bcrypt-backed SQLite store for the launcher dashboard password. |
Click to show internal directories.
Click to hide internal directories.