Keryx

A personal voice agent that keeps working after you hang up.

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.

Keryx triggers a callback after a task completed. I've named my voice companion Lyra, but this is configurable.

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 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:

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.

Coding agents: Claude Code or Codex

Tasks run on Claude Code or 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 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:

   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 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, and every command runs as uv run keryx from the checkout:

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 has the rest.

Documentation

• Setup guide: the phone, Google, the PIN, where files live, and costs
• Configuration reference: every setting
• Coding agents: signing in, installing only one, and what each can do
• Voice tools: what the voice model can do, and how to add a tool
• Approval bridge: answer Claude Code prompts on your screen by phone
• Security policy and threat model: read it before you put the phone line online
• Wiki: troubleshooting, the command-line reference, and writing your own tools
• Changelog

Getting help

1. Run keryx doctor. It checks the whole setup and says what's missing.
2. Read Troubleshooting on the wiki.
3. If that doesn't solve it, open an issue.

Report a security problem privately, as SECURITY.md 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 has the checklist for each.

Contributing and license

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