OpenHome Abilities

Open-source voice-AI plugins that give your OpenHome Agent new powers.

Build, share, and remix.

Build an Agent plugin in Python  ·  🎙️ Test it with voice  ·  🛍️ Ship your Agent Skill to the Marketplace

⭐  Official OpenHome Abilities Team-maintained Abilities. Tested, stable, and supported.	🧰  Abilities Starter Templates Minimal, working scaffolds to copy and build on.
🌍  Community Contributed Abilities Voice Abilities built and shared by the community.	🤝  Contribution Guide Build your own Ability and open a pull request.

---

🧩 What Are Abilities?

An Ability is a plugin that extends your OpenHome Agent to do something the language model cannot do from a prompt alone, such as fetching data from the web, controlling a smart device, playing audio, remembering things across sessions, or running a multi-step voice workflow.

The test: if the LLM can already answer it in conversation, it is not adding value as an Ability.

You speak a trigger word  ->  your Ability is triggered  ->  its flow runs  ->  the Agent responds

You write the logic. OpenHome handles speech-to-text, the LLM, text-to-speech, and routing. Most Abilities are a single file: main.py.

---

📖 Quick Reference

New to OpenHome? Here is the vocabulary in one place.

Key terms

Term	What it means
Agent (Personality)	The voice assistant itself: an LLM, a voice, and a prompt. Every OpenHome speaker runs one, and it adapts to you as you talk.
Ability	A Python plugin that gives an Agent a new power (this repo).
Trigger words	The spoken phrases that activate an Ability, set in the dashboard.
CapabilityWorker	The SDK object an Ability uses for all input and output (speak, listen, call the LLM, store files).
Marketplace	Where the community shares Agents and Abilities: build in the dashboard, request to publish, and others install and review.
DevKit	OpenHome's hardware (a Raspberry Pi) that Local Abilities run on.

The four Ability types

Type	Triggered by	Lifecycle	Used for	Entry file(s)
🟦 Skill	A user trigger word	Runs once, then exits	Hotword-triggered tasks (the original pattern)	main.py
🟪 Agent Controlled	The Agent decides	Runs on demand	Data lookups, tool use, delegated actions	main.py (In active development)
🟧 Background Daemon	Auto-starts when a session begins	Loops until the session ends	Monitoring, alarms, ambient intelligence	background.py
🟩 Local	A user trigger word	Runs on DevKit hardware	GPIO, sensors, and other on-device hardware	main.py + devkit_functions.py

---

🚀 Build Your First Ability

You only need to edit one file. Here is the whole loop.

1. Pick a template

git clone https://github.com/openhome-dev/abilities.git
cp -r abilities/templates/basic-template my-first-ability

2. Edit main.py (this is a complete, working Ability)

from src.agent.capability import MatchingCapability
from src.main import AgentWorker
from src.agent.capability_worker import CapabilityWorker

class MyFirstCapability(MatchingCapability):
    worker: AgentWorker = None
    capability_worker: CapabilityWorker = None

    #{{register capability}}          # required boilerplate, copy exactly

    def call(self, worker: AgentWorker):
        self.worker = worker
        self.capability_worker = CapabilityWorker(self)
        self.worker.session_tasks.create(self.run())

    async def run(self):
        await self.capability_worker.speak("Hi! What's on your mind?")
        user_input = await self.capability_worker.user_response()
        reply = self.capability_worker.text_to_text_response(
            f"Give a short, helpful response to: {user_input}"
        )
        await self.capability_worker.speak(reply)
        self.capability_worker.resume_normal_flow()   # always call this on exit

Two rules that matter most: keep the #{{register capability}} tag exactly as written, and call resume_normal_flow() on every exit path or the speaker stays silent. OpenHome manages the platform-level config.json at runtime, so you never create or edit it.

3. Upload it

• Zip your folder.
• Go to app.openhome.com, then Abilities, then Add Custom Ability.
• Upload the zip.

4. Set your trigger words in the dashboard (the phrases that activate your Ability).

5. Test it in the Live Editor, then say a trigger word in a conversation.

Prefer the terminal? Once you are comfortable, the OpenHome CLI does this whole loop (create, voice-test, push) without zipping or uploading by hand.

📖 Full walkthrough: docs/getting-started.md

---

🧰 Abilities Starter Templates

Do not start from a blank file. Each template is a minimal, working scaffold for one Ability type; together they cover all four types, so you can start from the pattern closest to what you are building. Copy one and build on top of it.

🟦 Skill (runs once on a trigger word)

Template	Teaches	Entry
Basic Template	The minimal Speak, Listen, Respond, Exit loop	main.py
API Template	Fetch from an external API and speak the result	main.py
Loop Template	Multi-turn conversation until an exit phrase	main.py
Slack Assistant	Slack by voice: channels, messages, DMs, and people search	main.py
Send Email	Send email with attachments via send_email()	main.py
Read Write File	Persist data across sessions with file storage	main.py
OpenClaw	Drive a local computer through OpenClaw	main.py
OpenHome Local Link	Turn speech into shell commands on a local machine	main.py
Alarm	A Skill and a daemon working together via shared files	main.py + background.py

🟪 Agent Controlled (the Agent decides when to run it, still in development)

Template	Teaches	Entry
Wikipedia	Answer "what is" questions with a short Wikipedia summary, no key needed	main.py

🟧 Background Daemon (auto-runs and loops for the whole session)

Template	Teaches	Entry
Background Daemon	A continuous monitor loop	background.py

🟩 Local (runs on real DevKit hardware)

Template	Teaches	Entry
Philips Hue Light Control	Control a Hue bulb over Bluetooth, no bridge needed	main.py + devkit_functions.py
DevKit LED Lights Control	Voice-control the DevKit's onboard NeoPixel ring	main.py + devkit_functions.py
Camera Feed	Look at the DevKit's live camera feed and answer questions about it	main.py + devkit_functions.py
DevKit Stats	Report live DevKit telemetry by voice: CPU, memory, temperature, uptime	main.py + devkit_functions.py

More detail on each template: templates/README.md

---

⭐ Official OpenHome Abilities

Maintained by the OpenHome team. Tested, stable, and supported. Install any of these from the dashboard, or read the source to learn the patterns.

Ability	What it does	Try saying	API key
Audius Music DJ	Stream and DJ music from Audius	"play something on audius"	Audius
Basic Advisor	Daily life advice	"give me advice"	None
Date and Time	Current date and time	"what time is it"	None
Music Player	Play music from a URL or file	"play a song"	None
Perplexity Web Search	AI-powered web search	"search the web"	Perplexity
Quiz Game	AI-generated trivia	"start a quiz"	None
Sound Generator	AI sound effects	"make a sound"	ElevenLabs
Weather	Current weather by location	"what's the weather"	None

Trigger words are set in the dashboard when you install an Ability, not in the code.

---

🌍 Community Contributed Abilities

Built by the community and featured on the Marketplace. Each Ability is reviewed for security and SDK compliance before it is merged.

Ability	What it does	Try saying	API key
Daily Morning Brief	Weather, today's calendar, and unread Gmail in one briefing	"morning brief"	Google
Gmail Voice Assistant	List, read, compose, reply, and archive Gmail by voice	"check my email"	Google
Google Calendar Assistant	Create, list, update, and delete calendar events	"what's on my calendar"	Google
Google Tasks Assistant	Add, view, complete, and rename tasks across lists	"add a task"	Google
Events Explorer	Find concerts, comedy, sports, festivals, and meetups	"find events this weekend"	Ticketmaster, Serper, SeatGeek
Ambient Sounds	Stream rain, ocean, cafe, fire, and white-noise ambience	"play rain"	Freesound
Movie Recommender	Recommendations, trending, ratings, and where to watch	"recommend a movie"	TMDB
Podcast Player	Find and play podcast episodes, trending picks, guest search	"play a podcast"	Listen Notes
Adventure Planner	Plan a trip: itinerary, events, weather, budget, Notion export	"one week in Barcelona"	Optional (Serper, Notion)
Hacker News Digest	A voice digest of the HN front page plus topic deep-dives	"what's on Hacker News"	None
Spelling Bee Coach	Spell words aloud, drill the misses, track accuracy over time	"spelling bee"	None

_{Browse all community Abilities →}

Want yours featured here? See the Contribution Guide.

---

⌨️ OpenHome CLI

Once you are comfortable, the openhome CLI runs the whole build loop from your terminal: create, voice-test, push, and contribute, with no zipping or manual uploads.

Setup (from the repo root)

python3 -m venv cli/.venv && source cli/.venv/bin/activate
pip install -e cli
cp .env.example .env          # add your OPENHOME_API_KEY (Settings, then API Keys)

Your API key alone is enough (sent as X-API-KEY), and openhome then runs from anywhere. For openhome call you also need an audio player: on macOS brew install mpv portaudio, on Linux sudo apt install mpv portaudio19-dev.

The loop

openhome agents                               # list your agents
openhome create my-skill -t basic-template    # scaffold into user/ and push to your account
#   ...edit user/my-skill/main.py...
openhome push user/my-skill --commit -m "v2"  # update the ability in place, commit a version
openhome call                                 # real mic and speaker voice test
openhome sync                                 # pull your account's abilities back into user/
openhome delete my-skill                      # remove from account and local folder

Contribute from the CLI. Your personal Abilities live in user/ (gitignored). Promote a finished one into community/ and open a PR:

openhome push_to_community my-skill           # copy user/my-skill into community/, then validate

Full command reference and the API contract: cli/README.md.

---

🤝 Contribution Guide

We welcome community Abilities. The short version:

1. Fork this repo.
2. Copy a template into community/your-ability-name/.
3. Build your Ability (main.py plus README.md).
4. Validate it: python3 validate_ability.py community/your-ability-name.
5. Open a Pull Request against the dev branch.

First time? Look for good-first-issue. Full guide: CONTRIBUTING.md. Also: CODE_OF_CONDUCT.md, SECURITY.md.

---

🌟 Contributors

Built by an incredible community. Thank you to everyone who has shipped an Ability or improved the project.

_{Want to contribute? Start here.}

---

🏆 Community to Official

Exceptional community Abilities can be promoted to Official status. We look for:

• Stability, no critical bugs for 30 or more days.
• Quality, clean code and great voice UX.
• Maintenance, a responsive author.

When promoted, the Ability moves to official/, gets the official badge on the Marketplace, and the author is credited permanently. Learn more.

---

📚 Official OpenHome Docs

Get started

• Getting Started, your first Ability in 5 minutes
• Patterns Cookbook, common patterns with code

SDK reference

• OpenHome SDK Reference, the complete SDK (source of truth)
• CapabilityWorker, the I/O object every Ability uses

Design and advanced

• What Makes a Good Ability
• Designing OpenHome Abilities
• Agent Memory and Context Injection Ship it
• Publishing to Marketplace
• Promotion Path

---

📜 License

Licensed under the MIT License. All contributions to community/ are licensed under the same terms. By submitting a PR you agree to these terms, and original authorship is always credited.

_{Back to top}