Yorishiro Gives Coding Agents a Body

Yorishiro is an open-source macOS terminal by sktkkoo that gives coding agents a visible body and a shared room to work in. It deals with a very real problem: long sessions with agents can make state, waiting, errors, and approvals feel buried in scrollback. The practical takeaway is simple: whether you use Yorishiro or plain Codex CLI, make agent state and repo rules visible before the agent runs for a long time.

Yorishiro is a “presence harness”: a terminal environment where the active agent appears as a 3D character, reacts to state changes, and can reshape parts of the workspace. In plain English, openai codex agents.md best practices means keeping repository instructions small, scoped, and testable enough for OpenAI Codex, the coding agent and CLI from OpenAI, to follow during a real command-line workflow.

Watch the agent, not just the scrollback

Yorishiro’s interesting move is not that it adds a character to a terminal. It is that it treats agent state as part of the interface.

When the agent is thinking, the character’s gaze can wander. When an error happens, the face can react. When approval is needed, the room lighting can change. That sounds playful, but the engineering point is serious: a long-running agent session needs ambient status, not only logs.

This matters if you use Codex CLI for tasks like “upgrade this package and fix the tests.” The trap is pretending that a spinner, a stream of text, and a final diff are enough. They often are not, especially when the agent pauses on permissions, hits an error, or keeps working after your attention has moved elsewhere.

A small version of Yorishiro’s idea works in any repo. Add visible checkpoints to your workflow: plan, files touched, tests run, approvals requested, result. You do not need a 3D room to ask for that shape.

See why Hacker News noticed it

The project landed because it touches a feeling many developers recognize: coding agents are powerful, but they can be oddly tiring to supervise. The agent is “doing things,” yet you are still the one watching for drift, stale assumptions, risky commands, and unfinished verification.

Yorishiro’s README says the agent and user share a single environment. That is the core bet. The terminal is no longer just a window into an agent; it becomes the place the agent inhabits.

As of July 2026, the repository is mainly TypeScript, MIT licensed, and was last pushed on 2026-07-20. The README also describes “packs,” persistent units that can change scenes, UI, personality, and reactions through conversation, with immediate effect and a one-click revert.

That self-modifiable layer is both charming and dangerous. The good version is local customization that makes state easier to read. The bad version is an interface that can rewrite its own behavior until nobody knows which signal means “safe,” “blocked,” or “done.”

One Hacker News objection went straight at the practical concern: what does it cost to render a 3D model inside a terminal? That is the right question. Presence is useful only if it does not steal attention, battery, or trust from the coding work.

Keep Codex rules boring on purpose

The Codex lesson is not “add an avatar.” It is “make the contract visible.” For Codex CLI workflows, that contract usually starts in AGENTS.md, where repository rules, architecture constraints, and verification expectations live.

AGENTS.md is a repository instruction file that tells Codex how to behave in a project. Good codex agents.md best practices are deliberately plain: tell Codex what to avoid, how to verify, when to ask, and what evidence to return.

Here is a small AGENTS.md starter rule set for a repo using a Next.js app, Vitest, and a read-only production database boundary:

# AGENTS.md

## Working style
- Start with a short plan before editing more than one file.
- Prefer the smallest change that fixes the issue.
- Do not rename public APIs unless the task explicitly asks for it.

## Safety boundaries
- Never run destructive database commands.
- Treat production credentials, tokens, and customer data as out of scope.
- If a command asks for network access or elevated permissions, explain why first.

## Verification
- After code changes, run: npm test -- --runInBand
- If tests are too slow or unavailable, say exactly what was not run and why.
- Include the changed files and verification result in the final response.

## UI and agent-state notes
- Surface blocked states clearly: waiting for approval, failing test, missing context.
- Do not hide errors behind “retrying” unless the retry count and command are shown.

The trap is turning AGENTS.md into a policy novel. Codex is more likely to follow ten sharp rules than sixty vague wishes. If a rule cannot change a command, a diff, or a review decision, it probably does not belong there.

For more on CLI-oriented habits, keep this near the related training topic. It pairs well with visible-state experiments like Yorishiro because both are about reducing supervision fatigue.

Try Yorishiro when presence solves a real pain

Yorishiro is worth trying if you already run long agent sessions and lose track of what the agent is doing. It is also worth trying if you are building agent interfaces and want to explore ambient state instead of another chat panel.

It is probably overkill if your Codex work is short, synchronous, and review-heavy. For example, “write a failing unit test, patch one function, run the test” does not need a living room. A regular terminal plus a crisp final receipt is enough.

The best small experiment is one evening, one non-critical repo, one agent, and one task that normally takes long enough to make you tab away. Ask whether the visual state helped you intervene sooner. Do not ask whether the character was delightful; delight fades faster than reliable state.

There is a fun parallel in joydex Turns a Flight Throttle Into Codex Controls: physical or spatial controls can make agent work feel more legible. The useful part is not the novelty. It is the boundary between “the agent is acting” and “the human is approving.”

Copy this safe trial checklist

Use this checklist before giving Yorishiro, or any agent-facing terminal experiment, a real repo with consequences.

A good first task is dull on purpose: upgrade one dev dependency, fix any failing tests, and produce a final receipt. If the visual environment makes that easier to supervise, Yorishiro has earned another trial.

Common questions

• What are openai codex agents.md best practices in this context?

  They are the repo-level rules that make Codex behavior predictable during CLI work. Keep them short, scoped, and verifiable: safety boundaries, allowed commands, test commands, and final-response expectations. Yorishiro’s lesson is that rules and state should be visible before the agent spends twenty minutes wandering through a codebase.

• Is Yorishiro a replacement for Codex CLI?

  No, Yorishiro is a terminal environment for working with agents, not a new coding model. The project description mentions coding agents like Claude Code, Anthropic’s coding agent, and Codex. Treat it as an interface experiment around presence, state, and shared workspace, not as a substitute for the agent’s own capabilities.

• Does a 3D agent make coding safer?

  No, a 3D agent does not make coding safer by itself. Safety still comes from permissions, scoped instructions, tests, review, and clear handoff receipts. The interface can help if it makes blocked, risky, or failed states harder to miss; it can hurt if it makes the agent feel more trustworthy than it is.

• When is Yorishiro too much?

  Yorishiro is too much when the task is short, the repo is sensitive, or the visual layer distracts from review. A one-file bug fix with a known test command usually needs a plain terminal and a clean diff. Save presence-heavy tools for long-running sessions where supervision fatigue is the real cost.

• What should Codex return after a long CLI session?

  Codex should return a concise receipt: what changed, which files changed, which commands ran, and what still needs human attention. One useful pattern is “Plan, Diff, Verification, Risks.” That gives the reviewer enough context without replaying the whole conversation or trusting a vague completion message.

Best ways to use this research

• Best for: Developers exploring agent interfaces, Codex CLI users who run long tasks, and anyone curious about reducing supervision fatigue without giving up review.
• Best first artifact: A short AGENTS.md rule set with safety boundaries, a verification command, and a final receipt format.
• Best comparison angle: Compare Yorishiro against a normal terminal on state visibility, not charm: thinking, blocked, error, approval, and complete.
• Best limitation to remember: Presence is not permissioning. A friendly agent body still needs narrow access, testable instructions, and a human-readable diff.

Further reading

• OpenAI Developers — AGENTS.md guide
• OpenAI Developers — Codex quickstart
• Yorishiro — source

Try one visible-state experiment

Pick one safe repo, add the starter AGENTS.md, and run one long Codex task with explicit state checkpoints. If you try Yorishiro, judge it by whether you notice errors and approvals sooner, not by whether the room looks cool.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.