Kiran Naragund

Posted on Oct 30

🚀 Build Custom AI Agents with Qodo Command

#qodo #cli #ai #automation

Hello Devs 👋

I recently tried Qodo Command, a CLI that lets you build, run, and automate AI-powered agents right from your repository like a custom AI assistants that live in your codebase.✨

Unlike generic AI tools or one-off scripts, Qodo agents are configurable, versionable, and CI-friendly. You describe what the agent should do (in a TOML/YAML file), and it runs that behavior consistently across local dev, PR checks, and CI pipelines. That means smarter automation for code review, reliability checks, documentation audits, test generation whatever your team needs.

If you’ve ever wished for an assistant that enforces your project’s specific standards (not someone else’s), Qodo Command makes it possible.🫡

In this article I’ll cover:

What Qodo Command actually does?
Why it’s useful for dev teams and CI/CD workflows
How to use it step-by-step
A hands-on example: building a Clean Code Description agent that ensures your codebase remains clean, readable, and well-documented by reviewing docstrings, comments, and naming conventions.

Let’s dive in. 🚀

What is Qodo Command?

Qodo Command is a developer-first CLI that lets you create and run custom AI agents inside your development workflow.

Think of it as your personal automation engine powered by AI but instead of generic prompts, you define repeatable rules, logic, and behaviors for the agent in a config file.

Qodo Command supports:

Custom agent configuration
CI and automation integration
Interactive web UI mode
General code generation
Intelligent PR code review

If ChatGPT is a smart assistant you talk to, then Qodo Command is an AI teammate that lives in your repo and enforces your standards.

⭐️ Key Features

Interactive Chat Mode: Talk to an agent in natural language directly in your terminal (qodo chat), exactly like with Qodo Gen Chat.
Custom Agent Commands: Configure your own agent and define reusable workflows (qodo <command>).
Interactive Web UI mode: Run Qodo Command with --ui to interact with Qodo Command's chat in an interactive web UI.
Serve Agents as HTTP APIs: Turn any agent into a callable service (--webhook mode).
Model Control: Choose which AI model to use (Claude, GPT-4, etc.) with --model={model-name}.
Agent to MCP: Turn any agent into an MCP with --mcp.
Secure Integration: Use tools without exposing your API keys.

🚀 How to Install & Use Qodo Command

Now that you know what Qodo Command is, let's get it running.

npm install -g @qodo/command

To start using Qodo Command, you need to log in first:

qodo login

Once login is completed you'll receive an API key in the terminal.

The API key is also saved locally in the .qodo folder in your home dir, and can be reused (e.g., in CI).

Interactive AI Chat Mode

qodo chat

In this mode you can send prompts such as:

Write tests for the files in the auth directory

Add better logging througout my project

Use Qodo Merge to describe the changes in my working folder

And Qodo Command will follow your guidelines.

🛠️ Build a Custom Qodo Agent From Scratch

Now, Let’s create a Clean Code Documentation agent, an agent that reviews your repo for:

✔️ Missing docstrings
✔️ Outdated or misleading comments
✔️ Poor naming issues
✔️ Documentation consistency

1️⃣ Create the agent config
At your project's root directory level, create a file called clean-doc-agent.toml. This file will hold all agent files that Qodo Command will know and be able to call.

# Clean Code Description Agent Configuration
version = "1.0"

[commands.clean_code_description]
description = "Analyze code for clean, consistent, and accurate descriptions in docstrings, comments, and naming conventions"

instructions = """
You are an expert in code documentation and clean code practices. Your task is to:
1. Analyze code changes using Qodo Merge to identify documentation issues
2. Focus on:
   - Missing or incomplete docstrings
   - Outdated or incorrect docstrings/comments
   - Redundant or low-value comments
   - Inconsistent documentation styles
   - Poorly named functions, classes, or variables
3. Categorize findings by severity: Critical, High, Medium, Low
4. Provide clear, actionable feedback for each issue
5. Suggest improvements with concrete examples
6. Ensure that the documentation aligns with the actual behavior of the code
Return feedback that helps developers maintain a clean, readable, and maintainable codebase.
"""

arguments = [
    { name = "target_branch", type = "string", required = false, default = "main", description = "Branch to compare changes against" },
    { name = "severity_threshold", type = "string", required = false, default = "medium", description = "Minimum severity level to report (low, medium, high, critical)" },
    { name = "include_suggestions", type = "boolean", required = false, default = true, description = "Include improvement suggestions" },
    { name = "focus_areas", type = "string", required = false, description = "Comma-separated focus areas (docstrings, comments, naming)" },
    { name = "exclude_files", type = "string", required = false, description = "Comma-separated list of file patterns to exclude from analysis" }
]

tools = ["qodo_merge", "git", "filesystem"]
execution_strategy = "act"

output_schema = """
{
  "type": "object",
  "properties": {
    "summary": {
      "type": "object",
      "description": "High-level summary of documentation and naming quality issues found",
      "properties": {
        "total_issues": {"type": "number", "description": "Total number of issues identified"},
        "critical_issues": {"type": "number", "description": "Number of issues categorized as critical"},
        "high_issues": {"type": "number", "description": "Number of high severity issues"},
        "medium_issues": {"type": "number", "description": "Number of medium severity issues"},
        "low_issues": {"type": "number", "description": "Number of low severity issues"},
        "missing_docstrings": {"type": "number", "description": "Number of functions/classes missing docstrings"},
        "outdated_descriptions": {"type": "number", "description": "Number of outdated or incorrect docstrings/comments"},
        "redundant_comments": {"type": "number", "description": "Number of unnecessary or low-value comments"},
        "poor_names": {"type": "number", "description": "Number of functions, classes, or variables with unclear or inconsistent names"},
        "files_reviewed": {"type": "number", "description": "Total number of files analyzed"},
        "overall_score": {"type": "number", "minimum": 0, "maximum": 10, "description": "Overall documentation quality score (0-10)"}
      },
      "required": [
        "total_issues",
        "critical_issues",
        "high_issues",
        "medium_issues",
        "low_issues",
        "missing_docstrings",
        "outdated_descriptions",
        "redundant_comments",
        "poor_names",
        "files_reviewed",
        "overall_score"
      ]
    },
    "issues": {
      "type": "array",
      "description": "Detailed list of individual issues identified in the codebase",
      "items": {
        "type": "object",
        "properties": {
          "file": {"type": "string", "description": "Path to the file containing the issue"},
          "line": {"type": "number", "description": "Line number where the issue occurs"},
          "severity": {"type": "string", "enum": ["critical", "high", "medium", "low"], "description": "Severity level of the issue"},
          "category": {"type": "string", "description": "Category of the issue (e.g., docstring, comment, naming)"},
          "title": {"type": "string", "description": "Short title summarizing the issue"},
          "description": {"type": "string", "description": "Detailed explanation of the problem"},
          "suggestion": {"type": "string", "description": "Suggested fix or improvement"},
          "code_example": {"type": "string", "description": "Example of improved or corrected code"}
        },
        "required": ["file", "severity", "category", "title", "description"]
      }
    },
    "suggestions": {
      "type": "array",
      "description": "List of broader improvement suggestions for code cleanliness and documentation",
      "items": {
        "type": "object",
        "properties": {
          "file": {"type": "string", "description": "File path for the suggestion"},
          "type": {"type": "string", "description": "Type of suggestion (e.g., naming, docstring, structure)"},
          "description": {"type": "string", "description": "Description of the suggested improvement"},
          "implementation": {"type": "string", "description": "Recommended way to apply the suggestion"}
        },
        "required": ["file", "type", "description"]
      }
    },
    "approved": {"type": "boolean", "description": "Indicates if code meets cleanliness standards"},
    "requires_changes": {"type": "boolean", "description": "Indicates if changes are required before approval"}
  },
  "required": ["summary", "issues", "approved", "requires_changes"]
}
"""

exit_expression = "approved"

The fields of the agent file are:

Field name	Type	Description
`description`	string	Description of what your agent does. This field is required when an agent is run with `--mcp`.
`instructions`	string	Required field. Prompt for the AI models explailing the required behavior.
`arguments`	list of objects. Supported types: `'string' \| 'number' \| 'boolean' \| 'array' \| 'object'`	List of possible arguments that can be given to the agent. The arguments will be translated and forwarded to MCP servers.
`mcpServers`	string	List of MCP servers used by the agent
`tools`	list	List of MCP server names. Allows you to filter specific MCP servers that can be used by your agent
`execution_strategy`	"act" or "plan"	Plan lets the agent think through a multi-step strategy, act executes actions immediately
`output_schema`	string	Valid json of the wanted agent output
`exit_expression`	string (JSONPath)	Only applicable when `output_schema` is given. For CI runs, a condition used to determine if the agent run succeeded or failed.

Our agent accepts the following parameters:

Parameter	Type	Required	Default	Description
`target_branch`	string	No	`"main"`	Branch to compare changes against
`severity_threshold`	string	No	`"medium"`	Minimum severity to report (low/medium/high/critical)
`include_suggestions`	boolean	No	`true`	Include improvement suggestions in output
`focus_areas`	string	No	-	Comma-separated list of areas to review (docstrings, comments, naming)
`exclude_files`	string	No	-	File patterns to exclude from analysis

2️⃣ Run the agent locally
You can run this agent by passing optional arguments

# Run the agent to review code documentation
qodo clean_code_description

# Compare current changes against the main branch
qodo clean_code_description --target_branch=main

# Focus only on docstrings and naming issues
qodo clean_code_description --focus_areas=docstrings,naming

With Advanced Configuration

qodo clean_code_description \
  --target_branch=develop \
  --severity_threshold=medium \
  --focus_areas=docstrings,comments,naming \
  --exclude_files="tests/*,*.md" \
  --include_suggestions=true

3️⃣ Output Format

The agent returns structured JSON output:

{
  "summary": {
    "total_issues": 8,
    "critical_issues": 0,
    "high_issues": 3,
    "medium_issues": 4,
    "low_issues": 1,
    "files_reviewed": 5,
    "overall_score": 7.8,
    "missing_docstrings": 3,
    "outdated_descriptions": 2,
    "redundant_comments": 2,
    "poor_names": 1
  },
  "issues": [
    {
      "file": "src/utils/formatter.py",
      "line": 12,
      "severity": "medium",
      "category": "docstring",
      "title": "Missing function docstring",
      "description": "The function `format_name` lacks a docstring, making its behavior unclear.",
      "suggestion": "Add a concise docstring describing the purpose and parameters.",
      "code_example": "\"\"\"Format the input name by capitalizing each word.\"\"\""
    }
  ],
  "suggestions": [
    {
      "file": "src/models/user.py",
      "type": "naming",
      "description": "Rename variable `usrObj` to `user` for clarity",
      "implementation": "Use descriptive names that reflect purpose instead of type"
    }
  ],
  "approved": false,
  "requires_changes": true
}

Here is the full demo video 👇

Now, The most common way to use this agent is through GitHub Actions to automatically review pull requests.

Let's create a github-action file for it.

GitHub Actions

name: Clean Code Description Agent
on:
  pull_request:
    branches: [main, develop]

jobs:
  clean-code:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      checks: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Clean Code Description Agent
        uses: qodo-ai/command@v1
        env:
          QODO_API_KEY: ${{ secrets.QODO_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          prompt: clean_code_description
          agent-file: path/to/agent.toml
          key-value-pairs: |
            target_branch=${{ github.base_ref }}
            focus_areas=docstrings,comments,naming
            severity_threshold=medium
            include_suggestions=true