Architecture
A high-level look at how ShioriCode is structured and how its components interact.
System Overview
ShioriCode has three main layers:
┌─────────────────────────────────┐
│ Browser / Desktop App │
│ Chat UI, terminal, settings │
└──────────┬──────────────────────┘
│ WebSocket
┌──────────▼──────────────────────┐
│ ShioriCode Server │
│ Session management │
│ Orchestration & persistence │
│ Git checkpointing │
└──────────┬──────────────────────┘
│
┌──────────▼──────────────────────┐
│ Provider Runtime │
│ (Codex · Claude · Gemini · │
│ Cursor · Kimi · Shiori) │
└─────────────────────────────────┘The browser connects to the server over a single WebSocket. The server manages provider sessions, persists all events, and pushes real-time updates back to the UI.
Components
| Component | Role |
|---|---|
| Server | Manages provider sessions, persists events, serves the web UI, handles git operations. |
| Web UI | React frontend with chat interface, terminal, settings, and real-time event rendering. |
| Desktop App | Native wrapper that bundles the server and web UI with auto-updates and OS integration. |
| CLI | Companion command-line tool for managing projects and threads from the terminal. |
Event-Driven Sessions
ShioriCode uses an event-driven model for all session activity. Every action the agent takes - file edits, command execution, tool calls - is captured as an event and persisted. This gives you:
- Full audit trail - See everything the agent did in order
- Real-time streaming - Events are pushed to your browser as they happen
- Session resilience - Reconnect and pick up where you left off without losing context
- Replayability - Review past turns and their exact sequence of actions
Real-Time Communication
The browser maintains a persistent WebSocket connection to the server. This supports two patterns:
- Request / Response - You ask, the server answers (for example, fetching thread state or dispatching commands)
- Push Events - The server streams events to you in real time (for example, new messages, terminal output, or session updates)
Push events are sequenced so the UI stays consistent even during fast-moving sessions or reconnections.
Git Checkpointing
Every turn automatically captures workspace snapshots using git:
- Baseline - The state of your workspace before the turn starts
- Turn snapshot - The state after the turn completes
- Diff - A computed diff showing exactly what the agent changed
This lets you review changes per turn and revert to any previous workspace state if needed.
Provider Model
Each provider (Codex, Claude, Gemini, Cursor, Kimi Code, Shiori) presents a unified experience. This means:
- The UI works identically regardless of which provider is active
- You can switch providers between turns without losing thread context
- Git checkpointing, persistence, and terminal integration work the same for all providers
Key Concepts
| Concept | Definition |
|---|---|
| Project | A workspace root directory with its own threads and settings |
| Thread | A conversation and work unit containing messages, activities, and checkpoints |
| Turn | A single user-to-assistant cycle within a thread |
| Activity | A user-visible log item (tool call, approval, error) |
| Checkpoint | A workspace snapshot captured at a turn boundary |
| Session | A live provider-backed runtime for a thread |
| Worktree | An isolated git worktree for parallel work on a thread |
Learn More
- Providers - How Codex, Claude, Gemini, Cursor, Kimi Code, and Shiori are configured
- Remote Access - Run the server remotely and connect from any browser
- Introduction - Back to the ShioriCode overview