---
title: "onescope"
url: https://recursiveai.org/onescope/
description: "A viewer for deterministic libraries, for .NET 10. Open a scene, snapshot or replay, or attach to a running program: scrub its history, inspect any entity, compare runs and fork from any frame. In a window or headless. Open source, MIT or Apache-2.0. 1.0.0."
---

# onescope

A viewer for deterministic libraries. Open a scene, snapshot or replay, or attach to a running program, and watch the world: scrub its history, inspect any entity, compare runs, and fork from any frame to poke at it.

**Open source**, MIT or Apache-2.0, made by Recursive AI. Version 1.0.0 is on NuGet, for .NET 10. One shell, one module per library; the [onephysics](https://recursiveai.org/onephysics/) and [onepath](https://recursiveai.org/onepath/) modules are bundled. Everything the window does is also a command-line operation and a Model Context Protocol tool, so an agent can drive it the same way.

```sh
dotnet tool install --global RecursiveAI.OneScope.Tool
```

- [Getting started](https://recursiveai.org/onescope/docs/getting-started/)
- [Docs](https://recursiveai.org/onescope/docs/)
- [GitHub](https://github.com/recursive-ai-oss/onescope-csharp)
- [NuGet](https://www.nuget.org/packages/RecursiveAI.OneScope.Tool)

## A quick look

A OnePhysics replay scrubbed back and forth: contact normals and the limits of a hinge, a slider and a cone joint, at any step, exactly.

Recorded with onescope 1.0.0.

[Source on GitHub](https://github.com/recursive-ai-oss/onescope-csharp)

Open a replay headless, seek to a step, inspect the world and capture a frame. Each operation prints its result as one line of JSON.

The frame is from a run of the 1.0.0 tool from NuGet on a 240-step [onephysics](https://recursiveai.org/onephysics/) replay: five balls on the ground at step 120, in a 2D and a 3D view, with the inspector, the timeline and the event log. Getting started has the program that recorded it and the full output.

*Terminal · shell*

```
onescope open run.oppr --headless \
  --run 'seek {"step":120}' \
  --run 'inspect {"entity":1}' \
  --run 'capture_frame {"path":"frame.png"}'
```

[Getting started](https://recursiveai.org/onescope/docs/getting-started/)

*frame.png, step 120 of 240 · capture_frame*

```

```

## A step index, and the library’s own hash

From the README:

> Time is a step index. Seeking to step *k* lands on exactly the state that playing straight to *k* gives, however you got there, and the world hash it reports is the library’s own. A fork re-simulates from the original’s bits, records each poke into its own replay, and shows where it diverges. The original file and the running program are never changed.

Attached to a running program through its probe, forked from the live frame, then a body dragged in the fork. The original is untouched, and

diff

names where the two part.

- [Live attach](https://recursiveai.org/onescope/docs/live-attach/)
- [Time, history and forks](https://recursiveai.org/onescope/docs/history/)

### Scrub and inspect

An entity tree, an inspector, 2D and 3D scene views, and a timeline with a track per source, plus an event log and a compare panel.

### Fork and poke

Fork any source at any step, poke the fork, step it, and find where it diverges. Forks hang below the timeline as branches; in a window, drag a body in a fork to poke it.

### Compare

A fork against its original, or two versions of a library on one replay, each module in its own load context.

### Watch a running program

A host calls `RecursiveAI.OneScope.Probe` once, and the shell attaches to its live stream. The probe never blocks or throws into the host.

### Headless and scriptable

Every operation takes and returns JSON, from the window, the command line or the Model Context Protocol. Headless captures are byte-identical from run to run on one renderer.

### Add a library

A module built on `RecursiveAI.OneScope.Sdk` describes a world as data. The library never depends on onescope; the module lives in the library’s repository.

## Two builds of a library on one replay

In the README’s words: “Compare two versions of a library on one replay, each module in its own load context.”

One replay played by two builds of the same module, each in its own load context, stepped to the first divergence at step 300. The difference shows in the compare panel and agreement track, not in the picture.

- [Compare in the docs](https://recursiveai.org/onescope/docs/shell/#compare)

## Navigation meshes, crowds and flow fields

The [onepath](https://recursiveai.org/onepath/) module is bundled with the physics one: in the README’s words, “physics and navigation files open with no extra options.”

A navigation mesh build stepped stage by stage, a crowd on the timeline, and a flow-field search stepped by iteration.

- [Bundled modules](https://recursiveai.org/onescope/docs/shell/#bundled-modules)

## Drive it over the Model Context Protocol

`onescope open <file> --live <socket>` serves the operations on a Unix socket, and `onescope mcp --socket <socket>` bridges it to stdio. The README’s client configuration:

*Client configuration · JSON*

```
{ "mcpServers": { "onescope": { "command": "onescope", "args": ["mcp", "--socket", "/tmp/onescope.sock"] } } }
```

The same operations a window or an agent over the Model Context Protocol uses, from the command line against a headless shell. Output is shortened with an ellipsis; the two pictures are the files the capture commands wrote.

- [Getting started](https://recursiveai.org/onescope/docs/getting-started/)
- [Every operation](https://recursiveai.org/onescope/docs/shell/)

## Status and packages

- **Tool**: `RecursiveAI.OneScope.Tool`: the `onescope` command and shell, a [onegame](https://recursiveai.org/onegame/) program. A window on Linux, macOS and Windows, or headless.
- **Bundled modules**: `RecursiveAI.OnePhysics.Scope` 1.1.0 for [onephysics](https://recursiveai.org/onephysics/) 1.0.0, and `RecursiveAI.OnePath.Scope` 1.0.0 for [onepath](https://recursiveai.org/onepath/) 1.2.0. Other modules load from a path with `--module`.
- **Sdk**: `RecursiveAI.OneScope.Sdk`: the module contract, the draw list and the time model. BCL only; AOT and trim safe.
- **Probe**: `RecursiveAI.OneScope.Probe`: what a host calls to stream a replay. BCL only; AOT, trim and WebAssembly safe.
- **Attach**: `RecursiveAI.OneScope.Attach`: the viewer side of a probe, and the `.oscope` session file. BCL only.
- **Status**: 1.0.0, all four packages: the first stable release. Earlier versions were 0.x previews.
- **.NET**: .NET 10, C#. MIT or Apache-2.0.

## Go further

- [GitHub](https://github.com/recursive-ai-oss/onescope-csharp)
- [NuGet](https://www.nuget.org/packages/RecursiveAI.OneScope.Tool)
- [Getting started](https://recursiveai.org/onescope/docs/getting-started/)
- [All docs](https://recursiveai.org/onescope/docs/)
- [Live attach](https://recursiveai.org/onescope/docs/live-attach/)
- [Writing a module](https://recursiveai.org/onescope/docs/module-authoring/)
- [Changelog](https://recursiveai.org/onescope/docs/changelog/)