agent-notes

agent-notes is a deterministic TypeScript CLI and ESM library that scans a repository and generates lightweight Markdown context files for AI coding agents and human contributors.

It does not call AI services, use external project APIs, or mutate hidden repo state. Generated files are plain Markdown so changes are easy to review.

Why

AI coding agents work better when project context is explicit and reviewable. agent-notes keeps the scope intentionally small: it detects common Node.js and TypeScript project signals, then writes a conservative AGENTS.md plus a few supporting notes under .agent-notes/.

Install

npm install --save-dev agent-notes

Run without installing globally:

npx agent-notes scan

Usage

Scan the current repository:

agent-notes scan
agent-notes scan --json

Example scan output:

agent-notes scan
Root: /path/to/repo
Project types: Node.js
Languages: TypeScript
Frameworks: Vitest
Workspaces: none detected
Package manager: npm
Important files: package.json, tsconfig.json
Commands: test (npm run test)
Warnings: none detected

Scan another repository without changing directories:

agent-notes scan --path ../other-repo
agent-notes scan --path ../other-repo --json

Generate notes:

agent-notes init
agent-notes init --path ../other-repo
agent-notes init --dry-run
agent-notes init --force

Refresh generated notes while preserving manual content outside generated sections:

agent-notes update
agent-notes update --dry-run
agent-notes update --force

Check whether expected note files exist:

agent-notes doctor
agent-notes doctor --path ../other-repo
agent-notes doctor --json

Example doctor output:

agent-notes doctor
present  AGENTS.md
present  .agent-notes/project.md
present  .agent-notes/commands.md
present  .agent-notes/conventions.md
present  .agent-notes/risks.md

Library API

The package also exposes ESM entry points for tools that want to reuse the same deterministic scan, generate, plan, and write pipeline:

import {
  generateFiles,
  planUpdates,
  planWrites,
  scanRepo,
  writeFiles,
  writeUpdates
} from "agent-notes";

const analysis = await scanRepo(process.cwd());
const files = generateFiles(analysis);

const writePlan = await planWrites(process.cwd(), files);
await writeFiles(process.cwd(), files, writePlan);

const updatePlan = await planUpdates(process.cwd(), files);
await writeUpdates(process.cwd(), files, updatePlan);

The CLI program factory is available for integrations that need to compose the Commander program directly:

import { createProgram } from "agent-notes/cli";

Generated Files

AGENTS.md
.agent-notes/
  project.md
  commands.md
  conventions.md
  risks.md

init refuses to overwrite existing files unless --force is passed. When --force overwrites files, the CLI names the overwritten paths. Generated content is wrapped in deterministic markers:

<!-- agent-notes:start -->
<!-- generated by [email protected] -->
generated content
<!-- agent-notes:end -->

update only refreshes content inside those markers unless --force is passed.

CLI Commands

• scan: prints a human-readable summary for the current directory.
• scan --path <dir>: scans a different directory.
• scan --json: prints the same analysis as JSON.
• init: writes AGENTS.md and .agent-notes/*.md.
• init --path <dir>: writes notes in a different directory.
• init --dry-run: prints the write plan without changing files.
• init --force: overwrites expected generated files.
• update: refreshes agent-notes generated sections.
• update --dry-run: prints the update plan without changing files.
• update --force: overwrites expected generated files that do not have markers.
• doctor: reports which expected files are present or missing.
• doctor --path <dir>: checks expected files in a different directory.
• doctor --json: prints file status as JSON for scripts and CI.

v0.2 Detection Scope

agent-notes focuses on Node.js and TypeScript repositories. It detects common files such as package.json, lockfiles, pnpm-workspace.yaml, tsconfig.json, Vite/Next configs, ESLint/Prettier configs, test configs, README.md, and GitHub Actions workflows. It also detects package-manager workspaces from package.json and pnpm-workspace.yaml, supports * and ** workspace patterns, and infers common apps/*, packages/*, and services/* layouts when those directories contain their own package.json.

Limitations:

• It does not parse arbitrary framework configuration deeply.
• It does not infer scripts that are missing from package.json.
• It does not inspect remote services.
• It does not publish, commit, or push anything.

Roadmap

The current 0.2.1 release keeps the v0.2 detection scope and tightens fresh-checkout test reliability, public library exports, package-manager detection, and workspace matching correctness.

Future releases are planned as boring-useful improvements:

• Deeper monorepo detection
• .agent-notes.json config support

See ROADMAP.md for scope notes.

Contributing

Keep changes deterministic, small, and easy to review. Avoid adding external service calls or hidden repository mutation.

License

MIT