PARSEME

Local code analysis and context generation to improve token efficiency of AI Coding agents Cross-project access via Cloud MCP

PARSEME analyzes your TypeScript/JavaScript projects and generates a PARSEME.md file—a README.md for AI agents. This file provides comprehensive context documentation that helps AI assistants understand your codebase structure, architecture, and patterns. By providing persistent, reusable context, PARSEME prevents AI agents from repeatedly analyzing your codebase from scratch—saving valuable tokens and improving efficiency for every interaction.

Table of Contents

• Development Status
• Features
  • What PARSEME Detects
  • Language Support
  • Supported Projects
• Installation
• Quick Start
• Automation Options
  • Option 1: Manual Execution
  • Option 2: Automatic Local Generation
  • Option 3: Automatic Local and Remote Generation (Advanced Git Hooks)
  • Option 4: GitHub Actions for Remote Generation paired with Local Generation
• Configuration
  • Configuration File Formats & Priority
  • Configuration Priority
  • Configuration Options
  • CLI Options
  • Interactive Configuration
• CLI Commands
• Programmatic API
• Output Format
• AI Agent Integration
• Requirements
• License

Development Status

This project is currently in active development.

The core functionality is working, but expect:

• API modifications as the interface gets refined
• Additional features being added regularly
• Possible bugs and edge cases

Feedback Welcome!

Your feedback is highly appreciated and helps shape the future of this tool! Please:

• Report bugs or issues
• Suggest features or improvements
• For other inquiries, contact: [email protected]

Features

• Project Analysis - AST-based code analysis with automatic endpoint, component, and service discovery
• Universal Pattern Detection - Dynamic code analysis that works across many JavaScript/TypeScript frameworks
• Git Integration - Includes repository status and change tracking
• Configurable - Comprehensive configuration options via JavaScript, TypeScript, or JSON
• Dev Tool Integration - Works seamlessly as a npm script

What PARSEME Detects

PARSEME uses AST analysis to identify:

• API Endpoints - HTTP routes, GraphQL resolvers, RPC methods
• Components - UI components across all major frameworks
• Services - Business logic classes and service functions
• Data Models - Interfaces, types, schemas, DTOs
• Middleware - Request/response handlers and interceptors
• Utilities - Helper functions, hooks, composables
• Project Structure - Organized by detected patterns and purpose

Language Support

• TypeScript - Full support including advanced types, decorators, interfaces
• JavaScript (ES6+) - Modern JavaScript with ES features
• JSX/TSX - React and other JSX-based frameworks
• Mixed codebases - Projects with both JS and TS files

Supported Projects

PARSEME aims to automatically analyse any JavaScript or TypeScript project like:

Backend APIs

• NestJS - Controllers, services, decorators, dependency injection
• Express.js - Routes, middleware, error handlers
• Fastify - Route registration, plugins, hooks

Frontend Applications

• React - Components (functional & class), hooks, JSX patterns
• Vue.js - Components (Composition & Options API), composables
• Angular - Components, services, decorators, modules
• Svelte - Components, stores, reactive patterns
• Lit - Web components, custom elements
• Vanilla JS/TS - Functions, classes, modules, event handlers

Fullstack Frameworks

• Next.js - Pages, API routes, middleware, components
• Nuxt.js - Pages, server routes, composables, components

Packages & Libraries

• TypeScript utilities - Types, interfaces, enums, generic helpers
• JavaScript helpers - Functions, classes, utilities, data manipulation
• Node.js modules - Exports, imports, CommonJS/ESM patterns
• Monorepo packages - Shared utilities, cross-package dependencies

Development Tools

• CLI tools - Commands, options, argument parsing
• Build plugins - Plugin functions, configuration handlers
• Desktop apps - Main processes, renderers, IPC handlers
• Testing utilities - Test functions, mocks, utilities, custom matchers

Note: PARSEME provides specialized analysis for Express.js, NestJS, and Fastify, including route detection, middleware identification, and decorator analysis. All other frameworks benefit from universal AST-based analysis.

Installation

npm install --save-dev @parseme/cli

Quick Start

1. Initialize configuration:

   npx @parseme/cli init
   # or use the alias
   npx @parseme/cli i

   You'll be prompted for:

   • Context directory path (default: parseme-context)
   • Exclude patterns (default: node_modules/**, dist/**, .git/** - in git repositories, additional patterns on top of git-tracked files)

   A minimal config file will be created with only your custom settings.

   Setup tips will be displayed:

   • How to add parseme script to package.json
   • How to integrate with git hooks
   • README section to help AI agents find context
   • AI agent configuration files to reference PARSEME.md

2. Generate context:

   npx @parseme/cli generate
   # or use the alias
   npx @parseme/cli g

This creates:

• PARSEME.md - Main overview with links to context files
• parseme-context/ - Structured data files (file list, AST structure, routes, git diff)

Automation Options

PARSEME can be integrated into your workflow in several ways, from manual execution to fully automated generation. Choose the approach that best fits your needs:

Option 1: Manual Execution

Run parseme manually whenever you need updated context.

Setup:

Add to your package.json scripts (optional, for convenience):

{
  "scripts": {
    "parseme": "parseme generate"
  }
}

Usage:

npm run parseme
# or directly
parseme generate

Option 2: Automatic Local Generation

Automatically generate parseme files locally after every commit. Files are committed to the repository.

Setup with Husky:

# Install Husky (if not already installed)
npm install --save-dev husky
npx husky init

# Create post-commit hook
cat > .husky/post-commit << 'EOF'
#!/bin/sh

# Load nvm if available
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Generate PARSEME files locally after commit
npx @parseme/cli generate
EOF

# Make hook executable
chmod +x .husky/post-commit

Setup with manual git hooks:

cat > .git/hooks/post-commit << 'EOF'
#!/bin/sh

npx @parseme/cli generate
EOF

chmod +x .git/hooks/post-commit

How it works:

• After each commit, parseme automatically generates context files with full git info
• Files are ready to be staged and committed with your next commit
• Simple setup with minimal configuration

Note: If using a custom contextDir, ensure the path is consistent across your team's configuration.

Option 3: Automatic Local and Remote Generation (Advanced Git Hooks)

Automatically update parseme files locally and remotely with git hooks. Keeps the remote version clean (without git-specific info) while maintaining full context locally. Uses multiple git hooks to manage local vs remote state.

Setup with Husky:

# Install Husky (if not already installed)
npm install --save-dev husky
npx husky init

# Create post-commit hook
cat > .husky/post-commit << 'EOF'
#!/bin/sh

# Load nvm if available
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

npx @parseme/cli generate
EOF

# Create pre-push hook
cat > .husky/pre-push << 'EOF'
#!/bin/sh

# Load nvm if available
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Regenerate without git info for clean remote state
npx @parseme/cli generate --no-git-info

# Stage parseme files
git add parseme-context/ PARSEME.md

# Amend the commit with updated parseme files
git commit --amend --no-edit --no-verify
EOF

# Create post-push hook
cat > .husky/post-push << 'EOF'
#!/bin/sh

# Load nvm if available
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Regenerate with git info for local development
npx @parseme/cli generate
EOF

# Make hooks executable
chmod +x .husky/post-commit .husky/pre-push .husky/post-push

Setup with manual git hooks:

# Post-commit: Generate context with git info after each commit
cat > .git/hooks/post-commit << 'EOF'
#!/bin/sh

npx @parseme/cli generate
EOF

# Pre-push: Regenerate without git info and amend before pushing
cat > .git/hooks/pre-push << 'EOF'
#!/bin/sh

# Regenerate without git info for clean remote state
npx @parseme/cli generate --no-git-info

# Stage parseme files
git add parseme-context/ PARSEME.md

# Amend the commit with updated parseme files
git commit --amend --no-edit --no-verify
EOF

# Post-push: Restore git info locally after push completes
cat > .git/hooks/post-push << 'EOF'
#!/bin/sh

# Regenerate with git info for local development
npx @parseme/cli generate
EOF

# Make hooks executable
chmod +x .git/hooks/post-commit .git/hooks/pre-push .git/hooks/post-push

How it works:

1. post-commit: Generates context files with full git info locally
2. pre-push: Regenerates without git info and amends the commit before pushing
3. post-push: Restores full git info locally after push completes

The --no-verify flag in pre-push prevents an infinite loop by skipping hook execution on the amend.

Note: If using a custom contextDir, update the git add path in the pre-push hook (e.g., git add docs/context/ PARSEME.md).

Option 4: GitHub Actions for Remote Generation paired with Local Generation

Use GitHub Actions to automatically update PARSEME files on every push to main. This is the recommended approach for teams using GitHub.

Setup:

1. Create .github/workflows/parseme-update.yml:

name: Update PARSEME Documentation

on:
  push:
    branches:
      - 'main'

jobs:
  update-parseme:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      GITHUB_TOKEN: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}

    steps:
      - name: Service Account Gate
        run: |
          if [ "${{ github.event.pusher.name }}" = "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}" ]; then
            echo "::notice::Skipping workflow - push was made by service account"
            exit 1
          fi

      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}

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

      - name: Configure Git
        run: |
          git config user.name "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}"
          git config user.email "${{ secrets.GH_SERVICE_ACCOUNT_USERNAME }}@users.noreply.github.com"

      - name: Configure npm for GitHub Packages
        run: |
          npm config set @netgear:registry https://npm.pkg.github.com/
          npm config set //npm.pkg.github.com/:_authToken "${{ secrets.GH_SERVICE_ACCOUNT_TOKEN }}"

      - name: Install dependencies
        run: npm ci

      - name: Generate PARSEME documentation
        run: npx parseme generate --no-git-info

      - name: Stage changes
        run: |
          git add PARSEME.md parseme-context/

      - name: Check for changes
        id: check_changes
        run: |
          if git diff --cached --quiet; then
            echo "changes=false" >> $GITHUB_OUTPUT
          else
            echo "changes=true" >> $GITHUB_OUTPUT
          fi

      - name: Commit
        if: steps.check_changes.outputs.changes == 'true'
        run: |
          git commit -m "chore: Update PARSEME AI Agent Context [skip ci]" --no-verify
          git push

2. Configure GitHub secrets:

• GH_SERVICE_ACCOUNT_TOKEN: A GitHub personal access token with repo write permissions
• GH_SERVICE_ACCOUNT_USERNAME: The username of your service account

3. Setup local git hooks with Husky:

# Install Husky (if not already installed)
npm install --save-dev husky
npx husky init

# Create pre-commit hook
cat > .husky/pre-commit << 'EOF'
#!/bin/sh

# Pre-commit hook to reset PARSEME files to prevent them from being committed
for file in $(git ls-files parseme-context/ PARSEME.md 2>/dev/null); do
    git restore --staged "$file" 2>/dev/null
done
EOF

# Create post-commit hook
cat > .husky/post-commit << 'EOF'
#!/bin/sh

# Load nvm if available
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Generate PARSEME files locally after commit for local AI agent usage
npx @parseme/cli generate --no-git-info
EOF

# Create post-merge hook
cat > .husky/post-merge << 'EOF'
#!/bin/sh

# Load nvm if available
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Generate PARSEME files locally after merge for local AI agent usage
npx @parseme/cli generate --no-git-info
EOF

# Create post-checkout hook
cat > .husky/post-checkout << 'EOF'
#!/bin/sh

# Load nvm if available
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

# Generate PARSEME files locally after checkout for local AI agent usage
npx @parseme/cli generate --no-git-info
EOF

# Make hooks executable
chmod +x .husky/pre-commit .husky/post-commit .husky/post-merge .husky/post-checkout

How it works:

1. On push to main: GitHub Actions detects the push
2. Service account check: Workflow exits early if the push was made by the service account
3. Generate and commit: Generates PARSEME files with --no-git-info flag and creates a new commit with [skip ci] message
4. Push changes: The new commit is pushed back to the repository
5. Local hooks: Pre-commit hook prevents PARSEME files from being committed manually, while post-commit/merge/checkout hooks regenerate them locally for AI agent usage

Notes:

• The workflow only runs on the main branch (adjust as needed for your branching strategy)
• If using a custom contextDir, update the paths in both the workflow and hooks accordingly

Configuration

PARSEME supports multiple configuration formats with automatic discovery and priority handling.

The parseme init command creates a minimal config with only your custom settings. Defaults are applied automatically at runtime.

Minimal config example (created by parseme init):

/** @type {import('@parseme/cli').ParsemeConfigFile} */
const config = {
  contextDir: 'parseme-context',
  excludePatterns: ['node_modules/**', '.git/**'],
};

export default config;

Full config example (all available options):

/** @type {import('@parseme/cli').ParsemeConfigFile} */
const config = {
  // Output settings
  outputPath: 'PARSEME.md',
  contextDir: 'parseme-context',

  // Analysis settings
  rootDir: './',
  analyzeFileTypes: ['ts', 'tsx', 'js', 'jsx'],
  excludePatterns: ['**/*.test.ts', 'dist/**'],
  maxDepth: 10,

  // Git integration
  includeGitInfo: true, // Include git repository information in context
  useGitForFiles: true, // Use git to discover files (respects .gitignore)

  // Size limits
  limits: {
    maxFilesPerContext: 5000,
  },

  // Content sections (all default to true)
  sections: {
    overview: true,
    architecture: true,
    routes: true,
    dependencies: true,
    git: true,
    fileStructure: true,
  },

  // Style options
  style: {
    includeLineNumbers: false,
    includeFileStats: true,
    groupByType: true,
    sortOrder: 'type', // 'alphabetical' | 'type' | 'size'
  },
};

export default config;

Configuration File Formats & Priority

PARSEME supports three configuration formats with the following priority:

1. JSON (.json) - parseme.config.json, .parsemerc.json, .parsemerc
2. TypeScript (.ts) - parseme.config.ts, .parsemerc.ts
3. JavaScript (.js) - parseme.config.js, .parsemerc.js

Example JSON Configuration

{
  "contextDir": "parseme-context",
  "excludePatterns": ["node_modules/**", "dist/**", ".git/**"]
}

Example TypeScript Configuration

import type { ParsemeConfigFile } from '@parseme/cli';

const config: ParsemeConfigFile = {
  contextDir: 'parseme-context',
  excludePatterns: ['node_modules/**', 'dist/**', '.git/**'],
  // ... other options
};

export default config;

Example JavaScript Configuration

/** @type {import('@parseme/cli').ParsemeConfigFile} */
const config = {
  contextDir: 'parseme-context',
  excludePatterns: ['node_modules/**', 'dist/**', '.git/**'],
  // ... other options
};

export default config;

Configuration Priority

Configuration values are resolved in the following order (highest to lowest priority):

1. CLI flags - --output, --root, --config, etc.
2. Config file - Based on file format priority above
3. Default values - Built-in sensible defaults

Example: parseme --output custom.md overrides outputPath from config file.

Configuration Options

Output Settings

• outputPath - Where to save the main PARSEME.md file (default: "PARSEME.md")
• contextDir - Directory for detailed context files (default: "parseme-context")

Analysis Settings

• rootDir - Project root directory (default: process.cwd())
• analyzeFileTypes - File extensions to analyze (default and supported: ['ts', 'tsx', 'js', 'jsx'])
• excludePatterns - Additional glob patterns to exclude files. In git repositories, only git-tracked files are analyzed (respecting all .gitignore files automatically). Use excludePatterns to exclude additional files beyond what git ignores.
• maxDepth - Maximum directory depth to traverse (default: 10)

Git Integration

• includeGitInfo - Include git repository information in context files (default: true)
• useGitForFiles - Use git to discover files, respecting .gitignore (default: true)

Content Sections

Toggle which sections to include in the output (all default to true):

• sections.overview - Project overview and metadata
• sections.architecture - File type breakdown
• sections.routes - API endpoints and routing
• sections.dependencies - Package dependencies
• sections.git - Repository information
• sections.fileStructure - Detailed file listing

Style Options

• style.includeLineNumbers - Add line numbers to code references (default: false)
• style.includeFileStats - Include file statistics (default: true)
• style.groupByType - Group files by detected type (default: true)
• style.sortOrder - Sort order: "alphabetical", "type", or "size" (default: "type")

Size Limits

• limits.maxFilesPerContext - Maximum number of files to analyze (default: 5000)

CLI Options

Generate Command (parseme generate or parseme g)

• -c, --config <path> - Config file path
• -o, --output <path> - Output file path
• -r, --root <path> - Root directory to analyze
• --context-dir <path> - Context directory path (default: parseme-context)
• --file-types <types...> - File types to analyze (e.g., ts tsx js jsx)
• --exclude <patterns...> - Additional exclude patterns (glob, in git repositories on top of git-tracked files)
• --no-git-info - Disable git info generation (keeps git for file discovery)
• --no-git-files - Disable git for file discovery (uses filesystem crawling instead)
• --max-depth <number> - Maximum directory depth

Init Command (parseme init or parseme i)

• -f, --force - Overwrite existing config
• --format <format> - Config format: json, ts, or js (default: json)

Interactive Configuration

When running parseme init interactively (TTY, not CI), you'll be prompted to configure:

• Context directory - Where to store context files (default: parseme-context)
• Exclude patterns - Comma-separated glob patterns (default: node_modules/**, dist/**, .git/** - in git repositories, additional patterns on top of git-tracked files)

After initialization, setup tips are displayed:

• Package.json script suggestion
• Git hook integration suggestion
• README.md section suggestion for AI agents
• AI agent configuration files to reference PARSEME.md

CLI Commands

# Generate context (auto-detects config file)
parseme generate
parseme g  # alias

# Initialize configuration (JSON by default)
parseme init
parseme i  # alias

# Initialize with TypeScript format
parseme init --format ts

# Initialize with JavaScript format
parseme init --format js

# Use custom config file
parseme generate --config custom.config.js

# Override config with CLI flags
parseme generate --output custom.md --context-dir docs/context --root ./src

# Disable git info generation (keeps git for file discovery)
parseme generate --no-git-info

# Disable git for file discovery (keeps git info generation)
parseme generate --no-git-files

# Disable both git info and git file discovery
parseme generate --no-git-info --no-git-files

# Specify file types and exclude patterns
parseme generate --file-types ts js --exclude "**/*.test.ts"

Programmatic API

You can also use PARSEME programmatically:

import { ParsemeGenerator } from '@parseme/cli';

const generator = await ParsemeGenerator.fromConfig('./custom.config.js');
const context = await generator.generate();

// Or generate directly to file
await generator.generateToFile('./output/PARSEME.md');

Output Format

PARSEME generates the following output files:

• PARSEME.md - Main overview with links to context files and project summary (Markdown)
• Context directory (default: parseme-context/) with structured data files:
  • files.md - Complete list of all project files (Markdown)
  • structure.json - AST analysis with exports, imports, functions, classes, and route references (JSON)
  • routes.json - API routes with methods, paths, and handlers (JSON, only if routes detected)
  • gitDiff.md - Git diff statistics from generation time (Markdown, only if git is enabled and changes exist)

The context directory location can be customized via the contextDir configuration option.

AI Agent Integration

To help AI coding assistants efficiently understand your codebase structure and context, add instructions to your agent configuration files:

Claude Code (.claude/README.md or .claude/instructions.md)

Read PARSEME.md and parseme-context/ to understand the codebase structure and context.

GitHub Copilot (.github/copilot-instructions.md)

Read PARSEME.md and parseme-context/ to understand the codebase structure and context.

Cursor (.cursorrules)

Read PARSEME.md and parseme-context/ to understand the codebase structure and context.

ChatGPT / Custom GPT

Add to project instructions or system prompt:

Read PARSEME.md and parseme-context/ to understand the codebase structure and context.

This ensures AI assistants use your pre-generated context for efficient codebase understanding.

Requirements

• Node.js ≥20.19.5 <21 || ≥22.21.1
• npm ≥10.8.2

License

MIT