Files Explorer & Graph

The Files tab in XO Space: List, Graph, and Tree lenses with project drawers and safe in-place file previews.

The Files tab is one top-level home with three interchangeable lenses behind a List | Graph | Tree switch. It lands on List for operational browsing, offers Graph for cross-project relationships, and provides Tree for horizontal directory hierarchy.

The Files list: one row per project with counts, activity and descriptions

Three Lenses, One Tab

1. List Lens (Operational Directory)

The List lens gives every project under XO_PROJECTS_ROOT a dedicated operational row:

Project Metadata: Display name, description (extracted from project.json, README.md, PROJECT.md, or OBJECTIVES.md), and creation date.
Activity & Presence: Live badges indicating active agent sessions (Claude Code, OpenClaw, Hermes, Codex, Cursor) currently running in that directory.
Last Active: Timestamp sourced from normalized watcher timeline events.
Unscaffolded Badges: Folders lacking a project.json are still listed so no workspace code is hidden.

The Project Drawer

Clicking any project row opens a multi-panel slideout drawer:

A project drawer: two-pane file explorer beside todos, sessions and events

Files Panel: Path-safe folder-by-folder file explorer via GET /api/xo-projects/{id}/tree. Includes clickable breadcrumbs, file size indicators, item counts for subfolders, and modified timestamps.
Todos Panel: Lists open and completed tasks from portable todos.json.
Sessions Panel: Shows active and historical agent chat threads for that specific project.
Timeline Panel: Live stream of file modifications, additions, and deletions captured by the watcher.

Safe In-Place File Viewer

Clicking any file row in the Project Drawer, Tree lens, or Graph detail panel opens the safe in-place preview drawer:

The file previewer: rendered markdown in a side drawer over the tree

Markdown: Rendered with GitHub-flavored Markdown, headings, tables, task lists, and syntax blocks.
HTML: Rendered inside an isolated iframe with empty sandbox attributes (sandbox="") and zero same-origin access.
Code & Text: Escaped syntax display with line numbers and a 256 KB safety cap. Unsupported file types return a clean notice.
Raw Source Toggle: Toggle between rendered view and raw plaintext source at any time; press Esc to close immediately.
Graph Jump: Click the "Graph" button in the preview header to immediately fly to that file's node in the Graph lens.

Graph Lens (Relationship Network)

The Graph lens maps the workspace as projects, artifact clusters, and cross-project ties:

Cluster Expansion: Double-click clusters to expand or collapse child leaves.
Neighborhood Focus: Click a node to highlight its connected paths and dim unrelated areas.
Show on Timeline: Click "Show on timeline" to carry the selected run or artifact directly into the Timeline tab.

Data Sources & Safety

Endpoint	File / Store	Purpose
`GET /xo/space.json`	`<XO root>/.xo/space.json`	Atlas graph, tree, and project counts. Rebuilt by the watcher at most every 30s.
`GET /api/xo-projects`	Project directory scan	High-level project catalog paired with `/activity` and `/timeline`.
`GET /api/xo-projects/{id}/tree`	Project filesystem	Bounded, folder-by-folder file listing for the drawer explorer.
`GET /api/xo-projects/{id}/file`	Project filesystem	File content for the safe previewer (256 KB cap, suffix allowlist).

The Files tab is strictly read-only. It reads derived metadata and project structure, and never modifies project files, .xo, or .quirq files.