Session OS
Session OS is Jarvis’s session coordination layer. It gives the chat workspace a stable way to launch, discover, inspect, replay, and hand off work across Claude Code, Codex, and OpenCode sessions.
Definition
Section titled “Definition”Session OS is the subsystem that turns individual coding runtime processes into durable session records with status, history, and control surfaces.
It covers two session types:
- Managed sessions are launched from Jarvis. Jarvis knows who launched them, which runtime they use, and how to send follow-up work.
- Local runtime sessions were started outside Jarvis, usually in a terminal. Jarvis can discover them and surface their state without requiring you to relaunch the work.
Why It Exists
Section titled “Why It Exists”Coding agents are useful, but raw terminal sessions are hard to supervise once you have more than one running at a time. Session OS exists so you can:
- keep active work visible from one chat workspace
- compare managed and externally started sessions in one list
- resume work without pasting full terminal logs back into chat
- let workers ask for help when they hit a blocker or need a decision
- recover context after page reloads, reconnects, or short-lived runtime failures
Without Session OS, orchestration quickly collapses into manual terminal switching and ad hoc copy-paste.
How It Works
Section titled “How It Works”Session OS combines several behaviors:
-
Launch or discovery Jarvis either starts a managed session itself or discovers a compatible local runtime session that already exists on the machine.
-
Normalization Runtime-specific details are mapped into a shared session model so Claude Code, Codex, and OpenCode can be shown through one UI.
-
Status tracking Each session is continuously represented as a user-facing state such as running, waiting, blocked, or idle.
-
Low-noise visibility Jarvis does not inject full terminal streams into the main chat. Instead, it keeps the chat informed through summary capsules and worker MCP reporting tools.
-
Human handoff When a worker needs a decision, Jarvis routes that request back to the main chat so you can answer once and keep the session moving.
-
Replay and follow-up You can reopen a session, inspect what happened, and dispatch more work without reconstructing the entire thread from scratch.
Common Session States
Section titled “Common Session States”- Running
- Agent is actively producing output or executing work.
- Waiting
- Agent is waiting for a tool, model, or external process.
- Blocked
- Agent needs human input or cannot proceed safely.
- Idle
- Session is available but not currently progressing.
- Human
- A user decision or remote response is needed.
- Agent
- A worker or brain session reported state through MCP.
Managed vs. Local Runtime Sessions
Section titled “Managed vs. Local Runtime Sessions”| Session type | How it appears | What Jarvis usually knows | Typical use |
|---|---|---|---|
| Managed session | Started from Jarvis UI | runtime, launch intent, session metadata, follow-up control | New work you want Jarvis to supervise end to end |
| Local runtime session | Discovered after it already exists | runtime identity and observable state, with control depending on runtime and attachment safety | Ongoing work you started manually and now want to inspect or bring under supervision |
Failure Modes
Section titled “Failure Modes”Session OS is designed to degrade gracefully, but a few failure modes matter:
- Runtime unavailable: the CLI exists in theory, but Jarvis cannot launch or attach to it from the current machine state.
- Discovered but not controllable: Jarvis can see a local runtime session, but safe follow-up control is limited.
- Status drift: a runtime can stop responding before the UI catches up, so a session may briefly look active until discovery or cleanup logic reconciles it.
- Missing progress reports: a worker may continue running even when no MCP report arrives for a while. In that case, the summary capsule becomes the main source of truth.
- Human decision bottleneck: a worker can remain blocked until someone answers the question or dispatches the next instruction.
The important design point is that loss of one signal does not erase the session record. Jarvis keeps the session visible even when one control path is degraded.