Medusa

Inspiration

MEDUSA was born from a desire to analyze entire projects, not just single files or lines of code. I wanted a tool that could read directories as a whole, understand patterns, and provide actionable insights automatically. From the start, I chose C for its performance, low-level control, and portability, reflecting my philosophy that a well-optimized program can run anywhere while handling large codebases efficiently. The goal was to create a system that evaluates code critically, intelligently, and consistently — a meticulous AI agent inspired by how developers like Linus Torvalds approach software: strategic, efficient, and deeply aware of every layer of the system.

What it does

MEDUSA is a command-line AI analysis tool that:

• Traverses directories and reads all files
  
• Constructs a prompt for Gemini 3 to analyze code or text in context
  
• Generates a detailed, human-readable report highlighting errors, potential causes, severity, and improvement suggestions
  
• Produces output in plain text or markdown
  
• Works efficiently on minimal environments thanks to pure C implementation

How we built it

• Language: C for speed, low memory usage, and maximum portability
  
• Libraries: libcurl for HTTP requests to Gemini 3, cJSON for parsing API responses
  
• Architecture:
  
  • Local engine handles file reading, directory traversal, prompt construction
    
  • Gemini 3 provides reasoning, code critique, and report generation
    
• Security model: API key embedded at compile-time, removed after binary creation to ensure safety
  
• Open-source: fully transparent and extensible for anyone to contribute
  

Challenges we ran into

• Safely reading files into memory without causing segmentation faults
  
• Managing large directories and multiple files efficiently
  
• Controlling prompt size for Gemini 3 without exceeding buffer limits
  
• Handling relative vs absolute directory paths consistently
  
• Designing a low-level, portable architecture that still integrates a modern AI API
  

Accomplishments that we're proud of

• Fully functional CLI tool with Gemini 3 integration
  
• Secure, compile-time API key model
  
• Multilingual report support (English & Portuguese)
  
• Optimized memory usage and low-level architecture, ensuring portability
  
• Open-source implementation suitable for learning and contribution
  

What we learned

• Low-level programming in C requires strategic memory management and attention to detail
  
• Integrating modern AI into minimal environments is possible with clever design and efficient libraries
  
• Large-scale file analysis can be done reliably without heavyweight frameworks
  
• Clear documentation and modular architecture make complex tools maintainable and extendable
  

What's next for MEDUSA

• Support for recursive directory traversal for deep codebases
  
• Advanced configurable analysis (e.g., file size limits, verbosity levels)
  
• More natural language options beyond PT/EN
  
• Potential integration with CI/CD pipelines for automated project audits
  
• Continuous improvement of AI prompt strategies to generate smarter, more actionable reports

Built With

• c
• gemini