Custom agents

Custom agents are review rules that enforce your organization’s specific best practices across pull requests. Use the Agents library to create agents, adopt community agents, and choose which repositories run them.

​

Agents library

Manage your agents from the Agents library.

​

Creating custom agents

To create an agent, open the Agents library and click Add agent. To start from a popular or suggested agent, click Enable agent (the + button) on its card. Each custom agent includes:

1. A Name
   A concise title, like “Prevent N+1 Queries” or “Require Sentry Error Handling.”
2. A Description
   A clear, natural-language instruction the AI will use, such as “Flag code that may cause multiple database calls inside loops.”
   Be as clear and explicit as possible; the more specific you are, the better the results.
3. Linked instruction files For repository-specific agents, open Advanced and enter one repo-relative path per line, such as docs/style-guide.md or .cubic/review-agent.md. You can use linked files together with text instructions. You can also define linked files in cubic.yaml with a file_paths list. cubic reads those files from the pull request head commit when the review runs, so updates to the file apply to future reviews without editing the agent. CLI reviews read cubic.yaml and linked files from the repository’s default branch, so changes apply to CLI reviews once they are merged. File-backed agents are best when your team already maintains detailed style, framework, or architecture rules in the repository. General context files help cubic understand the codebase, but custom agents are the right place for checks you want cubic to actively flag.
   The agent text and linked files share one 10,000 character limit. cubic uses the first 10,000 characters and ignores the rest. Agents you add in the Agents library are text-only. To link files, add the agent in a repository’s Custom agents tab or in cubic.yaml.
4. Optional Path Filters Use Glob patterns to limit where the agent applies (or exclude certain paths). This is especially helpful for monorepos, where different directories often require different agents. For example:
   • Include: backend/** to apply the agent only to files under a backend folder.
   • Exclude: !tests/** to ignore test files and focus on production code.
5. Repositories Choose where the agent runs under Apply to repositories. See Choose which repositories an agent runs on.

​

Agent attribution in comments

When a custom agent flags an issue, the review comment will indicate which agent triggered it. This helps you understand which agents are working and allows you to iterate on your agent instructions over time.

​

Choose which repositories an agent runs on

An agent you add in the Agents library runs on every repository by default, including repositories added later. To change that, use Apply to repositories in the agent dialog:

• Skip some repositories: uncheck them under All repositories. The agent still runs on every other repository, including new ones.
• Run on only some repositories: uncheck All repositories, then check the repositories that should run the agent.
• Match by name: type a pattern such as web-*, then choose Only repositories matching or Skip repositories matching. The pattern also applies to repositories created later.

A repository you check stays selected after it’s renamed. Patterns follow the same rules as only_repositories and exclude_repositories in cubic.yaml. When the scope includes a pattern, the dialog shows how many repositories it matches, such as “Runs on 9 of 44 repositories, plus new ones that match web-*.”

​

Managing agents across repositories

Each agent’s card in the Agents library shows where the agent runs and how many repositories run it. Changes to the agent apply to every repository it runs on. From the card’s menu, Turn off everywhere pauses the agent and keeps its settings, and Delete agent removes it from every repository. In a repository’s Custom agents tab, these agents are read-only and labeled Agents library. Edit them in the Agents library. Agents saved as one copy per repository, such as agents added in a repository’s Custom agents tab, keep the repository list when you edit them, and you can turn them on or off for each repository.

​

When a repository reaches its agent limit

Each repository runs agents up to its agent limit, in this order:

1. Agents from cubic.yaml.
2. Agents saved for that repository, newest first.
3. Agents from the Agents library, oldest first, so a new agent never takes the place of an older one.

An agent from the Agents library doesn’t run on a repository where an agent with the same name and instructions already runs. If the limit keeps an agent off some repositories, the agent dialog warns you before you save, the agent’s card shows how many of its repositories run it, and the repository’s Custom agents tab marks it Not running.

​

Limitations

• Agent limit: The standard limit is 5 enabled custom agents per repository, or 15 on plans that include codebase scans, such as Pro and Max. Some organizations have a higher limit. The Agents library allows you to define more agents, but only up to your limit can be active per repository. See When a repository reaches its agent limit for which agents run.
• Instruction length: Text instructions and resolved file instructions use the same 10,000 character limit per custom agent. cubic concatenates the text and files in order and uses only the first 10,000 characters; the rest is not included in the review prompt. The dashboard shows how many characters are left or truncated before you save.
• File paths: File-backed agents accept repo-relative file paths only. Absolute paths, globs, parent-directory traversal, directories, binary files, and unreadable files are rejected or shown as warnings. Markdown and YAML files are read as plain text; cubic does not parse them as structured rule definitions.
• Potential false positives: Occasionally, the AI might incorrectly flag or overlook certain scenarios. Consider AI feedback as helpful guidance rather than definitive judgments.

​

Tips for effective custom agents

• Describe the code to flag and explain why it matters. Include examples when the rule is easy to misinterpret.
• Combine related checks when they share the same scope.
• Use path filters to keep rules relevant to the files being reviewed.
• Focus on checks that linters do not cover, such as business logic and team-specific conventions.

​

Next steps

• Agents library: Explore community agents and manage your custom agents across repositories.
• AI review settings: Configure AI review behavior for your repositories.
• Introduction: Understand how cubic reviews pull requests by default.