Custom agents

Discover, create, and manage custom agents across your repositories

Custom agents are review rules that enforce your organization’s specific best practices across pull requests.

The rules library lets you discover proven agents from other successful teams, apply one agent to multiple repositories, and manage everything from a central dashboard.

Rules library

The rules library enables teams to share and adopt best practices efficiently. Instead of creating the same agent for each repository, you can create an agent once and apply it to any number of repositories.

Manage all your agents from the rules library

Creating custom agents

To create a new agent, navigate to the Rules library in cubic and click “Add rule”. You can also adopt existing agents from the community library with a single click.

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.

   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. The multi-repository rules-library dialog still creates text-only agents; use repository-scoped agents or cubic.yaml for linked files.

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.

Custom agents can be applied to multiple repositories from a single definition. You can enable different combinations of agents for each repository while managing them all from one central location.

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.

Managing agents across repositories

The multi-repository management capability streamlines how teams handle custom agents at scale:

One agent, many repositories

When you create or edit an agent, you can select which repositories it applies to:

• Use the repository selector to choose multiple targets
• Apply the same security check to all 150 microservices with one agent
• Maintain consistency without duplication

Repository-specific control

While agents are centrally managed, you maintain granular control:

• Enable or disable agents per repository as needed
• Different repositories can use different combinations of agents
• Changes propagate instantly across all selected repositories

Benefits for teams at scale

This approach dramatically simplifies agent management:

• Before: Creating 150 separate agents for 150 microservices
• After: One agent applied to all 150 repositories
• Time saved: Hours of setup reduced to minutes
• Maintenance: Update once, apply everywhere

Limitations

• Agent limit: Each repository can have a maximum of 5 enabled custom agents at a time. The rules library allows you to define more agents but only 5 can be active per repository.
• 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

• Start with the library: Before creating a new agent, check if a similar one already exists in the community library. You can adopt and customize popular agents to fit your needs.

• Combine related checks: With a limit of 5 active agents per repository, combine multiple related checks into a single agent where it makes sense. The multi-repository feature means you only need to define this once.

• Leverage path filters in monorepos: When working with monorepos, use Glob patterns to target specific files or folders. The “glob wizard” and “glob testing” tools help ensure your patterns work correctly.

• Use repository groups: Apply agents to logical groups of repositories (e.g., all frontend repos, all microservices) to maintain consistency across similar projects.

• Learn from others: Browse popular agents in the library to see what other successful teams are checking for. This can inspire new agents or improvements to your existing ones.

• Complement existing tools: Custom agents should focus on checks that standard tools like ESLint or Prettier might miss, such as business logic validations or team-specific conventions.

Next steps

• Rules 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.