Code clarity Agent - Submission for #QodoAgentChallenge

[suvo-app]

User description

Universal Code Clarity Agent

Don't just detect code quality issues—FIX them automatically with AI, for any language.

This Qodo agent analyzes source code in any language (Python, JavaScript, Java, Rust, and more) for common clarity and quality problems, generates language-specific AI-powered fixes, and provides a quantifiable score to prove the improvement.

---

Competition Category
Best Agent for Clean Code Description

---

Quick Start

To analyze and automatically refactor a file, run:

qodo code-clarity --set file_path=path/to/your/code.js --set language=javascript

qodo code-clarity --set file_path=path/to/your/code.py --set language=python

---

Core Features

• ✅ Detects 5 Types of Issues: Finds missing docstrings, magic numbers, poor variable names, overly complex functions, and redundant comments.
• ✅ Generates AI-Powered Fixes: Automatically generates high-quality docstrings, extracts magic numbers into named constants, and suggests better variable names.
• ✅ Quantifiable Scoring: Calculates a "Clarity Score" (0-100) before and after the fixes, so you can see the concrete improvement.
• ✅ Before/After Comparison: The agent's output includes the original and the refactored code, making it easy to review the changes.

---

Core Philosophy: From Detection to Solution

Many code quality tools are excellent at detecting problems. They generate a list of issues, leaving the developer with the manual task of fixing them.

This agent is built on a different philosophy: it provides a solution, not just a report.

By leveraging AI, the Universal Code Clarity Agent moves beyond simple analysis to offer automated, language-aware refactoring. Its core value is in saving developer time and cognitive load by not just identifying what's wrong, but by actively fixing it.

Key Differentiators

• Automated Refactoring: Instead of just flagging missing docstrings or magic numbers, the agent generates high-quality, language-specific fixes and applies them.
• Quantifiable Improvement: The Clarity Score (0-100) provides a concrete metric to demonstrate the value of the changes, showing a clear "before and after" state.
• Multi-Language by Design: The agent is built to be language-agnostic, applying the appropriate documentation standards (JSDoc, Google-style docstrings, etc.) based on the user's input.

---

Example Workflow

1. You run the agent on a file:
   qodo code-clarity --set file_path=examples/bad_code.py

2. The agent analyzes the code and finds:

   • 2 missing docstrings
   • 1 magic number
   • 2 poor variable names
   • Initial Score: 45/100

3. The agent automatically applies fixes:

   • Generates two complete, Google-style docstrings.
   • Extracts 0.15 into a constant named THRESHOLD.
   • Suggests renaming calc to calculate_value and x to base_value.

4. The agent displays the results:

   • Final Score: 90/100
   • Improvement: +100%
   • A clear, side-by-side view of the original and refactored code.

---

Value Proposition

The Universal Code Clarity Agent transforms code quality analysis from a manual, time-consuming chore into a fast, automated workflow. By using AI to generate fixes and providing a clear scoring system, it allows developers to improve their codebase's readability and maintainability in seconds, not hours. This means less time spent on tedious refactoring and more time focused on building features.

---

Requirements

• Qodo CLI: Requires a standard installation and login (qodo login).
• No Special API Keys: Unlike other agents that may require a QODO_API_KEY for premium services, our agent uses the core AI model and local tools, making it accessible to anyone with a basic Qodo account.

---

PR Type

Enhancement

---

Description

• Add Universal Code Clarity Agent for multi-language code analysis

• Implement AI-powered automatic code fixes with quantifiable scoring

• Create example files demonstrating clarity issues in Python and JavaScript

• Remove outdated GitHub workflow and update root configuration

---

Diagram Walkthrough

flowchart LR
  A["Code Clarity Agent"] --> B["Analyze Code Issues"]
  B --> C["Generate Language-Specific Fixes"]
  C --> D["Calculate Clarity Score"]
  D --> E["Output Refactored Code"]

Loading

File Walkthrough

	Relevant files
Configuration changes	agent.toml Agent configuration for code clarity analysis                        agents/code-clarity-agent/agent.toml Define agent configuration with Claude 4.5 Sonnet model Specify code-clarity command with detailed instructions for multi-language analysis Configure arguments for file_path and language parameters Define output schema for clarity scores and fixes applied +100/-0  agent.yaml YAML configuration for code clarity agent                                agents/code-clarity-agent/agent.yaml Provide YAML alternative to TOML agent configuration Include comprehensive instructions for code analysis workflow Define scoring rubric for detecting 5 types of clarity issues Specify output schema with issues detected and fixes applied +103/-0  agent.toml Root agent configuration with imports                                        agent.toml Add root-level agent configuration file Set default model to Claude 4.5 Sonnet Import code-clarity-agent configuration +10/-0
Documentation	README.md Comprehensive documentation for clarity agent                        agents/code-clarity-agent/README.md Document Universal Code Clarity Agent features and philosophy Provide quick start examples for Python and JavaScript analysis Explain core features including issue detection and AI-powered fixes Include example workflow showing score improvement from 45 to 90 +82/-0    README.md Minor README formatting updates                                                    README.md Update root README title formatting Ensure proper newline at end of file +2/-2
Tests	bad_code.py Python example with code clarity issues                                    agents/code-clarity-agent/examples/bad_code.py Create Python example file with intentional clarity issues Include missing docstrings, magic numbers, and poor variable names Demonstrate DataProcessor class and utility functions Serve as test case for agent analysis and refactoring +27/-0    bad_code.js JavaScript example with code clarity issues                            agents/code-clarity-agent/examples/bad_code.js Create JavaScript example file with intentional clarity issues Include missing docstrings, magic numbers, and poor variable names Demonstrate DataProcessor class and utility functions Serve as test case for agent analysis and refactoring +33/-0
Miscellaneous	update-readme-for-merged-pr.yml Remove outdated README update workflow                                      .github/workflows/update-readme-for-merged-pr.yml Remove outdated GitHub workflow for README updates Eliminate workflow_dispatch trigger and associated job steps +0/-60

---

[qodo-free-for-open-source-projects]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Unrestricted shell access Description: Granting the "shell" tool to an AI-driven command without explicit constraints can enable arbitrary command execution if inputs are not strictly validated, posing a potential RCE risk. agent.toml [52-52] Referred Code tools = ["filesystem", "shell"]
	Unrestricted shell access Description: Allowing the "shell" tool in the agent configuration may permit arbitrary command execution depending on how user-supplied arguments are handled, creating a potential RCE vector. agent.yaml [56-56] Referred Code tools: ["filesystem", "shell"]
Ticket Compliance
⚪	🎫 No ticket provided - [ ] Create ticket/issue <!-- /create_ticket --create_ticket=true --> </details></td></tr>
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	No custom compliance provided Follow the guide to enable custom compliance check.

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-free-for-open-source-projects]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Add explicit output calculation instructions Add explicit instructions to the agent on how to calculate the score_improvement_percent and summary fields to ensure the final JSON output is complete and correct as per the schema. agents/code-clarity-agent/agent.toml [41-44] 5. **Generate the Output:** + * Calculate `score_improvement_percent`. If `initial_score` is 0, this should be 0. Otherwise, it is `((final_score - initial_score) / initial_score) * 100`. + * Populate the `summary` object: + * `total_issues_found`: The total count of items in the `issues_detected` list. + * `automatic_fixes_applied`: The count of fixes that modified the code (e.g., "Generated Docstring", "Extracted Constant", "Removed Comment"). + * `suggestions_provided`: The count of fixes that are only suggestions (e.g., "Suggested Variable Name"). * Produce a JSON object that strictly follows the `output_schema`. * **Do not write to any files.** The JSON object should be the final output printed to the console. - * The output must include the initial score, final score, a list of issues found, a list of fixes applied, the original code, and the refactored code. + * The output must include all required fields from the schema. Apply / Chat Suggestion importance[1-10]: 8 __ Why: The suggestion correctly points out that the agent's instructions are incomplete regarding the output_schema, and provides explicit calculations that are crucial for ensuring reliable and consistent JSON output.	Medium
High-level	Remove redundant agent configuration files The agent's configuration is duplicated in both agent.toml and agent.yaml files. To prevent maintenance problems, the redundant file should be removed, leaving a single source of truth. Examples: agents/code-clarity-agent/agent.toml [1-100] version = "1.0" model = "claude-4.5-sonnet" [commands.code-clarity] description = "Analyzes source code in any language for clarity issues, auto-fixes them using AI, and reports the score improvement." instructions = """ You are an expert code quality analyst and refactoring assistant for multiple programming languages. Your goal is to analyze a given source file, identify clarity issues, automatically fix them, and report the improvement with a scoring system. The user will specify the language. Follow these steps precisely: ... (clipped 90 lines) agents/code-clarity-agent/agent.yaml [1-103] version: "1.0" model: "claude-4.5-sonnet" commands: code-clarity: description: "Analyzes source code in any language for clarity issues, auto-fixes them using AI, and reports the score improvement." instructions: | You are an expert code quality analyst and refactoring assistant for multiple programming languages. Your goal is to analyze a given source file, identify clarity issues, automatically fix them, and report the improvement with a scoring system. The user will specify the language. Follow these steps precisely: ... (clipped 93 lines) Solution Walkthrough: Before: # File structure before agents/code-clarity-agent/ ├── agent.toml # Configuration in TOML format ├── agent.yaml # Identical configuration in YAML format ├── README.md └── examples/ ├── bad_code.js └── bad_code.py After: # File structure after agents/code-clarity-agent/ ├── agent.toml # Single source of truth for configuration ├── README.md └── examples/ ├── bad_code.js └── bad_code.py Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies redundant configuration files (agent.toml and agent.yaml), which is a significant maintainability issue that could lead to future inconsistencies.	Medium
Possible issue	Refine final score calculation logic Adjust the final score calculation instructions to ignore penalties for issues where only a suggestion was provided (e.g., poor variable names), ensuring the score accurately reflects the agent's improvements. agents/code-clarity-agent/agent.toml [38-39] 4. **Calculate the Final Score:** - * Analyze the refactored code using the same scoring rubric from step 1. This will be the final "Clarity Score". + * Analyze the refactored code using the same scoring rubric from step 1. + * When calculating the final score, do not subtract points for issues where a fix was only suggested and not automatically applied (e.g., "Poor Variable Name"). This ensures the final score reflects the full value of the agent's contributions. This will be the final "Clarity Score". Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a logical flaw in the agent's instructions where the final score would be unfairly penalized for issues it was told not to fix, leading to a misleading result.	Medium
More