Agent Note

[en] [ja] [fr] [de] [it] [es] [ko] [zh-CN] [zh-TW] [ru] [id] [pt-BR]

Saiba por que seu código mudou, não apenas o que mudou.

Agent Note salva a conversa com a AI e os arquivos alterados em cada Commit. Quando há detalhes suficientes, ele também mostra uma estimativa prática de quanto da mudança veio da AI.

Pense nele como git log mais a conversa de AI por trás da mudança.

Documentação

Por que Agent Note

Registre prompts, respostas, arquivos alterados e AI Ratio para cada Commit assistido por AI.
Continue usando git commit normal; Agent Note registra o contexto em background.
Entregue a reviewers humanos e a ferramentas de AI review um PR Report com resumo visível e Reviewer Context oculto.
Abra um Dashboard compartilhado, ou use agent-note why <file:line> para ir de uma linha à conversa do Commit.
Mantenha tudo Git-native em refs/notes/agentnote — sem Hosted Service, sem Telemetry.

Requisitos

Git
Node.js 20 ou mais recente
Um Coding Agent compatível, instalado e autenticado

Quick Start

Habilite Agent Note para seu Coding Agent.

npx agent-note init --agent claude
# ou: codex / cursor / gemini

Cada desenvolvedor deve executar isso uma vez localmente após clonar.

Você pode habilitar mais de um Agent no mesmo Repository:

npx agent-note init --agent claude cursor

Se também quiser o shared Dashboard no GitHub Pages:

npx agent-note init --agent claude --dashboard

Faça Commit dos arquivos gerados e Push.

git add .github/workflows/agentnote-pr-report.yml .claude/settings.json
# substitua .claude/settings.json pela config do seu agent abaixo
# com --dashboard, adicione também .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 e .codex/hooks.json
Cursor: Commit .cursor/hooks.json
Gemini CLI: Commit .gemini/settings.json

Continue usando seu Workflow normal de git commit.

Com os Git Hooks gerados instalados, Agent Note registra automaticamente os Commits feitos com git commit.

AI Agent Skill

Se o seu AI Agent oferece suporte a GitHub Agent Skills, instale o Agent Note Skill para pedir tarefas do Agent Note em linguagem natural.

gh skill install wasabeef/AgentNote agent-note --agent codex --scope user

Para gh skill install, escolha o identificador de agente correto: codex, claude-code, cursor or gemini-cli. O Skill normalmente guia o agente para apenas seis comandos públicos: init, deinit, status, log, show e why.

Dados salvos

Agent Note salva a história do Commit:

Conversa: o pedido e a resposta da AI que levaram à mudança
Contexto: notas curtas mostradas como 📝 Context quando o pedido sozinho é curto demais
Arquivos: arquivos modificados e se a AI ajudou a Editá-los
AI Ratio: uma porcentagem geral, mais contagem de linhas quando Agent Note consegue estimar

Temporary Session Data ficam em .git/agentnote/. O Permanent Record fica em refs/notes/agentnote e é compartilhado com git push.

Excluir bundles gerados do AI Ratio

Se bundles ou generated outputs commitados devem continuar visíveis, mas não influenciar o AI Ratio, adicione-os à .agentnoteignore na raiz do repository:

packages/cli/dist/**
packages/pr-report/dist/**

Esses arquivos continuam aparecendo em Notes, PR Report e Dashboard. Eles são removidos apenas do denominador do AI Ratio.

Agent Support

Agent	Status	Prompt	Response	Files	AI Ratio	Line Estimate
Claude Code	Full support	Sim	Sim	Sim	Sim	Por padrão
Codex CLI	Supported	Sim	Sim	Sim	Sim	Quando o histórico de patches do Codex bate com o Commit final
Cursor	Supported	Sim	Sim	Sim	Sim	Quando a contagem de edições coincide e o arquivo final ainda bate com a última edição da IA
Gemini CLI	Preview	Sim	Sim	Sim	Sim	Ainda não

Files significa que Agent Note pode mostrar quais arquivos commitados foram tocados pelo Agent. Line Estimate significa que ele também pode estimar linhas escritas pela IA, em vez de apenas contar arquivos.

Verifique o Setup

npx agent-note status

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: mostra quais adaptadores de agent estão habilitados. capture: resume o que os hooks ativos coletam. git: mostra se os Git Hooks locais gerenciados estão instalados. commit: indica se git commit é o caminho principal de rastreamento.

O que você recebe

Todo Commit conta sua 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

Escaneie sua history rapidamente

$ 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

Por padrão, a GitHub Action publica um relatório de sessão de IA na descrição da PR:

O bloco agentnote-reviewer-context é salvo como hidden comment no PR body. AI Review tools que leem a raw PR description, como Copilot, CodeRabbit, Devin e Greptile, podem usá-lo como intent e review focus adicionais.

## 🧑💬🤖 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>

Como funciona

Você envia um Prompt ao Coding Agent
        │
        ▼
Hooks salvam a conversa e as informações de Session
        │
        ▼
O Agent edita arquivos
        │
        ▼
Hooks ou Local Transcripts registram quais arquivos mudaram
        │
        ▼
Você executa `git commit`
        │
        ▼
Agent Note grava uma Git Note para esse Commit
        │
        ▼
Você executa `git push`
        │
        ▼
`refs/notes/agentnote` é enviado junto com a Branch

Para o Flow detalhado, como Agent Note estima o trabalho escrito pela IA e o Schema salvo, veja Como funciona.

Commands

Command	O que faz
`agent-note init`	Configura Hooks, Workflow, Git Hooks e notes auto-fetch
`agent-note deinit`	Remove hooks e config do Agent Note
`agent-note status`	Mostra o estado de rastreamento
`agent-note log [n]`	Lista commits recentes com AI Ratio
`agent-note show [commit]`	Mostra a sessão de IA por trás de `HEAD` ou de um Commit SHA
`agent-note why <target>`	Explica o contexto do Agent Note por trás de uma linha ou intervalo de arquivo

GitHub Action

A root action tem dois modes:

PR Report Mode atualiza a Pull Request description ou publica um comment.
Dashboard Mode gera os dados do Dashboard compartilhado e publica /dashboard/ via GitHub Pages.

PR Report Mode é o default:

- uses: wasabeef/AgentNote@v1
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Defina prompt_detail como compact ou full quando quiser um histórico de Prompts focado ou completo. O padrão é compact: ele mantém o relatório legível mostrando os Prompts que explicam o Commit, enquanto full mostra todos os Prompts salvos.

Dashboard Mode usa a mesma action com dashboard: true:

- uses: wasabeef/AgentNote@v1
  with:
    dashboard: true
    prompt_detail: compact

Dados do Dashboard

Na maioria dos repositórios, você não precisa escrever o Workflow manualmente. Gere com init:

npx agent-note init --agent claude --dashboard

Depois faça Commit de .github/workflows/agentnote-pr-report.yml e .github/workflows/agentnote-dashboard.yml, habilite GitHub Pages com GitHub Actions como Source e abra /dashboard/.

Se você já tem um Site GitHub Pages, veja a configuração combinada segura nas Dashboard Docs.

Full example with outputs

- 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 }}%"

O que é salvo

$ git notes --ref=agentnote show ce941f7

{
  "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 }
  }
}

Security & Privacy

Agent Note é Local-first. O Core CLI funciona sem Hosted Service.
Temporary Session Data são armazenados em .git/agentnote/ dentro do seu repositório.
O Permanent Record é armazenado em refs/notes/agentnote, não em Tracked Source Files.
Para Agents que mantêm logs locais da conversa, Agent Note lê esses arquivos do Data Directory do próprio Agent.
O CLI não envia Telemetry.
Commit Tracking é Best-effort. Se Agent Note falhar durante um Hook, seu git commit ainda será bem-sucedido.

Design

Zero runtime dependencies · Git notes storage · Never breaks git commit · No telemetry · Agent-agnostic architecture

Detalhes da arquitetura →

Contributing

Contributing guide → · Code of Conduct →

Licença

MIT — LICENSE

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Agent Note

Por que Agent Note

Requisitos

Quick Start

AI Agent Skill

Dados salvos

Excluir bundles gerados do AI Ratio

Agent Support

Verifique o Setup

O que você recebe

Todo Commit conta sua Story

Escaneie sua history rapidamente

PR Report

Como funciona

Commands

GitHub Action

Dados do Dashboard

Security & Privacy

Design

Contributing

Licença

Uh oh!

FilesExpand file tree

README.pt-br.md

Latest commit

History

README.pt-br.md

File metadata and controls

Agent Note

Por que Agent Note

Requisitos

Quick Start

AI Agent Skill

Dados salvos

Excluir bundles gerados do AI Ratio

Agent Support

Verifique o Setup

O que você recebe

Todo Commit conta sua Story

Escaneie sua history rapidamente

PR Report

Como funciona

Commands

GitHub Action

Dados do Dashboard

Security & Privacy

Design

Contributing

Licença