🦅 LogHawk - AI-First Log Analysis Platform

The first log analysis platform built specifically for AI-powered development workflows.

LogHawk eliminates the painful cycle of manual log hunting that breaks AI-assisted development flow. Instead of copy/pasting logs for 5+ minutes per AI interaction, your AI agent can directly fetch structured, filtered logs in one API call.

🎯 The Problem LogHawk Solves

Every AI developer knows this workflow:

• AI Agent: "Check your logs for errors"
• You: grep, copy/paste, screenshot console, repeat...
• AI Agent: "I need backend logs too"
• You: More terminal work, more copy/paste...

This cycle kills productivity. LogHawk makes AI agents truly autonomous by providing direct API access to intelligently filtered logs.

🚀 Quick Start (3 Steps)

Step 1: Install LogHawk

git clone https://github.com/yourusername/LogHawk
cd LogHawk
pip install -r requirements.txt
playwright install chromium  # CRITICAL - Browser automation

Step 2: Start LogHawk Server

python run_loghawk.py
# 🌐 HTTP:  http://127.0.0.1:8765 ✅ (Recommended - Works with all tools)
# 🔒 HTTPS: https://127.0.0.1:8766 ⚠️ (Self-signed cert - Limited compatibility)

Step 3: Connect Your AI

For Claude Code users:

1. Add loghawk_claude.xml to your workspace
2. Ask: "Use LogHawk to analyze my logs"
3. Claude automatically runs: curl "http://127.0.0.1:8765/api/logs?preset=full_stack_web"

For other AI tools:

curl "http://127.0.0.1:8765/api/logs?preset=react_debugging"

✅ Verify Installation

python test_install.py  # Comprehensive installation check

🖥️ Platform Support

Windows ✅

# Install Python 3.8+ from python.org
pip install -r requirements.txt
playwright install chromium
python run_loghawk.py

macOS ✅

brew install python@3.11
pip3 install -r requirements.txt
playwright install chromium
python3 run_loghawk.py

Linux ✅ (Fastest Performance)

# Ubuntu/Debian
sudo apt update && sudo apt install python3 python3-pip
pip3 install -r requirements.txt
playwright install chromium
python3 run_loghawk.py

# Red Hat/CentOS/Fedora
sudo dnf install python3 python3-pip
pip3 install -r requirements.txt
playwright install chromium
python3 run_loghawk.py

🤖 Claude Code AI Integration

LogHawk includes comprehensive Claude Code integration via loghawk_claude.xml:

How to Use with Claude Code

1. Add Integration File: Place loghawk_claude.xml in your Claude Code workspace
2. Natural Language: Ask "Use LogHawk to analyze my application logs"
3. Automatic API Calls: Claude automatically fetches filtered logs with optimal parameters
4. Structured Analysis: Receives JSON responses designed for AI consumption

Example Claude Code Workflow

You: "My React app is crashing on user interactions"
Claude Code: [Uses LogHawk integration]
Claude: "I found 3 issues in your logs:
1. useState hook error in UserProfile.jsx:47
2. Failed API call to /api/users (CORS issue) 
3. Unhandled click event on submit button
Let me fix these..."

Before LogHawk: 5+ minutes of manual log hunting per AI interaction
With LogHawk: AI gets full context in 1 API call

✨ Key Features

• 🧠 AI-Native Design - Direct API access with structured JSON responses
• 🎯 Smart Presets - react_debugging, api_testing, full_stack_web, infrastructure_monitoring
• 🔍 Multi-Technology - 197+ keywords across React, Python, Java, Node.js, Go, Infrastructure
• 🚀 Real-Time Browser Capture - Playwright integration for live frontend debugging
• 🌙 Professional UI - Dark/light themes with GitHub-inspired design
• 🏷️ Interactive Filtering - Visual filter badges with one-click removal
• 📡 RESTful API - Complete programmatic access for automation
• 🖥️ Cross-Platform - Windows, macOS, Linux support

🔧 Usage

Web Interface

Open http://127.0.0.1:8765 in your browser for the full-featured LogHawk interface:

• 🌙 Theme Toggle: Switch between dark and light modes with persistence
• 🏷️ Active Filter Badges: Visual display of applied filters with one-click removal
• 🚀 Quick Presets: Debug User Clicks, React Debugging, API Testing, Full Stack Web, Infrastructure
• 📂 Filter Categories: 8 comprehensive technology-specific filter groups with modern accordion design
• 🎯 Custom Keywords: Add your own patterns with regex support (enabled by default)
• 📁 Folder Browser: Visual directory selection with enhanced UI
• ⚡ Real-time Analysis: Live filtering with professional log display and syntax highlighting

API Endpoints

Get All Logs with Advanced Filtering

# Basic usage
curl "http://127.0.0.1:8765/api/logs"

# With technology filters
curl "http://127.0.0.1:8765/api/logs?categories=frontend_react,user_interactions&max_lines=1000"

# With custom keywords and regex
curl "http://127.0.0.1:8765/api/logs?custom_keywords=click.*button,form.*submit&use_regex=true"

# Using presets
curl "http://127.0.0.1:8765/api/logs?preset=react_debugging"

Backend/Frontend Specific

# Backend logs only
curl "http://127.0.0.1:8765/api/logs/backend?categories=backend_python"

# Frontend logs only  
curl "http://127.0.0.1:8765/api/logs/frontend?categories=frontend_react"

🎨 UI/UX Excellence

LogHawk features a modern, developer-centric interface designed for extended use:

🌙 Dark Mode First

• GitHub-Inspired Theme: Professional dark interface reducing eye strain
• Light Theme Alternative: Clean, accessible light mode for different preferences
• Theme Persistence: Your preference saved in browser localStorage
• System Integration: Respects prefers-color-scheme media queries

🏷️ Smart Filter Management

• Active Filter Badges: See all applied filters at a glance with individual removal
• Real-time Updates: Filter changes reflected immediately across the interface
• Category Indicators: Count of selected keywords per technology group
• Preset Highlighting: Clear visual feedback for active configurations

🎯 Enhanced User Experience

• Card-Based Layout: Modern design with subtle shadows and hover effects
• Professional Typography: Improved font stacks and visual hierarchy
• Color-Coded Elements: Log levels and interface elements use semantic colors
• Responsive Design: Optimized for both desktop and mobile use
• Accessibility First: Full keyboard navigation and screen reader support

🎯 Filter Categories

Core Technology Stacks

• 🔴 Core Log Levels - FATAL, ERROR, WARNING, INFO, DEBUG, TRACE
• 👆 User Interactions - clicks, navigation, forms, DOM events
• ⚛️ Frontend React/JS/TS - hooks, components, browser errors
• 🐍 Backend Python - exceptions, frameworks (Django, Flask, FastAPI)
• ☕ Backend Java/Spring - common Java patterns and Spring errors
• 🟢 Backend Node.js - Node-specific errors and frameworks
• ⚙️ Other Languages - C#, PHP, Go patterns
• 🏗️ Infrastructure - Docker, Kubernetes, databases, caching

Quick Presets

• Debug User Clicks - Focus on user interaction events and navigation
• React Debugging - Frontend React development issues
• API Testing - Backend API and request/response issues
• Full Stack Web - Combined frontend + backend debugging
• Infrastructure - DevOps and system-level monitoring

🔍 Interactive Browser Capture

Capture real-time browser logs while testing your application:

# Start interactive browser session
python run_playwright.py --url https://yourapp.com

# Headless capture
python run_playwright.py --headless --url https://yourapp.com

Browser logs are automatically saved to browser_logs/ and integrated with LogHawk analysis.

🤖 Claude Code Integration

LogHawk is optimized for AI-powered log analysis:

⚠️ WebFetch Compatibility Issue

IMPORTANT: Claude Code's WebFetch tool has SSL compatibility issues:

• HTTP URLs: Auto-upgraded to HTTPS, causing protocol mismatch
• HTTPS URLs: Rejects self-signed certificates

Recommended Solutions:

# Use Bash tool with curl (WORKS PERFECTLY)
curl "http://127.0.0.1:8765/api/logs?preset=full_stack_web&max_lines=2000"

# Or use browser directly
# Open: http://127.0.0.1:8765

🛠️ Port Management

Use the built-in port management utility:

# Check LogHawk server status
python kill_ports.py status

# Start LogHawk server
python kill_ports.py start

# Restart LogHawk server  
python kill_ports.py restart

# Force kill processes on port 8765
python kill_ports.py kill --force

📝 Configuration

API Parameters

• max_files - Number of recent log files to scan (default: 3, max: 20)
• max_lines - Maximum lines to return (default: 1000, 0=unlimited)
• categories - Comma-separated filter categories
• custom_keywords - Comma-separated custom patterns
• preset - Quick preset configuration
• use_regex - Enable regex pattern matching

Log Detection

LogHawk automatically detects and filters important log levels:

• Standard levels: WARNING, ERROR, CRITICAL, FATAL
• Exception patterns: Exception, Traceback, Stack traces
• Technology-specific patterns: 100+ predefined keywords
• File types: .log, .txt, .json files
• Sorting: By modification time (newest first)

🔧 Troubleshooting

Installation Issues

❌ "playwright install chromium" Failed

Solution: Install system dependencies first

# Ubuntu/Debian
sudo apt-get install -y wget ca-certificates fonts-liberation libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libx11-6 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6

# macOS
brew install --cask microsoft-edge  # Alternative browser option

❌ "Permission denied" on Linux/macOS

pip3 install --user -r requirements.txt  # Install to user directory
python3 -m playwright install chromium   # Use module syntax

❌ Python Version Issues

LogHawk requires Python 3.8+. Check with: python --version

# Install newer Python:
# Ubuntu: sudo apt install python3.11
# macOS: brew install python@3.11  
# Windows: Download from python.org

Runtime Issues

❌ "Connection refused" at http://127.0.0.1:8765

Solutions:

1. Start the server: python run_loghawk.py
2. Check ports: python kill_ports.py status
3. Force restart: python kill_ports.py restart
4. Try different port: Edit log_server.py line with port=8765

❌ "No logs found"

Check log paths:

curl "http://127.0.0.1:8765/api/paths"  # View current paths
curl -X POST "http://127.0.0.1:8765/api/paths" -d "backend=./your_logs_folder"

❌ SSL Certificate Issues (HTTPS)

Use HTTP instead: http://127.0.0.1:8765 (recommended for AI tools)

# If you need HTTPS, regenerate certificates:
cd ssl/
openssl req -x509 -newkey rsa:4096 -keyout loghawk-key.pem -out loghawk-cert.pem -days 365 -nodes

AI Integration Issues

❌ Claude Code WebFetch SSL Problems

Solution: Use curl instead of WebFetch

# Add to Claude Code instructions:
curl "http://127.0.0.1:8765/api/logs?preset=full_stack_web"

❌ Empty Results from API

Try broader filters:

curl "http://127.0.0.1:8765/api/logs?categories=core_levels&max_lines=0"

Platform-Specific Issues

Windows: "python command not found"

• Install Python from python.org
• Check "Add Python to PATH" during installation
• Use py instead of python: py run_loghawk.py

macOS: Certificate verification failed

/Applications/Python\ 3.x/Install\ Certificates.command  # Run Python's cert installer

Linux: Browser crashes in headless mode

export DISPLAY=:99  # Set virtual display
Xvfb :99 -screen 0 1024x768x24 &  # Start virtual framebuffer

Performance Issues

Slow log analysis

1. Reduce file scope: max_files=1 for recent logs only
2. Limit lines: max_lines=500 for quick analysis
3. Use presets: More efficient than manual category combinations
4. Specific keywords: error,timeout instead of broad regex patterns

Getting Help

1. Run diagnostics: python test_install.py
2. Check server status: python kill_ports.py status
3. Review logs: Check console output when starting python run_loghawk.py
4. GitHub Issues: Report bugs with diagnostic output

🏗️ Architecture

Cross-Platform Technology Stack:

• FastAPI - High-performance async web framework (Python 3.8+)
• Uvicorn - Production ASGI server with SSL support
• Playwright - Cross-platform browser automation (Chromium)
• Modern CSS - Custom properties for smooth dark/light themes
• Vanilla JavaScript - Event-driven UI with zero dependencies
• RESTful Design - JSON APIs optimized for AI consumption

📄 License

MIT License - Built for developers, by developers.

---

LogHawk - Advanced Multi-Technology Log Analysis Platform
🦅 Soaring above your logs, spotting issues with precision