Skip to main content

Subagents

Subagents are specialized AI assistants in Codely CLI designed to handle specific types of tasks. They allow you to delegate work to AI agents configured with task-specific prompts, tools, and behaviors.

What are Subagents?​

Subagents are independent AI assistants with the following characteristics:

  • Specialized Tasks - Each subagent is configured with a focused system prompt for a specific type of work
  • Independent Context - They maintain their own conversation history, separate from the main conversation
  • Controlled Tool Access - You can configure which tools each subagent can access
  • Autonomous Work - Once given a task, they work independently until completion or failure
  • Detailed Feedback - You can view their progress, tool usage, and execution statistics in real-time

The subagent system significantly improves efficiency and output quality by breaking down complex tasks and handling them with specialized agents.

Key Advantages​

  • Task Specialization - Create agents optimized for specific workflows (testing, documentation, refactoring, etc.)
  • Context Isolation - Separate specialized work from the main conversation
  • Reusability - Save and reuse agent configurations across projects and sessions
  • Controlled Access - Limit tools each agent can use for improved security and focus
  • Progress Visibility - Monitor agent execution with real-time progress updates

How Subagents Work​

  1. Configuration - Create subagent configurations defining behavior, tools, and system prompts
  2. Delegation - The main AI can automatically delegate tasks to appropriate subagents
  3. Execution - Subagents work independently, using their configured tools to complete tasks
  4. Results - Return results and execution summaries to the main conversation

Quick Start​

Viewing Available Agents​

List all available subagents:

/agents list

Viewing Agent Details​

View detailed information about a specific agent:

/agents info <agent_name>

Reloading Configuration​

After modifying agent configuration, reload to apply changes:

/agents reload

Using Subagents​

The simplest way is to directly tell the main AI what you need, and it will automatically select the appropriate subagent:

Write comprehensive tests for the authentication module

The main AI will automatically recognize this is a testing task and delegate it to the testing expert subagent.

You can also explicitly specify which subagent to use:

Let the testing-expert subagent create unit tests for the payment module

Creating Custom Subagents​

Storage Location​

Subagent configuration files are stored in the following locations:

  • Project Level: .codely-cli/agents/ (higher priority)
  • User Level: ~/.codely-cli/agents/ (fallback)

This allows you to have project-specific agents and personal agents that work for all projects.

⚠️ Important Notes​

1. task is a Reserved Field (and Must be Provided)​

task is a system reserved field: used for passing "the task to complete" when calling a subagent. In the input_schema of a custom agent:

  • Must include task = "string" (required, cannot be optional, cannot be renamed)
  • Cannot define agent_name (this field is reserved by the delegate_to_agent tool for selecting which agent to run)

Note

  • Old implementations provided this as query="${task}", new versions can omit it as codely will inject it automatically

❌ Wrong Example:

[validation]
input_schema = {
  task = "string?",  # Wrong! task must be required string
  agent_name = "string" # Wrong! agent_name is a reserved field
}

✅ Correct Example:

[validation]
input_schema = {
  task = "string",          # Required: the task to complete
  target = "string",
  description = "string?"
}

You must correctly configure the task field, which is key to the subagent running correctly.

It is recommended to use CODELY TOML format (.toml) when creating new subagent configurations.

3. Other Formats Not for Direct Creation​

For compatibility with other tools, Codely CLI also supports the following formats, but not recommended for directly creating new subagents:

  • Gemini TOML format (**.toml**): Compatible with Gemini's configuration format
  • Claude YAML Frontmatter format (**.md**): Compatible with Claude's configuration format

These formats are only for migrating existing configurations from other tools. Create new subagents using the recommended Legacy TOML format.

description = "Brief description of the agent's functionality"

[agent]
name = "planner"
system_prompt = """
Detailed system prompt defining the agent's behavior, capabilities, and methods.
Use `${variable_name}` placeholders for dynamic input replacement (only TOML format supports this; YAML frontmatter format will not interpolate).
"""
query = "\$\{task\}"

# Optional model configuration
[agent.model_config]
model = ""  # Empty string uses default model
temp = 0.1
top_p = 0.95

[agent.run_config]
# Optional run configuration settings

[agent.tools]
allowed_tools = ["tool1", "tool2", "tool3"]

[validation]
input_schema = {
  required_param = "string",
  optional_param = "string?",
  array_param = "array?"
}

[example]
inputs = { required_param = "example_value", optional_param = "optional_value" }
description = "Brief description of what this example demonstrates"

Configuration Field Descriptions​

Basic Information​

  • name: Unique identifier for the agent (internal use)
  • description: Concise summary of the agent's purpose

Prompt Configuration​

  • system_prompt: Detailed prompt defining agent behavior, expertise, and methods

Model Configuration (Optional)​

  • model: Model name to use (empty string uses default, same as current)
  • temp: Temperature setting (0.0-1.0, lower values = more deterministic)
  • top_p: Top-p sampling parameter

Tool Configuration​

  • tools / allowed_tools: Specify the list of tools the agent can use, default is empty allowing all tools, otherwise only allows given tools

Input Validation​

  • input_schema: Define expected input parameters and their types

Examples​

  • example: Provide usage examples for documentation and testing

Available Tools​

Custom agents can access the following tools:

File System Tools​

  • read_file: Read file contents
  • write_file: Write content to files
  • read_many_files: Read multiple files at once
  • list_directory: List directory contents
  • glob: Find files matching patterns
  • search_file_content: Search in file contents

Analysis Tools​

  • sequential_thinking: Step-by-step reasoning
  • analyze_multimedia: Analyze images, audio, video

System Tools​

  • run_shell_command: Execute shell commands

Web Tools​

  • web_fetch: Fetch and process web content
  • web_search: Search web information

Memory Tools​

  • save_memory: Save information to memory

Task Management​

  • todo_write: Create and manage task lists

Best Practices​

Design Principles​

Single Responsibility Principle​

Each subagent should have a clear, focused purpose.

✅ Good:

name = "testing-expert"
description = "Write comprehensive unit tests and integration tests"

❌ Avoid:

name = "general-helper"
description = "Help with testing, documentation, code review, and deployment"

Reason: Focused agents produce better results and are easier to maintain.

Clear Specialization​

Define specific areas of expertise rather than broad capabilities.

✅ Good:

name = "react-performance-optimizer"
description = "Optimize React application performance using profiling and best practices"

❌ Avoid:

name = "frontend-developer"
description = "Handle frontend development tasks"

Reason: Specific expertise leads to more targeted and effective assistance.

Actionable Descriptions​

Write descriptions that clearly indicate when to use the agent.

✅ Good:

description = "Review code for security vulnerabilities, performance issues, and maintainability problems"

❌ Avoid:

description = "A useful code reviewer"

Reason: Clear descriptions help the main AI select the correct agent for each task.

Configuration Best Practices​

System Prompt Guidelines​

Specify expertise explicitly:

You are a Python testing expert with expertise in:

- pytest framework and fixtures
- Mocking objects and dependency injection
- Test-driven development practices
- Performance testing with pytest-benchmark

Include step-by-step methodology:

For each testing task:

1. Analyze code structure and dependencies
2. Identify key functionality and edge cases
3. Create a comprehensive test suite with clear naming
4. Include setup/teardown and appropriate assertions
5. Add comments explaining complex test scenarios

Specify output standards:

Always follow these standards:

- Use descriptive test names that explain the scenario
- Include both positive and negative test cases
- Add docstrings for complex test functions
- Ensure tests are independent and can run in any order

Security Considerations​

  • Tool Restrictions: Subagents can only access their configured tools
  • Sandboxing: All tool execution follows the same security model as direct tool usage
  • Audit Trail: All subagent operations are logged and visible in real-time
  • Access Control: Project and user-level separation provides appropriate boundaries
  • Sensitive Information: Avoid including keys or credentials in agent configurations
  • Production: Consider using separate agents for production and development environments

Frequently Asked Questions​

How to enable the subagent feature?​

In Codely CLI, the agents (subagent) system is enabled by default. If you previously disabled it, you can enable/disable it via:

  • Command Line: codely --agents=true (or remove --no-agents); to disable: codely --agents=false
  • Configuration File: In .codely-cli/settings.json (workspace) or ~/.codely-cli/settings.json (user), set:
{
  "agents": { "enabled": true }
}

Additionally, built-in agents are not loaded by default (agents.enableBuiltin=false). To load built-in agents:

{
  "agents": { "enableBuiltin": true }
}

Can subagents call each other?​

No. To prevent recursive calls and infinite loops, subagents cannot call the delegate_to_agent tool.

How to debug subagents?​

Run the CLI in debug mode to see more detailed logs, for example: codely --debug (you can also use DEBUG=1 codely).

What if subagent execution times out?​

You can set a timeout in the agent configuration (in minutes):

[agent.run_config]
max_time_minutes = 30  # Timeout after 30 minutes

How to limit the maximum conversation turns for subagents?​

Set the maximum turns in the agent configuration:

[agent.run_config]
max_turns = 10  # Maximum 10 conversation turns

Advanced Usage​

Parallel Execution of Multiple Subagents​

Some models can execute tools in parallel, and the main AI can delegate multiple subagents simultaneously to handle different tasks in parallel, improving efficiency.

However, it must be noted that changes from each agent cannot overlap, and directory isolation is preferred.

For example:

Run testing and documentation generation in parallel, testing all subpkg for all packages
tip

Parallel execution can significantly shorten project development time, especially for large projects.

Using Specific Models​

You can configure different models for specific subagents:

[agent.model_config]
model = "gpt-4"  # Use GPT-4 instead of the default model