GRWM (Get README With Me) is an AI Agentic system that transforms your GitHub profile into a stunning, personalized portfolio README in seconds. Unlike traditional generators, GRWM uses a Multi-Agent AI architecture where three specialized AI agents collaborate to analyze your GitHub profile and craft custom-toned professional portfolios.

• Creating a compelling GitHub README is time-consuming
• Generic templates don't capture your unique developer identity
• Keeping your profile updated is tedious
• Choosing the right tone and style is challenging

GRWM automates the entire process using AI Agentic Workflows with three specialized agents working in harmony:

• 🔍 Detective Agent: Investigates your GitHub profile, analyzes repositories, and gathers comprehensive data
• 🧠 CTO Agent: Performs deep technical analysis, identifies skills, determines developer archetype, and calculates impact metrics
• ✍️ Ghostwriter Agent: Crafts personalized, engaging README content with custom tones and styles

• 3 Specialized AI Agents working collaboratively
• LangGraph-powered workflow orchestration
• Real-time progress streaming with Server-Sent Events (SSE)
• Autonomous decision-making with intelligent routing

• 4 Style Presets: Professional, Creative, Minimal, Detailed
• Custom Tone Control: Tailor the writing style to your preference
• Personalized Descriptions: Add specific requirements or highlights
• Live Preview: Dark/Light mode markdown preview

• Grind Score Calculation: Measures your GitHub activity and impact
• Developer Archetype Detection: Identifies your coding personality
• Tech Stack Recognition: Automatically detects languages, frameworks, and tools
• Key Project Identification: Highlights your most impactful repositories
• Social Proof Metrics: Analyzes stars, forks, and community engagement

• Frontend: Next.js 16.1.1, React 19, TypeScript, TailwindCSS 4
• Backend: Python 3.11+, FastAPI, LangGraph, LangChain
• AI: Google Gemini Flash (Free Tier)
• Real-time: Server-Sent Events (SSE) for live updates
• PWA: Installable as Progressive Web App

• Instant download and clipboard copy
• Social media sharing with screenshot capture
• Responsive brutalist design
• SEO optimized with comprehensive metadata
• Zero-cost AI model (Gemini Flash free tier)

Visit the live application: getreadmewithme.vercel.app

1. Enter GitHub Username - Start with any public GitHub profile
2. Watch AI Agents Work - See real-time progress as each agent completes its task
3. Choose Your Style - Select from 4 professional style options
4. Get Your README - Download, copy, or share your personalized portfolio

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                        │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ Home Screen │→│ Progress View │→│ Preview & DL  │       │
│  └─────────────┘  └──────────────┘  └──────────────┘       │
└────────────────────────┬────────────────────────────────────┘
                         │ SSE Connection
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                  Backend (FastAPI + SSE)                     │
│                                                               │
│  ┌─────────────────────────────────────────────┐            │
│  │         LangGraph Orchestration              │            │
│  │                                               │            │
│  │  ┌──────────────┐                            │            │
│  │  │ 🔍 DETECTIVE │  Fetches Profile Data      │            │
│  │  │    AGENT     │  • GitHub API Client       │            │
│  │  │              │  • Repository Analysis     │            │
│  │  │              │  • Tech Stack Detection    │            │
│  │  └──────┬───────┘                            │            │
│  │         │ State Flow                         │            │
│  │         ↓                                    │            │
│  │  ┌──────────────┐                            │            │
│  │  │   🧠 CTO     │  Technical Analysis        │            │
│  │  │    AGENT     │  • Language Analysis       │            │
│  │  │              │  • Skill Mapping           │            │
│  │  │              │  • Archetype Detection     │            │
│  │  │              │  • Grind Score Calculation │            │
│  │  └──────┬───────┘                            │            │
│  │         │ Awaits User Style Selection        │            │
│  │         ↓                                    │            │
│  │  ┌──────────────┐                            │            │
│  │  │✍️ GHOSTWRITER│  Content Generation        │            │
│  │  │    AGENT     │  • Gemini Flash LLM        │            │
│  │  │              │  • Tone Instructions       │            │
│  │  │              │  • Style Templates         │            │
│  │  │              │  • Markdown Generation     │            │
│  │  └──────────────┘                            │            │
│  └─────────────────────────────────────────────┘            │
└─────────────────────────────────────────────────────────────┘

AgentState = {
    "username": str,
    "user_preferences": {
        "tone": str,      # professional/creative/minimal/detailed
        "style": str,     # user's selected style
        "description": str # custom requirements
    },
    "raw_data": dict,     # Detective's gathered data
    "analysis": dict,     # CTO's analysis results
    "final_markdown": str, # Ghostwriter's output
    "messages": list,     # Agent communication log
    "error": str,         # Error tracking
    "retry_count": int,   # Retry logic
    "intermediate_results": dict,
    "generation_history": list
}

{
    "profile": {
        "name", "username", "bio", "location",
        "company", "public_repos", "followers", "following"
    },
    "repositories": [
        {
            "name", "description", "stars", "forks",
            "language", "topics", "is_pinned", "is_archived"
        }
    ],
    "social_proof": {
        "total_stars", "total_forks", "total_repos"
    },
    "contributions": {
        "total_commits", "active_streak"
    },
    "existing_readme": str  # If found
}

{
    "grind_score": {"score": int, "label": str, "emoji": str},
    "developer_archetype": {"title": str, "full_title": str},
    "language_analysis": {"primary": dict, "distribution": list},
    "skill_mapping": {"languages": list, "frameworks": list, "tools": list},
    "tech_diversity": {"score": float, "description": str},
    "key_projects": list,
    "impact_metrics": dict
}

Frontend subscribes to SSE endpoint:
GET /api/generate/{session_id}/stream

Backend emits events:
{
  type: "detective_progress" | "detective_complete" |
        "cto_progress" | "cto_complete" |
        "ghostwriter_progress" | "ghostwriter_complete" |
        "awaiting_style_selection",
  stage: "detective" | "cto" | "ghostwriter",
  message: string,
  timestamp: ISO string,
  data?: any
}

const eventSource = new EventSource(`/api/generate/${sessionId}/stream`);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Update UI based on event type
  setEvents(prev => [...prev, data]);
};

• Node.js 18+ (for frontend)
• Python 3.11+ (for backend)
• GitHub Personal Access Token (for API access)
• Google Gemini API Key (free tier available)

# Navigate to backend directory
cd backend
# download uv first
# pip install uv
uv sync

# Activate virtual env
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Create .env file
cat > .env << EOL
GITHUB_PAT=your_github_token_here
GEMINI_API_KEY=your_gemini_api_key_here
EOL

# Run the server
python api.py

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Create .env.local file
cat > .env.local << EOL
NEXT_PUBLIC_API_URL=http://localhost:8000
EOL

# Run development server
npm run dev

1. Start the Application

   • Open http://localhost:3000 in your browser
   • Or visit the live demo at getreadmewithme.vercel.app

2. Enter GitHub Username

   • Type any public GitHub username
   • Press Enter or click "START"

3. Watch the Agents Work

   • 🔍 Detective gathers profile data (5-10 seconds)
   • 🧠 CTO analyzes your tech stack (5-8 seconds)
   • ⏸️ System awaits your style selection

4. Customize Your README

   • Choose from 4 style options
   • (Optional) Add custom description for specific requirements

5. Get Your README

   • ✍️ Ghostwriter generates your portfolio (10-15 seconds)
   • Preview in dark/light mode
   • Download, copy, or share

cd backend

# Test Detective Agent only
python test_agents.py
# Select option 1

# Test CTO Agent (requires Detective data)
python test_agents.py
# Select option 2

# Test Ghostwriter Agent (requires both)
python test_agents.py
# Select option 3

# Test complete pipeline
python test_agents.py
# Select option 4

from agents import (
    create_detective_graph,
    create_initial_state,
    GhostwriterAgent
)

# Create the agent graph
app = create_detective_graph()

# Initialize state
initial_state = create_initial_state(
    username="octocat",
    preferences={
        "tone": "professional",
        "style": "modern"
    }
)

# Run Detective and CTO
for event in app.stream(initial_state):
    print(event)

# Get final state
final_state = next(iter(event.values()))

# Run Ghostwriter separately
ghostwriter = GhostwriterAgent()
result = ghostwriter(final_state)

print(result["final_markdown"])

Start a new README generation session.

Request:

{
  "username": "octocat",
  "tone": "professional",
  "style": "modern"
}

Response:

{
  "session_id": "uuid-string",
  "message": "Generation started"
}

Server-Sent Events endpoint for real-time progress updates.

Events:

• detective_progress: Detective agent working
• detective_complete: Detective finished
• cto_progress: CTO agent analyzing
• cto_complete: CTO finished
• awaiting_style_selection: Waiting for user to choose style
• ghostwriter_progress: Ghostwriter generating
• ghostwriter_complete: README ready

Continue generation after style selection.

Request:

{
  "style": "professional",
  "description": "Highlight my open-source contributions"
}

Response:

{
  "session_id": "uuid-string",
  "message": "Continuing with Ghostwriter"
}

Get the final generated README.

Response:

{
  "session_id": "uuid-string",
  "username": "octocat",
  "markdown": "# Full README content...",
  "analysis": {
    "grind_score": {...},
    "developer_archetype": {...}
  }
}

{
  "detail": "Error message",
  "error": "INTERNAL_ERROR | NOT_FOUND | VALIDATION_ERROR",
  "timestamp": "2025-12-29T12:00:00Z"
}

allow_origins = [
    "http://localhost:3000",
    "https://*.vercel.app"
]

cd backend

# Run test suite
python test_agents.py

# Test options:
# 1. Detective Agent Only
# 2. CTO Agent Only  
# 3. Ghostwriter Agent Only
# 4. Complete Pipeline

cd frontend

# Run type checking
npm run type-check

# Build test
npm run build

# Lint
npm run lint

def _get_tone_instructions(self, tone: str) -> str:
    instructions = {
        "professional": "...",
        "creative": "...",
        "minimal": "...",
        "your_new_tone": """
        TONE: Your Custom Tone Description
        - Instruction 1
        - Instruction 2
        """
    }
    return instructions.get(tone, instructions["professional"])

def _get_style_instructions(self, style: str) -> str:
    instructions = {
        "professional": "...",
        "creative": "...",
        "minimal": "...",
        "your_new_style": """
        STYLE: Your Custom Style
        SECTIONS TO INCLUDE:
        - Section 1
        - Section 2
        """
    }
    return instructions.get(style, instructions["professional"])

const styles = [
    { id: 'professional', name: 'Professional', icon: Briefcase, color: 'bg-blue-50' },
    // Add your new style
    { id: 'your_new_style', name: 'Your Style', icon: YourIcon, color: 'bg-custom' },
];

• Framework: Next.js 16.1.1 (React 19.2.3)
• Language: TypeScript 5
• Styling: TailwindCSS 4 (Brutalist Design)
• UI Components: Custom + Lucide Icons
• Markdown: ReactMarkdown + remark-gfm + rehype-raw
• PWA: Service Worker + Web Manifest
• Screenshot: html2canvas-pro

• Framework: FastAPI 0.115+
• Language: Python 3.11+
• AI/ML: LangGraph, LangChain, Google Gemini Flash
• GitHub API: PyGithub + httpx
• State Management: LangGraph MemorySaver
• Async: asyncio, uvicorn
• Environment: python-dotenv

• Frontend Hosting: Vercel
• Backend Hosting: Railway/Render/Fly.io
• CDN: Vercel Edge Network
• Domain: Custom domain support

Contributions are welcome! Here's how you can help:

1. Fork the Repository
2. Create a Feature Branch

   git checkout -b feature/AmazingFeature

3. Commit Your Changes

   git commit -m 'Add some AmazingFeature'

4. Push to the Branch

   git push origin feature/AmazingFeature

5. Open a Pull Request

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

This project is licensed under the MIT License - see the LICENSE file for details.

• Google Gemini for providing free-tier AI models
• LangGraph for agent orchestration framework
• GitHub API for profile data access
• Shields.io for beautiful badges
• Vercel for seamless deployment

• Single session per user (no concurrent generations)
• In-memory session storage (not production-scalable)
• Limited to public GitHub profiles
• GitHub API rate limits apply

• Redis-based session storage
• User authentication & saved READMEs
• Multiple README versions
• Private repository support (OAuth)
• More customization options
• Batch generation for organizations
• Analytics dashboard
• API key management for users

Created by: Parampreet Singh

Email: connectwithparam.30@gmail.com

Portfolio: parampreetsingh.me

GitHub: @Param302

Live Demo: getreadmewithme.vercel.app