diff --git a/site/_data/site.json b/site/_data/site.json index 95facb26..b2da0f99 100644 --- a/site/_data/site.json +++ b/site/_data/site.json @@ -1,5 +1,5 @@ { "title": "Toolpath", - "description": "A format for artifact transformation provenance", + "description": "The open, portable session format for coding agents", "repo": "https://github.com/empathic/toolpath" } diff --git a/site/css/style.css b/site/css/style.css index ee3a75af..40238052 100644 --- a/site/css/style.css +++ b/site/css/style.css @@ -376,6 +376,40 @@ color: var(--text-dim); } + /* --- Harness list (stamped mono chips) --- */ + .harness-list { + display: flex; + flex-wrap: wrap; + gap: var(--space-sm); + list-style: none; + margin: 1.25rem 0; + padding: 0; + } + .harness-list li { + font-family: var(--font); + font-size: 0.82rem; + letter-spacing: 0.03em; + padding: 0.45rem 0.8rem; + background: var(--bg-surface); + border: 1px solid var(--border); + transition: border-color 0.15s ease; + } + .harness-list li:hover { + border-color: var(--accent); + } + .harness-list li em { + font-style: normal; + font-size: 0.72rem; + color: var(--text-secondary); + } + .harness-list a { + color: inherit; + text-decoration: none; + } + .harness-list li:hover a { + color: var(--accent); + } + /* --- Tables --- */ table { border-collapse: collapse; @@ -612,7 +646,7 @@ /* --- Hero --- */ .hero { - padding: var(--space-2xl) 0 var(--space-xl); + padding: var(--space-lg) 0 var(--space-xl); border-bottom: none; margin-bottom: 0; display: flex; @@ -903,7 +937,7 @@ .hero { flex-direction: column; gap: var(--space-md); - padding: var(--space-xl) 0 var(--space-lg); + padding: var(--space-md) 0 var(--space-lg); } .hero h1 { font-size: 1.6rem; diff --git a/site/index.md b/site/index.md index 1133b72f..00c1f7fc 100644 --- a/site/index.md +++ b/site/index.md @@ -8,9 +8,9 @@ nav: home

Toolpath

- What happens between commits? Toolpath records the - decisions that get lost at merge time. Record, transform, and analyze - sessions in a tool agnostic way. + The open session format. What your coding agent did, + why, what it tried, and what it cost, in one portable schema. Read + it, query it, share it, resume it in any harness.

@@ -74,37 +74,70 @@ Explore Toolpath documents in your browser. Real path commands, rea ## The problem -When Claude writes code, `rustfmt` reformats it, and a human refines it, git -blame attributes everything to the human's commit. The actual provenance is -lost. Dead ends disappear. Tool contributions collapse into whoever typed `git -commit`. +Every coding agent writes its own undocumented session log. Claude Code +keeps rotating JSONL chains, Codex writes rollout files, Gemini has chat +directories, Copilot an event stream. The session that produced a change +is locked inside the harness that ran it, and that harness can change +its format at any time. -Toolpath records **who** changed **what**, **why**, what they tried that didn't -work, and how to verify all of it. +## One format for everyone's tools + +Toolpath is the open session format: every harness's sessions in one +portable schema that records **who** changed **what**, **why**, what +they tried that didn't work, and what it cost. + +One schema means tooling stops being per-agent. A cost dashboard, a +review surface, a search index, an archive: build it once against the +format and it works with sessions from every supported harness. And +when the next agent ships, one new parser brings it into every tool +you already have.

When you need it

-

Multi-actor PR

-

Claude wrote the implementation, rustfmt reformatted, you refined the - error messages. Toolpath gives each actor their own step so reviewers see - who did what.

+

Reduce review time

+

An agent wrote the diff, and the diff can't say why. Share the + session to Pathbase and link it + from the PR: reviewers see what was asked, what was tried and + rejected, and how the result was verified. The questions that + stall a merge get answered before they're asked.

-

Rotated AI session

-

Claude Code hit context limits mid-task and rotated to a new session. - Toolpath chains the segments together so no work is lost.

+

One query, every agent

+

Which sessions burned the most tokens? What did the agent try + before the fix that worked? path query answers it with + one jq filter across every session on the machine, whichever + agents wrote the logs.

-

Release lineage

-

Three teams contributed PRs to the release. Toolpath merges the - provenance into a single Graph so you can trace any line back to the - intent behind it.

+

Pick up where anyone left off

+

Start on your laptop, push the agent to a server. Hand a stuck + session to a teammate. Move a Claude Code session into Codex. + Wherever it lands, the next agent starts with everything the last + one knew: the intent, the state, the dead ends already ruled + out.

+## Parse in, project out + +Toolpath is open and versioned: the schema is published, and a document +that validates today will validate tomorrow. Harness formats are +neither. They are undocumented, proprietary, and change without notice. +So Toolpath treats them as boundaries around a stable center, and +everything it does is one of three moves across that boundary: + +- **Parse in.** A session crosses the boundary once and becomes a + stable document you can keep, query, and share. +- **Project out.** A document becomes the on-disk layout a target + harness expects. Any writable harness, not just the one the session + started in. +- **Resume.** A projection followed by a handoff: Toolpath writes the + session where the harness looks for it, then starts the harness on + it. + ## Three core objects
@@ -175,6 +208,29 @@ ancestry of `path.head`.
+## Supported harnesses + + + +Parsing captures the full session: prompts, tool calls, reasoning, +file changes, sub-agent work, token usage. Projecting writes a session +the harness accepts as its own, so it resumes natively. Where a +harness's log genuinely doesn't record something, the gap is +documented in the [format notes]({{ site.repo }}/tree/main/docs/agents/formats) +rather than papered over. + +Git history and GitHub pull requests parse into the same schema, so a +session, the PR it became, and the release that shipped it can share +one graph. + ## What Toolpath adds | What | Git | Toolpath | @@ -223,19 +279,19 @@ No parents (it's the first step). No meta. One file, one perspective. Every docu # Install cargo install path-cli -# Import provenance from this repo's git history (top-level surface is -# the porcelain; plumbing lives under `path p …`) -path p import git --repo . --branch main --no-cache --pretty +# Archive every agent session on this machine (all harnesses, incremental) +path p cache sync -# Visualize it -path p import git --repo . --branch main --no-cache | path p render dot | dot -Tpng -o graph.png +# Query across all of them with a jq filter, whichever agent produced them +path query 'map(select(.dead_end))' +path query 'map(select(.step.actor | startswith("agent:")))' -# Import from Claude conversation logs -path p import claude --project /path/to/project --no-cache --pretty +# Share a session, then resume it in the original harness or a different one +path share +path resume https://pathbase.dev/alex/pathstash/path-pr-42 --harness codex -# Query the local cache with a jaq (jq) filter — dead ends, or steps by an agent -path query 'map(select(.dead_end))' -path query --input doc.json 'map(select(.step.actor | startswith("agent:")))' +# Derive provenance from git history and visualize it +path p import git --repo . --branch main --no-cache | path p render dot | dot -Tpng -o graph.png ``` -## Workspace - -Toolpath is a Rust workspace of focused crates: - -| Crate | What it does | -| ---------------------------------------------------- | -------------------------------------- | -| [`toolpath`](https://docs.rs/toolpath) | Core types, builders, query API | -| [`toolpath-convo`](https://docs.rs/toolpath-convo) | Provider-agnostic conversation traits | -| [`toolpath-git`](https://docs.rs/toolpath-git) | Derive from git history | -| [`toolpath-github`](https://docs.rs/toolpath-github) | Derive from GitHub pull requests | -| [`toolpath-claude`](https://docs.rs/toolpath-claude) | Derive from Claude conversations | -| [`toolpath-dot`](https://docs.rs/toolpath-dot) | Graphviz DOT visualization | -| [`path-cli`](https://docs.rs/path-cli) | Unified CLI (`cargo install path-cli`) | - -See [Crates](/crates/) for details, or [docs.rs](https://docs.rs/toolpath) for API reference. +
+

Go deeper

+
+
+

Read the spec

+

The format stands alone: an RFC, a + JSON + Schema, and a dozen + example documents. + If Rust isn't your language, implement the schema in yours.

+
+
+

Build on the crates

+

Everything the CLI does is a library call: core types, a + provider crate per harness, renderers for DOT and Markdown. See + the crates or the + API reference.

+
+
+

Stay in Claude Code

+

/plugin install path@toolpath adds + /path:share and /path:query as slash + commands and installs the CLI on first use. See + the + plugin.

+
+
+