Toolpath

Know your tools. A tool-agnostic format for tracking artifact transformation provenance. Git blame, but for everything that happens to code — including the stuff git doesn't see.

$ cargo install toolpath-cli

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.

Toolpath records who changed what, why, what they tried that didn't work, and how to verify all of it.

Three core objects

Step

A single change to artifact(s) by one actor. One commit, one edit, one format pass.

Path

A DAG of steps with a base context. A PR, a coding session, a branch.

Graph

A collection of related paths. A release, a sprint, a project.

Steps form a DAG via parent references. Dead ends are implicit: steps not in the ancestry of path.head.

What Toolpath adds

What	Git	Toolpath
Who made the change	Single author per commit	Typed actors: `human:`, `agent:`, `tool:`, `ci:`
Why they changed it	Unstructured commit message	`meta.intent` + linked refs
Abandoned approaches	Lost when branch is deleted	Dead ends preserved in the DAG
Multi-actor provenance	Collapsed into one commit	Each actor gets their own step
Verification	GPG on whole commit	Scoped signatures: author, reviewer, CI
Granularity	Commit-level	Sub-commit: multiple steps between commits

Minimal example

A valid Toolpath document can be tiny:

{
  "Step": {
    "step": {
      "id": "step-001",
      "actor": "human:alex",
      "timestamp": "2026-01-29T10:00:00Z"
    },
    "change": {
      "src/main.rs": {
        "raw": "@@ -12,1 +12,1 @@\n-    println!(\"Hello world\");\n+    println!(\"Hello, world!\");"
      }
    }
  }
}

No parents (it's the first step). No meta. One file, one perspective. Still valid.

Quick start

# Install
cargo install toolpath-cli

# Derive provenance from this repo's git history
path derive git --repo . --branch main --pretty

# Visualize it
path derive git --repo . --branch main | path render dot | dot -Tpng -o graph.png

# Derive from Claude conversation logs
path derive claude --project /path/to/project --pretty

# Query for dead ends
path query dead-ends --input doc.json

# Filter by actor
path query filter --input doc.json --actor "agent:"

Workspace

Toolpath is a Rust workspace of focused crates:

Crate	What it does
`toolpath`	Core types, builders, query API
`toolpath-git`	Derive from git history
`toolpath-claude`	Derive from Claude conversations
`toolpath-dot`	Graphviz DOT visualization
`toolpath-cli`	Unified CLI (`cargo install toolpath-cli`)

See Crates for details, or docs.rs for API reference.