🔭 TrogScope

AI-Powered Technical Research Assistant

English | 简体中文

---

TrogScope is an open-source, AI-driven technical research platform. Simply describe your technical requirements, and the Agent automatically searches GitHub, performs deep analysis, scores repositories across multiple dimensions, and generates structured research reports. Say goodbye to manual comparison — let AI find the best tech stack for you.

✨ Features

🔍 Smart Discovery — Multi-Source Candidate Search

• Parallel Search Strategies — GitHub API, Topic tags, Awesome Lists, and Trending repos running concurrently
• Intelligent Dedup & Filtering — Auto-merges duplicates, LLM semantic filtering for relevance
• Query Enhancement — Converts natural language descriptions into optimized GitHub search queries

📊 Deep Analysis — Two-Phase Repository Evaluation

• Shallow Analysis — Core metrics: star growth trends, issue close rates, activity levels, README quality
• Deep Analysis — LLM-driven file exploration: architecture pattern recognition, code quality assessment, dependency analysis
• 7-Dimensional Scoring — Popularity, Activity, Code Quality, Documentation, Community, Architecture, Ease of Use (each 0–100)

📝 Report Generation — Structured Research Output

• Comparison Tables — Multi-repo side-by-side comparison at a glance
• Visual Charts — Radar chart (multi-dimensional), bar chart (overall scores), trend chart (star growth)
• Recommendations — Primary pick + alternatives + use-case matrix

💬 Real-time Interaction — Agent Chat Experience

• Live Progress — SSE streaming, track Agent status in real time
• Clarification Dialogue — Agent proactively asks questions when requirements are ambiguous
• Multi-turn Chat — Follow-up questions and deeper exploration of results

🛠 Tech Stack

Category	Technology
Monorepo	pnpm workspace + Turborepo
Agent Orchestration	@earendil-works/pi-agent-core + @earendil-works/pi-ai
API Framework	Hono
Database	PostgreSQL + Drizzle ORM
Task Queue	BullMQ (Redis)
Auth	Clerk
Frontend	React 19 + TanStack Router + Vite 6
State Management	Zustand
Charts	Recharts
i18n	i18next
Code Quality	Biome
Observability	Langfuse

🏗 Architecture

┌─────────────────┐        SSE/HTTP         ┌─────────────────┐
│    Frontend     │ ◄─────────────────────► │   API Server    │
│   (React SPA)   │                          │     (Hono)      │
└─────────────────┘                          └────────┬────────┘
                                                      │
                                                 BullMQ (Redis)
                                                      │
                                               ┌──────▼──────┐
                                               │    Agent     │
                                               │   Service    │
                                               └──────┬──────┘
                                                      │
                                 ┌─────────────────────┼─────────────────────┐
                                 │                     │                     │
                           ┌─────▼─────┐        ┌─────▼─────┐        ┌─────▼─────┐
                           │ PostgreSQL │        │  GitHub   │        │  LLM API  │
                           │  (Drizzle) │        │ (Octokit) │        │   (BYOK)  │
                           └───────────┘        └───────────┘        └───────────┘

📦 Package Structure

Package	Description
packages/shared	Shared types & database schema (Drizzle ORM)
packages/agent	AI Agent service: multi-agent orchestration, GitHub search, deep analysis, report generation
packages/server	REST API: auth, CRUD, SSE real-time events, API key management
packages/web	Frontend SPA: task management, real-time chat, report viewer, data visualization

🚀 Quick Start

Prerequisites

• Node.js ≥ 18
• pnpm ≥ 9
• PostgreSQL
• Redis
• GitHub Token (create one here)
• At least one LLM API Key (OpenAI / Anthropic / Google / DeepSeek)

Local Development

# Clone the repo
git clone https://github.com/your-username/TrogScope.git
cd TrogScope

# Install dependencies
pnpm install

# Configure environment variables
cp .env.example packages/server/.env.local
cp .env.example packages/agent/.env.local
# Edit .env.local with your configuration

# Start all services
pnpm dev

After startup:

• Frontend: http://localhost:5173
• API Server: http://localhost:3000

Available Commands

pnpm dev              # Start all packages in dev mode
pnpm build            # Build all packages
pnpm lint             # Run linter
pnpm format           # Format code
pnpm test             # Run tests
pnpm type-check       # Type checking

# Database
pnpm db:migrate       # Run database migrations
pnpm db:generate      # Generate migration files

🐳 Docker Deployment

# Build and start all services
docker compose up -d

📁 Project Structure

TrogScope/
├── packages/
│   ├── shared/           # Shared types & database schema
│   │   └── src/
│   │       ├── db/       # Drizzle ORM table definitions
│   │       └── index.ts  # Type exports
│   ├── agent/            # AI Agent service
│   │   └── src/
│   │       ├── agents/   # Orchestrator, search/analysis/report agents
│   │       ├── analysis/ # Shallow/deep analysis, scoring engine
│   │       ├── github/   # GitHub API client
│   │       └── llm/      # LLM provider wrapper
│   ├── server/           # API Server
│   │   └── src/
│   │       ├── routes/   # research, settings, health routes
│   │       ├── middleware/# Auth, logging middleware
│   │       └── db/       # Database connection & migrations
│   └── web/              # Frontend application
│       └── src/
│           ├── components/ # UI components
│           ├── stores/     # Zustand state management
│           ├── hooks/      # SSE, router hooks
│           └── i18n/       # Internationalization
├── turbo.json            # Turborepo config
├── pnpm-workspace.yaml   # pnpm workspace config
└── docker-compose.yml    # Docker orchestration

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork this repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Please make sure your code passes lint and type checks:

pnpm lint && pnpm type-check

📄 License

MIT License

Copyright (c) 2026 TrogScope Team