A GitHub Action that automatically analyzes your codebase and generates focused AI agent context documentation recommendations (CLAUDE.md, AGENTS.md, or similar) for AI coding assistants. The action provides detailed analysis with concrete examples and language-specific suggestions displayed directly in GitHub Actions step summaries.
This action uses Claude AI to:
- Analyze your entire codebase - Examines source code, dependencies, configuration files, and project structure
- Auto-detect programming languages - Automatically recommends language-specific conventions (Python PEP 8, JavaScript ESLint, etc.)
- Generate focused recommendations - Creates targeted suggestions for missing critical context, not verbose documentation
- Provide concrete examples - Every recommendation includes specific examples of naming patterns, commands, and code structures
- Prioritize actionable insights - High/Medium/Low priority recommendations that save AI assistants time and prevent errors
Create .github/workflows/analyze-claude-md.yml
:
name: Analyze AI Context Documentation
on:
push:
branches: [main]
workflow_dispatch:
jobs:
analyze-codebase:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run AI Agent Context Optimizer
uses: guyaluk/contextor@v0
with:
claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
context-file: 'CLAUDE.md' # or 'AGENTS.md'
# Results will be displayed in the step summary above
- Claude API Key: This action uses Claude Code SDK for intelligent codebase analysis
- Get your API key from Claude AI
- The key is required because the action uses Claude's AI to analyze your codebase and generate context recommendations
- GitHub Secret: Add your API key as
CLAUDE_API_KEY
in your repository secrets- Go to your repository β Settings β Secrets and variables β Actions
- Create a new secret named
CLAUDE_API_KEY
with your API key as the value
Input | Description | Required | Default |
---|---|---|---|
claude-api-key |
Claude API key for authentication | β Yes | - |
context-file |
AI agent context file to analyze (CLAUDE.md or AGENTS.md) | β Yes | - |
The action communicates success/failure via standard exit codes:
- Exit 0: Analysis completed successfully, recommendations written to step summary
- Exit 1: Analysis failed, check the action logs for details
The generated recommendations provide insights for these essential AI agent context documentation sections:
π― Detected Languages & Standards (New!)
- Auto-detected programming languages with specific conventions
- Concrete examples: "Python β snake_case functions (get_user_data), PascalCase classes (UserManager)"
Core Sections:
- π Overview - Project purpose, users, development stage
- ποΈ Architecture - System design, tech stack, components, data flow
- β‘ Key Commands - Essential commands not obvious from scripts
- π οΈ Development Setup - Critical setup steps that aren't automated
- π Project Structure - Non-standard directory organization and conventions
- π Coding Standards - Project-specific patterns that differ from defaults
- π§ Framework & Technology - Unusual configurations or integration approaches
- π§ͺ Testing - Testing approach, frameworks, patterns, quality gates
New Two-Section Format:
- Issues & Recommendations: Clear list of what's missing and needs to be added
- Complete Copyable Context File: Full recommended documentation in a code block for easy copying
Focus on Critical Context Only:
- Recommendations target missing information that would cause AI assistants to waste time or make wrong assumptions
- Every recommendation includes concrete examples and implementation details
- Avoids documenting obvious information that's easily discoverable in configuration files
on:
workflow_dispatch:
inputs:
detailed_analysis:
description: 'Run detailed analysis'
required: false
default: true
type: boolean
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: guyaluk/contextor@v0
with:
claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
context-file: 'CLAUDE.md'
on:
schedule:
- cron: '0 9 * * 1' # Weekly analysis on Mondays at 9 AM UTC
workflow_dispatch:
jobs:
weekly-analysis:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Weekly AI Context Analysis
uses: guyaluk/contextor@v0
with:
claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
context-file: 'CLAUDE.md'
on:
pull_request:
branches: [main]
jobs:
analyze-pr:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Analyze codebase for AI agent context recommendations
uses: guyaluk/contextor@v0
with:
claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
context-file: 'CLAUDE.md'
Check the examples/
directory for complete workflow examples:
basic-usage.yml
- Basic analysis workflow that displays AI agent context recommendations in step summary
The action uses standard exit codes. You can add steps that run conditionally:
- name: Run AI Agent Context Optimizer
uses: guyaluk/contextor@v0
with:
claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
context-file: 'CLAUDE.md'
- name: Success notification
if: success()
run: echo "β
Analysis completed successfully! Check step summary above for recommendations"
- name: Failure notification
if: failure()
run: echo "β Analysis failed! Check the logs above for details"
This action follows semantic versioning:
@v0
- Latest v0.x.x (current version)@v0.1
- Latest v0.1.x patch@v0.1.0
- Specific version (for maximum control)
- Major versions (
v0
,v1
) - Automatically updated to latest - Minor versions (
v0.1
,v0.2
) - Updated to latest patch - Patch versions (
v0.1.0
,v0.1.1
) - Immutable specific versions
- API Key Security: Your Claude API key is passed as a secret and never logged
- Isolated Execution: Runs in a Docker container with minimal permissions
- No Data Persistence: No data is stored outside your repository
- Read-Only Analysis: Only reads your codebase, generates recommendations without modifying any source code
Action fails with API key error:
β Error: CLAUDE_API_KEY environment variable is required
- Ensure you've added
CLAUDE_API_KEY
to your repository secrets - Check that the secret name matches exactly
No recommendations generated:
- Check the action logs for Claude API errors
- Verify your API key has sufficient credits
- Ensure the repository has source code to analyze
- Look for recommendations in the GitHub Actions step summary
Python environment errors:
- The action runs in a Python 3.12 Docker container with all dependencies pre-installed
- For local testing, see the
agent/README.md
for setup instructions
- Check the workflow logs for detailed error messages
- Review the examples for correct configuration
- Open an issue with your workflow configuration and error logs
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Test with the provided workflows
- Submit a pull request
To test changes locally:
# Build the Docker image
docker build -t contextor .
# Test with a sample repository
docker run --rm -v $(pwd):/github/workspace \
-e CLAUDE_API_KEY=your_key_here \
contextor
I'd love to hear from users about their experience with this action! Whether you have:
- π€ Questions about features or implementation
- π Issues you've encountered
- π‘ Feature requests or ideas for improvements
- π General feedback on what you think about the product
- π― Use cases you'd like to see supported
Feel free to reach out:
- Open an issue on this GitHub repository for bugs, feature requests, or questions
- Send me a DM if you want to discuss something interesting or share feedback privately
Your input helps make this tool better for everyone using AI-assisted development!
This action helps bridge the gap between human developers and AI assistants by ensuring your project documentation is always current, comprehensive, and AI-friendly.