Project Analyzer Meta-Agent

A sophisticated AI meta-agent that analyzes codebases and dynamically generates optimized sub-agents specialized for that specific project.

Overview

This implements the Agent Factory pattern with hierarchical orchestration:

1. Analyze any codebase to understand its structure, languages, frameworks, and patterns
2. Generate specialized sub-agents tailored to that project's specific tech stack
3. Export ready-to-use agent definitions directly into the analyzed project
4. Orchestrate these agents to perform complex multi-step tasks

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Meta-Agent Orchestrator                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Project   │  │    Agent    │  │    Task             │  │
│  │   Analyzer  │──│   Factory   │──│   Orchestrator      │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
           ┌──────────────────┼──────────────────┐
           ▼                  ▼                  ▼
    ┌─────────────┐   ┌─────────────┐    ┌─────────────┐
    │   Code      │   │  Framework  │    │   Security  │
    │  Reviewer   │   │  Specialist │    │   Auditor   │
    └─────────────┘   └─────────────┘    └─────────────┘

Quick Start

# Analyze any project - agents are auto-exported to the project folder
python test_analyzer.py /path/to/your/project

# Output: /path/to/your/project/yourproject_agents.py

Features

Project Analysis

• Language Detection: Identifies all programming languages used
• Framework Detection: Recognizes 30+ frameworks (React, Next.js, Vue, Django, FastAPI, etc.)
• Architecture Patterns: Detects MVC, component-based, service layers, etc.
• Tooling Detection: Build tools, testing frameworks, CI/CD, Docker

Dynamic Agent Generation

Each generated agent is customized with:

• Project-specific context in its system prompt
• Appropriate tools for its role
• Optimal model tier (opus/sonnet/haiku)
• Framework and language expertise

Auto-Export

Agents are automatically exported to the analyzed project's folder as a Python file ready for use with Claude Agent SDK.

Generated Agent Types

Agent	Purpose	Model	Priority
code-reviewer	Quality, security, best practices	sonnet	high
framework-specialist	Framework-specific expertise	sonnet	high
test-writer	Unit/integration tests	sonnet	medium
security-auditor	Vulnerability scanning	opus	high
performance-optimizer	Profiling, optimization	sonnet	medium
documentation-writer	README, API docs	haiku	low

Installation

Prerequisites

# Install Claude Code (optional, for full SDK features)
npm install -g @anthropic-ai/claude-code

# Set API key
export ANTHROPIC_API_KEY=your-key-here

Standalone Analyzer (No SDK Required)

# Just run - no dependencies needed!
python test_analyzer.py /path/to/project

Full SDK Installation

# Python
pip install -r requirements.txt

# TypeScript
npm install

Usage

Analyze & Export (Recommended)

# Analyze project and auto-export agents to project folder
python test_analyzer.py /path/to/project

# Custom output path
python test_analyzer.py /path/to/project -o /custom/path/agents.py

Example Output

🔍 Analyzing: /path/to/my-nextjs-app

======================================================================
  PROJECT ANALYSIS: my-nextjs-app
======================================================================

  Path: /path/to/my-nextjs-app
  Type: fullstack-web
  Primary Language: TypeScript
  Total Files: 156
  Total Lines: 12,450

  Languages:
    TypeScript            89 files  ████████████████████
    JavaScript            23 files  ███████████
    CSS                   18 files  █████████
    ...

  Frameworks: Next.js, React, Tailwind CSS, Prisma
  Patterns: App Router, Component-Based, API Layer

  Features:
    Tests: ✓
    CI/CD: ✓
    Docker: ✓
    Docs: ✓

======================================================================
  GENERATED AGENTS (6)
======================================================================

  🔴 code-reviewer
     Expert TypeScript code reviewer for Next.js, React...
     Model: sonnet | Tools: Read, Grep, Glob

  ...

======================================================================
  EXPORT COMPLETE
======================================================================

  📦 File: /path/to/my-nextjs-app/my_nextjs_app_agents.py
  📊 Agents: 6 specialized sub-agents generated
  🎯 Optimized for: my-nextjs-app (fullstack-web)

Using Exported Agents

# 1. Import the generated agents
from my_nextjs_app_agents import agents, PROJECT_PROFILE

# 2. Create options with agents
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    agents=agents,
    allowed_tools=["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Task"],
    cwd="/path/to/my-nextjs-app",
    permission_mode="acceptEdits"
)

# 3. Run queries - Claude auto-delegates to specialists
async for msg in query("Review auth code for security", options=options):
    print(msg)  # security-auditor handles this automatically

# 4. Or access individual agents
from my_nextjs_app_agents import code_reviewer, security_auditor

Interactive Mode (Full SDK)

# Python
python src/meta_agent.py work /path/to/project

# TypeScript
npx ts-node src/meta-agent.ts work /path/to/project

How It Works

1. Project Analysis

The analyzer scans your codebase to detect:

{
    "name": "my-nextjs-app",
    "primary_language": "TypeScript",
    "frameworks": ["Next.js", "React", "Tailwind CSS", "Prisma"],
    "project_type": "fullstack-web",
    "architecture_patterns": ["App Router", "Component-Based", "API Layer"],
    "has_tests": True,
    "has_ci": True,
    "total_files": 156,
    "total_lines": 12450
}

2. Agent Factory

Based on the profile, specialized agents are generated:

agents = {
    "code-reviewer": AgentDefinition(
        description="Expert TypeScript code reviewer for Next.js, React...",
        prompt="""You are an expert TypeScript code reviewer.
        Project type: fullstack-web
        Frameworks: Next.js, React, Tailwind CSS, Prisma""",
        tools=["Read", "Grep", "Glob"],
        model="sonnet"
    ),
    "security-auditor": AgentDefinition(
        description="Security specialist for TypeScript/Next.js...",
        prompt="""You are a security expert for TypeScript applications...""",
        tools=["Read", "Grep", "Glob", "Bash"],
        model="opus"  # Strongest model for security
    ),
    # ... more agents
}

3. Task Orchestration

The meta-agent delegates to specialists:

User: "Add authentication with NextAuth"

Meta-Agent:
  1. Identifies this needs framework-specialist
  2. Delegates implementation to framework-specialist
  3. Delegates security review to security-auditor
  4. Delegates test creation to test-writer
  5. Aggregates results

Project Structure

project-analyzer-agent/
├── CLAUDE.md               # Agent instructions for Claude Code
├── README.md               # This file
├── package.json            # Node.js config
├── requirements.txt        # Python dependencies
├── test_analyzer.py        # Standalone analyzer (no SDK required)
├── src/
│   ├── meta_agent.py       # Python implementation (requires SDK)
│   └── meta-agent.ts       # TypeScript implementation (requires SDK)
└── tools/
    └── project_analyzer.py # MCP analysis tools

Detection Capabilities

Supported Frameworks

JavaScript/TypeScript:

• React, Next.js, Vue.js, Nuxt.js, Angular, Svelte
• Express.js, Fastify, Hono
• Tailwind CSS, Prisma, tRPC, GraphQL

Python:

• Django, Flask, FastAPI
• Streamlit, LangChain
• PyTorch, TensorFlow
• SQLAlchemy, Pydantic

Project Types Detected

Type	Indicators
fullstack-web	Next.js, Nuxt.js
frontend-spa	React, Vue, Angular
backend-api	Express, FastAPI, Flask
ml-ai	PyTorch, TensorFlow
monorepo	nx.json, turbo.json, lerna.json

Architecture Patterns

• Component-Based (src/components)
• Pages Router (src/pages)
• App Router (app/)
• Service Layer (src/services)
• API Layer (src/api)
• MVC (src/controllers, src/models)
• Agent Architecture (agents/)

Key Patterns Used

Agent Factory Pattern

Dynamic creation of agents based on runtime analysis, inspired by Microsoft's AI Agent Design Patterns.

Hierarchical Orchestration

Manager-worker pattern where the meta-agent decomposes tasks and delegates to specialized sub-agents, based on AgentOrchestra research.

Context-Aware Specialization

Agents receive project-specific context in their prompts, following patterns from LLM Agent surveys.

Extending

Add New Agent Types

# In test_analyzer.py or meta_agent.py
def generate_agents(profile: dict) -> dict:
    agents = {}

    # Add custom agent
    if "graphql" in [f.lower() for f in profile.get("frameworks", [])]:
        agents["graphql-specialist"] = {
            "description": f"GraphQL expert for {profile['primary_language']}",
            "tools": ["Read", "Edit", "Write", "Grep", "Glob"],
            "model": "sonnet",
            "priority": "high",
            "prompt": f"You are a GraphQL expert..."
        }

    return agents

Add Detection Patterns

# In test_analyzer.py
FRAMEWORK_PACKAGES["my-framework"] = "My Framework"
PYTHON_FRAMEWORKS["my-lib"] = "My Library"
ARCHITECTURE_PATTERNS["src/my-pattern"] = "My Pattern"

Model Selection Strategy

Model	Use Case	Cost
opus	Security audits, complex decisions	High
sonnet	Code review, implementation, testing	Medium
haiku	Documentation, simple tasks	Low

License

MIT