Commands

Use this page when you already know what Agent Note is and need the exact user-facing command or flag. For the first setup path, start with Installation instead.

Common Tasks

• First setup: agent-note init
• Remove Agent Note from a repository: agent-note deinit
• Verify hooks and the active adapter: agent-note status
• Review recent activity: agent-note log
• Check what a commit recorded: agent-note show
• Ask why a line changed: agent-note why

Note

PR Report and Dashboard are GitHub Actions features. agent-note init usually creates the workflow files; the reports and Dashboard are generated later by those workflows.

agent-note init

Set up Agent Note in the current repository.

npx agent-note init --agent claude

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

agent-note deinit

Remove Agent Note hooks and configuration for one or more agents.

npx agent-note deinit --agent claude

Flag	Description
--agent <name...>	claude, codex, cursor, or gemini
--remove-workflow	Also remove the PR Report and Dashboard workflows
--keep-notes	Keep notes auto-fetch config

agent-note status

Show current tracking state.

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-note log

List recent commits with AI Ratio.

npx agent-note log
npx agent-note log 20

ce941f7 feat: add auth  [a1b2c3d4… | 🤖60% | 2p]
326a568 test: add tests [a1b2c3d4… | 🤖100% | 1p]
ba091be fix: update deps

agent-note show

Show AI session details for a commit.

npx agent-note show
npx agent-note show abc1234

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  👤

prompts: 2

  1. Implement JWT auth middleware with refresh token rotation
  2. Add tests for expired token and invalid signature

agent-note why

Show the Agent Note context behind the commit that last changed a file line.

npx agent-note why src/middleware/auth.ts:42
npx agent-note why src/middleware/auth.ts:42-55
npx agent-note why src/middleware/auth.ts:42:7
npx agent-note why src/middleware/auth.ts#L42
npx agent-note why src/middleware/auth.ts#L42-L55
npx agent-note why src/middleware/auth.ts#L42C7
npx agent-note why @src/middleware/auth.ts#L42
npx agent-note why https://github.com/owner/repo/blob/main/src/middleware/auth.ts#L42
npx agent-note why file:///workspace/repo/src/middleware/auth.ts#L42
npx agent-note why vscode://file/workspace/repo/src/middleware/auth.ts:42:7

Note

why accepts path:line, path:line-end, path:line:column, path#Lline, path#Lline-Lend, path#LlineCcol, GitHub file URLs, file://..., vscode://file..., and leading @ path mentions copied from AI Agent output. It shortens the manual git blame → git notes --ref=agentnote show <commit> lookup flow.

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:

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.