Creating and Managing Agents

Run Qodo Gen CLI with a configured agent

Create your own agent for Qodo Gen CLI to use, then run Qodo Gen CLI with a customizable command.

1. Create an agent file

Create a file <your-command-name-here>.toml and save it under a folder called agents.

You can create an initial skeleton of an agent file by running:

qodo init

2. Customize your agent

Follow the skeleton and customize your agent to your needs. You can set instructions, import existing agents configurations for your agent to use, and give it tools to utilize:

Name your agent file after the command you want to use to run it. This name should also appear in the file itself, under the commands section.

The fields of the agent file are:

Field name	Accepted values	Description
description	string	Description of what your agent does
instructions	string	Prompt for the AI models explailing the required behavior
arguments	list of objects	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
available_tools	list	List of MCP server names
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	For CI runs, a condition used to determine if the agent run succeeded or failed

Example agent TOML file

description = "Explain the code changes."
instructions = """
Review the code changes and provide a detailed explanation of the modifications.
Focus on the purpose of each change, the reasoning behind it, and any potential impact on the overall functionality.
Summarize the changes in a clear and concise manner.
"""
arguments = [
    { name = "coverage_score_threshold", type = "number", required = false, description = "Minimum coverage score for the tests to be considered sufficient." },
]

mcpServers = """
{
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/sagimedina/WebstormProjects/qodo-cli"
      ]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"]
    }
}
"""

available_tools = ["git", "filesystem"]

execution_strategy = "act"

output_schema = """
{
    "properties": {
        "significant_changes:": {
            "description": "The significant changes that were made.",
            "title": "Significant Changes",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "minor_changes": {
            "description": "The minor changes that were made.",
            "title": "Minor Changes",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "include_tests": {
            "description": "Whether tests were cover the changes.",
            "title": "Include Tests",
            "type": "boolean"
        },
        "walkthrough": {
            "description": "Walkthrough",
            "title": "Walkthrough",
            "type": "string"
        }
    }
}
"""

exit_expression = "include_tests"

3. Set output type

You can give your agent a json schema to follow as its output. If there’s no output schema given, your agent will output a textual summary as a reply for a query.

4. Create an agent.toml file

Add your agent to a file called agent.toml. This file will hold all agent files that Qodo Gen CLI will know and be able to call. Example agent.toml file:

# Version of the agent configuration standard
version = "1.0"

model = "claude-4-opus"

imports = [
    "agents/explain.toml",
    "agents/review.toml",
    "agents/test_codebase.toml",
    ... # more agents
]

Use your agent

You can now run your agent by calling:

qodo <command_name>

Agent as server

You can also run an agent as a tool server:

qodo <command_name> --mcp

This launches the agent as a service listening on port 3000.

The service can be integrated with other AI tools or exposed via URL.

You can exit at any time by pressing Escape.

AI Model selection

You can use a specific AI model with --model=<model_name>.

For a list of available model names, run qodo models.

mcp.json file

You can define MCP servers to be used by agents in a file called mcp.json. This will make the MCP servers available to all agents you're configuring.

If you want a specific MCP server for your agent that doesn't need to be reused for other agents, you can define it in the specific agent configuration TOML file.

---

Available Agent Commands and Flags

Command	Description
init	Generate starter agent configuration file
create-agent	Create a new agent by translating user requirements into a valid TOML configuration
<command-name>	Run a configured agent
-agentfile=path	Specify a custom path to an agent TOML file
<command-name> --mcp	Run an agent as a service (listening on port 3000)
mcp-list	List available local and remote tools
models	List available models
--model=model_name	Specify a custom model to use
--ci	Run commands in CI mode
--mcp	Run all configured agents as tools in MCP-server mode
--ui	Open Qodo Gen CLI with web interface
-h, --help	View all available commands and flags
-l, --log=path	Redirect console output to a file (directed in the path), or to stdout or stderr
--silent	Suppress all console output except the final result. Logs go to /dev/null
--resume=session_id	Resume a task with the given session ID