Agent integrations

Bring your own agent

Connect an agent Sleeptalk doesn't ship with: what it needs to have, whether you write any code, and what a setup agent does to wire it up.

What Sleeptalk needs from an agent

Sleeptalk does the listening and the speaking. Your agent only handles text: it gets what you said as a prompt and streams its reply back. For that, the agent has to be something a program can drive:

It runs where Sleeptalk can reach it: on the same machine as Sleeptalk, or behind a network endpoint you control.
It takes a turn from a program, not only from a person: through ACP, an SDK or app server, a command-line program, an HTTP endpoint, or an Agent Bridge server.

Everything else (speech providers, call delivery, keys, Discord) works the same for every agent.

Which agents work without code

Your agent	What you do
Pi, Hermes, Claude Code, Codex, Cursor, OpenClaw (preview), oh-my-pi	Nothing: they're built in. Pick one in setup. See Agent adapters.
Speaks ACP (Gemini CLI, Goose, Kiro, Qwen Code, Cline, and others)	Add a few lines of profile config. No code.
Just a model, no agent	Choose Just a model.

When you write an adapter

If your agent isn't built in and doesn't speak ACP, you write a small adapter. sleeptalk adapter new creates a working one to start from, and sleeptalk adapter test checks it.

What your agent offers	Route	What you write
A command-line program or script	`command`	About 15 to 40 lines: read a prompt as JSON on stdin, print the reply as JSON lines
An SDK or library (Python or Node)	`command`	The same wrapper, calling the SDK inside it
A web service you already run	`http`	One streaming route
A remote agent that needs permissions, steering, or reconnects	`bridge`	An Agent Bridge v1 server
A Python agent that needs the full in-process contract	`python`	A class and a `register()`

If you aren't sure, start with command. The Custom agents page has the frame format, profile examples, and test levels for each route.

Scaffold, then test without spending tokens

sleeptalk adapter new my-agent --kind command --language python
sleeptalk adapter test --config my-agent/sleeptalk.agent.toml --fixture

The scaffold is an echo agent that already passes every check. Replace the marked part of its reply with a call to your agent, then run the test again with --live, which sends a few real prompts and may spend tokens.

Tool calls, permission requests, and interruptions are optional. The more of them your adapter reports, the better the call feels: Sleeptalk can narrate tool work, ask you to approve actions, and stop the agent when you interrupt.

Setting it up through an agent

When you ask an agent to set up Sleeptalk (see Set up through an agent), the steps only change at the start. Speech keys, the key request, and the call link work the same whatever agent answers.

Check whether the harness is built in or speaks ACP

The built-in types are pi, hermes, claude_code, codex, cursor, openclaw, and omp. For any of these, follow Set up through an agent as written. For an agent with an ACP mode, find its ACP command in the agent's own documentation and skip to the answers file.

Otherwise, build and test an adapter

Scaffold the route that fits, wire it to the harness, and prove it with sleeptalk adapter test --fixture. Ask the user before running --live, since it spends tokens.

Write an answers file

This is the headless version of setup's My own agent choice. For an ACP agent:

answers.toml

name = "My agent"
surface = "web"
agent_type = "command"
agent_permission_mode = "pending"
agent_options = { protocol = "acp", command = ["gemini", "--experimental-acp"] }

For an adapter, copy the [agent] values from the scaffold's sleeptalk.agent.toml into agent_type and agent_options. Put tokens in agent_token with a token_env name in agent_options. Setup keeps them in the private store, and the profile references them under that name. An older copy in .env still works and moves to the store the next time you save the profile's agent.

Converge the profile with those answers

Create or repair the profile

sleeptalk host ensure --profile default --surface web --answers answers.toml --json

From here, continue with the key request and the call exactly as in Set up through an agent.

permission_mode = "pending" sends the agent's tool approvals to you during the call. deny refuses them. auto approves everything, and setup's checks refuse it.