CodeSage

• 

  CodeSage analyses the script first and identifies the highest-priority maintainability hotspot using transparent measurements.

• 

  GPT-5.6 explains the measured issue, refers to the relevant code and states what static analysis cannot prove.

• 

  The suggested change is shown only after CodeSage rebuilds the file, analyses it again and confirms a measured maintainability improvement.

• 

  Users can inspect the complete before-and-after measurements and see whether unrelated definitions were preserved.

• 

  Ask CodeSage explains the current result using the same measured evidence and clearly states the limits of static analysis.

Inspiration

CodeSage grew out of my interest in software sustainability and the question: how can we assess whether software is sustainable? The more I researched it, the clearer it became that maintainability, energy use, performance and longevity are related, but they are not interchangeable.

For OpenAI Build Week, I focused on one practical problem: helping Python developers identify and understand difficult to maintain code and assess whether an AI-generated refactor actually improves the measured issue.

The core idea behind CodeSage became: measure first, explain second, and then refactor carefully.

What it does

CodeSage is a maintainability coach for complete Python scripts.

Users can paste code, upload a .py file, load a public GitHub file or use the built-in example.

CodeSage performs deterministic static analysis without executing the code. It measures complexity, nesting, size, parameters and maintainability smells, then ranks the most important hotspots using transparent rules.

Users can then request an AI review. GPT-5.6-sol explains the findings using CodeSage’s measurements, evidence references and code locations.

When a refactor is justified, GPT-5.6-sol returns only the selected function or method. CodeSage reconstructs the complete file locally, checks that unrelated code was preserved and compares the original and suggested versions.

It shows improvements, remaining issues and trade-offs without claiming that static checks prove runtime correctness.

How I built it

I built CodeSage as a solo project using GPT-5.6-sol, Codex, Python, Streamlit, the OpenAI Responses API, Pydantic, Python’s ast module and Radon.

The workflow has three stages:

1. Analyse — identify and measure maintainability hotspots.
2. Understand — use GPT-5.6-sol to explain the evidence.
3. Refactor — generate and statically check a focused change.

I used GPT-5.6-sol and Codex in complementary ways.

GPT-5.6-sol helped me narrow the original sustainability idea, develop the implementation plan, engineer the prompts and structured outputs, troubleshoot failures and critically assess whether recommendations followed from CodeSage’s measurements.

Codex worked directly in the repository. It implemented modules, created regression tests, traced Streamlit state problems and supported major architecture and interface revisions.

I made the final product decisions, including separating deterministic analysis from AI guidance, preventing code execution, rejecting an aggregate quality score and limiting refactors to validated hotspots.

Challenges I ran into

The main challenge was preventing confident but unsupported AI recommendations. CodeSage therefore calculates the measurements itself and validates the evidence and code locations cited by GPT-5.6-sol.

An early version asked the model to rewrite the whole file. This produced large outputs and made unrelated changes difficult to detect. I redesigned it so the model returns one function or method and CodeSage reconstructs the file locally.

Large test files also produced overwhelming results, so the interface was redesigned around summaries, focused diffs, collapsible evidence and a print-friendly report.

Finally, a refactor can improve one measurement while worsening another. CodeSage needed to show those trade-offs rather than declaring every generated suggestion “better.”

Accomplishments that I'm proud of

I built CodeSage from a blank repository into a working developer tool in under four days!

Its targeted refactoring workflow combines AI generation with deterministic reconstruction and structural checks, rather than displaying generated code without verification.

The project now includes more than 200 automated tests and supports pasted code, .py uploads, public GitHub files and a no-setup built-in example.

I also tested the full workflow on a 50,000-character Python file containing 248 analysable code units. CodeSage isolated one hotspot, generated a focused refactor and preserved the unrelated file structure.

Most importantly, it can report that no refactor is needed and does not hide remaining issues or measured trade-offs.

What I learned

The biggest lesson was that GPT-5.6-sol produced its strongest results when given clear structure, measured evidence and a well-defined role.

CodeSage works best when deterministic software performs the measurements, GPT-5.6-sol explains them, and deterministic software checks what the model returns.

I also learned that maintainability cannot be represented honestly by one number, and that clear interface design is essential if users are expected to understand evidence, uncertainty and trade-offs.

What's next for CodeSage

The current release focuses on complete Python scripts and static maintainability analysis.

Future work could include Jupyter notebooks, repository-wide analysis, additional languages, configurable thresholds, test generation and isolated runtime verification.

I would also like to continue the original software-sustainability research while keeping maintainability, runtime efficiency and environmental impact clearly separated.

Built With

• api
• ast
• codex
• gpt-5.6sol
• httpx
• openai
• pydantic
• pytest
• radon
• responsesapi
• ruff
• streamlit