# Agent Note
<p align="center">
[en] [<a href="./README.ja.md">ja</a>] [<a href="./README.fr.md">fr</a>] [<a href="./README.de.md">de</a>] [<a href="./README.it.md">it</a>] [<a href="./README.es.md">es</a>] [<a href="./README.ko.md">ko</a>] [<a href="./README.zh-cn.md">zh-CN</a>] [<a href="./README.zh-tw.md">zh-TW</a>] [<a href="./README.ru.md">ru</a>] [<a href="./README.id.md">id</a>] [<a href="./README.pt-br.md">pt-BR</a>]
</p>
<p align="center">
<img src="docs/assets/hero.png" alt="Agent Note — AI conversations saved to git" width="720">
</p>
<p align="center">
<a href="https://github.com/wasabeef/AgentNote/actions"><img src="https://img.shields.io/github/actions/workflow/status/wasabeef/AgentNote/ci.yml?branch=main" alt="CI"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
<a href="https://www.npmjs.com/package/agent-note"><img src="https://img.shields.io/npm/v/agent-note" alt="npm"></a>
</p>
<p align="center"><strong>Know <em>why</em> your code changed, not just <em>what</em> changed.</strong></p>
<p align="center">
Agent Note saves the AI conversation and changed files for each commit. When enough detail is available, it also shows a practical estimate of how much of the change came from AI.
</p>
<p align="center">
Think of it as <code>git log</code> plus the AI conversation behind the change.
</p>
<p align="center">
<a href="https://wasabeef.github.io/AgentNote/">Documentation</a>
</p>
<p align="center">
<img src="docs/assets/dashboard-preview.png" alt="Agent Note dashboard preview" width="1100">
</p>
## Why Agent Note
- Capture prompts, responses, changed files, and AI Ratio for every AI-assisted commit.
- Keep using normal `git commit`; Agent Note records the context in the background.
- Give human reviewers and AI review tools a PR Report with visible summaries plus hidden Reviewer Context.
- Open a shared Dashboard, or run `agent-note why <file:line>` to jump from a line back to the commit conversation.
- Keep everything git-native in `refs/notes/agentnote` — no hosted service, no telemetry.
## Requirements
- Git
- Node.js 20 or later
- A supported coding agent installed and authenticated
## Quick Start
1. Enable Agent Note for your coding agent.
```bash
npx agent-note init --agent claude
# or: codex / cursor / gemini
```
Each developer should run this once locally after cloning.
You can enable more than one agent in the same repository:
```bash
npx agent-note init --agent claude cursor
```
If you also want the shared Dashboard on GitHub Pages:
```bash
npx agent-note init --agent claude --dashboard
```
2. Commit the generated files and push.
```bash
git add .github/workflows/agentnote-pr-report.yml .claude/settings.json
# replace .claude/settings.json with your agent config below
# with --dashboard, also add .github/workflows/agentnote-dashboard.yml
git commit -m "chore: enable agent-note"
git push
```
- Claude Code: commit `.claude/settings.json`
- Codex CLI: commit `.codex/config.toml` and `.codex/hooks.json`
- Cursor: commit `.cursor/hooks.json`
- Gemini CLI: commit `.gemini/settings.json`
3. Keep using your normal `git commit` workflow.
With the generated git hooks installed, Agent Note records commits automatically.
## AI Agent Skill
If your AI coding agent supports GitHub Agent Skills, install the Agent Note skill so you can ask for Agent Note tasks in natural language.
```bash
gh skill install wasabeef/AgentNote agent-note --agent codex --scope user
```
For `gh skill install`, use the matching agent identifier: `codex`, `claude-code`, `cursor`, or `gemini-cli`. The skill guides the agent to the public commands: `init`, `deinit`, `status`, `log`, `show`, and `why`.
## Saved Data
Agent Note stores the commit story:
- Conversation: the request and AI answer that led to the change
- Context hints: short notes shown as `📝 Context` when the request alone is too short
<img src="website/public/images/context-dashboard-example.png" alt="Agent Note Dashboard showing Context before a short prompt" width="750">
- Files: changed files and whether AI helped edit them
- AI Ratio: an overall percentage, plus the likely AI-written lines when Agent Note can estimate them
Temporary session data lives under `.git/agentnote/`. The permanent record lives in `refs/notes/agentnote` and is shared on `git push`.
### Keep generated bundles out of AI Ratio
If committed bundles or generated outputs should stay visible but not affect AI Ratio, add them to the repository-root `.agentnoteignore`:
```gitignore
packages/cli/dist/**
packages/pr-report/dist/**
```
Those files still appear in Notes, PR Report, and Dashboard. They are only removed from the AI Ratio denominator.
## Agent Support
| Agent | Status | Prompt | Response | Files | AI Ratio | Line Estimate |
| --- | --- | --- | --- | --- | --- | --- |
| Claude Code | Full support | Yes | Yes | Yes | Yes | Default |
| Codex CLI | Supported | Yes | Yes | Yes | Yes | When Codex patch history matches the final commit |
| Cursor | Supported | Yes | Yes | Yes | Yes | When edit counts match and the final file still matches the latest AI edit |
| Gemini CLI | Preview | Yes | Yes | Yes | Yes | Not yet |
`Files` means Agent Note can show which committed files were touched by the agent. `Line Estimate` means it can also estimate AI-written lines instead of only counting files.
## Check Your Setup
```bash
npx agent-note status
```
```text
agent-note v1.x.x
agent: active (cursor)
capture: cursor(prompt, response, edits, shell)
git: active (prepare-commit-msg, post-commit, pre-push)
commit: tracked via git hooks
session: a1b2c3d4…
agent: cursor
linked: 3/20 recent commits
```
`agent:` shows which agent adapters are enabled. `capture:` summarizes what the active agent hooks collect. `git:` shows whether the managed repository-local git hooks are installed. `commit:` tells you whether plain `git commit` is the primary tracking path.
## What You Get
### Every commit tells its story
```
$ npx agent-note show
commit: ce941f7 feat: add JWT auth middleware
session: a1b2c3d4-5678-4abc-8def-111122223333
ai: 60% (45/75 lines) [█████░░░]
model: claude-sonnet-4-20250514
agent: claude
files: 3 changed, 2 by AI
src/middleware/auth.ts 🤖
src/types/token.ts 🤖
src/middleware/__tests__/auth.test.ts 🤖
CHANGELOG.md 👤
README.md 👤
prompts: 2
1. Implement JWT auth middleware with refresh token rotation
2. Add tests for expired token and invalid signature
```
### Scan your history at a glance
```
$ npx agent-note log
ce941f7 feat: add JWT auth middleware [a1b2c3d4… | 🤖60% | 2p]
326a568 test: add auth tests [a1b2c3d4… | 🤖100% | 1p]
ba091be fix: update dependencies
```
### PR Report
By default, the GitHub Action posts an AI session report to the PR description:
The `agentnote-reviewer-context` block is hidden from the rendered PR body. AI review tools that read the raw PR description, such as Copilot, CodeRabbit, Devin, and Greptile, can use it as extra intent and review focus.
```
## 🧑💬🤖 Agent Note
**Total AI Ratio:** ████████ 73%
**Model:** `claude-sonnet-4-20250514`
<!-- agentnote-reviewer-context
Generated from Agent Note data. Use this as intent and review focus, not as proof that the implementation is correct.
Changed areas:
- Documentation: `README.md`, `docs/usage.md`
- Source: `src/auth.ts`
- Tests: `src/auth.test.ts`
Review focus:
- Check that docs and examples match the implemented behavior.
- Compare the stated intent with the changed source files and prompt evidence.
Author intent signals:
- Commit: feat: add auth
- Prompt: Add JWT authentication and update the PR docs
-->
| Commit | AI Ratio | Prompts | Files |
|---|---|---|---|
| ce941f7 feat: add auth | ████░ 73% | 2 | auth.ts 🤖, token.ts 🤖 |
<div align="right"><a href="https://OWNER.github.io/REPO/dashboard/?pr=123" target="_blank" rel="noopener noreferrer">Open Dashboard ↗</a></div>
```
## How It Works
```
You prompt your coding agent
│
▼
Hooks save the conversation and session info
│
▼
The agent edits files
│
▼
Hooks or local transcripts record which files changed
│
▼
You run `git commit`
│
▼
Agent Note writes a git note for that commit
│
▼
You run `git push`
│
▼
`refs/notes/agentnote` is pushed alongside your branch
```
For the detailed flow, how Agent Note estimates AI-written work, and the stored schema, see [How it works](https://wasabeef.github.io/AgentNote/how-it-works/).
## Commands
| Command | What it does |
| --- | --- |
| `agent-note init` | Set up hooks, workflow, git hooks, and notes auto-fetch |
| `agent-note deinit` | Remove Agent Note hooks and config |
| `agent-note status` | Show tracking state |
| `agent-note log [n]` | List recent commits with AI Ratio |
| `agent-note show [commit]` | Show the AI session behind `HEAD` or a commit SHA |
| `agent-note why <target>` | Explain the Agent Note context behind a file line or range |
## GitHub Action
The root action has two modes:
- PR Report Mode updates the Pull Request description or posts a comment.
- Dashboard Mode builds the shared Dashboard bundle and publishes `/dashboard/` through GitHub Pages.
PR Report Mode is the default:
```yaml
- uses: wasabeef/AgentNote@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
Set `prompt_detail` to `compact` or `full` when you want a focused or complete prompt history. The default is `compact`: it shows the prompts that explain the commit, while `full` shows every stored prompt.
Dashboard Mode uses the same action with `dashboard: true`:
```yaml
- uses: wasabeef/AgentNote@v1
with:
dashboard: true
prompt_detail: compact
```
The action resolves the published GitHub Pages URL automatically, including private and Enterprise Pages sites served from `*.pages.github.io` domains. Set `pages_base_url` only when the resolved URL needs an explicit override, for example behind a custom proxy:
```yaml
- uses: wasabeef/AgentNote@v1
with:
dashboard: true
pages_base_url: https://pages.example.com/apps/
```
### Dashboard Data
For most repositories, you do not need to hand-write the workflow. Generate it with `init`:
```bash
npx agent-note init --agent claude --dashboard
```
Then commit `.github/workflows/agentnote-pr-report.yml` and `.github/workflows/agentnote-dashboard.yml`, enable GitHub Pages with `GitHub Actions` as the source, and open `/dashboard/`.
If you already have a GitHub Pages site, see [Dashboard docs](https://wasabeef.github.io/AgentNote/dashboard/) for the safe combined setup.
<details>
<summary>Full example with outputs</summary>
```yaml
- uses: wasabeef/AgentNote@v1
id: agent-note
with:
base: main
# Use structured outputs
- run: echo "Total AI Ratio: ${{ steps.agent-note.outputs.overall_ai_ratio }}%"
```
</details>
<details>
<summary>What gets saved</summary>
```bash
$ git notes --ref=agentnote show ce941f7
```
```json
{
"v": 1,
"agent": "claude",
"session_id": "a1b2c3d4-...",
"timestamp": "2026-04-02T10:30:00Z",
"model": "claude-sonnet-4-20250514",
"interactions": [
{
"prompt": "Implement JWT auth middleware",
"contexts": [
{
"kind": "scope",
"source": "current_response",
"text": "I will create the JWT auth middleware and wire it into the request pipeline."
}
],
"selection": {
"schema": 1,
"source": "primary",
"signals": ["primary_edit_turn"]
},
"response": "I'll create the middleware...",
"files_touched": ["src/auth.ts"],
"tools": ["Edit"]
}
],
"files": [
{ "path": "src/auth.ts", "by_ai": true },
{ "path": "CHANGELOG.md", "by_ai": false }
],
"attribution": {
"ai_ratio": 60,
"method": "line",
"lines": { "ai_added": 45, "total_added": 75, "deleted": 3 }
}
}
```
</details>
## Security & Privacy
- Agent Note is local-first. The core CLI works without a hosted service.
- Temporary session data is stored under `.git/agentnote/` inside your repository.
- The permanent record is stored in `refs/notes/agentnote`, not in tracked source files.
- For agents that keep local conversation logs, Agent Note reads those files from the agent's own data directory.
- The CLI does not send telemetry.
- Commit tracking is best-effort. If Agent Note fails during a hook, your `git commit` still succeeds.
## Design
Zero runtime dependencies · Git notes storage · Never breaks `git commit` · No telemetry · Agent-agnostic architecture
[Architecture details →](docs/architecture.md)
## Contributing
[Contributing guide →](CONTRIBUTING.md) · [Code of Conduct →](CODE_OF_CONDUCT.md)
## License
MIT — [LICENSE](LICENSE)