Skip to main content
Custom agents are in beta. Behavior and screens may still change.

​
Overview

A custom agent is a reviewer your team writes for one concern: architecture boundaries, duplicated code, a security policy, end-to-end test coverage. Each agent has:
  • Instructions: what to look for, what to ignore, and what proof a finding needs
  • Files: the globs it reviews. It runs only when a pull request changes one of them
  • Skills & docs: guides from the repository it follows
  • Tools: read-only plugins, your team’s CLIs and ast-grep rules
  • Comments & model: its tag, format, severity floor, comment limit, writing style and model
Agents run beside Kody’s own review. Each one reports only its own focus, and its comments carry a tag with its name, so the team knows who is speaking. Available on Teams and Enterprise plans, and during the trial. On the Free plan no custom agent runs: not in reviews, not with @kody -v, not in Try it. Saved agents, skills and docs are kept and run again after an upgrade.

Skills, docs and tools

Link repository guides, plugins, team CLIs and ast-grep rules.

Best practices

Write agents that find real problems and stay quiet otherwise.

​
Where to find them

Open Code review → What to review. The Custom agents section sits below the review categories, with a New agent button and a link to Skills & docs. Each row shows the agent’s switch, its tag color, the first line of its instructions, chips for its files, skills, docs and tools, and what it did lately (for example 9 PRs · 15 posted · 30 days). Click a row to open the agent’s page. The ⋯ menu has Edit, Try it and Delete.
Custom agents are configured in the app only. customAgents and knowledge keys in kodus-config.yml are ignored, and the review says so in its closing comment. See FAQ.

​
Levels

Agents follow the scope picker at the top of the Code review group, like the rest of your settings. At a directory, an inherited agent opens read-only with Override at this directory. Overriding copies the agent into the directory with the same id, so the copy replaces the repository’s agent for that directory: change its instructions, or turn it off. Deleting the override brings the repository’s agent back.
A directory’s agents run when the review uses that directory’s settings. See Directory-Level Settings for how a pull request picks its settings.

​
Create an agent

1

Click New agent

In What to review → Custom agents, click New agent.
2

Pick a starting point

Templates start from written instructions:Import from repository lists the skills found on the repository’s default branch and turns one into a reviewer that loads it on every review. It is not available at the global level, since skills live in each repository.
3

Shape it on its page

The agent is saved right away and its page opens. Set its files, link skills and docs, add tools.
4

Try it, then turn it on

A new agent starts off. Run it with Try it on a real pull request. When its comments look right, turn it on.
The agent’s name is also its command name: “Data Contracts” answers to @kody -v data-contracts. Two agents whose names give the same command name can’t be saved at the same level.

​
The agent page

The page has a status line (on/off, the files it runs on and what it posted in the last 30 days), four cards, and the Try it panel. Changes on the page are kept with Save. When the agent’s latest runs failed or stopped before finishing, the status line says so, with the reason and what fixes it: Change the model when the model is gone or the account can’t use it, Open AI providers for a rejected key or an account out of credits. It clears once a run finishes.

​
Instructions

​
Files & knowledge

Globs are matched against the path from the repository root, at every level, including at a directory. Ignored files. Your repository’s ignored paths (in General) still apply, with one exception: a glob that names a file reaches it even when the repository ignores it. A glob names a file when one of its path segments is literal and its last segment is more than * or **: Secret files (.env*, *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore, id_rsa* and other SSH keys) are never handed to an agent from the ignored paths, even by a glob that names them. A pull request whose changed files are all ignored is still reviewed by an agent that names one of them, and only by it: Kody’s own review has nothing to look at.

​
Tools

What the agent can run besides reading the code, all read-only towards your systems: Plugins (MCP), CLIs (up to 3) and, under Advanced, Structural search (ast-grep rules). See Skills, docs and tools.

​
Comments & model

​
Try it

Try it runs the agent as it is on screen, saved or not, on one pull request of the repository. Nothing is posted.
1

Paste a pull request link

On the agent’s page, paste the link of a pull request from this repository and click Run agent. It takes a few minutes on a large change.
2

Read the result

The header counts findings, how many were kept and how many would post. Below it:
  • Warnings: what the run lost, such as no checkout (the agent read only the diff), a CLI that could not be installed, or a skill or doc that could not be used
  • Skills opened, with the reference files the agent read
  • Tool calls, each with its input and output, including CLI output
  • Findings: each one kept, dropped or unverified, with the reason, the rule it quotes, and the Comment that would post
3

Change and run again

Edit the instructions, globs or tools and run again. If you edit after a run, the page warns that the result is from an earlier version.
Try it works at repository and directory level, and needs permission to edit code review settings. If no changed file matches the agent’s globs, the run is skipped and says why.

​
Run one agent on a pull request

Comment on a pull request with the agent’s command name on the first line:
Kody runs that agent alone, on the whole pull request, even while the agent is off, and posts its comments. Kody’s own reviewers don’t run, and the pull request is never approved by this command. If no agent answers to that name, Kody replies with the names that do.

​
How agents run in a review

1

Pick the agents

Every enabled agent whose globs match at least one changed file runs. An agent with no matching file doesn’t run.
2

Review

Each agent reviews only its files, beside Kody’s own review, and reports only what its instructions ask for. It reads skills and docs from the target branch (a guide of another repository from the branch set for it) and uses its tools.
3

Check every finding

A convention finding must quote the rule it applies, from a linked guide or from the agent’s instructions. A quote that is not in the guide, on the branch it is read from, is dropped. A quote shortened with ”…” passes when each part is there, in order. A verifier then drops findings outside the agent’s focus or without support in the code. An ast-grep match counts as proof on its own.
4

Apply the agent's settings

The agent’s minimum severity, then its comment limit (the most severe are kept).
5

Merge with the main review

When an agent and Kody report the same problem, one comment is kept. For a team rule inside the agent’s focus, the agent’s comment wins. For anything else, Kody’s comment stays.
6

Post

Comments carry the agent’s tag. A convention comment cites the rule applied (the guide and its words, or “agent’s instructions”). A finding backed by a CLI shows the CLI output lines that name the file, under Evidence.
Each agent’s comments carry its tag, so the pull request shows which agent said what. The agent’s page shows what it did in the last 30 days: the pull requests it reviewed and the comments it posted.

​
Limits

​
FAQ

Check, in order:
  • It is off. New agents start off. @kody -v <name> runs it anyway.
  • No changed file matches its Files globs, or every match is in Except.
  • Its files are in the repository’s ignored paths and its globs don’t name them. Name the files explicitly (see Files & knowledge).
  • Its files were deleted in the pull request.
  • At a repository with its own list, an agent added at the global level later doesn’t reach it.
  • At a directory, the review used the repository’s settings (for example, the pull request touched two configured directories).
Run the agent with Try it on the same pull request: each dropped finding shows its reason. The usual ones:
  • The quote is not in the guide on the branch it is read from (paraphrased, or the guide changed only in the pull request).
  • The finding is outside what the agent’s instructions ask for.
  • The verifier found no support for it in the code.
  • It was below the agent’s minimum severity, or over its comment limit.
  • Kody’s review reported the same problem and kept its comment.
Try it shows, under Warnings, which file was not read and why. The usual reasons:
  • The repository is no longer connected to Kodus (unselected in Git settings, renamed, or its access revoked). Connect it again, then pick it under Other repository….
  • The integration’s repositories could not be listed at that moment. The next review tries again.
  • The file is not on that repository’s default branch, or on the branch or tag you set.
No. customAgents and knowledge in kodus-config.yml are not read. The closing comment says: “kodus-config.yml: customAgents is not read from this file; configure custom agents in the app.”
No. Skills, docs and ast-grep rule files are read from the pull request’s target branch. Edits to them in the pull request apply after it merges. A skill or doc of another repository is read at that repository’s default branch, or the branch or tag the team set, never at a ref the pull request names.
Its findings stay on past pull requests. The skills and docs stay registered on the Skills & docs page.