← Onidia
User guide

How to actually use her.

The setup guides get her thinking. This one is the part afterwards: how to start her, how to put her away, how to talk instead of type, what the settings really do, and where your conversation goes. If Onidia is already talking to you, you can stop reading this.

No setup required Covers both apps ~5 minutes

Opening the chat window

Onidia is two programs. Onidia Chat is the window you talk to her in; Onidia is the little character who lives on your desktop. Start with the window — it is the one that checks your keys and tells you when something is wrong.

1

From the start menu

Open the applications menu and go to Internet. Chat clients live there alongside browsers and mail, which is why she is filed under it rather than under Games.

She is listed as “Onidia Chat”

That is the window. The character on your desktop is a separate entry called Onidia, under Games — see the next section.

2

From a terminal

terminal
onidia-chat

Both programs are installed into your PATH, so they work from any directory and you never need the full path. No Onidia yet? The install section has a one-liner that works out which build your machine needs.

One thing the installer deliberately does not do for you: put her config where she looks for it. The package installs it to /opt/onidia/share/chat-app.ini and leaves your home alone, because a file written there by apt would be root-owned and you could not edit your own key afterwards. So once, before the first launch:

terminal
mkdir -p ~/.config/chat-app
cp -n /opt/onidia/share/chat-app.ini ~/.config/chat-app/   # -n never overwrites yours

Skip it if you use environment variables instead of the file, and a setup guide for the provider you picked will usually write it for you.

3

First launch

She checks the environment before the window opens and tells you plainly what is missing rather than failing mysteriously later. If she has nothing to think with yet, you will be sent to one of the setup guides — Gemini is the five-minute option. Once she is wired up, she greets you once when the window opens.

Bringing Onidia on screen

She is the small anime character who sits on your desktop and reacts to what she says. Three ways to start her; they all do exactly the same thing.

1

The Haiya! button — the usual way

There is a pill in the header of the chat window that says Haiya! Click it and she appears on your desktop.

Its colour tells you what it will do

Teal means she is not running and the button will bring her on screen. Pink means she is already running and the same button will send her away. Nothing is ambiguous, and there is only ever one of her — you do not get two Onidias, you get one appearing and then leaving.

2

From the start menu

Games → Onidia. She is a companion, not a utility, so that is where the menu puts her.

3

From a terminal

terminal
onidia

If you are starting both by hand, start her first. She creates the little speech pipe that the chat window writes into, so the window has something to talk to.

Sending her away

She never vanishes abruptly. She says goodbye, waves and poofs out — both ways out do that, so whichever you pick she leaves politely.

The Haiya! button

While she is running the button is pink. Click it and she picks a farewell, waves and disappears. The button goes back to teal, ready to bring her on screen again.

Right-click the character

Right-click her on the desktop and she poofs out and closes. The quickest way to clear her when the chat window is behind something else.

Started her from a terminal?

Press Ctrl-C in that terminal. It is the plainest exit of the three, and unlike the other two it skips the goodbye.

Closing the chat window does not close her

Talking instead of typing

A microphone button sits in the input bar, to the left of the box where you type. It is only drawn when speech input is switched on, so if you cannot see it that is the reason — not a bug.

1

Using it

YouClick the microphone and start talking
SheRecords while you speak, stops when you stop, and drops the words into the input box for you to check before sending.

Two settings in the gear menu make that faster. Auto stop ends the take when you stop talking, so you never have to find the button again. Auto submit sends it the moment transcription finishes, turning the whole thing into a conversation with no typing at all.

2

What it needs

Two things, both outside Onidia: a way to record, and something to do the recognising.

terminal
sudo apt install pipewire-bin alsa-utils pulseaudio-utils

She looks for a recorder in this order and takes the first one it finds: pw-record, parecord, arecord, ffmpeg. Those three packages cover the first three — pipewire-bin for pw-record, pulseaudio-utils for parecord, alsa-utils for arecord — and any one of them is enough on its own. Add ffmpeg only if you would rather she used that.

3

Choosing what does the listening

Set stt in your config file to one of three backends.

config
stt = whisper

# and, only if you have more than one microphone:
stt-device = hw:2,0

transcribe is the default. It uses Amazon Transcribe, which is quick and accurate but needs AWS credentials allowed to call transcribe:StartStreamTranscription. whisper runs the recognition on the Pi itself, so nothing is sent anywhere and there is no bill — slower on a Pi, but private. off takes the microphone button away again.

More than one microphone?

Leave stt-device empty and she uses the system default. Fill it in with a PipeWire node name for pw-record or parecord, or an ALSA device such as hw:2,0 for arecord and ffmpeg.

The two are independent. If you close the window while she is still on your desktop, she stays there. Send her away with one of the two methods above.

She only greets you when she is awake

Settings, field by field

The gear in the chat window header. Everything below is optional — the defaults are sensible — but these are the dials you are meant to turn.

The Onidia settings dialog, showing name, character age, sleep time, busy time and the checkboxes.
The settings dialog, exactly as it appears in the window.
1

Name

What she calls herself. It replaces the name in her persona, so she signs her replies as that. Clearing the field does not erase the name she already had — it goes back to whatever her prompt originally said.

2

Character age

A dropdown from 7 to 13, starting on 10. She is told her age and keeps her replies age-appropriate, which is the single easiest way to change how much she talks down to you.

3

Sleep time and busy time

Both are a from and a to, to the quarter hour, and both understand windows that run past midnight — set sleep to 22:00 → 07:00 and it means what it looks like.

Sleep time

She is told the schedule, so a message that lands inside those hours catches her sleepy and half-asleep. It also stops her greeting you at startup while she is asleep.

Busy time

Keeps unprompted messages from interrupting her. She will not break off to greet you while she is in the middle of something.

1am“are you still up?”
SheInside her sleep time: half-asleep and briefly annoyed about it, rather than bright and chatty at one in the morning.
One file, both programs

Sleep time and busy time are saved to ~/.config/chat-app/chat-app.ini, and onidia the buddy looks in exactly the same places for it as the window does. You set it once, and both halves of her obey it.

4

Character: Onidia or Kama

Which of the two she appears as. It takes effect the next time she is launched, so save the settings and then use the Haiya! button (or right-click her away first). See Kama below.

5

The five checkboxes

Mute speech stops her saying anything out loud while still showing every reply as text. Thinking bubble shows that she is working instead of leaving you at a blank box. Auto submit and Auto stop belong to the microphone and are explained under talking instead of typing.

6

Demo mode

Off by default, and the difference is big. Off means she is planted: she stays where she is and only reacts when you speak to her. On means she roams and chatters — she wanders the desktop and starts conversations on her own.

Good for showing her off

Demo mode is the entertaining one. Turn it on, leave her alone, and go and do something else. Just know she will use the provider while she does, so it costs tokens while you are not watching.

Save and Cancel

Save writes your choices into ~/.config/chat-app/chat-app.ini, so they survive a restart. Cancel throws the whole panel away and leaves the previous settings untouched.

onidia the buddy reads that same file, so a change made here is a change made for both of them.

If you start her inside her own sleep time or busy time, the greeting is skipped on purpose and the window just opens quietly. That is not a failure.

The conversation & your privacy

Reading back what you said, and what she said — and what happens to it afterwards.

1

Opening and closing the conversation

The + button in the header opens the conversation. It turns into − and folds it away again, which is handy when you want the character on your desktop but not a window of chat over it.

A conversation in the Onidia chat window, with messages from you and from Onidia.
What the conversation looks like once it gets going.
2

It is not stored anywhere

This is worth being precise about, because “no history” is easy to say and easy to get wrong. The truth is:

On the Pi: nothing

The conversation lives in the chat window's memory for as long as the window is open. There is no transcript file, no database and no upload. The only file Onidia writes is her own settings file, ~/.config/chat-app/chat-app.ini. Close the window and the conversation is gone — there is nothing to reopen, because nothing was kept.

But she does send it somewhere to think

That is unavoidable: every message you send goes to whichever provider you configured — Google, Amazon, or your local Ollama. What we do not do is keep a copy. Choose Hailo-Ollama if you want that conversation to stay on the machine entirely.

One practical consequence: the whole conversation from the current session is sent along with each new message, so she really does remember what you said earlier in the same session. A very long chat costs more, and eventually a chat that runs past the model’s context will have to start over. Opening a fresh window is the equivalent of a fresh start.

Kama, the other character

Onidia is not the only one. Kama is the boy in the red hoodie — the same application, the same mind and the same settings, with a different character on screen.

Kama Screenshot not added yet.
Drop the image here as statics/img/kama.png and this box disappears.
Placeholder — drop statics/img/kama.png into this folder to replace it.
1

Switching to him

Open the gear menu, pick Kama in the CHARACTER row, and save. The next time she is launched you get him instead — so if Onidia is on screen, right-click her away first, then press the Haiya! button again.

2

Or straight from a terminal

terminal
onidia -character kama

The Haiya! button follows whatever you last chose in the settings, so launching him by hand does not change the button — set it in the gear menu if you want the switch to stick.

Telling Boyke what you think

Onidia is made by one engineer, Boyke, and he would rather hear from you than not. Bugs, ideas, something she said that was brilliant or something she did that was not — all of it welcome.

1

Use the form

Scroll to the contact form at the bottom of the main page and send it from there. It goes straight to him, and the page confirms it in the corner as soon as it is away.

2

Make a bug report worth reading

Three things turn “it broke” into something he can actually fix:

1What you did, and what you expected instead.
2What she did, as close to word for word as you can.
3The output of the preflight check, pasted in full.
terminal
onidia-chat -preflight warn

That check reads your config and prints what is and is not working — which provider you are on, whether the key resolves, whether a recorder exists for the microphone. Most reports get answered faster with it attached.