changesaga

Change Saga

Change Saga turns a large code change into a reviewable document. It gives the change an overview, chapters, diagrams, examples, and links to the exact code behind each explanation. Critically, it validates that every change in the diff is mapped somewhere in the document. Mapping catches omissions; it is not a claim that the explanation or code is correct. The result lives in Git beside the code and can be reviewed a chapter at a time.

Install

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/twentyideas/changesaga/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/twentyideas/changesaga/main/scripts/install.ps1 | iex

Then check the installation:

change-saga version
change-saga help

Change Saga is experimental. The v2 format may change before 1.0.

Quick start

Change Saga is designed to work with the coding agent you already use. This prints a short, portable prompt that teaches the agent how to author a saga:

change-saga install-skill

Paste the output into Claude Code, Codex, OpenCode, or another coding agent in the repository containing your change. It uses the project's normal PR-writing workflow, but produces a visual, structured saga instead of one long PR description.

To create one manually:

change-saga init --base main --head HEAD --title "Checkout rewrite" checkout.saga
change-saga add-chapter --title "Backend" checkout.saga backend
change-saga add-fragment --section backend.chapter --type markdown \
  --title "Request flow" checkout.saga
change-saga add-landmark --target backend.chapter/request-flow.fragment \
  --heading-id request-validation --label "Request validation" checkout.saga

Ask which changes still need an explanation:

change-saga status checkout.saga

Open the review UI:

change-saga open checkout.saga

Run these commands from the changed repository on the branch containing the work. If the saga lives in a separate repository, pass --repo /path/to/source-checkout to commands that inspect the diff.

What it does

A normal PR description sits above a flat file-by-file diff. That works for small changes. With a large change, the reviewer has to understand the whole system while reading isolated files in an arbitrary order.

A saga introduces the change gradually:

1. The overview explains the goal and the shape of the change.
2. Chapters divide it into reviewable pieces—the PRs you might have created if you had split the work.
3. Diagrams, interactive HTML, screenshots, and examples show the important flows and data models.
4. Each part links to the files and exact diff ranges that implement it.
5. change-saga status reports any changed code that has not been accounted for.

The tool does not review the code or generate a verdict. It helps the author prepare the material that other people will review. AI is useful here because it can build the first draft, create diagrams and examples, and iterate until the complete diff is represented. The reviewer still decides whether the change is correct.

Saga content can be Markdown, text, images, SVG, or interactive HTML with JavaScript. Headings, diagram nodes, exact text, and image regions can link to one or more files and diff ranges. Everything remains ordinary files in a .saga directory; SPEC.md defines the format.

Reviewing a saga

change-saga open starts a local review application with three views:

• Saga presents the overview and chapters. Linked code opens in a large drawer without losing the narrative.
• Code Diff provides a traditional changed-file tree and diff view, with links back to every relevant explanation.
• Coverage shows the mapping in both directions: code to explanations and explanations to code.

Reviews can be spread across multiple sessions. Reviewers can comment on text or code, highlight content, draw shapes, add sticky notes, mark files reviewed, and approve or reject individual parts of the saga.

Every newly initialized saga also carries a small root README.md. It tells a human or AI assistant how to install and open the intended reviewer, and tells assistants to ask before downloading or executing anything from PR content.

Review data is stored inside the saga. Each comment, reply, annotation, and state transition gets its own file, which keeps concurrent Git changes small and avoids shared comment arrays. Attribution comes from the commit that adds the record.

Structured access for AI

Agents do not need to crawl the saga's files. The CLI exposes a bounded, read-only JSON interface for the overview, hierarchy, content, reviews, coverage gaps, diff ownership, mapping quality, author claims, and verification:

change-saga query overview --saga checkout.saga
change-saga query gaps --saga checkout.saga --kind uncovered
change-saga query mappings --saga checkout.saga --sort scrutiny
change-saga query claims --saga checkout.saga --status unverified

mappings ranks broad or thin evidence so an AI can start with the weakest justification. Claims are falsifiable assertions tied to exact code; verification results are append-only and attributed through Git. An AI review can inspect the diff cold first, then reconcile its findings against this structured author account.

Authoring is batchable in the same spirit. change-saga cover --batch - reads newline-delimited JSON records from standard input, resolves the whole batch before writing anything, and leaves the saga untouched if any record fails:

printf '%s\n' \
  '{"target":"api.chapter","path":"api.go","side":"new","lines":"18-24","note":"validates the request"}' \
  '{"target":"api.chapter/flow.fragment#submit-action","path":"ui.ts","side":"new","lines":"9","note":"wires the control"}' \
  | change-saga cover --batch - checkout.saga

See the AI-facing interface for the complete contract.

Security

The review application runs only on loopback and refuses remote bind addresses. Mutations require a per-process token and same-origin requests. Interactive fragments run in sandboxed frames with network access and parent application access disabled.

A saga can still contain untrusted HTML, SVG, and JavaScript. Treat one from an untrusted author with the same care as code from an untrusted branch. See SECURITY.md for the threat model and private reporting process.

Building from source

Change Saga requires Go 1.26.1:

git clone https://github.com/twentyideas/changesaga
cd change-saga
go build -o ./bin/change-saga ./cmd/change-saga
./bin/change-saga help

The release build is a single executable with no separately installed Go runtime and no hosted service.

Project links

• Format specification
• Documentation index
• Contributing
• Security policy
• Support
• Governance
• Changelog
• Release process

License

MIT. See LICENSE.