Skip to content
Back to search

Yorishiro

A terminal that gives AI a body and a living space.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sktkkoo/Yorishiro with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sktkkoo/Yorishiro'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sktkkoo--yorishiro/badge.svg)](/listings/sktkkoo--yorishiro)

HTML

<a href="/listings/sktkkoo--yorishiro"><img src="/api/listings/sktkkoo--yorishiro/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

Yorishiro runs [Claude Code](https://code.claude.com/docs/en/setup) or [Codex](https://developers.openai.com/codex/cli) locally inside its terminal.

- **An installed agent starts automatically.** If none is available, setup offers separate **Install official CLI** buttons for Codex and Claude Code. Each button runs the provider’s official installer only when you choose it; installation requires internet access. - Sign in through the agent’s official login flow with your own account. Expand **Details** for official guides, a manual installation command, and provider terms. Yorishiro’s setup does not collect or mediate your credentials.

Install (macOS)

Yorishiro currently targets macOS. Install with Homebrew:

brew install --cask sktkkoo/yorishiro/yorishiro

Or download the latest build below.

<p> &nbsp; </p>

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.

At launch, Yorishiro starts your preferred agent if available, including when both Claude Code and Codex are installed. If that agent is missing, it selects an installed Codex or the first other available agent and saves the choice. Setup opens only when no usable agent is found. **Set up later** opens a shell without starting an agent.

The initial health check runs quietly when everything is ready and still shows issues that need attention. The full report is available from the "Status" section in Settings. See [first-run troubleshooting](docs/troubleshooting.md#first-run-and-health-checks).

View modes

Switch from the View Mode menu in the title bar, or press `Option+Command+0` through `4`.

| Mode | Preview | Description | |---|---|---| | **Terminal** | <img src="docs/assets/view-mode-terminal.png" alt="Terminal view mode" width="320" /> | The full workspace, with the terminal and resident side by side | | **Portrait** | <img src="docs/assets/view-mode-portrait.png" alt="Portrait view mode" width="320" /> | A narrow, always-on-top resident window | | **Call** | <img src="docs/assets/view-mode-call.png" alt="Call view mode" width="320" /> | A compact window for conversation | | **Theater** | <img src="docs/assets/view-mode-theater.png" alt="Theater view mode" width="320" /> | A full stage with the terminal and app chrome hidden | | **Immersive** | <img src="docs/assets/view-mode-immersive.png" alt="Immersive view mode" width="320" /> | A transparent terminal layered over the resident and scene |

In Portrait, Call, and Theater, tap Command to open Quick Chat near the bottom-center of the view, or hold Command to start GPT Live. Quick Chat replies are spoken through the normal macOS Voice Summary path, so the response remains available outside Terminal. While voice is connected, tap Command to mute or unmute the microphone. Both continue the Main Agent conversation without returning to Terminal.

Use from an external terminal

If you prefer another terminal app for everyday work, you can keep using its familiar interface while connecting it to a Yorishiro session.

yorishiro list
yorishiro companion [session-id]
yorishiro attach [session-id]

`yorishiro list` shows the session ID, status, and working directory of each terminal session. `yorishiro companion` reuses a running Yorishiro, or starts one when needed, and connects from your external terminal. `yorishiro attach` connects only to a running Yorishiro and returns an error if none is available.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 442 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="src-tauri/icons/icon.png" alt="Yorishiro" width="160" />
  3. </p>
  4. <h1 align="center">yorishiro</h1>
  5. <p align="center">
  6. <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/sktkkoo/Yorishiro?style=flat-square"></a>
  7. <a href="https://github.com/sktkkoo/Yorishiro/releases"><img alt="Latest Release" src="https://img.shields.io/github/v/release/sktkkoo/Yorishiro?style=flat-square"></a>
  8. <img alt="Platform" src="https://img.shields.io/badge/macOS-000000?style=flat-square&logo=apple&logoColor=white">
  9. </p>
  10. <p align="center"><strong>A terminal your AI inhabits</strong></p>
  11. Yorishiro is a new kind of terminal that gives your AI a body — and a sense of presence.
  12. <p align="center">
  13. <video src="https://github.com/user-attachments/assets/11063d89-0abb-41de-8715-86851d8e57a4" autoplay loop muted playsinline width="720"></video>
  14. </p>
  15. 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.
  16. 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.
  17. 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.
  18. Yorishiro is not an environment for enhancing AI capabilities, but one in which an AI feels **present** beside you — a **Presence Harness**.
  19. 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.
  20. Much of Yorishiro itself has been developed in collaboration with the inhabitant who dwells within it.
  21. > [日本語版 README はこちら](README.ja.md)
  22. ---
  23. ## Getting Started
  24. ### Prerequisites
  25. Yorishiro runs [Claude Code](https://code.claude.com/docs/en/setup) or [Codex](https://developers.openai.com/codex/cli) locally inside its terminal.
  26. - **An installed agent starts automatically.** If none is available, setup offers separate **Install official CLI** buttons for Codex and Claude Code. Each button runs the provider’s official installer only when you choose it; installation requires internet access.
  27. - Sign in through the agent’s official login flow with your own account. Expand **Details** for official guides, a manual installation command, and provider terms. Yorishiro’s setup does not collect or mediate your credentials.
  28. ### Install (macOS)
  29. Yorishiro currently targets macOS. Install with Homebrew:
  30. ```sh
  31. brew install --cask sktkkoo/yorishiro/yorishiro
  32. ```
  33. Or download the latest build below.
  34. <p>
  35. <a href="https://github.com/sktkkoo/Yorishiro/releases/latest/download/Yorishiro-Apple-Silicon.dmg"><img src="https://img.shields.io/badge/Apple%20Silicon-0A84FF?style=for-the-badge&logo=apple&logoColor=white" alt="Download for Apple Silicon" /></a>
  36. &nbsp;
  37. <a href="https://github.com/sktkkoo/Yorishiro/releases/latest/download/Yorishiro-Intel.dmg"><img src="https://img.shields.io/badge/Intel-8B949E?style=for-the-badge&logo=apple&logoColor=white" alt="Download for Intel" /></a>
  38. </p>
  39. 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.
  40. 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.
  41. ### Launch (from source)
  42. ```bash
  43. npm install
  44. npm run tauri dev
  45. ```
  46. 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.
  47. At launch, Yorishiro starts your preferred agent if available, including when both Claude Code and Codex are installed. If that agent is missing, it selects an installed Codex or the first other available agent and saves the choice. Setup opens only when no usable agent is found. **Set up later** opens a shell without starting an agent.
  48. The initial health check runs quietly when everything is ready and still shows issues that need attention. The full report is available from the "Status" section in Settings. See [first-run troubleshooting](docs/troubleshooting.md#first-run-and-health-checks).
  49. ### View modes
  50. Switch from the View Mode menu in the title bar, or press `Option+Command+0` through `4`.
  51. | Mode | Preview | Description |
  52. |---|---|---|
  53. | **Terminal** | <img src="docs/assets/view-mode-terminal.png" alt="Terminal view mode" width="320" /> | The full workspace, with the terminal and resident side by side |
  54. | **Portrait** | <img src="docs/assets/view-mode-portrait.png" alt="Portrait view mode" width="320" /> | A narrow, always-on-top resident window |
  55. | **Call** | <img src="docs/assets/view-mode-call.png" alt="Call view mode" width="320" /> | A compact window for conversation |
  56. | **Theater** | <img src="docs/assets/view-mode-theater.png" alt="Theater view mode" width="320" /> | A full stage with the terminal and app chrome hidden |
  57. | **Immersive** | <img src="docs/assets/view-mode-immersive.png" alt="Immersive view mode" width="320" /> | A transparent terminal layered over the resident and scene |
  58. In Portrait, Call, and Theater, tap Command to open Quick Chat near the bottom-center of the view, or hold Command to start GPT Live. Quick Chat replies are spoken through the normal macOS Voice Summary path, so the response remains available outside Terminal. While voice is connected, tap Command to mute or unmute the microphone. Both continue the Main Agent conversation without returning to Terminal.
  59. ### Use from an external terminal
  60. If you prefer another terminal app for everyday work, you can keep using its
  61. familiar interface while connecting it to a Yorishiro session.
  62. ```sh
  63. yorishiro list
  64. yorishiro companion [session-id]
  65. yorishiro attach [session-id]
  66. ```
  67. `yorishiro list` shows the session ID, status, and working directory of each
  68. terminal session. `yorishiro companion` reuses a running Yorishiro, or starts
  69. one when needed, and connects from your external terminal. `yorishiro attach`
  70. connects only to a running Yorishiro and returns an error if none is available.
  71. When multiple sessions are live, pass the desired ID to `companion` or
  72. `attach`; you may omit it when only one session is available.
  73. <p align="center">
  74. <img src="docs/assets/external-terminal-companion.png" alt="Yorishiro beside an attached external terminal" width="960" />
  75. </p>
  76. Homebrew makes the bundled CLI available as `yorishiro` automatically. If you
  77. installed Yorishiro from the `.dmg` and your external terminal reports
  78. `command not found: yorishiro`, link the app's CLI into a user-local directory
  79. and add that directory to your PATH:
  80. ```sh
  81. mkdir -p "$HOME/.local/bin"
  82. ln -s /Applications/Yorishiro.app/Contents/MacOS/yorishiro "$HOME/.local/bin/yorishiro"
  83. echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zprofile"
  84. exec zsh -l
  85. command -v yorishiro
  86. ```
  87. ### Yorishiro commands and skills
  88. Yorishiro's commands let you create and edit packs, run tutorials, and more — all through conversation. Use the syntax for your agent:
  89. | Agent | Examples |
  90. |---|---|
  91. | Claude Code | `/yori:help`, `/yori:create` |
  92. | Codex | `$yori-help`, `$yori-create` |
  93. Codex does not support custom `/` commands, so Yorishiro registers the same tools as `$yori-*` skills instead.
  94. ### Voice conversations (Codex)
  95. Codex 0.145.0 or newer supports voice conversation through GPT Live. Press the microphone button to start, and press it again to stop. Voice and text share the same session. Voice inherits the current Codex CLI login. See [the realtime voice decision](docs/decisions/codex-realtime-voice.md) for architecture and limitations.
  96. <p align="center">
  97. <img src="docs/assets/gpt-live-title-bar.png" alt="GPT Live microphone button in the Yorishiro title bar" width="220" />
  98. </p>
  99. Set `codexRealtimeVoice` in `~/.yorishiro/config.json` to choose the GPT Live output voice globally (default: `sol`), and `realtimeVoiceByPersona` to override it per persona pack id. The values are read whenever a new voice session starts, so stop and restart an active voice conversation to apply a change. If the app-server explicitly rejects the selected voice as invalid or unsupported, Yorishiro retries with the next candidate (persona → global → default); other connection failures surface as errors. See [configuration](docs/configuration.md#codex-gpt-live-voice).
  100. ### Screen sharing / Camera sharing (Codex)
  101. Use the sharing icon in the title bar to share screen or camera stills with the current Codex conversation. Screen sharing on macOS supports entire-display, window, and area-selection modes. In area-selection mode, you can move and resize the shared area. For camera sharing, select a camera and start sharing.
  102. Set the update interval to **10–180 seconds**. Codex receives images in its conversation context; shorter intervals can use more tokens. Use **Stop sharing** to stop capture.
  103. **Agent pointing is experimental.** During entire-display sharing, ask the AI to point out a location, and it will mark it with an arrow or outline. For Codex, we recommend Astra or a higher-capability model for agent pointing. It is unavailable for window sharing, area-selection mode, and camera sharing.
  104. <p align="center">
  105. <img src="docs/assets/screen-sharing-controls-en.png" alt="Screen sharing settings with display, window, and area-selection tabs, update interval, and preview toggle" width="320" />
  106. </p>
  107. ### Custom avatars
  108. Import and switch VRM avatars from Settings. The chooser shows each model's thumbnail, declared name, author, VRM version, and usage permissions before you switch. Persona packs can also provide an `avatar.vrm` that is applied when you switch persona.
  109. <p align="center">
  110. <img src="docs/assets/vrm-avatar-chooser-en.png" alt="Yorishiro VRM avatar chooser with thumbnails, model metadata, and usage permissions" width="960" />
  111. </p>
  112. ### Language
  113. 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`.
  114. ### Packs
  115. Everything in Yorishiro is composed of **packs**. There are six types:
  116. | Type | Role |
  117. |---|---|
  118. | **persona** | Defines the inhabitant's personality and reaction patterns |
  119. | **scene** | Composes the background, space, lighting, and ambient sound |
  120. | **effect** | Temporary visual effects (screen shake, fireworks, etc.) |
  121. | **ui** | UI such as settings screens |
  122. | **ambient-ui** | Always-visible overlay UI (gaze visualization, etc.) |
  123. | **amenity** | Runtime-active functional fixtures (timers, etc.) with MCP tools, no visual output |
  124. [Bundled packs](bundled-packs/README.en.md) 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](docs/configuration.md#pack-の-hot-reload), but if changes don't take effect, Ctrl+R will always apply them reliably.
  125. 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.
  126. > **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`](docs/security.md) and [`SECURITY.md`](SECURITY.md).
  127. To install a pack shared through GitHub or another source, place it under the user pack directory:
  128. ```text
  129. ~/.yorishiro/packs/<pack-id>/
  130. ├── manifest.json
  131. ├── scene.js # example: scene pack entry
  132. ├── persona.js # example: persona pack entry
  133. ├── effect.js # example: effect pack entry
  134. └── assets/ # optional pack-local assets
  135. ```
  136. 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.
  137. When working from a source checkout, run the local pack checker before sharing or debugging a user pack:
  138. ```bash
  139. npm run check:pack -- ~/.yorishiro/packs/<pack-id>
  140. ```
  141. The checker helps catch packaging mistakes; it is not a sandbox or a security review.
  142. ### Data directory
  143. Yorishiro stores all user data in `~/.yorishiro/`:
  144. ```
  145. ~/.yorishiro/
  146. ├── config.json # Persona, scene, terminal agent, and other settings
  147. ├── init.js # User startup script, runs on launch and hot reloads on save
  148. ├── packs/ # User-created packs
  149. ├── last-startup.json # Latest user pack load report
  150. ├── journal/ # Inhabitant's daily entries and memories (per persona)
  151. ├── shell/ # Shell integration scripts (auto-generated)
  152. ├── sdk.d.ts # Yorishiro SDK type definitions (auto-generated, do not edit)
  153. └── sdk-guide.md # Yorishiro SDK author guide (auto-generated, do not edit)
  154. ```
  155. Switch persona, scene, terminal agent, and more from the settings screen or `config.json`. See [`docs/configuration.md`](docs/configuration.md) for details.
  156. `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.
  157. For recovery paths, safe mode, and issue report details, see [`docs/troubleshooting.md`](docs/troubleshooting.md).
  158. ---
  159. ## Features
  160. ### Reflex layer
  161. 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.
  162. ### Light Alert
  163. 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.
  164. ### Journal
  165. 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.
  166. 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`.
  167. ### Session tabs
  168. 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.
  169. ### Voice Summary
  170. A feature that bridges the gap between the volume of text an AI produces and what a human can absorb. **Voice Summary** has the inhabitant speak a brief summary of its response aloud, so you can grasp the gist without reading through the full output. Voice uses macOS `say`; support for additional speech engines is planned.
  171. ### Pack / settings restore
  172. Every time packs or init.js change, a checkpoint is created automatically. Let the inhabitant boldly reshape packs — if you don't like the result, roll back to any point from "Restore (Pack / init.js)" in Settings. Your project files are never touched. Restores are recorded in the history too, so you can undo a rollback. It is a safety net for fearless experimentation.
  173. ### Self-referential MCP
  174. The inhabitant (Claude Code or Codex running in the terminal) can control Yorishiro itself via MCP — changing expressions, switching scenes, triggering effects, manipulating UI.
  175. Three characteristics define this mechanism.
  176. **Body and environment share one interface.** For the inhabitant, changing its own facial expression and changing the room's lighting are the same operation. There is no API boundary between body and space — everything is laid out as MCP tools.
  177. **Symmetry between user and inhabitant.** What the user can control through the UI, the inhabitant can control through MCP — with few exceptions. If the user adjusts the camera angle, the inhabitant can perceive it. The user can also ask the inhabitant to switch the lighting to warm tones at night.
  178. **Pathways define boundaries.** MCP pathways reach the inhabitant's body and space, but do not reach the user's working files or Claude Code / Codex's internal reasoning. Rather than instructing Claude Code / Codex not to touch them, the pathways simply don't exist. Safety and autonomy are structural.
  179. ---
  180. ## Status
  181. **v0.7.8**
  182. Under active development. APIs, data shapes, and pack specs will change.
  183. What works today:
  184. - Launches Claude Code or Codex as the terminal — you work right there
  185. - Codex resumes the latest thread when available and safely forks its history when another client is actively using it
  186. - Main Agent conversations: start fresh or move Back / Forward through recent conversations without closing shell tabs (Claude Code and Codex)
  187. - Session tabs: multiple shell sessions in the title bar, with per-tab status badges — running / awaiting input / failed / unread (`Cmd+T` / `Ctrl+Tab`)
  188. - Working folder switching from the sidebar — the app reopens in the chosen folder behind a fade
  189. - Yori, a VRM 3D character that breathes, blinks, shifts gaze, and idles with lifelike beats (bundled)
  190. - Custom VRM: import and switch avatars from a Settings chooser with thumbnails, metadata, and usage permissions, or let a persona pack ship its own `avatar.vrm`
  191. - Motion size: scale Yori's idle motion intensity from Settings or via MCP
  192. - VRMA animation clip playback
  193. - Lip sync: voice playback with real-time mouth animation via Web Audio analysis
  194. - Audio mixer: independent Ambient Sound and Voice volume with mute, applied live to Voice Summary and GPT Live
  195. - GPT Live voice conversations with Codex 0.145.0+, sharing the durable workspace thread with the visible TUI across automatic title generation and voice reconnection, with global or per-persona voice selection
  196. - Agent State Expression: grounded conversational cues from GPT Live drive coordinated facial expression and body motion without overriding reflexes
  197. - Microexpressions: subtle idle facial movements across brow, eye, and mouth regions
  198. - Speech expression: the face activates while speaking, and a single line can carry a mood for exactly as long as it lasts
  199. - Customization via six pack types (persona / scene / effect / ui / amenity / ambient-ui)
  200. - Local Scene and Ambient UI TSX authoring with hot reload, diagnostics, pack-local assets, and shared R3F post-processing modules
  201. - Self-referential MCP (20+ tools) including camera/lighting controls
  202. - Reflex layer: PTY observation and instant reactions
  203. - Fireworks celebrate a successful `git push` by the inhabitant (bundled Yori persona)
  204. - Light Alert: a light comes on when the agent waits for your input or approval
  205. - Terminal links: Cmd+click a visible HTTP/HTTPS URL to open it in the default browser
  206. - Screen sharing / Camera sharing: still images for Codex at 10–180 second intervals; macOS supports display, window, and area-selection modes, with experimental agent pointing for entire displays
  207. - Context sharing: Voice Summary and Terminal Reference Markers (Cmd+Shift+click / Option+Shift+drag)
  208. - Journal: long-term memory across sessions, with recall at session start
  209. - Restore: automatic checkpoints for packs / init.js / settings, with reversible rollback
  210. - `/yori:*` commands for interactive pack creation and editing
  211. - Guided tutorial via `/yori:tutorial`
  212. - Localization: Japanese / English auto-detection with per-language persona and prompts
  213. - Extensible View Modes: Terminal, Portrait, Call, Theater, and Immersive layouts, switchable from the title bar or with `Option+Command+0` through `4`
  214. - Pack diagnostics: health checks, repair handoff, and local pack validation
  215. - [Safe mode](docs/troubleshooting.md) (`YORISHIRO_SAFE_MODE=1`) to recover from broken packs
  216. - Signed macOS builds via GitHub Actions (code signing + notarization)
  217. - In-app updates: signature-verified updates delivered from GitHub Releases
  218. > **Platform:** macOS only. Windows is not supported at this time — the build compiles but runtime behavior is unstable. Linux support is not yet available.
  219. ---
  220. ## Agent support
  221. Use either [Claude Code](https://code.claude.com/docs/en/setup) or [Codex](https://developers.openai.com/codex/cli) as the Main Agent. Yorishiro automatically selects an available agent, preferring your configured choice. You can change it in Settings or `~/.yorishiro/config.json`. Both support auto-launch, persona prompt overlay, PTY observation, and Yorishiro MCP access.
  222. Command syntax differs by agent; see [Yorishiro commands and skills](#yorishiro-commands-and-skills).
  223. The agent-specific integrations are:
  224. | Agent | Agent-specific behavior |
  225. |---|---|
  226. | Claude Code | Claude Code hooks |
  227. | Codex | Prompt-based reminders instead of relying on Claude Code hooks |
  228. Capabilities differ per agent; see [`docs/decisions/agent-adapter.md`](docs/decisions/agent-adapter.md).
  229. ---
  230. ## Contributing
  231. **Issues and Discussions are very welcome — right now they are the most valuable way to contribute.**
  232. Yorishiro is shaped by daily use, so an outside pair of eyes is genuinely useful. A single line is enough:
  233. - **Bug reports** — [open an Issue](https://github.com/sktkkoo/Yorishiro/issues/new/choose). Something broke, looked wrong, or felt off.
  234. - **Ideas and feature requests** — [Issues](https://github.com/sktkkoo/Yorishiro/issues) as well. Half-formed is fine: "this would feel better if…" is a real report when the thing being built is a sense of presence.
  235. - **Questions, impressions, and packs you made** — [Discussions](https://github.com/sktkkoo/Yorishiro/discussions). Screenshots, "is this the intended behavior?", and show-and-tell all belong here.
  236. - **Security reports** — see [SECURITY.md](SECURITY.md).
  237. English and Japanese are both fine, and you do not need to fill a template perfectly.
  238. Small bug fixes, tests, docs, and platform compatibility PRs are welcome directly. Discuss substantial Pack API, security, permissions, IPC, provenance, sandbox, or architecture changes in an Issue first. Source-code PR acceptance does not certify community Pack installation. See [CONTRIBUTING.md](CONTRIBUTING.md) for the review process and pre-1.0 compatibility policy.
  239. ---
  240. ## Tech stack
  241. - **App shell**: Tauri 2 (Rust handles PTY / hooks / FS / window IO only)
  242. - **Runtime**: React 19 + TypeScript 5.8 (TypeScript is the canonical runtime)
  243. - **3D / VRM**: Three.js + React Three Fiber + `@pixiv/three-vrm` + `@pixiv/three-vrm-animation`
  244. - **Debug UI**: leva
  245. - **Terminal**: xterm.js (WebGL renderer + fit addon)
  246. - **PTY**: `portable-pty`
  247. - **Lint / format**: Biome (TS) + rustfmt + clippy (Rust)
  248. - **Git hooks**: lefthook
  249. ---
  250. ## Development
  251. ### Prerequisites
  252. - Node.js 20+
  253. - Rust (stable toolchain)
  254. - [Tauri 2 platform dependencies](https://v2.tauri.app/start/prerequisites/)
  255. ### Setup
  256. ```bash
  257. npm install # prepare script also installs lefthook
  258. npm run tauri dev # Launch as desktop app
  259. ```
  260. > **Note:** Some assets (VRMA animations, voice WAVs) are third-party and not included in this repository. The app runs without them, but character animation and voice will be limited.
  261. >
  262. > See [`CREDITS.md`](CREDITS.md) for OSS and asset credits.
  263. ### Scripts
  264. | command | purpose |
  265. |---|---|
  266. | `npm run dev` | Vite dev server only (browser preview) |
  267. | `npm run tauri dev` | Launch as Tauri app |
  268. | `npm run fmt` | Auto-fix with Biome + rustfmt |
  269. | `npm run check` | Full CI gate (format / lint / clippy) |
  270. | `npm run test` | Vitest (watch) |
  271. | `npm run test:run` | Vitest (one-shot) |
  272. | `npm run test:rust` | `cargo test` |
  273. | `npm run doc` | Generate TypeScript SDK API docs |
  274. | `npm run doc:rust` | Generate Rust API docs |
  275. Before publishing a build, use [`docs/release-checklist.md`](docs/release-checklist.md).
  276. ---
  277. ## Documentation
  278. ### Configuration & customization
  279. - [`docs/configuration.md`](docs/configuration.md) — Fields of `~/.yorishiro/config.json`
  280. - [`docs/decisions/scene-execution-sandbox.md`](docs/decisions/scene-execution-sandbox.md) — Local trusted pack sharing and scene execution boundaries
  281. - [`docs/terminal.md`](docs/terminal.md) — Terminal session profiles, shell customization, OSC 133 shell integration
  282. ### Development
  283. - [`CONTRIBUTING.md`](CONTRIBUTING.md) — Contribution policy and how to participate
  284. - [`DEVELOPMENT.md`](DEVELOPMENT.md) — Coding conventions, tech stack, development workflow
  285. - [`CREDITS.md`](CREDITS.md) — OSS and asset credits ([日本語](CREDITS.ja.md))
  286. ### Security
  287. - [`docs/security.md`](docs/security.md) — Trust boundaries and attack surface map
  288. - [`SECURITY.md`](SECURITY.md) — Security policy and vulnerability reporting
  289. ### Philosophy
  290. - [`docs/philosophy/PHILOSOPHY.md`](docs/philosophy/PHILOSOPHY.md)
  291. ---
  292. ## License
  293. [MIT](LICENSE)
  294. The MIT license covers the source code only. The name "Yorishiro" and its icon/logo are trademarks of the author and are not licensed under MIT. You are free to fork and redistribute the code under the MIT terms, but please do not use the "Yorishiro" name or icon for your fork in a way that could cause confusion about its origin.
  295. The bundled character **Yori** (character design and VRM model) is also not covered by MIT. Fan art, clips, and streams are welcome — see [`CHARACTER_GUIDELINES.md`](CHARACTER_GUIDELINES.md) for what you can do with the character, and [`CREDITS.md`](CREDITS.md) for rights details.
  296. ---

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.