Change Saga turns a large code change into a guided visual review: a sequence of slides that explains what changed, why it matters, and what may surprise a reviewer. Instead of reconstructing intent from file-by-file diffs, reviewers get the system context, tradeoffs, and intentional deviations first.
Each part of that story links directly to the exact code behind it, and Change Saga checks that every changed line is accounted for. Reviewers can move from the big picture to its evidence—and back—without losing context. Change Saga is experimental, and its formats may change before 1.0.
change-saga-example.mp4
macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/twentyideas/changesaga/main/scripts/install.sh | shWindows PowerShell:
irm https://raw.githubusercontent.com/twentyideas/changesaga/main/scripts/install.ps1 | iexThen check the installation:
change-saga version
change-saga helpThe repository's canonical example Saga reviews the change that introduced the slide-native v4 format itself. The video above walks through this same Saga. After installing Change Saga, open it from a source checkout with:
change-saga open docs/sagas/examples/slide-native-format.sagaThe example is intentionally self-referential: its semantic Items link every
changed line in 6740031..974eaa3 to the visual argument that explains it.
Change Saga is designed to work with the coding agent you already use. Give it these prompts from the repository containing your change:
To install the Change Saga skill:
Use the change-saga cli to install its skill for this coding agent
To author a PR's saga:
Use the change-saga cli to create a Saga for this PR
To review a PR's saga:
Use the change-saga cli to open this PR's Saga
If the implementation or PR already exists, first ask whether its review is complex enough to need a Saga. A small focused change may be clearer as a normal PR. For a large change—one spanning multiple behaviors, risks, systems, or workstreams—the Saga is authored from the completed implementation and exact diff as the guide reviewers will follow. It does not need retroactive requirements, prototypes, technical design, or a work plan merely to fill out the format.
For a new feature or exploration, a Saga can begin before implementation. A typical path starts with a prototype for the UX and UI, develops sourced user stories and acceptance criteria, turns those into a technical design, and then organizes implementation into dependency-aware waves of parallel workspaces. That is not a waterfall: prototypes and stories can evolve together, design can start while they mature, and work-plan drafting can overlap the design.
Saga files are built for that parallelism too. Separate agents can own story revisions, prototype packages, design fragments, and work items, then merge the document alongside the implementation as work fans out and converges. Before peer review, consolidate those lanes and connect the delivered commits and exact diffs back to the acceptance criteria and design they satisfy.
Change Saga works with the coding assistant you already use, but authoring a substantial Saga asks that assistant to navigate a repository, use tools, explain architecture, create diagrams, and connect exact Git evidence. Use a capable agentic model when possible. Smaller, free, or preview models may still complete the workflow, but they often need more guidance and revision.
Treat a generated Saga as a first draft. Even frontier models rarely produce a clear, complete Saga in one pass. Review the prose and diagrams, then ask the assistant to revise anything repetitive, vague, or difficult to follow. A useful follow-up prompt is:
Keep the explanations concise, direct, and factual. Remove repetition. Prefer a clear diagram or concrete example over another paragraph. Revise the Saga until each slide explains one coherent idea. Establish the system model, then foreground the consequential behavior, tradeoffs, and deviations that may surprise a reviewer. Show what they would reasonably expect, what actually happens, why, and the consequence—preferably as a callout on the responsible part of the visual.
Review the Saga yourself before asking peers to review the change. AI can do a good job of connecting explanations to code, but complete coverage does not prove that each claim has the right evidence or that every link belongs where it was placed. Check those relationships, correct anything misleading, and make sure the narrative is coherent. Preparing a Saga for peer review is not automatic: Change Saga provides a robust surface for reviewing the work, but the author is still responsible for making it a quality piece of work.
Change Saga provides the structure that links technical documentation to exact Git evidence; it does not impose a writing personality. If your assistant tends to over-explain or overbuild, optional agent guidance such as Ponytail may help, but it is not required.
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 slide-native saga turns the expression of the code change into a guided visual argument:
- An overview deck establishes the goal and shape of the change.
- Change decks divide it into independently reviewable concerns.
- Diagrams, interactive HTML, screenshots, and examples show the important flows and data models.
- Expectation/actual callouts expose surprising behavior, tradeoffs, hidden coupling, and intentional deviations from repository norms.
- Semantic items inside each slide link to the exact diff ranges they explain.
change-saga statusreports 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.
Version 4 is intentionally slide-native rather than a compatibility mode for older reports. Slides use self-contained SVG, raster, or sandboxed HTML visual entrypoints; prose formats are not slide entrypoints. Each slide makes one review argument, and its addressable items carry the exact implementation evidence. Existing v2/v3 sagas remain readable as legacy reports and must be semantically rewritten—not mechanically upgraded or paginated—to become v4.
Everything remains ordinary files in a .saga directory. The v4 flat format
keeps decks, slides, items, evidence, claims, verifications, and review actions
in small independent records so separate agents or branches can work without a
shared presentation file. SPEC.md defines the format.
In legacy report sagas, prose citations and visual nodes have the same evidence requirement. A Markdown
footnote marker and definition are not a finished citation until the definition
is an exact-text landmark with focused diff evidence. Likewise, a code-bearing
diagram node is unfinished without its element landmark and diffs. Requirements
provenance created with citation add is different: it records where a story or
decision came from and does not substitute for implementation evidence.
change-saga open starts a local review application with three views:
- Saga presents v4 as decks of authored slides with thumbnails, sequential navigation, and fullscreen presentation. Linked code opens in a drawer without losing the active slide. V2/v3 retain their legacy report reader.
- 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 report sections or, in v4, complete slides.
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.
A Saga can document a repository over its entire lifetime, not only one PR. Its authoring and maintenance workflow is designed for AI, not manual human operation. Maintaining exact coverage, granular citations, diagrams, and structured evidence by hand would be unreasonable. That exhaustive bookkeeping is precisely the kind of tedious work AI is good at; humans can focus on understanding and reviewing the result.
To create a Saga for the whole codebase:
Use the change-saga cli to create a Saga for this codebase since inception
To update the codebase Saga for a PR:
Use the change-saga cli to update this codebase's Saga for the changes in this PR
To update it from an existing PR Saga:
Use the change-saga cli to compare this PR's Saga with the codebase Saga and update what changed
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 unverifiedmappings 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.sagaSee the AI-facing interface for the complete contract.
For a focused file whose entire change belongs to one explanation,
change-saga cover --path FILE --changed-lines derives its exact changed-line
and file-event selectors and stores gapless lines as canonical dense ranges.
Generated evidence paths identify the selector set rather than the authoring
timestamp: unrelated selectors stay in unrelated files, while a different
explanation for the same selectors requires explicit reconciliation. Coverage
summaries can be bounded with --json or silenced with --quiet. Repair broad
mappings using the evidence_file from query mappings:
replace-coverage --record PATH --batch - atomically splits or retargets one,
while remove-coverage --record PATH deletes one.
If a base branch advances and is then merged into the feature while the product patch stays byte-for-byte identical, use the guarded bulk migration instead of hand-editing every URI:
change-saga rebase-evidence --repo ../source --dry-run checkout.saga
change-saga rebase-evidence --repo ../source checkout.sagaThe command proves the unchanged base-independent product identity and verifies
every translated selector before writing. It refuses a changed product diff,
preserves evidence targets, notes, paths, sides, and ranges, and rolls affected
immutable claims forward through v3 supersedes relations. Replacement claims
remain unverified unless --carry-verifications is explicitly requested; a
carried result is a new analysis verification with an audit trail, never an
edit or a claim that the original check was rerun.
Most people should let their coding agent manage these commands. If you want to author a saga directly, the basic workflow is:
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 \
--id request-flow --title "Request flow" checkout.saga
change-saga set-fragment-content --target request-flow --source ./request-flow.md \
checkout.saga
change-saga add-landmark --target backend.chapter/request-flow.fragment \
--heading-id request-validation --label "Request validation" checkout.sagaCheck for unexplained changes, then open the review UI:
change-saga status checkout.saga
change-saga open checkout.sagaopen leaves the reviewer running in the background so it remains available
after the command returns. Manage it later with:
change-saga serve status checkout.saga
change-saga serve stop checkout.sagaUse change-saga serve --open checkout.saga when you deliberately want the
reviewer attached to the current terminal instead.
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.
Project a PR's source diff onto an existing codebase Saga:
change-saga compare --repo /path/to/checkout \
--base <pr-base> --head <pr-head> codebase.sagaIf the PR already has a Saga, use its source comparison directly:
change-saga compare --repo /path/to/checkout \
--against-saga pr-123.saga codebase.sagacompare never compares prose, diagrams, or other Saga content. It follows
conflicting and nearby source changes through existing evidence ownership and
reports targets that must be updated, targets that should be considered, and
changes that need new content. The command is read-only; use --json for CI or
an agent-driven maintenance loop.
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.
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 helpThe release build is a single executable with no separately installed Go runtime and no hosted service.
- Format specification
- Documentation index
- Contributing
- Security policy
- Support
- Governance
- Changelog
- Release process
MIT. See LICENSE.