Operance

Operance

Turn intent into action.

Operance is a local-first AI desktop action layer that lets you control your computer with natural language. Speak or type what you want, and Operance turns that intent into safe, typed desktop actions before anything runs.

The current public beta is Fedora KDE Plasma Wayland first and uses a tray-first click-to-talk workflow. It is ready for outside developers and early adopters to install, test, report issues, and help extend.

Today, Operance can open apps and websites, focus or quit apps with confirmation, list recent files, list or search known folders by file name, show basic file metadata, manage Desktop files or folders with confirmation, list, find, or switch windows, answer desktop-status questions, and control basic audio state. It also supports safe JSON desktop skill packs for adding exact phrase shortcuts that emit existing typed actions without changing the portable core.

The tray and verified commands work without an AI model. A local OpenAI-compatible model, such as an Ollama-served Qwen model, can be enabled as a bounded planner fallback after operance --planner-readiness reports it is safe to enable. Model output is still constrained to Operance's typed action schema and goes through validation, policy, and confirmation gates.

For developers, Operance is also built to be extended. Under the hood, it has a shared portable core, per-platform providers and adapters, and an MCP-compatible control surface. The current delivery scope stays Linux-first while keeping the core portable for later Windows and macOS adapters.

Platform roadmap:

• Phase 1: Linux/KDE/Wayland
• Phase 2: Windows
• Phase 3: macOS

The implementation stays Linux-first today. The portable core remains shared across platforms, including the voice pipeline orchestration, planner, typed action schema, safety model, and MCP server, while platform providers own host-specific readiness, setup workflow, and release-verification rules and OS-specific execution or input translation stays behind per-platform adapters. That keeps the current delivery scope simple without closing off the later Windows and macOS paths.

Windows and macOS provider scaffolds exist for adapter authors, but they are intentionally unverified and block live desktop commands until native adapters are implemented.

Public Beta Quickstart

Use the packaged Fedora RPM for the public beta experience. From the current GitHub release, run the setup script against that release's asset URL:

curl -fsSLO https://github.com/raunakkathuria/operance/releases/download//setup.sh
bash ./setup.sh --release-url https://github.com/raunakkathuria/operance/releases/download/
operance --version
operance --installed-smoke
operance --public-beta-checklist
operance --beta-feedback

If you already downloaded the RPM from the same release, the stable local package setup path is:

bash ./setup.sh --package ./operance-0.1.0-1.noarch.rpm
operance --version
operance --installed-smoke
operance --public-beta-checklist
operance --beta-feedback

operance --installed-smoke, operance --public-beta-checklist, and tray Setup and status now include one explicit next action. When the install is ready, the next action is to click the tray icon once and say open browser.

Then click the tray icon and say:

open browser
open the browser
open google.com
go to google.com
search google for linux automation
search the web for linux automation
open firefox
open downloads
open folder downloads
list files in downloads
find file named notes.txt
search documents for invoice
show details for notes.txt
show recent downloads
open the first one
what can I say
what did you hear
are you listening
is local AI ready
why did that fail
what apps are open
is firefox open
switch to it
switch to firefox window
what time is it
wifi status
what is the volume
set volume to 50 percent

If anything fails, collect a support bundle before changing the machine:

operance --support-bundle

The bundle includes issue-report.md, a redacted paste-ready GitHub issue draft. If you only need the draft without creating an archive, run:

operance --issue-report

For one combined install, verify, try, and report checklist, run:

operance --public-beta-checklist
operance --beta-feedback

The tray menu exposes Setup and status, Try commands, Beta feedback guide, Supported commands, Report an issue, optional always-on listening controls, recent interaction details, and release update checks. Detailed diagnostics such as planner readiness, installed-smoke output, and raw support snapshots remain available from the CLI and the setup/status flow instead of crowding the default tray menu.

The release artifact set includes setup.sh beside the RPM, checksums, and manifest. The repo-local copy lives at scripts/setup.sh. --release-url downloads the manifest, checksums, setup script, and RPM from the same release asset base URL, verifies SHA256SUMS, then runs the same install, tray startup, installed-smoke, command catalog, and support-bundle flow as --package.

Use [docs/release/public-beta.md](docs/release/public-beta.md) for the public beta install, local AI planner, release artifact, and feedback path.

The repository also includes a static public landing page at [site/index.html](site/index.html). It explains Operance for new users and links back to GitHub-rendered canonical Markdown docs for developer details. The site build entrypoint is ./scripts/build_site.sh, which writes a self-contained artifact to dist/pages/ by copying the shared brand icon into the deployment root. The Cloudflare Workers Static Assets deployment is configured in wrangler.toml: use ./scripts/build_site.sh as the build command and npx wrangler deploy as the deploy command.

Developer Quickstart

Use this path when developing Operance itself from a source checkout:

./scripts/install_linux_dev.sh --ui --voice
.venv/bin/python -m operance.cli --version
.venv/bin/python -m operance.cli --about
.venv/bin/python -m operance.cli --check-updates
.venv/bin/python -m operance.cli --doctor
.venv/bin/python -m operance.cli --getting-started
.venv/bin/python -m operance.cli --supported-commands --supported-commands-available-only
.venv/bin/python -m operance.cli --skills
./scripts/run_mvp.sh
./scripts/run_checkout_smoke.sh

Try a few live commands from the verified subset:

OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "what time is it"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "what is my battery level"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "wifi status"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "open firefox"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "open localhost:3000"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "show recent files"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "what can I say"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "is local AI ready"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "list windows"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "switch to window firefox"
OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "set volume to 50 percent"

If the MVP path fails or you need to file a bug, collect the current issue artifact with:

.venv/bin/python -m operance.cli --support-bundle

That archive includes a generated issue-report.md draft. For a quick paste-only draft from a source checkout, use:

.venv/bin/python -m operance.cli --issue-report

For release-readiness work, use the repository gate that combines tests, branding guard, source-checkout smoke, reset-aware Fedora package gate dry-run, and the installed desktop smoke checklist. The gate also runs controlled live command smoke against a temporary desktop fixture, so file-command verification does not touch your real Desktop directory:

./scripts/run_release_readiness_gate.sh

Before tagging a packaged release candidate on Fedora KDE, run the packaged evidence gate from the same checkout. It rebuilds the mvp RPM, verifies the artifact, installs it with stale user-service reset, runs installed desktop smoke, captures a support bundle from the installed command, and then prints the manual tray click-to-talk checks that still require your active desktop session:

./scripts/run_package_evidence_gate.sh

Current assumptions for that path:

• Linux
• KDE Plasma on Wayland
• local source checkout
• optional voice and UI extras installed when you want the tray and click-to-talk path

Current Public Position

Operance is ready for a Fedora KDE Wayland public beta for outside developers and early adopters. It is not yet a broad public desktop release.

• Recommended public beta path: Fedora RPM install of the mvp runtime profile through setup.sh
• Developer/source path: source checkout with ./scripts/install_linux_dev.sh --ui --voice, .venv/bin/python -m operance.cli --doctor, ./scripts/run_mvp.sh, and ./scripts/run_checkout_smoke.sh
• Default interaction: tray plus click-to-talk
• Optional always-on listening: the tray can start or stop the voice-loop service when the voice runtime is configured
• The supported Fedora package path now vendors the tray UI and STT runtime dependencies needed for the MVP tray plus click-to-talk path
• First installed-package diagnostic: operance --installed-smoke
• Public beta install, verify, try, and report checklist: operance --public-beta-checklist
• 10-minute beta feedback loop: operance --beta-feedback
• First-run activation diagnostic: operance --getting-started
• Explicit release-channel check: operance --check-updates
• Product-facing local AI setup guide: operance --local-ai-coach
• Local AI planner status check: operance --planner-status
• Paste-ready feedback draft: operance --issue-report
• Stable packaged setup entrypoint: ./scripts/setup.sh --package ./operance-0.1.0-1.noarch.rpm
• Release-asset setup entrypoint: ./setup.sh --release-url https://github.com/raunakkathuria/operance/releases/download/
• Tray-first onboarding: setup/status, try commands, beta feedback guide,

supported commands, issue reporting, recent interaction details, update checks, and optional always-on listening controls are available from the tray menu

• First-run next action: installed smoke, public beta checklist, and tray

setup/status lead with the next user action, such as clicking the tray icon and saying open browser when the package is ready

• Public beta distribution guide: [docs/release/public-beta.md](docs/release/public-beta.md)
• Packaged release-candidate evidence gate: ./scripts/run_package_evidence_gate.sh
• Wake-word and TTS assets remain optional and are not part of the packaged support contract; spoken response text is available even when TTS audio is not configured
• Windows and macOS are architecture targets only; their current providers are scaffolds, not supported runtimes

Always-on listening is optional and experimental unless a model-backed wake-word asset is configured. For the current beta, the most reliable path is still click-to-talk. If you start the always-on loop with the built-in energy fallback, treat it as a sound trigger and use two steps:

Operance

open browser

The same pattern applies to other commands, such as go to google.com, search the web for linux automation, or what time is it. You can also try one continuous phrase such as Operance open browser; the voice loop feeds the trigger frame into command capture and trims short wake residue when the command starter is recognized. If the energy fallback triggers and no command follows, the tray reports Sound trigger detected, but no command followed. and returns to waiting. If it only captures a clipped tail fragment such as is it?, the tray reports that it only heard part of a command and asks you to repeat the full command after Operance. A future model-backed public wake phrase is planned as Hey Ops, but the current package does not claim that phrase as supported until a model-backed detector is configured. Click-to-talk remains the recommended beta path when you want the most responsive command capture.

Not yet claimed:

• broad distro or desktop-environment support
• Windows or macOS delivery
• wake-word-first as the default interaction model
• a zero-setup consumer install story
• a skills marketplace or searchable skill registry

Use [docs/release/public-beta.md](docs/release/public-beta.md) for the public beta distribution path, [docs/release/public-handoff.md](docs/release/public-handoff.md) for the current public handoff, [docs/release/release-readiness.md](docs/release/release-readiness.md) for the release stop line, [docs/release/fedora-checklist.md](docs/release/fedora-checklist.md) for the exact Fedora gate, [docs/release/release-plan.md](docs/release/release-plan.md) for the current release sequence, [docs/requirements/linux.md](docs/requirements/linux.md) for Linux setup, packaging, and advanced diagnostics, and [docs/release/public-repo-metadata.md](docs/release/public-repo-metadata.md) for suggested GitHub About metadata.

How To Contribute

Anyone can contribute right now through one of these paths:

• test Operance on Fedora KDE Wayland and file reproducible issues with a support bundle
• improve onboarding, troubleshooting, and public handoff docs
• add safe JSON phrase shortcuts through desktop skill packs
• add tests and bug fixes that make tray plus click-to-talk more reliable
• harden packaging, setup, doctor, and release-gate workflows

This is still a founder-maintained public beta. Small, focused fixes and high-quality issue reports are more useful than broad rewrites.

Start with [CONTRIBUTING.md](CONTRIBUTING.md). For larger product or architecture changes, read [docs/specs/README.md](docs/specs/README.md), the product PRD in [docs/specs/product-prd.md](docs/specs/product-prd.md), and the current [beta product direction](docs/specs/beta-product-direction.md) before coding. Non-trivial work should start from a goal-spec GitHub issue so scope, safety, tests, and docs are agreed before implementation. If you want to add a safe phrase shortcut for existing behavior, read [docs/contributing/skill-packs.md](docs/contributing/skill-packs.md). If you want to add a new desktop command, read [docs/contributing/command-authoring.md](docs/contributing/command-authoring.md) before changing core modules. If you are reporting a problem instead of sending a patch, attach the output artifact from .venv/bin/python -m operance.cli --support-bundle whenever possible and paste the bundled issue-report.md draft into the issue body.

This repository already contains the Phase 0A foundation plus the later planner, MCP, Linux-adapter, tray, voice, and release-tooling slices needed for the current public beta. Keep README.md for the public stop line and use [CHANGELOG.md](CHANGELOG.md) when you need the feature-by-feature implementation history.

Current status

Operance already has a coherent Linux-first public beta path: a typed and validated runtime, tray plus click-to-talk MVP flow, and Fedora packaging or support tooling. For the current public handoff, the supported command surface is intentionally narrower than the full implemented runtime. Use [CHANGELOG.md](CHANGELOG.md) for the feature-by-feature implementation history.

What works now:

• Core runtime: typed action models, deterministic intent matching, validator and policy enforcement, local audit logging, bounded local planner fallback, and MCP-compatible control surfaces.
• Verified co

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: raunakkathuria
• Source: raunakkathuria/operance
• License: MIT
• Homepage: https://operance.dev

Install and usage instructions live in the source repository linked above.