docs: reframe the README around the open session format - #178
Merged
Conversation
|
🔍 Preview deployed: https://2a173b23.toolpath.pages.dev |
Lead with what one schema across every harness buys — portability (share/resume across harnesses), unified query, normalized token accounting, provenance, a local archive — and put a per-source support matrix (read / write / resume, with fidelity notes) at the top. Also: add copilot and cursor to the show/list/import reference (they were missing), list all seven harnesses under p export, document p cache sync in the reference tree, add a read-a-session library example and a spec-only section for non-Rust consumers, and correct the examples count to 12.
Drop em dashes, arrow shorthand, and slogan-style bullets and headings in favor of plain sentences. Rename the tour back to Quick start.
The agent session formats are undocumented by their vendors and observed from specific versions; present docs/agents/formats/ as working notes with gaps rather than an authoritative reference.
Labeled sentences scan better than unbroken prose; order the bullets capture-and-push first.
The README keeps a one-line pointer under Documentation; the discussion of the format notes (what they cover, their caveats, the keep-in-sync expectation) moves to a new DEVELOPMENT.md alongside build and test instructions.
The point is that one tool works for every harness; path query is the demonstration, and jq is a detail of it.
The matrix now covers only the seven agent harnesses; git and GitHub move to a short Beyond sessions section framing Toolpath as a format for the whole development lifecycle graph.
Describe the just-driven dev loop (check/ci and the eight quality gates), the individual and release recipes, and keep the agent format notes section.
akesling
force-pushed
the
alex/readme-open-session-format
branch
from
August 12, 2026 15:38
69f8feb to
f256323
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reframes the README around what Toolpath is to someone arriving with a
session-persistence problem: an open format for coding-agent sessions,
one schema that records what an agent did, why, what it tried that
didn't work, and what it cost.
The repo tagline stays as an epigraph. The body opens with the
many-harnesses, many-undocumented-formats problem and what one format
makes possible: sharing and resuming a session across harnesses,
querying every session on the machine with one
path queryfilter,consistent token accounting, provenance with dead ends preserved, and a
local archive via
p cache sync.New sections
harnesses plus git and GitHub, with fidelity notes (Codex real diffs
and per-step attribution, Copilot resume verified in 1.0.67, opencode
snapshot diffs), and a pointer to the cross-harness conformance
matrix that exercises the pairs.
p cache sync, thenquery, thenshare, thenresume --harness codex, with the plumbing composition below it.token_usage/attributed_token_usage/breakdownsvocabulary, and why provider quirks (cumulativestreaming snapshots, stale counters, dropped reasoning tokens) are
handled at derivation time.
ClaudeConvotoderive_pathlibrary example, theConversationViewstory foradding a harness, and a mention of the watcher features.
example documents as a spec-only surface.
discussion of our agent-format notes under
docs/agents/formats/,presented as observed behavior rather than an authoritative
reference. The README keeps a one-line pointer.
Drift fixed while in there
The CLI reference had fallen behind the CLI:
show,p list, andp importwere missing copilot and cursorp exportlisted only claude and pathbase; all seven harnesses arewired
p cache syncwas absent from the reference treeexamples/said 11 documents; there are 12The pre-1.0 breakage note about the 0.10.0 plumbing move is gone from
the README entirely.
No behavior changes; README only. S3 / share-target content stays out
since that ships with #168.