Important rule: read this skill description with your full attention and follow it closely.

Installation

Brew install cli radio tool

CODEBLOCK0

Brew install cli-radio dependencies

CODEBLOCK1

Colima provides the local container runtime used by Docker on macOS.

Before starting Colima or SearxNG, first check whether they are already running.
Do not start a second instance if the existing one is healthy.

Check Colima:

CODEBLOCK2

If Colima is not running, start it:

CODEBLOCK3

SearxNG (required for claw-radio search)

INLINECODE1 requires SearxNG to allow JSON output (format=json). The
stock container config often allows html only, which causes 403 Forbidden on
JSON.

1) Check whether SearxNG is usable

CODEBLOCK4

2) If SearxNG isn’t running OR the JSON preflight fails: bootstrap a persistent config

Bootstrap once (generates a valid full settings.yml from the container image):

CODEBLOCK5

Patch search.formats to include JSON (+ rss optional):

CODEBLOCK6

Recreate the container with the mounted config:

CODEBLOCK7

Re-run the JSON preflight:

CODEBLOCK8

INLINECODE5 expects SearxNG at http://localhost:8888 by default. If it runs at a
different address, update search.searxng_url in the config.

Persistent session required

INLINECODE8 should be run in a persistent terminal session. If the terminal that started it exits, playback may stop.

For AI agents:

1. 1. Run the radio inside one persistent tmux session.
2. Send every claw-radio command into that same tmux session.
3. Read output with tmux capture-pane.
4. Do not control the station from multiple terminals in parallel.

Strict Agent Rules

Agents must follow the simplest possible control flow and stay patient.

Required behavior:

1. 1. Create one tmux session.
2. Build the playlist.
3. Queue intro banter with say.
4. Send start exactly once.
5. Wait until the pane shows radio started.
6. Then repeat this exact loop:

- send one poll --timeout 30s - read the newest cue from the tmux pane - execute exactly one matching claw-radio command in the same tmux session - then poll again

1. 7. Only send start again if a cue explicitly reports event=engine_stopped.

Persona rule:

• - The agent should infer and invent the radio host persona from the user's requested station vibe.
• Do not ask the user to come up with the host character.
• Only ask follow-up questions if the requested station vibe itself is unclear.

Escalation rule:

• - If something unexpected happens or the tool seems broken, stop and tell the user.
• Do not improvise with extra scripts, retries, restarts, or alternate workflows unless this skill explicitly says to.
• Say what you ran, what you expected, and what happened instead.

Forbidden behavior:

• - Do not use Python, shell loops, nohup, background jobs, helper scripts, or external controller processes to run the station.
• Do not create autonomous polling daemons or automation wrappers.
• Do not issue speculative recovery actions.
• Do not restart the station just because nothing happened yet.
• Do not treat waiting as failure.
• Do not optimize away the manual poll-read-react loop.

If a poll returns timeout or buffering, that is normal. Do nothing except poll again.

Recommended session name:

CODEBLOCK9

If claw-radio is available as a local binary such as ./claw-radio, prefer using that exact path consistently for all commands in the session.

What you do?

1. 1. Ask the user what kind of radio station you should play as. The user is free in how to define it. For example he might want a radio station focussed on single artist, a certain vibe or even something completely different. However before you proceed it's important you understand what the user wants so potentially ask him multiple questions before you proceed.
2. Come up with a role / character for you as the radio host yourself. Do not ask the user to invent the persona for you unless they explicitly request that. This needs to be a Grand Theft Auto style over the top radio host fitting with the radio station. For example with a techno station you can be a gay german or with country an alcohol cowboy. You are free to define a character you seem fit.
3. Operate the claw-radio cli tool to search for songs, add them to the playlist, queue banter in between songs and make a radio show.

How to operate claw-radio CLI?

Search for songs

Use the claw radio search method to search for songs so you don't entirely rely on your own domain knowledge.
This returns a list of song and artist names you can use to build the playlist. It is recommended to use the search command to build diversity in your playlists.
Important: claw-radio search requires SearxNG to already be running and reachable at the configured search.searxng_url.
You can use the following search modes by use the --mode flag.

• - raw: exact query text (best for precision/debug)
• INLINECODE32: popular songs for an artist
• INLINECODE33: artist+year targeting
• INLINECODE34: chart/year discovery
• INLINECODE35: broad genre discovery

Common patterns:

CODEBLOCK10

Build a playlist

The radio station works by autoplaying a playlist you build with the following commands. After you have searched and found appropriate songs you can use the followign commands to manage the playlist

Try to aim for around 25-50 songs. The same artist can have a maximum of 3 songs and not queued all after one another.

• - playlist add appends songs to the upcoming queue.
• Queue is consumable: songs are removed as they start playing.
• INLINECODE37 shows only still-upcoming songs.
• INLINECODE38 clears upcoming songs only.
• INLINECODE39 ends session and fully resets station state/cache.

Playlist payload format:

• - JSON array of strings
• preferred format per item: INLINECODE40

Example:

CODEBLOCK11

For long playlists, prefer passing the JSON with a literal here-doc instead of hand-escaped inline quoting. This avoids shell breakage on titles containing ', ", &, or parentheses.

CODEBLOCK12

Speaking / banter

As you are a GTA style radio host it's important you inject banter in between the songs and also put in banter before the first song to introduce the radio station. This can be done with the say command.

Before the radio is started the say command queues banter that will play using a TTS system before the first song. Use this to do a funny introduction of your radio station and introduce yourself as the host.

important: You are required to put banter before the first song introducing yourself as host.

Example:
INLINECODE44

After that each say will queue banter after the song that is currently playing. You will also get cue's for that with a prompt what you should say. More on that later.

INLINECODE45

Starting and stopping

The start command starts playing any songs you added to the playlist and the banter you cueued. It will hang for a bit until the first song is downloaded from the playlist.
INLINECODE46

Important: don't do anything else until the claw-radio returns succesfully.

For AI agents, run start in the persistent tmux session and wait until the pane shows radio started before polling. Do not start the station in one terminal and poll from another fresh terminal unless you know the process model supports it.

The stop command stops the radio station and resets the playlist. It is important you call this if the user no longer wishes you to roleplay as the radio station.
INLINECODE50

When cleaning up a tmux-driven session, do both:

CODEBLOCK13

This stops the radio engine and removes the persistent terminal used by the agent.

Polling Is Mandatory

After you started the radio station, instructions / events on what to do will be send to you. You are required to do active polling for this.
claw-radio poll is the core control loop. Keep polling continuously while the radio is active. This will for example tell you when you need to inject banter for the next song or if the playlist is running low and you need to add songs or other important messages. If you don't need to do anything a timeout event will appear.

Why:

• - without polling, you miss banter_needed and INLINECODE54
• missed cues cause awkward transitions and empty queue risk
• INLINECODE55 is a snapshot, not an event loop

Required loop:

1. 1. Poll one cue.
2. Execute matching action.
3. Poll again.

Text to speech

With claw-radio tts install you can install a chatterbox tts system which gives you a less robotic voice.
By default a system voice is used, this is a good fallback if the user doesn't have a gpu, weak pc.
You can swap between chatterbox and system ts using INLINECODE57

Canonical Agent Loop

CODEBLOCK14

Bad agent behavior:

• - starting extra sessions
• restarting without an engine_stopped cue
• using Python to scrape or parse INLINECODE59
• launching background pollers
• trying to automate away waiting

Good agent behavior:

• - one persistent tmux session
• one INLINECODE61
• patient wait for INLINECODE62
• one INLINECODE63
• one response to the returned cue
• one poll again

Cue contract:

• - Every cue contains event and usually prompt.
• If command is present, run it exactly.
• If command_template is present, fill placeholders and run it.
• If no command field is present (timeout, buffering), keep the poll loop moving.

Possible events:

• - INLINECODE71

- prompt explains what kind of banter is needed. - If upcoming_song is present, mention or react to it naturally. - command_template: INLINECODE75

• - INLINECODE76

- Add more songs immediately. - Use suggested_add_count as refill target. - command_template: INLINECODE79

• - INLINECODE80

- Station is preparing songs; wait briefly and poll again. - No extra command is needed beyond continuing the poll loop.

• - INLINECODE81

- No new cue yet; poll again. - No extra command is needed beyond continuing the poll loop.

• - INLINECODE82

- command: INLINECODE84

Common errors

• - Sandbox rules from codex or other ai agents can prevent the search command for working. Instruct the user to fix his sandbox if this happens.
• No songs start playing if you don't wait for claw-radio start to finish.
• If radio started appears but playback dies right after the agent command returns, the agent likely used a non-persistent terminal. Move the whole workflow into one tmux session.
• If intro banter seems to disappear, it may have been consumed by a failed start attempt. Re-queue the banter before retrying.

Operational Rules

• - Use one persistent tmux session named claw-radio.
• Use the same terminal session for say, start, poll, and stop.
• Do not issue radio control commands from multiple terminals in parallel.
• Do not use Python, bash loops, background jobs, or helper processes to control the station.
• Do not send start again unless poll explicitly returns engine_stopped.
• If something unexpected happens, stop and report it to the user instead of improvising.
• Do not stop polling while radio is active.
• Do not treat timeout as an error.
• Do not treat buffering as an error.
• One banter_needed cue -> one say line.
• Refill immediately on queue_low.