Installation

This page is the hands-on setup path. By the end, your repository can record Agent Note data during normal git commit and publish a PR Report on GitHub.

Install

1. Run init in your repository.

   npx agent-note init --agent claude

   For Codex CLI:

   npx agent-note init --agent codex

   For Cursor:

   npx agent-note init --agent cursor

   For Gemini CLI:

   npx agent-note init --agent gemini

   Multiple agents at once:

   npx agent-note init --agent claude cursor

   Agent Note sets up:

   • Agent hooks (.claude/settings.json for Claude Code, .codex/config.toml + .codex/hooks.json for Codex CLI, .cursor/hooks.json for Cursor, .gemini/settings.json for Gemini CLI)
   • Git hooks (prepare-commit-msg, post-commit, pre-push)
   • GitHub Action workflow (.github/workflows/agentnote-pr-report.yml)
   • Auto-fetch for git notes on pull

   If you also want the shared Dashboard:

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

   That also adds .github/workflows/agentnote-dashboard.yml.

2. Commit the generated files.

   git add .claude/settings.json .github/workflows/agentnote-pr-report.yml
   # with --dashboard, also add .github/workflows/agentnote-dashboard.yml
   git commit -m "chore: enable agent-note"
   git push

   Codex repositories commit .codex/config.toml, .codex/hooks.json, and .github/workflows/agentnote-pr-report.yml. Cursor repositories commit .cursor/hooks.json and .github/workflows/agentnote-pr-report.yml. Gemini CLI repositories commit .gemini/settings.json and .github/workflows/agentnote-pr-report.yml. With --dashboard, also commit .github/workflows/agentnote-dashboard.yml.

3. Start coding with your agent.

   Normal git commit works when the generated git hooks are installed.

Set Up Each Clone

Every developer should run init after cloning to install local git hooks:

git clone <repository-url>
cd <repository-dir>
npx agent-note init --agent claude

Note

Git hooks live inside .git/, so they are never committed. Each clone needs one local init.

What Happens Automatically

After setup, plain git commit will, when the current session has Agent Note data:

1. Inject an Agentnote-Session trailer into the commit message
2. Record prompts, responses, and file attribution as a git note
3. Push notes to the remote on git push

Cursor preview also restores prompt / response pairs from response hooks or local transcripts.

Verify It Works

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  🤖
  CHANGELOG.md  👤

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: shows the enabled adapter, capture: shows what the active hooks collect, git: confirms the repository-local git hooks, and commit: tells you whether plain git commit is the primary path.

Init Flags

Flag	Description
--agent <name...>	Choose one or more agent adapters: claude, codex, cursor, or gemini
--dashboard	Also create .github/workflows/agentnote-dashboard.yml for the shared Dashboard
--no-hooks	Skip agent hook configuration
--no-git-hooks	Skip git hook installation
--no-action	Skip workflow creation
--no-notes	Skip auto-fetch config
--hooks	Only install agent hooks
--action	Only create workflow

What Each Agent Supports

This is the quick view. For the detailed capture and attribution rules, see Agent Support.

Claude Code

Plain git commit works with the generated git hooks. Prompt / response recovery is hook-native, and attribution starts at line-level.

Codex CLI

Plain git commit works with the generated git hooks. Prompt / response recovery comes from the local transcript, and attribution upgrades to line-level only when transcript patch counts match the commit.

Cursor

Plain git commit works with the generated git hooks. Prompt / response recovery comes from response hooks or local transcripts, and attribution upgrades when edit counts match and the final file still matches the last AI edit.

Gemini CLI

Plain git commit works with the generated git hooks. Prompt / response recovery comes from BeforeAgent / AfterAgent hooks, and attribution currently stays at file-level.