toonchat

Chat with cartoon characters using a local Ollama model, in your terminal or your browser.

toonchat looks the character up on Wikipedia (and optionally a Fandom wiki), has your model write a short personality profile from what it finds, then chats with you in that character's voice. Profiles are saved in ~/.toonchat, so the lookup only happens once per character.

Install

npm install -g toonchat
ollama pull llama3.2

Requires Node 18.17+ and Ollama running locally. No other dependencies.

Use

toonchat "SpongeBob SquarePants"            # chat in the terminal
toonchat "Patrick Star" --fandom spongebob  # also read spongebob.fandom.com
toonchat serve --open                       # chat in your browser at http://127.0.0.1:4747
toonchat list                               # characters you've already set up
toonchat delete Mario                       # delete a character's saved profile

In the browser you can also start a group chat: click "Group chat" above your cast, pick 2 to 4 characters, and they'll all talk with you and with each other. Say someone's name to ask just them, or click "Let them talk" to let the characters keep the conversation going on their own.

Characters remember past chats. When you end a chat or start a new conversation, toonchat writes a few notes about what you talked about, and the character brings them up next time. You can see and clear these in the Profile window, or with /profile in the terminal. They're stored on your computer in ~/.toonchat, so every device using the same toonchat serve shares them.

If a name can't be found online, toonchat says so and suggests close matches. You can also choose to make up a brand-new character with that name.

The first time you open toonchat serve, a guided tour teaches you how to use it: a welcome screen, then eight hands-on steps on the real page (start a chat, say hi, tap a quick reply, turn on voices, play a game, open a profile, build a character, try a group chat). Each step finishes when you actually do it, and then the page is all yours. Replay it any time with "Take the tour again" at the bottom of the sidebar.

The browser version is interactive:

• Every character has their own cartoon face that changes expression with what they say, and their mouth moves while they talk.
• 🎲 Games: play Trivia, 20 Questions, Guess My Thing, Would You Rather, Story Time or Riddles with any character, or with a whole group.
• Tap-to-reply suggestions appear after each reply, including the A/B/C answers in trivia.
• ✨ Build your own character: give them a name, a backstory, a way of talking, a catchphrase, likes and dislikes, set their personality with sliders (shy to outgoing, serious to silly, grumpy to cheerful and more), and design their face. You can also change the personality and look of any character in your cast from their Profile.
• 🎤 Talk instead of typing with the microphone button. Browsers only allow the microphone on http://localhost, so on an iPad use the keyboard's own microphone key instead.

📞 Call a character (or a whole group) for a hands-free chat: you talk, they answer out loud, and it listens again. Browsers only allow the microphone on localhost or https, so in network mode toonchat also runs a secure copy on the next port (4748) for iPads. The first time, Safari warns that the connection isn't private, because the certificate is made on your own computer: tap Show Details, then "visit this website".

Characters can talk out loud. In the browser, click "Voice" to have replies read aloud as they arrive, or click 🔊 next to any message. Each character gets their own natural-sounding voice (the Mac's joke voices like Zarvox are never picked automatically), and you can pick a different voice and pitch in their Profile. In the terminal, add --speak (macOS).

Online voices (optional). For much more natural voices, use ElevenLabs or OpenAI. Get an API key from their website, then run toonchat key elevenlabs YOUR_KEY (or toonchat key openai YOUR_KEY) and restart toonchat serve. A Voices menu appears in the sidebar, and each character's Profile lets you pick their voice. The key stays on your computer in ~/.toonchat/config.json, and the browser never sees it. Only the text being spoken is sent to that company. If a clip fails (for example, you've run out of credits), toonchat falls back to the device's voice. Remove a key with toonchat key remove elevenlabs.

A rude-word filter is on by default. Swear words and insults you type are blocked (the character never sees them and gently asks you to keep it kind), and any that slip into a character's reply are replaced with ****. Rude character names are refused too. To switch it off, start toonchat with --no-filter.

In the terminal, type /profile to see the character sheet, /reset to start over, or /quit to leave. Ctrl+C stops a reply mid-sentence.

Options

| Option | What it does | | --- | --- | | -m, --model <name> | Ollama model to use (default llama3.2, or $TOONCHAT_MODEL) | | -f, --fandom <wiki> | Also read a Fandom wiki, using the part before .fandom.com | | --refresh | Look the character up again and rebuild the profile | | -p, --port <n> | Port for serve (default 4747) | | --host <addr> | Address for serve (default 127.0.0.1; use 0.0.0.0 for other devices on your network) | | -o, --open | Open the browser when serve starts | | -s, --speak | Read replies aloud in the terminal (macOS) | | --no-find | With --host 0.0.0.0: don't let nearby devices find this computer | | --no-filter | Turn off the rude-word filter (on by default) |

Set OLLAMA_HOST if Ollama isn't at http://127.0.0.1:11434.

Using it on an iPad or phone

Start toonchat with toonchat serve --host 0.0.0.0. It prints an address ending in .local that never changes, which is the best one to bookmark. Or just open https://toonchat.pages.dev on the iPad: toonchat tells that site it's running on your Wi-Fi, so the site finds your computer and takes you there. To turn that off, add --no-find.

Tips

• Fandom wikis usually describe personalities in more detail than Wikipedia.
• Bigger models give a much better character voice: try -m llama3.1:8b or -m qwen2.5:7b.
• In the browser, conversations are saved per character, and you can switch models from the sidebar.

License

MIT