Harness session history

<!-- translations:start -->

한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end --> Tesserae can import local AI-agent transcripts and render them as project memory under the static site's sessions/ section.

This feature is intentionally separate from export harness:

• export harness is outbound context for tools such as Claude Code, Codex, Gemini, Cursor, Kiro, and OpenCode.
• sessions ... is inbound history: it normalizes prior Claude Code/Codex sessions for the current project, stores them under .tesserae/harness_sessions/, and lets export site publish session index/detail pages.

Two ways in: batch import and live monitoring

Session ingestion is no longer batch-only. There are two paths into the same normalized store:

• Batch import — sessions discover/import scans transcript roots on demand and writes one-shot. This page documents that flow below.
• Live monitoring — the supervisor daemon (tesserae engine) runs a SessionTailer that watches this project's own Claude Code and Codex transcripts and ingests new turns as they land. Each tick seeks to a persisted per-file byte offset, reads only the new bytes, and stores complete turns into the SQLite HarnessSessionsDB (.tesserae/sqlite.db) before enqueuing a debounced recompile, so the compile always reads consistent state. The tailer is scoped to the project's own sessions (Claude projects/<slug>/*.jsonl; Codex filtered by cwd) and resumes from stored offsets after a restart without replaying turns.

Run the live loop with:

tesserae engine        # watch sources, coalesce bursts, auto-recompile
tesserae engine --once # single drain cycle then exit (deterministic)

tesserae refresh runs the same ingest → compile → project pipeline once, in-process, without starting the long-lived watcher (pass --skip-sessions to skip the harness-session discovery scan).

Privacy model

Both ingestion paths are explicit: the live tailer only runs while you keep tesserae engine alive, and batch discovery only writes with --import. A normal tesserae compile or tesserae export site reads already-normalized sessions from .tesserae/harness_sessions/ and the live records in .tesserae/sqlite.db, but it does not surprise-scrape private harness transcript directories on its own.

Imported session records are local project artifacts. Review them before publishing a public site, especially if your transcripts may include secrets, private paths, customer data, or unreleased code.

Discover and import local sessions

From the project root:

tesserae sessions discover --import

Discovery scans local Claude Code and Codex transcript roots that belong to the current project working directory. Use --root to scan a specific config directory, and repeat --harness to limit discovery:

tesserae sessions discover \
  --root ~/.claude \
  --root ~/.codex \
  --harness claude-code \
  --harness codex \
  --import

Without --import, discovery prints what it found without writing normalized session records.

Import normalized JSON directly

If another tool has already produced normalized HarnessSession JSON, import one file or a list of files:

tesserae sessions import path/to/session.json path/to/more-sessions.json

Each input may contain one session object or a list of session objects.

List imported sessions

tesserae sessions list

Sessions are stored below:

.tesserae/harness_sessions/
  manifest.json
  <harness>/
    <session>.json
    <session>.md

Live-monitored sessions are additionally tracked in the SQLite HarnessSessionsDB (.tesserae/sqlite.db), which also persists the per-file read offsets the tailer resumes from. tesserae sessions list reports the combined view.

Build the static session pages

After importing sessions, rebuild the site:

tesserae export site

The site emits:

.tesserae/site/sessions/index.html
.tesserae/site/sessions/<project>/<session>.html

The generated site links Sessions from the global rail, the home Browse cards, search entries, and each session detail page's breadcrumb trail.

Fast transcript search (memex)

When you tesserae serve the site, the sessions dashboard gains a full-text search box over every indexed Claude/Codex transcript, backed by MD1 (BM25). Results show project · role · date · score plus a matching snippet.

cargo install --git https://github.com/nicosuave/memex --locked   # or: tesserae config deps --install memex
memex index                                                        # build the index once
tesserae serve                                                     # search box appears on /sessions

It is optional and graceful: with no memex binary (or index) the box shows a clear, actionable message and the rest of the dashboard is unaffected. The search endpoint (GET /api/transcript-search) is gated to same-origin/loopback callers so a visited web page can't probe your local history.

Session detail page layout

Session detail pages use the shared static-site shell rather than a standalone transcript dump. They include:

• hero and stat strip;
• high-level summary;
• timeline and size metadata;
• decisions, files, commands, tools, and errors when present;
• collapsed subagent tree;
• turn-by-turn user/assistant conversation;
• collapsed tool-use blocks attached under the preceding assistant turn;
• a left conversation rail that links to #turn-N anchors.

Conversation markdown is rendered through the site markdown renderer. Semantic surfaces such as inline code, explicit command/tag markup, paths, filenames, and hashtags are decorated as compact chips; random capitalized nouns are not auto-chipped.

Current transcript typography:

Publishing checklist for sessions

Before deploying a public site that includes sessions:

1. Run tesserae sessions list and confirm the count is expected.
2. Inspect .tesserae/harness_sessions/ for sensitive content.
3. Rebuild with tesserae export site.
4. Open sessions/index.html and at least one session detail page locally.
5. Confirm tool blocks are collapsed by default and raw tool payloads are acceptable to publish.
6. Deploy with tesserae export site --deploy once the source tree is committed.