Metadata-Version: 2.5
Name: keryx-voice
Version: 0.2.0
Summary: Keryx, a voice assistant service: Twilio phone -> OpenAI Realtime -> Claude Agent SDK subagents
Project-URL: Homepage, https://github.com/wak31415/keryx
Project-URL: Repository, https://github.com/wak31415/keryx
Project-URL: Issues, https://github.com/wak31415/keryx/issues
Author-email: William Koch <47284092+wak31415@users.noreply.github.com>
Maintainer-email: William Koch <47284092+wak31415@users.noreply.github.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: claude-agent-sdk,openai-realtime,speech-to-speech,telephony,twilio,voice-agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: <3.13,>=3.12
Requires-Dist: fastapi<1.0,>=0.141.1
Requires-Dist: httpx<1.0,>=0.28.1
Requires-Dist: numpy<3,>=2.5.2
Requires-Dist: pydantic-settings<3,>=2.15.0
Requires-Dist: python-multipart<0.1,>=0.0.32
Requires-Dist: questionary<3,>=2.1.1
Requires-Dist: rich<16,>=15.0.0
Requires-Dist: soxr<2,>=1.1.0
Requires-Dist: twilio<10,>=9.11.0
Requires-Dist: typer<1.0,>=0.27.2
Requires-Dist: uvicorn[standard]<1.0,>=0.52.4
Requires-Dist: websockets<18,>=17.1
Provides-Extra: all
Requires-Dist: claude-agent-sdk<0.3,>=0.2.148; extra == 'all'
Requires-Dist: openai-codex==0.163.0; extra == 'all'
Provides-Extra: claude
Requires-Dist: claude-agent-sdk<0.3,>=0.2.148; extra == 'claude'
Provides-Extra: codex
Requires-Dist: openai-codex==0.163.0; extra == 'codex'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/keryx-mark.svg" width="88" alt="">
</p>

<h1 align="center">Keryx</h1>

<p align="center"><em>A personal voice agent that keeps working after you hang up.</em></p>

<p align="center">
  <a href="https://github.com/wak31415/keryx/actions/workflows/ci.yml"><img src="https://github.com/wak31415/keryx/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-6366f1.svg" alt="Apache-2.0"></a>
  <img src="https://img.shields.io/badge/python-3.12-6366f1.svg" alt="Python 3.12">
  <img src="https://img.shields.io/badge/coverage-%E2%89%A596%25-22d3ee.svg" alt="Coverage at least 96%">
</p>

Start hours of work from a short phone call: you can ask your assistant on the line to research
a question, change code, or run an experiment. The work then continues on your
machine, even after you hang up. You can check in or add instructions in a later call, and Keryx can call you back
or text you the report when it's done. You can call from a phone, or from a watch that can
place calls.

> [!NOTE]
> Keryx is pre-1.0. It's self-hosted: it runs on your own machine with your own API keys.
> While it only answers calls from your own phone number, and asks for your PIN before it
> does anything on your behalf in case someone spoofs it, please review
> [SECURITY.md](SECURITY.md) before deploying it.

<p align="center">
  <img src="docs/assets/keryx-incoming-call.jpg" width="480" alt="A Garmin watch showing an incoming call from Lyra.">
  <br>
  <em>Keryx triggers a callback after a task completed. I've named my voice companion Lyra, but this is configurable.</em>
</p>

## Example requests

> *"In the imaging project, run a learning-rate sweep on the microscopy images. Call me if
> you need a decision, and again when training finishes with a quick summary of the results."*

> *"Find the papers my group emailed this week, turn them into a reading-group presentation
> with polished animations and some discussion questions, and send it to me on Slack."*

> *"Add a voice command that checks whether my home server is up. Build it in the Keryx
> project and run the tests."*

> *"One more thing: include GPU memory use in that sweep comparison."*

## Features

Keryx turns the [Realtime API](https://developers.openai.com/api/docs/guides/realtime) into
a voice agent that you can use across many calls. This is how it compares with the Realtime
API alone and with ChatGPT Voice, as of September 2026:

| Feature | Realtime API | ChatGPT Voice | Keryx |
| --- | :---: | :---: | :---: |
| Live voice conversation and tools | ✅ | ✅ | ✅ |
| Phone calls, including from calling watches | 🟡 SIP setup | 🟡 1-800-CHATGPT, US/CA | ✅ |
| Email, calendar, and Slack by voice | 🟡 via MCP | ✅ | ✅ |
| **Tasks that continue after you hang up** | — | ✅ in Work | ✅ |
| Status and follow-ups in a later call | — | 🟡 in the app | ✅ |
| SMS links to written reports | — | — | ✅ |
| Call-backs when you ask for one | — | — | ✅ |
| Calls you when a task needs your input | — | — | ✅ |
| Add a feature to Keryx during a call | — | — | ✅ |
| Report a bug in Keryx by voice, filed as a GitHub issue | — | — | ✅ |
| Answer Claude Code prompts on your screen by phone | — | — | ✅ |

## System overview

*Keryx* (κῆρυξ) is Ancient Greek for a herald: a messenger who carries word back and forth.
That's the job here. Keryx answers the phone, hands your request to a coding agent on your
machine, and calls you back with the result. The messenger you talk to on the line is
called Lyra by default, and you can rename it with `keryx config set ASSISTANT_NAME …`.

The conversation runs on the OpenAI Realtime API. Lyra answers small questions itself.
Anything larger becomes a task for a coding agent and is handed to Keryx, which keeps running after you hang up.

In this example, one task spans three calls. Keryx calls back once so that Lyra can ask you
a question, and again with the training results.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/keryx-call-flow-dark.svg">
  <img src="docs/assets/keryx-call-flow-light.svg" alt="A call starts a tracked task that continues after you hang up and returns by SMS, callback, or a later call.">
</picture>

### Coding agents: Claude Code or Codex

Tasks run on [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or
[Codex](https://developers.openai.com/codex), signed in with a subscription or an API key.
Keryx is most extensively tested with Claude Code on a subscription. Codex is supported,
but it may not have every feature. `keryx setup` asks which agent to use by default. If you
enable both, you can say "have Codex do it" on a call.
[docs/agents.md](docs/agents.md) compares the two.

## Quickstart

### Requirements

- Linux or macOS, on a machine that stays on, such as a desktop or home server where your
  projects live. Keryx can't answer calls, keep working, or call you back while it sleeps.
- An OpenAI API key with Realtime access.
- A Claude or ChatGPT plan, or an API key, for the coding agent. Claude Code and Codex both
  come with Keryx.
- A Twilio phone number.
- A tunnel that gives Twilio a public address: Cloudflare Tunnel on Linux, ngrok on macOS.

### Install and set up

1. Install Keryx:

   ```bash
   curl -fsSL https://raw.githubusercontent.com/wak31415/keryx/main/install.sh | sh
   ```

   It installs the `keryx` command and starts `keryx setup`, a wizard that asks only for
   what's still missing and ends by installing the background service. Run `keryx setup`
   again at any time.

2. Call your Twilio number.

`keryx upgrade` updates Keryx and restarts the service onto the new version. You can also
ask for an upgrade on a call.

If a coding agent is setting Keryx up for you, point it at
`keryx setup --agent-instructions`, or, in a clone, give Claude Code the `skills/keryx-setup`
skill. The [Setup guide](https://github.com/wak31415/keryx/wiki/Setup) on the wiki covers
each step in detail.

### Developer install

Clone Keryx instead of installing it, and the service runs your checkout. That adds what an
installed copy can't do:

- **Changes to Keryx's own code by phone.** Ask on a call, for example "make the call-back
  name the project", and the task edits the checkout, restarts Keryx onto the change, and
  calls you back to say whether it came up.
- **Better bug reports.** With issue reports turned on in `keryx setup`, the task reads
  Keryx's code and logs before it files the issue.
- The test suite, and branches of your own.

It needs [uv](https://docs.astral.sh/uv/), and every command runs as `uv run keryx` from the
checkout:

```bash
git clone https://github.com/wak31415/keryx.git && cd keryx
uv sync
uv run keryx setup
```

To update, pull and then run `uv run keryx restart`. [CONTRIBUTING.md](CONTRIBUTING.md) has
the rest.

## Documentation

- [Setup guide](https://github.com/wak31415/keryx/wiki/Setup): the phone, Google, the PIN,
  where files live, and costs
- [Configuration reference](docs/configuration.md): every setting
- [Coding agents](docs/agents.md): signing in, installing only one, and what each can do
- [Voice tools](docs/tools.md): what the voice model can do, and how to add a tool
- [Approval bridge](https://github.com/wak31415/keryx/wiki/The-Approval-Bridge): answer
  Claude Code prompts on your screen by phone
- [Security policy and threat model](SECURITY.md): read it before you put the phone line
  online
- [Wiki](https://github.com/wak31415/keryx/wiki): troubleshooting, the command-line reference,
  and writing your own tools
- [Changelog](CHANGELOG.md)

## Getting help

1. Run `keryx doctor`. It checks the whole setup and says what's missing.
2. Read [Troubleshooting](https://github.com/wak31415/keryx/wiki/Troubleshooting) on the
   wiki.
3. If that doesn't solve it, [open an issue](https://github.com/wak31415/keryx/issues).

Report a security problem privately, as [SECURITY.md](SECURITY.md#reporting-a-vulnerability)
describes, never in a public issue.

## Roadmap

v0.3.0 plans to add local models for the voice and the agents. v0.4.0 plans to let you
talk to the assistant at a Mac, without a phone. A move to OpenAI's GPT-Live is being
considered but isn't scheduled. [docs/roadmap.md](docs/roadmap.md) has the checklist for
each.

## Contributing and license

Bug reports, corrections to the docs, and code are all welcome. See
[CONTRIBUTING.md](CONTRIBUTING.md). Keryx is licensed under [Apache 2.0](LICENSE).
