Agent Watch

https://github.com/surnr/agent-watch
Admin
Agent Watch is a CLI tool that automatically extracts patterns from AI chat sessions and...
Tokens:14,580
Snippets:215
Trust Score:7.3
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Initialize Agent Watch in Your Project

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Navigate to your project directory and run the agent-watch init command to start the interactive setup wizard. This wizard helps configure agent files, git context, chat session extraction, AI tools, and execution timing.

```bash
cd your-project
agent-watch init
```

--------------------------------

### Development Workflow Setup for Agent Watch

Source: https://github.com/surnr/agent-watch/blob/main/AGENTS.md

Steps to clone, install dependencies, build, and link the Agent Watch project for local development and testing.

```bash
git clone https://github.com/surnr/agent-watch.git
cd agent-watch
pnpm install
pnpm build
pnpm link --global  # Link for testing
```

--------------------------------

### Initialize Agent Watch Configuration

Source: https://context7.com/surnr/agent-watch/llms.txt

Use `agent-watch init` to start the interactive setup. It detects existing agent files, configures tracking, and installs git hooks. Configuration is saved to `.agent-watch/config.json`.

```bash
cd your-project
agent-watch init
```

```json
{
  "version": 1,
  "agentFiles": ["CLAUDE.md", ".github/copilot-instructions.md"],
  "watchFileChanges": true,
  "hookTrigger": "commit",
  "agents": ["claude-code", "github-copilot-chat", "github-copilot-cli"]
}
```

--------------------------------

### Set up development environment

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Commands to clone, install, and link the agent-watch repository for local development.

```bash
git clone https://github.com/surnr/agent-watch.git
cd agent-watch
pnpm install
pnpm build
pnpm link --global
```

--------------------------------

### Install Agent Watch Globally

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Install the agent-watch CLI tool globally for easy access across your projects. This is the recommended installation method.

```bash
npm install -g agent-watch
```

--------------------------------

### Install Git Hooks

Source: https://context7.com/surnr/agent-watch/llms.txt

Automate the installation of post-commit hooks, supporting Lefthook, Husky, or direct Git integration.

```typescript
import { installGitHook, type HookInstallResult } from "agent-watch/hooks"
import { findGitRoot } from "agent-watch/utils/git"

const projectRoot = "/path/to/your/project"
const gitRoot = findGitRoot(projectRoot)

if (!gitRoot) {
  console.error("Not in a git repository")
  process.exit(1)
}

// Install post-commit hook
const result: HookInstallResult = installGitHook(projectRoot, gitRoot, "commit")

console.log(`Success: ${result.success}`)
console.log(`Method: ${result.method}`)
// Method: "lefthook" | "husky" | "direct" | "manual"
console.log(`Message: ${result.message}`)

// For Lefthook projects, adds to lefthook.yml:
// post-commit:
//   commands:
//     agent-watch:
//       run: npx agent-watch run

// For Husky projects, creates .husky/post-commit:
// npx agent-watch run

// For direct installation, creates .git/hooks/post-commit:
// #!/bin/sh
// # >>> agent-watch hook start >>>
// npx agent-watch run 2>/dev/null || true
// # <<< agent-watch hook end <<<
```

--------------------------------

### Example Release Flow: Version and Publish

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Details the steps to prepare for release, including versioning packages with changesets, committing version updates, running CI tests, publishing to npm with OTP, and pushing tags.

```bash
pnpm changeset version
# Creates version 1.1.0 (minor bump)
# Updates CHANGELOG.md with both changes

git add .
git commit -m "chore: version packages"

pnpm test:ci
npm publish --otp=123456

git push --follow-tags
```

--------------------------------

### Install GitHub Copilot CLI

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Install the GitHub Copilot CLI using Homebrew on macOS or npm globally. Verify the installation by checking the version.

```bash
# macOS (Homebrew)
brew install gh-copilot
```

```bash
# npm
npm install -g @githubnext/github-copilot-cli
```

```bash
copilot -v
```

--------------------------------

### Agent Watch Configuration

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Example configuration file generated after running agent-watch init.

```json
{
  "version": 1,
  "agentFiles": ["CLAUDE.md", ".github/copilot-instructions.md"],
  "watchFileChanges": true,
  "hookTrigger": "commit",
  "agents": ["claude-code", "github-copilot-chat", "github-copilot-cli"]
}
```

--------------------------------

### Run Agent Watch Init Without Installation

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Execute the agent-watch initialization command directly using npx without a prior installation. This is useful for trying out the tool or for one-off initializations.

```bash
npx agent-watch init
```

--------------------------------

### Example Release Flow: Add Feature

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Demonstrates the process of adding a new feature, including creating a feature branch, making changes, generating a changeset for a minor version bump, committing, and pushing.

```bash
git checkout -b feat/new-agent-support
# ... make changes ...
pnpm changeset
# Select: minor
# Summary: "Add support for Aider agent configuration"
git add .
git commit -m "feat: add Aider agent support"
git push
```

--------------------------------

### Copilot CLI Configuration Help

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Get help specific to Copilot CLI configuration settings.

```bash
copilot help config
```

--------------------------------

### Start GitHub Copilot CLI Session

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Initiate an interactive Copilot CLI session, optionally starting with a specific prompt or in non-interactive mode. You can also resume previous sessions.

```bash
# Start interactive mode
copilot
```

```bash
# Start with a prompt
copilot -i "Fix the bug in main.js"
```

```bash
# Non-interactive mode (exits after completion)
copilot -p "Explain this function" --allow-all-tools
```

```bash
# Resume most recent session
copilot --continue
```

```bash
# Resume a specific session
copilot --resume <session-id>
```

```bash
# Resume using session picker
copilot --resume
```

--------------------------------

### General Copilot CLI Help

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Use this command to get general help information about the Copilot CLI.

```bash
copilot help
```

--------------------------------

### installGitHook

Source: https://context7.com/surnr/agent-watch/llms.txt

Install agent-watch hooks into git, with automatic detection and integration for Lefthook and Husky.

```APIDOC
## installGitHook

### Description
Installs agent-watch hooks into the git repository. Automatically detects and integrates with Lefthook or Husky if present.

### Parameters
- **projectRoot** (string) - The project root directory.
- **gitRoot** (string) - The git repository root directory.
- **hookType** (string) - The type of hook to install (e.g., 'commit').

### Response
- **success** (boolean) - Whether the installation was successful.
- **method** (string) - The installation method used ('lefthook', 'husky', 'direct', or 'manual').
- **message** (string) - Status message.
```

--------------------------------

### Integrate agent-watch with Git hooks

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Configuration examples for automating agent-watch execution via Lefthook or Husky.

```yaml
post-commit:
  commands:
    agent-watch:
      run: npx agent-watch run
```

```bash
npx husky add .husky/post-commit "npx agent-watch run"
```

--------------------------------

### Example Release Flow: Fix Bug

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Illustrates the workflow for fixing a bug, including making changes, generating a changeset for a patch version bump, committing, and pushing.

```bash
# ... make changes ...
pnpm changeset
# Select: patch
# Summary: "Fix file detection for nested directories"
git add .
git commit -m "fix: file detection in nested dirs"
git push
```

--------------------------------

### Install Agent Watch as a Dev Dependency

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Install agent-watch as a development dependency in your project for team consistency. Use npm or pnpm.

```bash
npm install -D agent-watch
```

```bash
pnpm add -D agent-watch
```

--------------------------------

### Implement Vitest Test Pattern

Source: https://github.com/surnr/agent-watch/blob/main/AGENTS.md

Standard test structure using Vitest with temporary directory setup and teardown.

```typescript
// Use beforeEach/afterEach for setup/teardown
describe("feature", () => {
  let tempDir: string

  beforeEach(() => {
    tempDir = mkdtempSync(join(tmpdir(), "test-"))
  })

  afterEach(() => {
    rmSync(tempDir, { recursive: true, force: true })
  })

  it("should do something", () => {
    // Test here
  })
})
```

--------------------------------

### Commit Code with Agent Watch Triggered

Source: https://github.com/surnr/agent-watch/blob/main/README.md

After initialization, agent-watch automatically runs on git commits. This example shows a typical commit process where agent-watch extracts sessions, generates summaries, and updates agent configuration files.

```bash
git add .
git commit -m "feat: add user authentication"
```

--------------------------------

### Initialize Copilot Repository Instructions

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Initialize Copilot instructions for a repository by creating the `.github/copilot-instructions.md` file and setting up repository-level configuration.

```bash
copilot init
```

--------------------------------

### Build and Test for Release

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Before publishing, run the full test suite and build the package to ensure everything is working correctly.

```bash
# Run full test suite
pnpm test:ci

# Build the package
pnpm build

# Verify package contents
npm pack --dry-run
```

--------------------------------

### Manage Pre-release Versions

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Commands for creating and publishing beta or alpha versions using Changesets.

```bash
# Create pre-release changeset
pnpm changeset --pre beta

# Version and publish
pnpm changeset version
npm publish --tag beta
```

--------------------------------

### Troubleshoot common issues

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Commands for resolving common configuration and environment issues.

```bash
agent-watch init
```

```bash
npm install -g @githubnext/github-copilot-cli
```

```bash
agent-watch run --debug
```

```bash
copilot auth
```

--------------------------------

### Include File as Context with '@' Prefix

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Utilize the '@' prefix to include a file's content as context for the AI. This allows Copilot to analyze or explain specific files.

```bash
@src/main.ts explain this
```

--------------------------------

### Copilot CLI Logging Configuration Help

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Details on how to configure logging for Copilot CLI.

```bash
copilot help logging
```

--------------------------------

### Copilot CLI Tool Usage Rules Help

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Understand the rules governing tool usage within Copilot CLI.

```bash
copilot help permissions
```

--------------------------------

### Develop Feature and Build

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Steps for developing a new feature, including creating a branch, making code changes, running tests, and building the project.

```bash
# Create a branch (optional but recommended)
git checkout -b feat/my-new-feature

# Make your changes
# ... edit files ...

# Run tests
pnpm test

# Build
pnpm build
```

--------------------------------

### Build and Test Commands for Agent Watch

Source: https://github.com/surnr/agent-watch/blob/main/AGENTS.md

Standard commands for building, testing, and linting the Agent Watch project. Use `pnpm build` for transpilation, `pnpm test:ci` for the full CI pipeline, and `pnpm test:unit` for unit tests.

```bash
pnpm build
# Output: dist/index.js, dist/index.cjs, dist/index.d.ts, dist/cli.js
```

```bash
pnpm test:ci
```

```bash
pnpm test:unit
```

```bash
pnpm check
```

```bash
pnpm check:fix
```

```bash
pnpm test:types
```

```bash
pnpm test:unused
```

```bash
pnpm test:exports
```

--------------------------------

### Create Changeset and Push Changes

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Standard workflow for initiating a version bump by creating a changeset and pushing to the repository.

```bash
# 1. Make changes
# ... edit code ...

# 2. Create changeset
pnpm changeset

# 3. Commit and push
git add .
git commit -m "feat: my feature"
git push
```

--------------------------------

### Manage Copilot Plugins

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Use this command to manage plugins and access plugin marketplaces within Copilot CLI.

```bash
copilot plugin
```

--------------------------------

### Release Workflow

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Follow this workflow to create and publish new releases. It involves bumping versions, reviewing changes, committing, and publishing to npm.

```bash
# 1. Bump version (consumes all pending changesets)
pnpm changeset version

# 2. Review the changes
git diff

# 3. Commit the version bump
git add .
git commit -m "chore: version packages"

# 4. Publish to npm (requires npm 2FA code)
npm publish --otp=YOUR_6_DIGIT_CODE

# 5. Push to GitHub
git push --follow-tags
```

--------------------------------

### Configure npm Automation Token

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Set up an npm automation token for publishing without needing to enter an OTP code each time. This involves generating a token on npmjs.com and configuring it locally.

```bash
# Set the token:
npm config set //registry.npmjs.org/:_authToken YOUR_TOKEN
```

--------------------------------

### Create GitHub Release

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Create a GitHub release using the GitHub CLI, linking it to a specific tag and providing release notes.

```bash
# Create a GitHub release
gh release create v1.X.X --title "v1.X.X" --notes "See CHANGELOG.md for details"
```

--------------------------------

### Commit and Push Workflows

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Commands to stage and push the newly created workflow files to the repository.

```bash
git add .github/workflows/
git commit -m "chore: add GitHub Actions workflows"
git push
```

--------------------------------

### Configure Custom Release Scripts

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Define custom release commands in the package.json file for standard or dry-run publishing.

```json
{
  "scripts": {
    "release": "changeset publish",
    "release:dry": "changeset publish --dry-run"
  }
}
```

--------------------------------

### Create a Changeset

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Use this command to create a changeset file after completing your code changes. It prompts for the type of change and a summary.

```bash
pnpm changeset
```

--------------------------------

### Publish to npm with 2FA

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Manually publish the package to npm using the npm publish command, requiring a 2FA code for authentication.

```bash
# Publish with 2FA
npm publish --otp=YOUR_6_DIGIT_CODE
```

--------------------------------

### Enable Provenance in package.json

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Configures the package to support provenance during publishing.

```json
{
  "publishConfig": {
    "provenance": true,
    "access": "public"
  }
}
```

--------------------------------

### Copilot CLI Environment Variables Help

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Information on environment variables that can be used with Copilot CLI.

```bash
copilot help environment
```

--------------------------------

### Daily Development Workflow

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Use this workflow for daily development tasks, including making code changes, creating a changeset, committing, and pushing.

```bash
# 1. Make code changes
# 2. Create a changeset
pnpm changeset

# 3. Commit with your changes
git add .
git commit -m "feat: your feature description"
git push
```

--------------------------------

### Publish with Two-Factor Authentication

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

When two-factor authentication is required for publishing, use the `--otp` flag with your one-time password. This ensures secure package publication.

```bash
npm publish --otp=123456
```

--------------------------------

### Run Copilot CLI Prompt and Exit

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Execute a prompt and exit immediately after completion. Use `--allow-all-tools` to permit all tool usage.

```bash
copilot -p "List all TODO comments in src/" --allow-all-tools
```

--------------------------------

### Select AI Model in GitHub Copilot CLI

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Choose a specific AI model for Copilot CLI using the `--model` flag. A list of available models is provided.

```bash
copilot --model claude-sonnet-4.5
```

```bash
copilot --model gpt-5
```

--------------------------------

### Review Changes

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

After bumping the version, review the changes using git diff and check the CHANGELOG.md to ensure accuracy.

```bash
# Check what changed
git diff

# Review the CHANGELOG.md
cat CHANGELOG.md
```

--------------------------------

### Copilot CLI Interactive Mode Commands Help

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Learn about the commands available in Copilot CLI's interactive mode.

```bash
copilot help commands
```

--------------------------------

### Delegate Prompt to Copilot Agent with '&' Prefix

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Employ the '&' prefix to delegate a prompt to the Copilot coding agent for processing. This is suitable for tasks that require AI assistance.

```bash
&fix the login bug
```

--------------------------------

### Save Copilot CLI Session as GitHub Gist

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Share the current Copilot CLI session as a GitHub Gist. Use the `--share-gist` flag.

```bash
copilot -p "Review my code" --share-gist
```

--------------------------------

### Utilize Git Repository Helpers

Source: https://context7.com/surnr/agent-watch/llms.txt

Check repository status and detect hook managers like Lefthook or Husky.

```typescript
import {
  findGitRoot,
  isGitRepo,
  hasLefthook,
  hasHusky,
  getLefthookPath,
  getGitHooksDir
} from "agent-watch/utils/git"

const cwd = process.cwd()

// Find git repository root
const gitRoot = findGitRoot(cwd)
if (gitRoot) {
  console.log(`Git root: ${gitRoot}`)
  // Git root: /home/user/my-project
}

// Check if in a git repository
if (isGitRepo(cwd)) {
  console.log("Inside a git repository")
}

// Detect git hook managers
const projectRoot = gitRoot || cwd

if (hasLefthook(projectRoot)) {
  const lefthookPath = getLefthookPath(projectRoot)
  console.log(`Lefthook config: ${lefthookPath}`)
  // Lefthook config: /home/user/my-project/lefthook.yml
}

if (hasHusky(projectRoot)) {
  console.log("Husky detected in .husky/")
}

// Get git hooks directory path
const hooksDir = getGitHooksDir(gitRoot)
console.log(`Hooks directory: ${hooksDir}`)
// Hooks directory: /home/user/my-project/.git/hooks
```

--------------------------------

### Troubleshoot Workflow Issues

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Commands to verify the presence of changesets and workflow files, or to force a re-trigger of the release process.

```bash
# Check for changesets
ls .changeset/

# Verify workflow file exists
ls .github/workflows/release.yml

# Re-trigger by pushing to main
git commit --allow-empty -m "chore: trigger release workflow"
git push
```

--------------------------------

### Detect AI Agent Files in Project

Source: https://context7.com/surnr/agent-watch/llms.txt

Use `detectAgentFiles` to find all known AI agent configuration file patterns in a project, and `getExistingAgentFiles` to list only those that currently exist. Both functions return an array of `AgentFileInfo` objects.

```typescript
import { detectAgentFiles, getExistingAgentFiles, type AgentFileInfo } from "agent-watch"

const projectRoot = "/path/to/your/project"

// Detect all known agent file patterns (existing or not)
const allFiles = detectAgentFiles(projectRoot)
for (const file of allFiles) {
  console.log(`${file.pattern.label}: ${file.exists ? "exists" : "missing"}`)
  // "AGENTS.md (Recommended): exists"
  // "CLAUDE.md (Claude Code): exists"
  // ".github/copilot-instructions.md (GitHub Copilot): missing"
  // ".cursor/rules (Cursor): missing"
}

// Get only existing agent files
const existingFiles = getExistingAgentFiles(projectRoot)
console.log(`Found ${existingFiles.length} agent file(s)`)
// Found 2 agent file(s)

for (const file of existingFiles) {
  console.log(`Path: ${file.absolutePath}`)
  console.log(`Agent: ${file.pattern.agent}`)
  // Path: /path/to/project/CLAUDE.md
  // Agent: Claude Code
}
```

--------------------------------

### Configure Release Workflow

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Automates the creation of versioning pull requests and publishing to npm using Changesets.

```yaml
name: Release

on:
  push:
    branches:
      - main

concurrency: ${{ github.workflow }}-${{ github.ref }}

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      id-token: write # Required for provenance

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10.8.0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          publish: pnpm release
          commit: 'chore: version packages'
          title: 'chore: version packages'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

--------------------------------

### Run CI Tests

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Execute the full test suite in CI mode to ensure all tests pass before publishing. This is a crucial step to maintain package stability.

```bash
pnpm test:ci
```

--------------------------------

### Manual Release Workflow Commands

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Commands used for manual package publishing before migrating to an automated system. Requires manual execution of versioning, publishing, and pushing tags.

```bash
pnpm changeset version
npm publish --otp=123456
git push --follow-tags
```

--------------------------------

### Push to GitHub with Tags

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Push your local commits and tags to the GitHub repository to update the remote.

```bash
# Push commits and tags
git push --follow-tags
```

--------------------------------

### Bump Version

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Execute this command to bump the package version based on recorded changesets, update CHANGELOG.md, and clean up changeset files.

```bash
pnpm changeset version
```

--------------------------------

### detectAgentFiles

Source: https://context7.com/surnr/agent-watch/llms.txt

Scans a project for known AI agent configuration files and returns information about each.

```APIDOC
## detectAgentFiles

### Description
Scans a project for known AI agent configuration files and returns information about each, including whether they exist.

### Parameters
#### Path Parameters
- **projectRoot** (string) - Required - The absolute path to the project root directory.

### Response
- **AgentFileInfo[]** (array) - Returns an array of objects containing file patterns, labels, and existence status.
```

--------------------------------

### Agent Watch Directory Structure

Source: https://github.com/surnr/agent-watch/blob/main/AGENTS.md

Overview of the Agent Watch project's directory layout, showing the organization of source files, commands, prompts, and utilities.

```tree
src/
├── cli.ts                          # Entry point, CLI command setup
├── config.ts                       # Config loading/saving (AgentWatchConfig)
├── constants.ts                    # Exported constants (file patterns, ignored files)
├── detect.ts                       # Detect existing agent files in project
├── hooks.ts                        # Git hook installation/management
├── index.ts                        # Public API exports
├── commands/
│   ├── init.ts                     # Interactive setup wizard
│   └── run.ts                      # Main execution flow (extract → summarize → update)
├── prompts/
│   ├── index.ts                    # Prompt builder exports
│   ├── session-analysis.ts         # Session → patterns prompt template
│   ├── agent-file-update.ts        # Agent file update prompt template
│   └── agent-file-creation.ts      # Agent file creation prompt template
└── utils/
    ├── copilot.ts                  # Copilot CLI interaction (--yolo mode)
    ├── git.ts                      # Git operations (get diff, changed files)
    ├── debug.ts                    # Debug output saving
    ├── logger.ts                   # Colored console output
    └── sessions/
        ├── index.ts                # Main session processing
        ├── state.ts                # Processed sessions state (sessions.json)
        ├── summarize.ts            # Session → summary via Copilot
        ├── types.ts                # SessionExtractor, Session interfaces
        └── extractors/
            ├── claude-code.ts      # Extract from ~/.claude/projects/
            ├── copilot-chat.ts     # Extract from VS Code workspaceStorage
            └── copilot-cli.ts      # Extract from ~/.copilot/session-state/
```

--------------------------------

### Manually Update Agent Files

Source: https://context7.com/surnr/agent-watch/llms.txt

Run `agent-watch run` to manually update agent files with recent context from AI sessions and git changes. Use `--debug` to inspect the extraction and summarization process.

```bash
agent-watch run
```

```bash
agent-watch run --debug
```

```bash
git add .
git commit -m "feat: add user authentication"
# agent-watch runs automatically after commit
# - Extracts latest 3 sessions from each AI tool
# - Generates summaries of patterns discussed
# - Updates CLAUDE.md, copilot-instructions.md, etc.
```

--------------------------------

### Run Pre-Publish Checks

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Execute build and TypeScript export tests before publishing to ensure package integrity. This script verifies successful compilation and valid exports.

```bash
pnpm run build && pnpm run test:exports
```

--------------------------------

### Configure Tool Permissions in GitHub Copilot CLI

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Manage permissions for tools, paths, and URLs using CLI flags. You can allow all permissions, specific categories, or deny specific tools and URLs.

```bash
# Allow all permissions (tools, paths, URLs)
copilot --allow-all
copilot --yolo
```

```bash
# Allow specific tool categories
copilot --allow-all-tools
copilot --allow-all-paths
copilot --allow-all-urls
```

```bash
# Allow specific tools
copilot --allow-tool 'shell(git:*)'
copilot --allow-tool 'write'
```

```bash
# Deny specific tools
copilot --deny-tool 'shell(git push)'
```

```bash
# Allow specific URLs/domains
copilot --allow-url github.com
```

```bash
# Deny specific URLs
copilot --deny-url malicious-site.com
```

```bash
# Add accessible directories
copilot --add-dir ~/workspace --add-dir /tmp
```

--------------------------------

### Build AI Prompts for Session Analysis and File Updates

Source: https://context7.com/surnr/agent-watch/llms.txt

Use these functions to generate prompts for extracting patterns from chat sessions or updating project-specific agent configuration files.

```typescript
import {
  buildSessionAnalysisPrompt,
  buildAgentFileUpdatePrompt,
  buildAgentFileCreationPrompt,
  PROMPT_SESSION_ANALYSIS,
  PROMPT_AGENT_FILE_UPDATE
} from "agent-watch/prompts"

// Build session analysis prompt
const humanMessages = [
  "How should we handle API errors?",
  "Should we use React Query or fetch directly?"
]
const aiResponse = "I recommend using React Query for all API calls. It provides built-in caching, error handling, and loading states..."

const analysisPrompt = buildSessionAnalysisPrompt(humanMessages, aiResponse)
// Returns prompt asking AI to extract patterns from the conversation

// Build agent file update prompt
const gitContext = `Commit message: feat: add user authentication
Files changed: src/auth/login.ts, src/auth/logout.ts`
const summaries = [
  "Use React Query for API calls with proper error boundaries",
  "Validate all inputs with Zod schemas"
]
const agentFilePaths = ["/project/CLAUDE.md", "/project/.github/copilot-instructions.md"]

const updatePrompt = buildAgentFileUpdatePrompt(gitContext, summaries, agentFilePaths)
// Returns prompt for updating agent files with new patterns

// Build agent file creation prompt
const creationPrompt = buildAgentFileCreationPrompt("CLAUDE.md")
// Returns: "Create a CLAUDE.md file for this project. Analyze the codebase to understand the project structure, tech stack, and conventions. Write the file directly."
```

--------------------------------

### Authenticate GitHub Copilot CLI

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Log in to GitHub Copilot CLI using the OAuth device flow. For GitHub Enterprise Server, specify the host.

```bash
# Login via OAuth device flow
copilot login
```

```bash
# Login to a GitHub Enterprise Server
copilot login --host https://github.example.com
```

--------------------------------

### loadConfig

Source: https://context7.com/surnr/agent-watch/llms.txt

Loads the agent-watch configuration from a project's .agent-watch/config.json file.

```APIDOC
## loadConfig

### Description
Loads the agent-watch configuration from a project's .agent-watch/config.json file.

### Parameters
#### Path Parameters
- **projectRoot** (string) - Required - The absolute path to the project root directory.

### Response
- **AgentWatchConfig** (object) - Returns the configuration object containing version, agentFiles, watchFileChanges, hookTrigger, and agents list.
```

--------------------------------

### Save Copilot CLI Session to Markdown

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Save the current Copilot CLI session to a markdown file. Requires `--allow-all` and a specified output path.

```bash
copilot -p "Fix the tests" --allow-all --share ./session.md
```

--------------------------------

### Run Local Tests

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Execute local tests to identify and fix failing tests before publishing. Use `pnpm test` to see failures and `pnpm test:ci` to re-run after fixes.

```bash
pnpm test
```

--------------------------------

### Run agent-watch in debug mode

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Executes the agent-watch process with debug logging enabled, creating a .agent-watch/debug/ directory with session data and prompt logs.

```bash
agent-watch run --debug
```

--------------------------------

### Update Copilot CLI

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Download the latest version of the Copilot CLI using the `update` command.

```bash
copilot update
```

--------------------------------

### Load Agent Watch Configuration Programmatically

Source: https://context7.com/surnr/agent-watch/llms.txt

Use the `loadConfig` function to load the agent-watch configuration from `.agent-watch/config.json`. It returns an `AgentWatchConfig` object or null if no configuration is found.

```typescript
import { loadConfig, type AgentWatchConfig } from "agent-watch"

// Load configuration from project root
const projectRoot = "/path/to/your/project"
const config = loadConfig(projectRoot)

if (config) {
  console.log("Agent files:", config.agentFiles)
  // ["CLAUDE.md", ".github/copilot-instructions.md"]

  console.log("Hook trigger:", config.hookTrigger)
  // "commit" or "push"

  console.log("Enabled AI tools:", config.agents)
  // ["claude-code", "github-copilot-chat", "github-copilot-cli"]

  console.log("Watch file changes:", config.watchFileChanges)
  // true
} else {
  console.log("No configuration found - run 'agent-watch init'")
}
```

```typescript
// AgentWatchConfig interface:
// {
//   version: 1
//   agentFiles: string[]
//   watchFileChanges: boolean
//   hookTrigger: "commit" | "push"
//   agents: string[]
// }
```

--------------------------------

### KNOWN_AGENT_FILES

Source: https://context7.com/surnr/agent-watch/llms.txt

Access the list of all supported AI agent configuration file patterns.

```APIDOC
## KNOWN_AGENT_FILES

### Description
Provides a list of supported AI agent configuration file patterns used for detection.

### Data Structure
- **path** (string) - The file path pattern.
- **agent** (string) - The name of the AI agent associated with the pattern.
```

--------------------------------

### Configure CI Workflow

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Defines the CI pipeline to run tests and builds on pull requests and pushes to the main branch.

```yaml
name: CI

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10.8.0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Run tests
        run: pnpm test:ci

      - name: Build
        run: pnpm build
```

--------------------------------

### Configure Monorepo Package Linking

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Define linked or fixed package groups in the Changesets configuration file for monorepo management.

```json
{
  "linked": [
    ["package-a", "package-b"]
  ],
  "fixed": [
    ["package-c", "package-d"]
  ]
}
```

--------------------------------

### Run Copilot CLI with Silent Output

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Run a prompt with silent output, showing only the agent's response and suppressing statistics. Use the `-s` flag for this.

```bash
copilot -p "What does main.ts do?" -s
```

--------------------------------

### Verify Package Signatures

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

Use npm audit to verify the cryptographic authenticity of the published package.

```bash
npm audit signatures
```

--------------------------------

### Git Utilities

Source: https://context7.com/surnr/agent-watch/llms.txt

Utility functions for working with git repositories and detecting hook managers.

```APIDOC
## Git Utilities

### Description
Helper functions to identify git repository roots, check for git status, and detect hook managers like Lefthook or Husky.

### Functions
- **findGitRoot(cwd)**: Returns the git root directory.
- **isGitRepo(cwd)**: Returns true if the path is inside a git repository.
- **hasLefthook(projectRoot)**: Checks for Lefthook configuration.
- **hasHusky(projectRoot)**: Checks for Husky configuration.
- **getGitHooksDir(gitRoot)**: Returns the path to the .git/hooks directory.
```

--------------------------------

### Execute Shell Command with '!' Prefix

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Use the '!' prefix to execute a shell command directly without AI processing. This is useful for running standard terminal commands.

```bash
!git status
```

--------------------------------

### Check TypeScript Types

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Before attempting to fix build errors, run `pnpm run test:types` to specifically check for TypeScript compilation errors. Address these errors before proceeding.

```bash
pnpm run test:types
```

--------------------------------

### Define AgentWatchConfig Interface

Source: https://github.com/surnr/agent-watch/blob/main/AGENTS.md

Configuration schema for user settings, including managed files and trigger hooks.

```typescript
interface AgentWatchConfig {
  version: 1
  agentFiles: string[]         // Relative paths to files to manage
  watchFileChanges: boolean    // Include git commit context
  hookTrigger: "commit" | "push"  // When to run
  agents: string[]             // Enabled AI tools
}
```

--------------------------------

### Set Custom Copilot CLI Log Directory

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Specify a custom directory for Copilot CLI logs using the `--log-dir` flag. The default log directory is `~/.copilot/logs/`.

```bash
copilot --log-dir /tmp/copilot-logs
```

--------------------------------

### processAllSessions

Source: https://context7.com/surnr/agent-watch/llms.txt

Process chat sessions from enabled AI tools, extract patterns, and return summaries.

```APIDOC
## processAllSessions

### Description
Processes chat sessions from specified AI tools, extracts patterns, and returns a list of summaries.

### Parameters
- **projectRoot** (string) - The root directory of the project.
- **enabledTools** (string[]) - List of tools to process (e.g., 'claude-code', 'github-copilot-chat').

### Response
- **summaries** (string[]) - A list of extracted pattern summaries.
```

--------------------------------

### Fix Pre-commit Hook Failures

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

If the pre-commit hook fails due to Biome checks, run the fix command to automatically resolve issues. Afterwards, stage the changes and commit.

```bash
pnpm run check:fix
git add .
git commit
```

--------------------------------

### Process AI Chat Sessions

Source: https://context7.com/surnr/agent-watch/llms.txt

Extract and summarize chat sessions from enabled AI tools. State is persisted in .agent-watch/sessions.json.

```typescript
import {
  processAllSessions,
  getProcessedSessionIds,
  markSessionsAsProcessed,
  clearProcessedSessions,
  type Session,
  type SessionContent
} from "agent-watch"

const projectRoot = "/path/to/your/project"
const enabledTools = ["claude-code", "github-copilot-chat", "github-copilot-cli"]

// Process sessions and get summaries
const summaries = processAllSessions(projectRoot, enabledTools)
// Returns: ["Summary 1: Use React Query for API calls...", "Summary 2: Zod for validation..."]

console.log(`Generated ${summaries.length} pattern summaries`)

// Check which sessions have been processed for a tool
const processedIds = getProcessedSessionIds(projectRoot, "claude-code")
console.log(`Already processed ${processedIds.length} Claude Code sessions`)

// Manually mark sessions as processed (for custom integrations)
markSessionsAsProcessed(projectRoot, "claude-code", ["session-abc123", "session-def456"])

// Clear processed sessions for a tool (useful for testing/reprocessing)
clearProcessedSessions(projectRoot, "github-copilot-chat")

// Session state is stored in .agent-watch/sessions.json:
// {
//   "processedSessions": {
//     "claude-code": ["session-1", "session-2"],
//     "github-copilot-chat": ["chat-1", "chat-2"],
//     "github-copilot-cli": ["cli-1", "cli-2"]
//   }
// }
```

--------------------------------

### Access Supported Agent File Patterns

Source: https://context7.com/surnr/agent-watch/llms.txt

Use KNOWN_AGENT_FILES to identify or filter supported AI agent configuration files in a project.

```typescript
import { KNOWN_AGENT_FILES, type AgentFilePattern } from "agent-watch"

// List all supported agent file patterns
for (const pattern of KNOWN_AGENT_FILES) {
  console.log(`${pattern.path} - ${pattern.agent}`)
}
// Output:
// AGENTS.md - Generic
// CLAUDE.md - Claude Code
// .github/copilot-instructions.md - GitHub Copilot
// .cursor/rules - Cursor
// .windsurfrules - Windsurf
// .clinerules - Cline

// Use patterns for custom file detection
const claudePattern = KNOWN_AGENT_FILES.find(p => p.agent === "Claude Code")
if (claudePattern) {
  console.log(`Claude Code uses: ${claudePattern.path}`)
  // Claude Code uses: CLAUDE.md
}
```

--------------------------------

### Commit Changeset

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Commit the changeset file along with your code changes to track modifications for release.

```bash
git add .
git commit -m "feat: add support for .aiderules file"
git push
```

--------------------------------

### Run agent-watch manually

Source: https://github.com/surnr/agent-watch/blob/main/README.md

Triggers the agent-watch process without requiring a git commit.

```bash
agent-watch run
```

--------------------------------

### Set Copilot CLI Log Level

Source: https://github.com/surnr/agent-watch/blob/main/docs/copilot-cli.md

Set the log level for Copilot CLI to 'debug' for detailed logging. Other levels include: `none`, `error`, `warning`, `info`, `all`, `default`.

```bash
copilot --log-level debug
```

--------------------------------

### Session Tracking Schema

Source: https://github.com/surnr/agent-watch/blob/main/README.md

JSON structure used to track processed sessions per tool to prevent redundant analysis.

```json
{
  "processedSessions": {
    "claude-code": ["session-1", "session-2"],
    "github-copilot-chat": ["chat-1", "chat-2"],
    "github-copilot-cli": ["cli-1", "cli-2"]
  }
}
```

--------------------------------

### Define Session Data Structures

Source: https://github.com/surnr/agent-watch/blob/main/AGENTS.md

Standardized interfaces for representing session data and content.

```typescript
interface Session {
  id: string
  content: SessionContent
  timestamp: number
}

interface SessionContent {
  userMessages: string[]
  aiResponse: string
}
```

--------------------------------

### Automated Release Workflow Trigger

Source: https://github.com/surnr/agent-watch/blob/main/docs/GITHUB_ACTIONS.md

The simplified trigger for an automated release process. After setting up workflows, the only action required is to merge the generated versioning pull request.

```bash
# Just merge the "Version Packages" PR
# Everything else happens automatically
```

--------------------------------

### Commit Version Bump

Source: https://github.com/surnr/agent-watch/blob/main/docs/RELEASE_GUIDE.md

Commit the changes related to the version bump after reviewing them.

```bash
git add .
git commit -m "chore: version packages"
```

--------------------------------

### Define SessionExtractor Interface

Source: https://github.com/surnr/agent-watch/blob/main/AGENTS.md

The contract for all tool-specific session extractors. Implementations must return the latest sessions from the specified home directory.

```typescript
interface SessionExtractor {
  extractLatestSessions(
    homeDir: string,
    limit: number
  ): Promise<Session[] | null>
}
```
Tokens:
Raw