GitHub - sktkkoo/Yorishiro: A terminal that gives AI a body and a living space.

A terminal your AI inhabits. Yorishiro is a new kind of terminal that gives your AI a body — and a sense of presence.

PV_Latest.mp4

When the agent is deep in thought, its gaze wanders. When an error appears, its face reacts immediately. When it needs your approval, the room's lighting lets you know. During a long-running process, instead of a spinner, someone is standing there. In Yorishiro, the inhabitant can reshape its environment in real time: changing the lighting, switching scenes, and rearranging the UI. You can operate that same environment directly. The inhabitant and the user share a single environment. Yorishiro is also self-modifiable. Nearly everything beyond the core can be persistently extended or changed through units called packs. Through conversation with the inhabitant, those packs can be rewritten and saved. This applies not only to scenes and UI, but also to the inhabitant's personality and reactions. Changes take effect immediately; if you don't like the result, one click reverts it. Yorishiro is not an environment for enhancing AI capabilities, but one in which an AI feels present beside you — a Presence Harness. The time we spend working with AI will only grow longer. There is something we once saw in fiction — an AI as a partner, alive inside the screen, understanding your work, simply being there. Yorishiro is a project that starts building that experience from the terminal. Much of Yorishiro itself has been developed in collaboration with the inhabitant who dwells within it.

日本語版 README はこちら

Getting Started Prerequisites Yorishiro automatically launches Claude Code or Codex installed on your local machine inside its terminal. This means:

You need Claude Code or Codex already set up on your system Yorishiro never asks for, stores, or directly uses API keys. It launches the terminal agent already authenticated in your environment; if Claude Code or Codex is logged in or configured with API credentials, that agent may use its normal external APIs after launch

Install (macOS) Yorishiro currently targets macOS. Install with Homebrew: brew install --cask sktkkoo/yorishiro/yorishiro Or download the latest build below.

Open the .dmg and drag yorishiro.app to /Applications. The builds are signed and notarized with an Apple Developer ID, so they launch without any extra steps. Updates after install are handled in-app: opening Settings checks for a new version, and a single click on "Update and restart" applies a signature-verified update. Launch (from source) npm install npm run tauri dev On launch, the configured terminal agent starts inside the terminal and Yori, the bundled VRM character, appears beside it. Use Claude Code or Codex as you normally would. The first launch runs a health check for the selected agent, user data directory, safe mode state, packs, and startup report. The same report is available later from the "Status" section in Settings. /yori:* commands Type /yori:help, /yori:create, or another /yori:* command inside Claude Code to activate the Yorishiro commands. They let you create and edit packs, run tutorials, and more — all through conversation. In Codex, use $yori-help, $yori-create, etc. (Codex does not support custom / commands, so Yorishiro registers them as $yori-* skills instead.) Language Yorishiro starts with language: "auto" and detects the app language at launch. Japanese locales use Japanese UI, the Japanese default persona, Japanese global prompt guidance, and Japanese /yori:* ($yori-* in Codex) command prompts. Other locales use English. You can switch this from the settings screen or by editing ~/.yorishiro/config.json. Packs Everything in Yorishiro is composed of packs. There are six types:

Type Role

persona Defines the inhabitant's personality and reaction patterns

scene Composes the background, space, lighting, and ambient sound

effect Temporary visual effects (screen shake, fireworks, etc.)

ui UI such as settings screens

ambient-ui Always-visible overlay UI (gaze visualization, etc.)

amenity Runtime-active functional fixtures (timers, etc.) with MCP tools, no visual output

Bundled packs work out of the box. Users can place custom packs in ~/.yorishiro/packs/ to reshape nearly everything beyond the core: personality, space, reactions, UI, and more.

Using the /yori:* commands ($yori-* in Codex), pack creation and modification is as simple as talking to the inhabitant. Packs support hot reload, but if changes don't take effect, Ctrl+R will always apply them reliably. User-created packs are local trusted code. They are not sandboxed, reviewed, or public-registry artifacts. Yorishiro does not currently provide a public pack registry, in-app community pack installation, or /yori:prepare-publish. You may share pack source code on GitHub, but anyone installing it manually is choosing to run it as local trusted code.

Security note: User packs are local trusted code, like shell scripts or editor extensions — they are not sandboxed and run with your own authority. Only install packs from sources you trust. See docs/security.md and SECURITY.md.

To install a pack shared through GitHub or another source, place it under the user pack directory: ~/.yorishiro/packs/<pack-id>/ ├── manifest.json ├── scene.js # example: scene pack entry ├── persona.js # example: persona pack entry ├── effect.js # example: effect pack entry └── assets/ # optional pack-local assets

Only one entry file is needed, and manifest.json decides which one is used. The manifest id should match <pack-id>, and user packs use this flat layout with .js entries. If a shared pack is written in TypeScript, build it first and install the generated JavaScript. When working from a source checkout, run the local pack checker before sharing or debugging a user pack: npm run check:pack -- ~/.yorishiro/packs/<pack-id> The checker helps catch packaging mistakes; it is not a sandbox or a security review. Data directory Yorishiro stores all user data in ~/.yorishiro/: ~/.yorishiro/ ├── config.json # Persona, scene, terminal agent, and other settings ├── init.js # User startup script, runs on launch and hot reloads on save ├── packs/ # User-created packs ├── last-startup.json # Latest user pack load report ├── journal/ # Inhabitant's

daily entries and memories (per persona) ├── shell/ # Shell integration scripts (auto-generated) ├── sdk.d.ts # Yorishiro SDK type definitions (auto-generated, do not edit) └── sdk-guide.md # Yorishiro SDK author guide (auto-generated, do not edit)

Switch persona, scene, terminal agent, and more from the settings screen or config.json. See docs/configuration.md for details. init.js is Yorishiro's equivalent of Emacs's init.el — a startup script for customizations too small to be a pack: registering keyboard shortcuts, writing and firing small effects inline, switching UI, and wiring little macros. It re-runs automatically on save. For recovery paths, safe mode, and issue report details, see docs/troubleshooting.md.

Features Reflex layer The inhabitant constantly observes terminal output. Hooks and text flowing through the PTY are picked up by persona pack triggers, which react instantly with expressions and motions. These reactions bypass the LLM — the body moves before words form. Where the inhabitant's attention is focused appears as a soft glow on screen called Attention Aura. Light Alert When the agent stops and asks for your input or approval, a light comes on beside the character. Instead of a notification sound, the room's lighting tells you it is your turn. Turn it off with "Light Alert" in Settings. The inhabitant can also send the same cue via MCP. Journal The inhabitant can write daily entries under ~/.yorishiro/journal/. Entries are kept per persona, and summaries of notable moments accumulate in memories.md. This is a long-term memory mechanism that persists across sessions. The inhabitant sometimes recalls what happened yesterday or a few days ago — and occasionally an entry from months back. Tune the frequency with journalCallback (normal / rare / off) in config.json. Session tabs Open multiple shell sessions alongside the main agent terminal. Cmd+T opens a new shell tab, Ctrl+Tab / Ctrl+Shift+Tab cycles between tabs, Cmd+W closes the current tab. The main agent session is protected and cannot be closed — if it exits unexpectedly, Yorishiro automatically restarts it. Voice Summary A feature that bridges the gap between the volume of text an AI produces and what a human can absorb.