Trajectory

Trajectory normalizes coding-agent session transcripts into stable, versioned
records you can store, search, replay, evaluate, train on, and observe.

One product. Three native packages. The same wire contracts and conformance
suite in every ecosystem.

Optional OpenTelemetry packages: Hypabolic.Trajectory.OpenTelemetry,
@hypabolic/trajectory-otel, hypabolic-trajectory-opentelemetry.

Releases use the git tag as the version (same model as Hypa): push
vX.Y.Z and CI stamps packages, publishes NuGet/npm/crates, and creates a
GitHub Release. See docs/publishing.md.

Published vs this tree: Registry packages at 0.1.0 include Pi, Claude
Code, Codex, OpenClaw, and Hermes only. AHP Shape A offline snapshot ingest
is implemented in this repository tip and will ship under the next
synchronized package version (a new tag after v0.1.0). Install unversioned
commands resolve to latest published 0.1.0 until that cut.

What you get

• Multi-source ingest — Pi, Claude Code, Codex, OpenClaw, Hermes, and AHP
  (Shape A offline ChatState snapshots; AHP is in-tree on main / next release — see note above)
• Deterministic normalization — stable IDs, ordering, hashes, content-safe
  diagnostics
• Multiple outputs from one decode: Hypabolic trajectory, canonical
  identity, compact message arrays, OpenAI chat messages, minimal JSONL, and
  optional OpenTelemetry GenAI spans
• Local store listing with explicit roots and pagination
• Partial / chunked input where the source supports append-only sessions
• Native AOT–friendly .NET, ESM TypeScript (Node 22+), Rust 2024 (MSRV 1.85)

Install

# .NET
dotnet add package Hypabolic.Trajectory
# optional: dotnet add package Hypabolic.Trajectory.OpenTelemetry

# TypeScript
npm install @hypabolic/trajectory
npm install @hypabolic/trajectory-node   # local listing
# optional: npm install @hypabolic/trajectory-otel

# Rust
cargo add hypabolic-trajectory
# optional: cargo add hypabolic-trajectory-opentelemetry

Usage examples

Trajectory is two steps:

1. Find sessions in the agent’s local store (listing APIs know default roots)
2. Normalize the transcript bytes into projections

You only pass a raw path when you already have one (export, upload, pipe).
For “what’s on this machine?”, use listing first.

.NET — list, then normalize

using Hypabolic.Trajectory;

// Discover Claude Code sessions under the default root (~/.claude/projects)
var page = await TrajectoryConverter.ListClaudeCodeTrajectoriesAsync(limit: 20);
var session = page.Items[0]; // Path, Id, UpdatedAt, …

byte[] transcript = await File.ReadAllBytesAsync(session.Path);
var engine = TrajectoryEngine.CreateDefault();

var ir = engine.NormalizeToIR(new NormalizeInput
{
    Source = TrajectorySource.ClaudeCode,
    Transcript = transcript,
});

var hypabolic = engine.Project<HypabolicTrajectoryV1>(
    ir, OutputSchemaIds.HypabolicTrajectoryV1);
var canonical = engine.Project<LettaCanonicalResult>(
    ir, OutputSchemaIds.LettaCanonicalV1);
var messages = TrajectoryConverter.NormalizeTranscript(
    TrajectorySource.ClaudeCode, transcript);

Same idea for any source (ListPiTrajectoriesAsync, ListCodexTrajectoriesAsync,
or ListTrajectoriesAsync(TrajectorySource.OpenClaw)). Pass root: to override
the default store. Codex partial/chunked input can still set GroupId and
BaseByteOffset when you feed append-only slices.

TypeScript — list (Node), then normalize

import { readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import {
  normalizeToHypabolic,
  normalizeToCanonical,
  normalizeToLetta,
} from "@hypabolic/trajectory";
import { listClaudeCodeTrajectories } from "@hypabolic/trajectory-node";

// Node listing package — pass the store root (defaults are not assumed)
const page = await listClaudeCodeTrajectories({
  root: join(homedir(), ".claude", "projects"),
  limit: 20,
});
const session = page.items[0]; // id, path, updatedAt, sizeBytes

const transcriptBytes = readFileSync(session.path);
const request = {
  source: "claude-code" as const,
  transcriptBytes,
  sourceContext: { partial: false },
};

const hypabolic = normalizeToHypabolic(request);
const canonical = normalizeToCanonical(request);
const messages = normalizeToLetta(request); // compact message trajectory

Also: listPiTrajectories, listCodexTrajectories, listOpenClawTrajectories.

Rust — list, then normalize

Rust listing always takes an explicit root (no home-directory default in
the library; the sample CLI applies the usual ~/.claude/projects etc.).

use std::fs;
use std::path::Path;
use hypabolic_trajectory::{
    list_claude_code_trajectories, normalize_claude_code, project_canonical,
    project_hypabolic, ListingOptions, NormalizeRequest,
};

let page = list_claude_code_trajectories(&ListingOptions {
    root: Path::new("/home/you/.claude/projects"),
    limit: 20,
    cursor: None,
})?;
let session = &page.items[0]; // id, path, updated_at, size_bytes

let bytes = fs::read(&session.path)?;
let ir = normalize_claude_code(NormalizeRequest {
    transcript: &bytes,
    ..Default::default()
})?;
let hypabolic = project_hypabolic(&ir)?;
let canonical = project_canonical(&ir)?;

Also: list_pi_trajectories, list_codex_trajectories, list_openclaw_trajectories
with matching normalize_* helpers.

Supported sources

Override listing roots with --root / TRAJECTORY_<SOURCE>_ROOT in the sample
CLIs, or pass an explicit root to listing APIs.

Sample CLIs (try your local sessions)

Unpublished developer tools that list agent stores on disk and normalize a
selected session into a privacy-safe summary (counts, roles, tools,
diagnostics—no transcript body by default).

Commands (same shape in all three)

Shared flags:

Run examples

# .NET — list Claude Code sessions, then show a fixture
dotnet run --project dotnet/samples/Trajectory.Cli -- list --source claude-code --limit 10
dotnet run --project dotnet/samples/Trajectory.Cli -- show \
  --source pi \
  --path conformance/cases/pi/tool-calls/input.jsonl
dotnet run --project dotnet/samples/Trajectory.Cli -- browse --source codex

# TypeScript
cd typescript && npm ci && npm run build
node packages/trajectory-cli/dist/cli.js list --source pi
node packages/trajectory-cli/dist/cli.js show \
  --source pi \
  --path ../conformance/cases/pi/tool-calls/input.jsonl \
  --format hypabolic
node packages/trajectory-cli/dist/cli.js browse

# Rust
cargo run -p trajectory-cli --manifest-path rust/Cargo.toml -- list --source codex
cargo run -p trajectory-cli --manifest-path rust/Cargo.toml -- show \
  --source hermes \
  --path conformance/cases/hermes/tool-calls/input.json
cargo run -p trajectory-cli --manifest-path rust/Cargo.toml -- show \
  --source ahp \
  --path conformance/cases/ahp/tool-calls/input.json

Notes

• Empty or missing stores exit successfully with a clear message.
• Hermes listing in core returns empty (no SQLite dependency); export JSON and
  show --path.
• AHP listing is Phase 3; normalize Shape A snapshots with show --path.
• These CLIs are not published NuGet/npm/crates packages.

How it works

native source bytes
  → source decoder
  → shared normalization policy
  → private intermediate representation
  → versioned output adapters

Implementations are independent per language. Behaviour is locked by shared
contracts (contracts/) and executable cases (conformance/).

Repository layout

contracts/     versioned schemas and behavioural specifications
conformance/   shared fixtures, goldens, verify.py, private runners’ protocol
dotnet/        libraries, tests, AOT smoke, sample CLI
typescript/    npm packages, tests, sample CLI
rust/          crates, conformance binary, sample CLI
docs/          architecture, authoring, contributing, publishing
tools/         release and npm bootstrap helpers

Build from source

.NET

dotnet restore dotnet/Trajectory.sln
dotnet build dotnet/Trajectory.sln -c Release --no-restore
dotnet test dotnet/tests/Trajectory.Tests/Trajectory.Tests.csproj -c Release --no-build

TypeScript

cd typescript && npm ci && npm run typecheck && npm test

Rust

cargo test --manifest-path rust/Cargo.toml --workspace --locked

Shared conformance

dotnet build dotnet/tests/Trajectory.Conformance/Trajectory.Conformance.csproj -c Release
python3 conformance/verify.py --repository-root . -- \
  dotnet dotnet/tests/Trajectory.Conformance/bin/Release/net10.0/trajectory-conformance.dll

See conformance/README.md for case authoring and all
runners.

Contributing

We welcome issues and PRs that improve adapters, fixtures, docs, and packaging.

1. Read Contributing for setup, PR checklist, and
   fixture privacy rules.
2. For new agent sources or output formats, follow
   Authoring sources and outputs (multi-runtime)
   and the .NET adapter seams when on C#.
3. Behaviour changes need shared conformance cases reviewed by hand—never
   auto-accept goldens in CI.

Compatibility promises

• Identity-bearing output bytes do not change under the same normalizer contract
  version (0.2.0 today).
• Diagnostics are typed and content-safe by contract.
• Capabilities are advertised only after shared cases pass.
• Pre-1.0 package versions stay synchronized across ecosystems.

Documentation

License

MIT — see LICENSE.