DEV Community: Daichi Furiya

Introducing Agent Note: saving the why behind AI-assisted code in Git

Daichi Furiya — Mon, 18 May 2026 04:28:20 +0000

Hi, I'm wasabeef.

I have been using coding agents such as Claude Code, Codex CLI, Cursor, and Gemini CLI regularly in daily development.

They no longer feel like experiments. They can already produce reviewable Pull Requests. But while reviewing AI-assisted changes, I kept running into the same problem.

A diff tells you what changed. It does not tell you why it changed.

That is already a problem with human-written commits when the commit message is weak. With AI-assisted commits, the missing context is even larger: the prompt, the response, the discussion that led to the implementation, the agent that touched each file, and the reason a particular path was chosen.

That is why I built Agent Note.

This article focuses less on the exact usage and more on why this kind of record is needed, and how Agent Note keeps that context in Git.

What is missing in AI-era code review

AI coding agents have become common in everyday development.

They write code quickly. They add tests. They update documentation. They can even open Pull Requests.

But review exposes a different problem.

The final diff does not show the background of the implementation.

What request started the change?
What assumptions did the AI make?
Did the direction change halfway through?
Is this a generated bundle, or source code someone intentionally edited?
Which commits were mostly AI-assisted, and which were mostly human follow-up?

In human-to-human development, commit messages, Pull Request descriptions, and review comments have carried that context.

In AI-assisted development, prompts and responses also belong in the review context. Without them, reviewers lose the trail before review even starts.

Until now, the conversation with the AI often stayed inside the agent UI or a local transcript. Once the session ended, the team usually received only the commit and the Pull Request.

The reason behind the change disappears.

AI review tools need context too

I also use AI review tools such as Copilot, CodeRabbit, Devin, and Greptile.

Their main inputs are usually the diff and the repository code.

That means AI can review AI-written code without seeing the prompt or intent that produced it.

When that happens, the review tends to stay near the surface of the diff.

To judge whether an implementation matches the intended change, a reviewer needs more than the final code. The reviewer needs to know what the author asked for, what the agent understood, and which parts of the repository were supposed to change.

Agent Note keeps that context in the Pull Request in a form AI review tools can read.

It renders a human-readable summary in the Pull Request body, and also embeds an agentnote-reviewer-context hidden comment. It is invisible in the rendered PR body, but AI review tools that read the raw Pull Request description can use it to understand changed areas, review focus, and author intent.

The reviewer gets more than the diff.

Today

git diff
Pull Request description

Prompt?       missing
Response?     missing
Why this way? reviewers have to infer it

With Agent Note

git diff
Pull Request description
refs/notes/agentnote
Dashboard

Prompt / Response / Context / AI Ratio stay connected to the commit

What gets recorded

Agent Note saves the AI conversation and changed files for each commit.

Think of it as git log with the AI conversation behind the change attached to it.

It records four kinds of information.

Data	What it helps you see
Prompt / Response	What was requested and how the AI answered
Files	Which files the agent touched
AI Ratio	A practical estimate of how much of the commit involved AI
Context	Extra context when the prompt alone is too short

For example, a prompt like yes, implement it does not carry enough meaning when it appears alone in a Pull Request.

Agent Note does not try to inflate that prompt. Instead, when the surrounding commit evidence helps, it can attach a short Context note.

The point is not to say "this code is correct because AI wrote it" or "this code is risky because AI wrote it."

The point is to give reviewers better evidence.

How it works

Agent Note is not a hosted service.

It adds a thin recording layer next to the normal Git workflow.

You prompt your coding agent
        │
        ▼
Agent hooks save the conversation and session info
        │
        ▼
The agent edits files
        │
        ▼
Hooks or local transcripts record changed files
        │
        ▼
You run `git commit`
        │
        ▼
A Git hook links the session to the commit
        │
        ▼
Agent Note writes a Git note for that commit
        │
        ▼
Agent Note's pre-push hook shares `refs/notes/agentnote`

Temporary session data lives under .git/agentnote/.

The permanent record lives in refs/notes/agentnote.

Agent Note does not modify the commit diff. It adds only a short session trailer to the commit message and stores the detailed record in Git notes. When you need the AI context behind a commit, you read the Git note.

Why Git notes

The design constraint I cared about most was avoiding unnecessary workflow changes.

I did not want to replace git commit, and I did not want the core record to depend on a hosted service.

The context behind AI-assisted code should be a team asset, just like the commit itself. Keeping that context in Git felt natural.

Git notes let Agent Note attach structured data to a commit without changing the regular commit history.

That balance felt right.

Use normal git log and Pull Requests most of the time
Read Agent Note data only when you need the deeper context
Share it with the team through refs/notes/agentnote
Avoid requiring a hosted service

The design keeps AI development context close to Git instead of sending it somewhere else.

What Agent Note does not do

Agent Note is not a tool for proving that AI-written code is correct.

AI Ratio is not an automatic judgment of responsibility or quality. It is a practical signal for understanding how much AI involvement a commit appears to have.

Agent Note also does not claim perfect line-to-prompt attribution today. agent-note why is a shortcut from a line, to the blamed commit, to the prompts, responses, and context attached to that commit.

The goal is not to replace review. The goal is to keep the context reviewers need from disappearing.

How it fits with Spec-Driven Development

Spec-Driven Development makes the intent explicit before implementation.

That works well with AI coding agents. If the input is vague, the agent may still produce code quickly, but reviewers later have to guess why the implementation took that shape.

A spec alone does not preserve the implementation conversation. It does not show how the agent interpreted the task, what changed during the session, or which prompts ended up in each commit.

If the spec is the intent before implementation, Agent Note is the execution record after implementation.

Together, they let reviewers compare the implementation against the spec, and also inspect the AI conversation that produced the commit.

How it relates to Entire

Agent Note is not the only project working on this problem.

Entire also connects the context behind AI-assisted code changes to Git. Entire records prompts, transcripts, tool calls, changed files, and other session data as Checkpoints linked to commits. It is a broader system for agent development history, including rewind, resume, search, and a web UI.

Agent Note is intentionally narrower.

It focuses on commits and Pull Request review. The persistent record lives in Git notes under refs/notes/agentnote, and the main surfaces are the PR Report, Dashboard, hidden reviewer context for AI review tools, and agent-note why.

I do not see this as a matter of which approach is correct. The scope is different.

If you want full session Checkpoints, rewind, resume, and repository-wide search, a system like Entire makes sense. If you mainly want lightweight commit-level review context in Pull Requests, Agent Note is designed for that narrower workflow.

PR Report and Dashboard

In Pull Requests, Agent Note renders a human-readable summary.

## 🧑💬🤖 Agent Note

**Total AI Ratio:** ██████░░ 73%
**Model:** `claude-sonnet-4-20250514`

| Commit | AI Ratio | Prompts | Files |
|---|---|---|---|
| ce941f7 feat: add auth | ████░ 73% | 2 | auth.ts, token.ts |

Open Dashboard ↗

The PR Report is the entry point for review.

The Dashboard is for deeper reading.

In the Dashboard, you can inspect Prompt / Response, changed files, AI Ratio, and diffs by PR and by commit.

The report answers "what should I look at first?" The Dashboard answers "what happened in this commit?"

The idea behind `agent-note why`

Agent Note also includes agent-note why.

It starts from a target line, uses git blame to find the commit, then reads the Agent Note attached to that commit.

npx agent-note why README.md:111

It does not claim exact line-to-prompt attribution yet.

But even without a new schema, connecting an individual line to the commit conversation is useful. It shortens the path from "why is this line here?" to "what did we ask the agent to do in that commit?"

Eventually, I want to get closer to line-level explanations. The MVP is intentionally smaller: connect existing Git blame data with existing Git note data and make the available context easy to reach.

Different agents expose different context

Agent Note supports multiple coding agents, but each agent exposes a different level of detail.

That is because every agent exposes hooks and transcripts differently.

Claude Code provides the richest signal today. Codex CLI, Cursor, and Gemini CLI are also supported, but Agent Note records only the prompt, response, changed files, and AI Ratio evidence that each agent can expose reliably.

I also do not want to overstate the evidence.

If Agent Note cannot know something reliably, it does not pretend to know it. AI Ratio is an estimate, not proof.

The latest support matrix is available in Agent Support.

Things to keep in mind

Agent Note records conversations with AI for the team.

That record should be handled carefully.

Do not put secrets in prompts or responses
When Git notes are pushed, the team can read the saved conversation
AI Ratio is an estimate, not an automatic judgment of quality or responsibility
Different agents expose different levels of detail
Gemini CLI support is still Preview

Agent Note is closer to review context than to an audit verdict.

Closing

The more we use AI coding agents, the less a diff alone is enough for code review.

Human commits have commit messages and Pull Request discussions. AI-assisted commits should also preserve prompts, responses, context, and AI Ratio.

Agent Note is an open source, Git-native way to do that.

GitHub: https://github.com/wasabeef/AgentNote
Documentation: https://wasabeef.github.io/AgentNote/
npm: https://www.npmjs.com/package/agent-note

If you want AI-assisted code to remain understandable after the session is over, please give Agent Note a try.

The Flutter code generator for your assets, fonts, colors, … — Get rid of all String-based APIs.

Daichi Furiya — Wed, 09 Sep 2020 14:59:20 +0000

Hey guys, We created the FlutterGen.

It's a Flutter code generator for your assets, fonts, colors, … — Get rid of all String-based APIs.

Inspired by SwiftGen.

Motivation.

Using asset path string directly is not safe.



# pubspec.yaml
flutter:
  assets:
    - assets/images/profile.jpg

❌ Bad

What would happen if you made a typo?



Widget build(BuildContext context) {
  return Image.asset('assets/images/profile.jpeg');
}

// The following assertion was thrown resolving an image codec:
// Unable to load asset: assets/images/profile.jpeg

⭕️ Good

We want to use it safely.



Widget build(BuildContext context) {
  return Assets.images.profile.image();
}

Installation

Run fluttergen after the configuration pubspec.yaml.

Use this package as an executable

Using a Homebrew Formula

Install FlutterGen



$ brew install FlutterGen/tap/fluttergen

Use FlutterGen



$ fluttergen -h

$ fluttergen -c example/pubspec.yaml

Using a Dart command-line

Install FlutterGen



$ pub global activate flutter_gen

$ export PATH="$PATH":"$HOME/.pub-cache/bin"

Use FlutterGen



$ fluttergen -h

$ fluttergen -c example/pubspec.yaml

Use this package as a part of build_runner

Add build_runner and FlutterGen to your package's pubspec.yaml file:



dev_dependencies:
  build_runner:
  flutter_gen_runner:

Install FlutterGen



$ flutter pub get

Use FlutterGen



$ flutter packages pub run build_runner build

Configuration file

FlutterGen generates dart files based on the key flutter and flutter_gen of pubspec.yaml.



# pubspec.yaml
# ...

flutter_gen:
  output: lib/gen/ # Optional (default: lib/gen/)
  lineLength: 80 # Optional (default: 80)

  integrations:
    flutter_svg: true

  colors:
    inputs:
      - assets/color/colors.xml

flutter:
  uses-material-design: true
  assets:
    - assets/images/

  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf
        - asset: assets/fonts/Raleway-Italic.ttf
          style: italic

Available Parsers

Assets

Just follow the doc Adding assets and images#Specifying assets to specify assets, then FlutterGen will generate related dart files.

No other specific configuration is required.

Ignore duplicated.



# pubspec.yaml
flutter:
  assets:
    - assets/images/
    - assets/images/chip3/chip.jpg
    - assets/images/chip4/chip.jpg
    - assets/images/icons/paint.svg
    - assets/json/fruits.json
    - pictures/ocean_view.jpg

These configurations will generate assets.gen.dart under the lib/gen/ directory by default.

Usage Example

FlutterGen generates Image class if the asset is Flutter supported image format.

Example results of assets/images/chip.jpg:

Assets.images.chip is an implementation of AssetImage class.
Assets.images.chip.image(...) returns Image class.
Assets.images.chip.path just returns the path string.



Widget build(BuildContext context) {
  return Image(image: Assets.images.chip);
}

Widget build(BuildContext context) {
  return Assets.images.chip.image(
    width: 120,
    height: 120,
    fit: BoxFit.scaleDown,
  );

Widget build(BuildContext context) {
  // Assets.images.chip.path = 'assets/images/chip3/chip3.jpg'
  return Image.asset(Assets.images.chip.path);
}

If you are using SVG images with flutter_svg you can use the integration feature.



# pubspec.yaml
flutter_gen:

  integrations:
    flutter_svg: true

flutter:
  assets:
    - assets/images/icons/paint.svg



Widget build(BuildContext context) {
  return Assets.images.icons.paint.svg(
    width: 120,
    height: 120
  );
}

In other cases, the asset is generated as String class.



// If don't use the Integrations.
final svg = SvgPicture.asset(Assets.images.icons.paint);

final json = await rootBundle.loadString(Assets.json.fruits);

The root directory will be omitted if it is either assets or asset.



assets/images/chip3/chip.jpg  => Assets.images.chip3.chip
assets/images/chip4/chip.jpg  => Assets.images.chip4.chip
assets/images/icons/paint.svg => Assets.images.icons.paint
assets/json/fruits.json       => Assets.json.fruits
pictures/ocean_view.jpg       => Assets.pictures.oceanView

Fonts

Just follow the doc Use a custom font to specify fonts, then FlutterGen will generate related dart files.

No other specific configuration is required.

Ignore duplicated.



# pubspec.yaml
flutter:
  fonts:
    - family: Raleway
      fonts:
        - asset: assets/fonts/Raleway-Regular.ttf
        - asset: assets/fonts/Raleway-Italic.ttf
          style: italic
    - family: RobotoMono
      fonts:
        - asset: assets/fonts/RobotoMono-Regular.ttf
        - asset: assets/fonts/RobotoMono-Bold.ttf
          weight: 700

These configurations will generate fonts.gen.dart under the lib/gen/ directory by default.

Usage Example



Text(
  'Hi there, I\'m FlutterGen',
  style: TextStyle(
    fontFamily: FontFamily.robotoMono,
    fontFamilyFallback: const [FontFamily.raleway],
  ),

Colors

FlutterGen supports generating colors from XML format files.

Ignore duplicated.



# pubspec.yaml
flutter_gen:
  colors:
    inputs:
      - assets/color/colors.xml
      - assets/color/colors2.xml

FlutterGen generates MaterialColor class
if the element has the attribute type="material", otherwise a normal Color class will be generated.



<color name="milk_tea">#F5CB84</color>
<color name="cinnamon" type="material">#955E1C</color>

These configurations will generate colors.gen.dart under the lib/gen/ directory by default.

Usage Example



Text(

  'Hi there, I\'m FlutterGen',

  style: TextStyle(

    color: ColorName.denim,

  ),

Conclusion

We are looking for co-developers. 😃

DEV Community: Daichi Furiya

Introducing Agent Note: saving the why behind AI-assisted code in Git

What is missing in AI-era code review

AI review tools need context too

Today

With Agent Note

What gets recorded

How it works

Why Git notes

What Agent Note does not do

How it fits with Spec-Driven Development

How it relates to Entire

PR Report and Dashboard

The idea behind agent-note why

Different agents expose different context

Things to keep in mind

Closing

The Flutter code generator for your assets, fonts, colors, … — Get rid of all String-based APIs.

Motivation.

Installation

Use this package as an executable

Using a Homebrew Formula

Using a Dart command-line

Use this package as a part of build_runner

Configuration file

Available Parsers

Assets

Usage Example

Fonts

Usage Example

Colors

Usage Example

Conclusion

The idea behind `agent-note why`