Toshi — a terminal companion

A tiny AI companion that lives beside your terminal, wearing the community-ready Toshi mascot from tinyhumansai/mascots. It watches your gitlawb/zero coding session and you can talk to it about what's happening — what changed, why a test is red, what to do next — through a small, token-cheap context instead of a full chat UI.

Not a new mascot. We take the already-open-source Toshi model (PR #2, merged) and give it tools: a zero plugin + an MCP server + a side-panel that renders the real Rive mascot.

What it is

• Rides on gitlawb/zero — Zero is the runtime (Go, MIT, MCP client and server). Toshi is a plugin (./.zero/plugins/toshi/) plus a stdio MCP server so any MCP client (Claude Desktop, Cline, …) can call it.

• The mascot on the side — panel/index.html is a WebView that loads the real toshi.riv from the tinyhumans manifest and drives its state machine (idle · look_around · pointing · hand_wave · dancing · celebration, plus the eye channel). It's the face; the MCP is the brain.

• Token-cheap by design — session awareness comes from DeusData/codebase-memory-mcp (MIT): a persistent knowledge graph of the repo, ~99% fewer tokens than reading files one by one. Toshi asks it what changed instead of re-reading the tree, so most turns stay small.

• You sign, always — any money action is descriptor-only: Toshi prepares a transaction, you sign it. No custody.

Related MCP server: Total Recall

Layout

toshi/
├── panel/index.html      the side-panel WebView (renders the real Toshi mascot + talk-to-session)
├── mcp/toshi-mcp.mjs      the MCP server (toshi_status / toshi_ask / toshi_mood) + the /ask bridge the panel calls
├── plugin/plugin.json     the gitlawb/zero plugin manifest
├── tinyhumans/mascots.json pinned copy of the upstream manifest (the mascot contract we consume)
├── ATTRIBUTION.md         upstream credits + licences
└── LICENSE                GPL-3.0 (the Toshi mascot is GPL-3.0, so this is too)

Run it

The floating companion (Clippy-energy) — one command launches the mascot window and its brain:

npm install          # once
npm run toshi        # a frameless, always-on-top Toshi floats bottom-right, over any terminal

Launch from anywhere (Windows · macOS · Linux) — npm i -g . once, then just type toshi in any repo and it floats over that terminal, reading that repo. Windows also has a double-clickable toshi.bat. Drag Toshi by its header; hide it with ✕. It greets you with a wave, floats + blinks on its own, reacts when you ask, and bursts into a celebration when it has a grounded answer from your repo.

Make its answers real — index your repo so toshi_ask reads the graph instead of guessing (token-cheap):

# get codebase-memory-mcp (MIT, local, no telemetry), then:
codebase-memory-mcp cli index_repository '{"repo_path":"/abs/path/to/your/repo"}'
# tell Toshi where the repo + binary are (optional; defaults to cwd / PATH):
export TOSHI_REPO=/abs/path/to/your/repo
export CODEBASE_MEMORY_BIN=/abs/path/to/codebase-memory-mcp

Until then Toshi runs in honest demo mode — the mascot is fully alive, and it says it can't read your session yet (with the exact index command) rather than inventing an answer.

Give Toshi a voice + chat (optional) — install zero and run zero setup with any provider (free/local models like ollama work). Toshi then speaks its grounded answers in your language — 1-3 warm sentences synthesized ONLY from what it retrieved, never invented — and it can just chat like a normal assistant when your message isn't a repo question (a greeting, small talk, a general "how do I…"). Chat replies are clearly conversation, not invented repo facts. No zero? Point Toshi at any OpenAI-compatible endpoint instead (see below). TOSHI_LLM=off disables both voice and chat.

Change Toshi's brain model

Toshi talks through any OpenAI-compatible chat endpoint. Two ways to wire it — env vars, or the toshi model command.

1. Point it at a provider. Either give a full explicit endpoint, or just drop in a provider key you already have and Toshi auto-maps it:

Keys are read from your environment and from a local .env — they never leave the process, and are never committed.

2. Choose the model — persisted to ~/.toshi.json, no env editing needed:

toshi model minimax/minimax-m3   # pick a model (saved to ~/.toshi.json)
toshi model                      # show the current model
toshi model --clear              # back to the provider default

Model resolution order: TOSHI_API_MODEL (env) → toshi model (~/.toshi.json) → the provider default above.

Example — MiniMax M3 via OpenRouter (what Phil runs):

export OPENROUTER_API_KEY=sk-or-...     # your OpenRouter key
toshi model minimax/minimax-m3          # the exact OpenRouter model id

The model id must be the exact slug OpenRouter lists on the model's page at openrouter.ai/models — copy it verbatim (e.g. minimax/minimax-m3, minimax/minimax-m2, deepseek/deepseek-r1:free). A wrong slug just makes the model call fail and Toshi falls back to its structural/greeting answer, so nothing breaks — it just won't speak.

New to OpenRouter? Step-by-step first-key guide (get a key → place it → verify it → pick a model, with copy-paste for Windows / mac / Linux and a troubleshooting table): docs/openrouter-key.md.

Put the CLI everywhere

The same three files run on Windows, macOS and Linux (CI-proven on all three):

Honest status

• v0, unaudited. The panel + mascot rendering are real; the MCP's "answer about your session" is a skeleton that bridges to codebase-memory-mcp — wire your model/provider before trusting its answers.

• The Rive runtime and the .riv load over the network in a real browser/WebView. Vendor them for offline use.

• Licence: GPL-3.0 (the upstream Toshi mascot is GPL-3.0; a derivative must match it). See ATTRIBUTION.md.

Credits

Mascot Toshi by tinyhumans (GPL-3.0). Session memory by codebase-memory-mcp (MIT). Runtime gitlawb/zero (MIT).