This is a self-contained Nuxt application that automatically creates JSON Context Profiles (JCPs) for any public GitHub repository. A JCP is a structured JSON document containing a high-level, AI-friendly summary of a codebase, perfect for providing context to Large Language Models (LLMs).

This tool runs entirely on your local machine, saving the generated JCPs to your filesystem for persistent, private use.

A JCP is a structured representation of a software project's architecture, key components, and overall purpose. Instead of feeding an LLM thousands of lines of raw code, you can provide a concise JCP to give it the necessary context for tasks like:

• Answering questions about the codebase.
• Generating new features that are consistent with the existing design.
• Onboarding new developers.
• Automating documentation.

• Automated JCP Generation: Turns any public GitHub repository into a structured, LLM-ready JCP.
• Local First: No database or external services required (besides GitHub and Gemini APIs). All JCPs are stored on your local disk.
• Persistent & Private: Generated profiles are saved in the .data/ directory, persisting across server restarts for your private use.
• Asynchronous Processing: Uses Nuxt's built-in task runner to perform the long-running analysis in the background without blocking the UI.
• Intelligent Analysis Pipeline:
  1. Fetches the repository's complete file structure.
  2. Uses an LLM to intelligently filter for the most relevant source code and configuration files.
  3. Analyzes each file's content to summarize its purpose, functions, classes, and exports.
  4. Synthesizes all file-level summaries into a final, high-level repository overview.
• Interactive UI: A simple interface to start new generation jobs, view progress, and browse your collection of JCPs.

• Node.js (v18.x or later)
• pnpm (or npm/yarn)

1. Clone the repository:

   git clone https://github.com/manbust/jcp-for-github.git
   cd jcp-for-github

2. Install dependencies:

   pnpm install or npm install or yarn install

3. Set up your environment variables:

   • Copy the example file: cp .env.example .env
   • Edit the .env file with your own API keys.
     • GITHUB_TOKEN: A GitHub Personal Access Token with repo scope is recommended.
     • GEMINI_API_KEY: Your Google AI Studio API key.

   Your .env file should look like this:

   # .env
   GITHUB_TOKEN="ghp_..."
   GEMINI_API_KEY="AIzaSy..."
   

4. Run the development server:

   pnpm dev or npm run dev or yarn dev

The application will be available at http://localhost:3000.

1. Navigate to http://localhost:3000/analyze.
2. Enter the URL or owner/repo of a public GitHub repository you wish to profile.
3. The app starts a new generation job and redirects you to the progress page.
4. The backend task runs the full pipeline to build the JCP.
5. The progress page polls for updates, showing you the current status and step.
6. Once complete, the final JCP is displayed in a user-friendly JSON viewer.
7. You can view all locally generated JCPs on the http://localhost:3000/analyses page.