{"id":48289335,"url":"https://github.com/empathic/toolpath","last_synced_at":"2026-04-04T23:01:20.661Z","repository":{"id":338883137,"uuid":"1156327639","full_name":"empathic/toolpath","owner":"empathic","description":"The story of how we got here","archived":false,"fork":false,"pushed_at":"2026-03-30T14:49:54.000Z","size":487,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T16:35:30.862Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/empathic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T14:24:33.000Z","updated_at":"2026-03-11T14:26:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/empathic/toolpath","commit_stats":null,"previous_names":["empathic/toolpath"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/empathic/toolpath","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empathic%2Ftoolpath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empathic%2Ftoolpath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empathic%2Ftoolpath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empathic%2Ftoolpath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/empathic","download_url":"https://codeload.github.com/empathic/toolpath/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empathic%2Ftoolpath/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31418286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T23:01:14.317Z","updated_at":"2026-04-04T23:01:20.602Z","avatar_url":"https://github.com/empathic.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Toolpath\n\nA tool-agnostic format for tracking artifact transformation provenance.\n\n## What is this?\n\nToolpath records the complete history of how code (and other artifacts) evolved:\n\n- **Who** made changes (humans, AI agents, formatters, linters, CI)\n- **What** they changed (unified diffs + structural AST operations)\n- **Why** they changed it (intent, linked issues, reasoning)\n- **What else they tried** (dead ends preserved for reflection)\n- **Verification** (cryptographic signatures, identity resolution)\n\n## Three core objects\n\n| Object    | What it represents                        | Example                |\n|-----------|-------------------------------------------|------------------------|\n| **Step**  | A single change to artifact(s)            | One commit, one edit   |\n| **Path**  | A sequence of steps with a base context   | A PR, a coding session |\n| **Graph** | A collection of related paths             | A release              |\n\nSteps form a DAG via parent references. Dead ends are implicit: steps not in the ancestry of `path.head`.\n\n```\n              +-- step-3a -- step-4a  (dead end)\nstep-1 -- step-2 --+\n              +-- step-3b -- step-4b -- step-5b  (head)\n```\n\n## Install\n\n```bash\ncargo install toolpath-cli\n```\n\nThis installs a binary called `path`.\n\n## Workspace\n\n```\ncrates/\n  toolpath/           Core types, builders, query API\n  toolpath-convo/     Provider-agnostic conversation types and traits\n  toolpath-git/       Derive from git repository history\n  toolpath-github/    Derive from GitHub pull requests\n  toolpath-claude/    Derive from Claude conversation logs\n  toolpath-dot/       Graphviz DOT visualization\n  toolpath-md/        Markdown rendering for LLM consumption\n  toolpath-cli/       Unified CLI (binary: path)\n```\n\nSee each crate's README for library-level documentation.\n\n## Quick start\n\n```bash\n# Build everything\ncargo build --workspace\n\n# Derive a Toolpath document from this repo's git history\npath derive git --repo . --branch main --pretty\n\n# Visualize it\npath derive git --repo . --branch main | path render dot | dot -Tpng -o graph.png\n\n# Render as Markdown for an LLM\npath derive git --repo . --branch main | path render md\n\n# Derive from a GitHub pull request\npath derive github --repo owner/repo --pr 42 --pretty\n\n# Derive from Claude conversation logs\npath derive claude --project /path/to/project --pretty\n\n# Query for dead ends (abandoned approaches)\npath query dead-ends --input doc.json\n\n# Filter steps by actor\npath query filter --input doc.json --actor \"agent:\"\n\n# Walk the ancestry of a step\npath query ancestors --input doc.json --step-id step-003\n\n# Merge multiple documents into a graph\npath merge doc1.json doc2.json --title \"Release v2\" --pretty\n\n# Validate a document\npath validate --input examples/step-01-minimal.json\n```\n\n## CLI reference\n\n```\npath\n  list\n    git       [--repo PATH] [--remote NAME] [--json]\n    github    --repo OWNER/REPO [--json]\n    claude    [--project PATH] [--json]\n  derive\n    git       --repo PATH --branch NAME[:START] [--base COMMIT] [--remote NAME] [--title TEXT]\n    github    --repo OWNER/REPO --pr NUMBER [--no-ci] [--no-comments]\n    claude    --project PATH [--session ID] [--all]\n  query\n    ancestors --input FILE --step-id ID\n    dead-ends --input FILE\n    filter    --input FILE [--actor PREFIX] [--artifact PATH] [--after TIME] [--before TIME]\n  render\n    dot       [--input FILE] [--output FILE] [--show-files] [--show-timestamps]\n    md        [--input FILE] [--output FILE] [--detail summary|full] [--front-matter]\n  merge       FILE... [--title TEXT]\n  track\n    init      --file PATH --actor ACTOR [--title TEXT] [--base-uri URI] [--base-ref REF]\n    step      --session FILE --seq N [--actor ACTOR] [--intent TEXT]\n    visit     --session FILE --seq N\n    note      --session FILE --intent TEXT\n    export    --session FILE\n    close     --session FILE\n    list\n  validate    --input FILE\n  haiku\n```\n\nGlobal: `--pretty` for formatted JSON output.\n\n## Using the libraries\n\n### Core types\n\n```rust\nuse toolpath::{Step, Path, Base, Document};\n\nlet step = Step::new(\"step-001\", \"human:alex\", \"2026-01-29T10:00:00Z\")\n    .with_parent(\"step-000\")\n    .with_raw_change(\"src/main.rs\", \"@@ -1,1 +1,1 @@\\n-hello\\n+world\")\n    .with_intent(\"Fix greeting\");\n\nlet path = Path::new(\n    \"path-pr-42\",\n    Some(Base::vcs(\"github:org/repo\", \"abc123\")),\n    \"step-001\",\n);\n```\n\n### Query operations\n\n```rust\nuse toolpath::query;\n\nlet ancestors = query::ancestors(\u0026path.steps, \u0026path.path.head);\nlet dead_ends = query::dead_ends(\u0026path.steps, \u0026path.path.head);\nlet by_actor = query::filter_by_actor(\u0026path.steps, \"agent:\");\nlet artifacts = query::all_artifacts(\u0026path.steps);\n```\n\n### Git derivation\n\n```rust\nuse toolpath_git::{derive, DeriveConfig};\n\nlet repo = git2::Repository::open(\".\")?;\nlet config = DeriveConfig { remote: \"origin\".into(), title: None, base: None };\nlet doc = derive(\u0026repo, \u0026[\"main\".into()], \u0026config)?;\n```\n\n### DOT rendering\n\n```rust\nuse toolpath_dot::{render, RenderOptions};\n\nlet dot_string = render(\u0026doc, \u0026RenderOptions::default());\n```\n\n### Markdown rendering\n\n```rust\nuse toolpath_md::{render, RenderOptions};\n\nlet md_string = render(\u0026doc, \u0026RenderOptions::default());\n```\n\n## Documentation\n\n- [RFC.md](RFC.md) -- Full format specification\n- [FAQ.md](FAQ.md) -- Design rationale and FAQ\n- [CHANGELOG.md](CHANGELOG.md) -- Release history\n- [schema/toolpath.schema.json](schema/toolpath.schema.json) -- JSON Schema\n- [examples/](examples/) -- 11 example documents covering steps, paths, and graphs\n\n## Requirements\n\nRust 1.85+ (edition 2024).\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fempathic%2Ftoolpath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fempathic%2Ftoolpath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fempathic%2Ftoolpath/lists"}