From Session Logs to a Live Village: How Agent Quest Works

Discover sessions through provider adapters

The server uses separate Claude and Codex providers. They locate supported session files and pass parsed events into a common flow. The Claude provider watches project logs from discovered configuration directories. The Codex provider scans its sessions tree for rollout files and reads new content as files grow.

In the reviewed implementation, the default polling intervals are two seconds for the Claude watcher and three seconds for the Codex scan. These are implementation settings, not guarantees about end-to-end display latency. File writes, parsing and browser updates add their own timing.

The providers retain source and configuration-directory identity. That matters when two installations produce similar-looking sessions: the system needs more context than a display name.

Turn log records into shared state

Provider-specific parsers interpret records and emit events the rest of the server can consume. The state layer represents agents with fields for identity, status and current activity. Reading, editing, commands and other recognized actions can then be handled consistently by the visualization.

A useful detail in the Codex provider is its treatment of partial writes during incremental reading. It processes complete newline-terminated records and holds an unfinished trailing record for a later scan. It advances the file offset by byte length, preserving the correct position when text contains multi-byte characters.

Those choices address file-following problems; they do not make log formats a permanent interface. Changes in a coding tool’s records can require corresponding parser updates.

Send snapshots and changes to the browser

The backend uses Bun and Hono, with WebSocket messages connecting it to the frontend. The client handles a snapshot plus events for new agents, state updates, completion and activity-log entries. React state drives panels such as the party bar and detail view.

The client also maintains a reconnect path when the WebSocket closes. A reconnected transport still needs current data to show an accurate picture. This is why troubleshooting should distinguish the HTTP health endpoint, the loaded web page and the live socket.

Map activity onto a visual place

The frontend combines React with a Phaser scene. Its building definitions associate activity categories with destinations: reading with the Library, editing with the Forge and shell commands with the Arena. An event bridge connects parts of the interface and scene.

This mapping compresses a stream of technical events into a spatial overview. The tradeoff is that a building cannot express everything in a command, result or conversation. The activity feed and detail panel preserve access to more context, while the original coding tool remains the place to inspect the full work.

To explore the implementation, start with the provider files, then follow the shared state and WebSocket messages into the client hook and building definitions. Use the linked source revision for this article; the main branch may evolve after publication.