Skip to content

Getting Started

Jump to bottom
Abid Ali Awan edited this page Dec 2, 2025 · 1 revision

Getting Started

This guide will help you set up and run Issue Analyzer on your local machine.

Prerequisites

Before you begin, ensure you have the following installed and configured:

Required Software

Requirement Version Purpose
Python 3.8+ Runtime environment
GitHub CLI Latest Repository access via gh commands
Git Latest Version control

Required API Keys

Service Environment Variable Purpose
OpenAI OPENAI_API_KEY GPT-5.1 Codex for AI analysis
Firecrawl FIRECRAWL_API_KEY Web scraping for documentation

Installation

Step 1: Clone the Repository

git clone https://github.com/kingabzpro/Issue-Analyzer.git
cd Issue-Analyzer

Step 2: Install Dependencies

pip install -r requirements.txt

This installs:

  • openai-agents==0.5.1 - OpenAI Agents SDK
  • firecrawl-py==2.4.0 - Firecrawl Python client

Step 3: Configure Environment Variables

Linux/macOS:

export OPENAI_API_KEY="your_openai_api_key_here"
export FIRECRAWL_API_KEY="your_firecrawl_api_key_here"

Windows (Command Prompt):

set OPENAI_API_KEY=your_openai_api_key_here
set FIRECRAWL_API_KEY=your_firecrawl_api_key_here

Windows (PowerShell):

$env:OPENAI_API_KEY = "your_openai_api_key_here"
$env:FIRECRAWL_API_KEY = "your_firecrawl_api_key_here"

Tip: For persistent configuration, add these to your shell profile (.bashrc, .zshrc) or system environment variables.

Step 4: Verify GitHub CLI

Ensure GitHub CLI is authenticated:

gh auth status

If not authenticated:

gh auth login

Usage

Command Line Interface

The primary way to use Issue Analyzer:

python src/app.py --repo owner/repository --issue 123

Parameters:

Parameter Description Example
--repo GitHub repository in owner/name format openai/openai-agents-python
--issue Issue number to analyze 456

Interactive Mode

Run without arguments for interactive prompts:

python src/app.py

You'll be prompted to enter:

  1. GitHub repo (owner/name)
  2. Issue number

Example Walkthrough

Let's analyze a real issue step by step:

1. Run the Command

python src/app.py --repo openai/openai-agents-python --issue 456

2. Watch Real-Time Analysis

The tool will display:

🔍 Analyzing openai/openai-agents-python#456...

💭 Reasoning: I need to understand the issue first...

[1] 🔧 Calling: get_github_issue → openai/openai-agents-python#456...

💭 Reasoning: This issue relates to the agent runner component.
   I should explore the src/agents/ directory...

[2] 🔧 Calling: list_repo_files_gh → ext=['.py'], paths=['src/agents/']...

[3] 🔧 Calling: get_repo_file_gh → src/agents/runner.py...

3. Review the Execution Plan

The AI generates a structured plan with:

  • Issue Summary: Clear problem description
  • Project Context: Where the issue fits architecturally
  • Key Files: Specific files to modify
  • Step-by-Step Plan: Detailed implementation steps
  • Testing Strategy: How to verify the fix
  • Risk Assessment: Edge cases and potential issues

4. Find the Output

Results are saved to:

output/execution_plan_{repo}_{issue}_{timestamp}.md

Example:

output/execution_plan_openai_openai-agents-python_issue_456_20251116_143022.md

Understanding the Output

Console Output

Symbol Meaning
🔍 Analysis started
💭 AI reasoning/thought process
🔧 Tool being called
[N] Tool call number (order of execution)
📊 Summary of tools used
✅ Output saved successfully

Execution Plan Structure

# GitHub Issue Analysis: owner/repo#123

**Generated on:** 2024-01-15 14:30:22
**Repository:** owner/repo
**Issue Number:** 123

---

## Issue Summary
[Clear description of the problem]

## Project/Codebase Understanding
[Where this issue lives in the architecture]

## Key Files / Components to Touch
[List of files with paths]

## Step-by-Step Implementation Plan
[Detailed steps 1, 2, 3...]

## Testing Strategy
[Unit / integration / manual testing approach]

## Edge Cases, Risks, and Open Questions
[Potential issues and considerations]

Troubleshooting

Common Issues

OPENAI_API_KEY is not set

Solution: Set the environment variable:

export OPENAI_API_KEY="your_key_here"

FIRECRAWL_API_KEY is not set

Solution: Set the environment variable:

export FIRECRAWL_API_KEY="your_key_here"

Failed to fetch issue via GitHub CLI

Possible causes:

  1. GitHub CLI not installed
  2. Not authenticated with gh auth login
  3. Invalid repository or issue number
  4. Private repository without access

Solution: Verify GitHub CLI:

gh auth status
gh issue view 123 --repo owner/repo

Unicode/Encoding Errors (Windows)

The application automatically handles UTF-8 encoding on Windows. If you still see issues, ensure your terminal supports UTF-8.

Tips for Best Results

  1. Be Patient: Complex issues may take 1-2 minutes to fully analyze
  2. Check API Costs: The tool is designed to be cost-efficient, but monitor your API usage
  3. Review Plans: Always review AI-generated plans before implementing
  4. Iterative Analysis: Run multiple times on complex issues for different perspectives

Next Steps

Clone this wiki locally