Live operating mode

Use Co-host Agenda Mode when Kira should help carry the stream without taking over.

Co-host mode is not full autonomy. The streamer prepares or approves the direction, then Kira keeps pacing, transitions, short turns, and compact chat reactions inside that lane.

Plain-language version

Think of Kira as a live radio co-host with a prepared rundown. You choose the segment, Kira helps keep it moving, and the host can interrupt or stop her at any time.

How a co-host segment flows

Host chooses topic

The stream direction starts with a human-approved idea.

Kira opens

Kira gives a short intro or transition, not a long lecture.

Live signals arrive

PTT, host input, chat summary, and timers can change the next turn.

Safe stop

The host can pause or stop the segment without losing control.

Quick path

1Queue a small set of streamer-approved topics with title, angle, and constraints.
2Enable Co-host Agenda Mode only when the host wants Kira to help drive the segment.
3Let Kira open the active topic, speak in short turns, then wait for PTT, compacted chat, or timer signals.
4Use soft stop at safe boundaries; use emergency stop only when speech/generation must be interrupted.

What the mode controls

Human-owned direction

Kira does not invent the show plan. Topics and direction are approved by the streamer first.

Short spoken turns

Each turn should fit live rhythm: one idea, one transition, or one reaction instead of a long monologue.

Priority inputs

PTT and direct host input outrank chat; chat is filtered and compacted before it becomes context.

Safe recovery

Stop and retry behavior must respect speaking/generation boundaries so the show degrades instead of deadlocking.

Good fit / bad fit

Use it when

You have a planned segment and want Kira to help with pacing, transitions, and light reactions.

Avoid it when

You need the host to speak freely with no AI-led agenda, or when the topic is not approved yet.

Developer notes

Do not build infinite autonomy

The product direction is deterministic co-host with agenda, not "Kira runs the stream forever".

Chat is a secondary signal

Raw chat should become compact intent, not a direct prompt dump into the model.

Cards can enrich direct host mode

A matching ARMED card can be injected for PTT/manual host input without consuming the card.

Editorial cards

Cards are curated context for Kira, not agenda topics.

Use cards to store a take, hook, counterpoint, or research angle that Kira may inject when a matching agenda topic or direct host question appears.

Plain-language version

A card is a sticky note for Kira. It tells her: "if this topic comes up, remember this prepared point." It is not the whole stream plan.

Card lifecycle

Draft

Write the idea while it is still hidden from Kira.

Arm

Mark it ready so Kira can use it when the right moment appears.

Match or link

Attach automatically by triggers, or link it deliberately to a topic.

Use or rearm

Keep history, disable stale notes, or rearm useful knowledge.

Quick path

1Create a card with topic, summary, streamer take, optional counterpoints, hooks, triggers, and expiry.
2Arm the card when it is ready. DRAFT cards are invisible to Kira.
3Let auto-attach match an ARMED card to an agenda topic, or use link for a deterministic override.
4Use rearm for reusable knowledge, disable for stale cards, and delete only when you really want hard removal.

Lifecycle

DRAFT

Editable and invisible to Kira. Safe staging state for humans and agents.

ARMED

Eligible for auto-attach, direct host injection, or explicit link.

ACTIVE / USED

ACTIVE means selected for a topic; USED preserves history after Kira consumes it.

EXPIRED

Excluded from matching. Can be rearmed when the content becomes useful again.

What users should write

Write the point

Keep the card focused: one take, one hook, one useful detail, or one counterpoint.

Add trigger words

Add names, games, topics, and phrases a host may actually say live.

Do not dump research

Summarize first. Kira needs a clean live cue, not a wall of notes.

Rules that matter

Cards vs topics

Cards are reusable knowledge. Topics are agenda instances. Do not use cards as a replacement for the topic queue.

Triggers are important

Conversational host input may not overlap the card title. Add triggers such as game names, people, or recurring phrases.

Chat never triggers card injection

Only the direct host path qualifies. Chat and SmartAggregator snapshots must not silently inject cards.

Link must match topic slug

The CLI validates topic_id against the card topic slug before activating a deterministic link.

Operator and agent CLI

Use the CLI for repeatable card and topic-inbox workflows.

The editorial CLI is a one-shot process: each command opens the SQLite store, performs one transaction, prints, and exits. This is intentionally automation-friendly.

Plain-language version

Most streamers do not need the CLI. It is for operators, scripts, and agents that prepare cards or topic suggestions in a repeatable way.

Safe CLI workflow

Prepare

A human, script, or agent creates a small card or topic proposal.

Validate

The CLI accepts only bounded, curated input and returns clear errors.

Review

Topic proposals still need human review in the app.

Use live

Approved content can support Kira during the stream.

Quick path

1Run commands from the repo root or packaged Python environment.
2Use --json for agents and parse stderr when the exit code is nonzero.
3Treat exit 1 as a decided validation/state result, not something to blind-retry.
4Retry only transient "database is locked" failures, with backoff.

Who should use it

Streamer

Use the app UI first. It is the safer, clearer path for live operation.

Operator

Use the CLI when preparing many cards or proposals before a show.

Agent/script

Use --json, check exit codes, and never assume topic approval happened.

Common commands

Create a card

$ python -m opencohost.editorial_cli --json create --from-json

Arm and inspect

$ python -m opencohost.editorial_cli arm <card_id>
python -m opencohost.editorial_cli show <card_id> --json

Explicit card link

$ python -m opencohost.editorial_cli link <topic_slug> <card_id>

Propose a topic

$ python -m opencohost.editorial_cli topic propose --title "<title>" --angle "<angle>" --source "<agent>"

List or discard proposals

$ python -m opencohost.editorial_cli topic list --json
python -m opencohost.editorial_cli topic discard <ti_id>

Hard boundaries

No CLI approval for topics

topic approve is deliberately refused. Approval happens in the app where the operator can read title and angle.

Curated context only

Cards reject raw dumps, code-like content, and oversized fields. Agents should summarize before writing.

One operation per process

There is no CLI daemon or session memory; command order is the state machine.

Stream integrations

Connect OBS avatar and chat by link; keep Stream Admin restricted.

OpenCohost should make stream integration simple without asking for dangerous credentials by default. Avatar and chat-link flows are the safe path; Stream Admin is MVP/testing only.

Plain-language version

There are two normal connections: OBS shows Kira visually, and the chat link lets Kira understand the room. Stream Admin is different: it can touch channel controls, so it stays restricted.

Safe stream connection map

OBS avatar

Visual state only: Kira changes image/state inside OBS.

Chat URL

Read the live chat from a YouTube/Twitch link.

OpenCohost

Shapes signals into safe context for Kira.

Stream Admin

Restricted MVP for privileged admin tests, not the default chat flow.

Quick path

1For the avatar, enable OBS WebSocket, create an Image source named KiraAvatar, then set host, port, password, source, and scene in the avatar panel or config/avatar.yaml.
2Use "Test connection" before going live. The avatar bridge updates OBS image sources when Kira changes state.
3For chat, paste the YouTube or Twitch live/chat URL into the chat connection field. This path is link-only and should not request OAuth write permissions.
4Keep Stream Admin disabled/restricted unless you are explicitly testing MVP admin flows with throwaway or approved credentials.

Featured features

OBS avatar states

Kira can expose idle, listening, thinking, speaking, and related states through OBS image-source updates.

Chat by URL

The streamer links a YouTube/Twitch live or chat URL; OpenCohost treats it as a chat source, not as channel administration.

Small-stream support

Stream Chico lowers thresholds/cooldowns so smaller rooms can still produce useful co-host moments.

Stream Admin MVP

OAuth/admin operations remain restricted, approval-gated, and test-mode oriented because write scopes are high risk.

Safe vs restricted

Safe default

OBS avatar and chat-by-link are the normal user path.

Restricted

OAuth/admin actions are test-mode only and require explicit approval.

Do not promise

Do not describe Stream Admin as general channel control until it is validated and released.

Limits to document clearly

OBS source requirements

OBS WebSocket v5 image updates require preserving OBS settings and setting both file and local_file on image sources.

Link-only chat is separate from admin

Pasting a chat link should not imply title editing, moderation, chat posting, or OAuth token storage.

Stream Admin is restricted

The MVP can expose YouTube admin capabilities in controlled tests, but public docs must frame it as restricted and approval-gated. Twitch admin remains future/placeholder unless separately validated.