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

$3

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: mail.citrus551@passmail.net

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

$3

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:

$3

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

$3

- 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

$3

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

$3

- 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

$3

- 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

``bash
npm install --save-dev @parseme/cli
`

Quick Start

1. Initialize configuration:

`bash
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:
`bash
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:

$3

Run parseme manually whenever you need updated context.

Setup:

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

`json
{
"scripts": {
"parseme": "parseme generate"
}
}
`

Usage:

`bash
npm run parseme


or directly


parseme generate
`

---

$3

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

Setup with Husky:

`bash


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:

`bash
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.

---

$3

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:

`bash


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:

`bash


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).

---

$3

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:

`yaml
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:

`bash


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):

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

export default config;
`

Full config example (all available options):

`javascript
/* @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;
`

$3

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

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

#### Example TypeScript Configuration

`typescript
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

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

export default config;
`

$3

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.

$3

#### 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)

$3

#### Generate Command (parseme generate or parseme g)

- -c, --config - Config file path
- -o, --output - Output file path
- -r, --root - Root directory to analyze
- --context-dir - Context directory path (default: parseme-context)
- --file-types - File types to analyze (e.g., ts tsx js jsx)
- --exclude - 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 - Maximum directory depth

#### Init Command (parseme init or parseme i)

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

$3

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

`bash


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:

`typescript
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:

$3

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

$3

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

$3

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

$3

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