Agents

Configure and use specialized agents.

Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.

You can switch between agents during a session or invoke them with the @ mention.

Types

There are two types of agents in codeflow; primary agents and subagents.

Primary agents are the main assistants you interact with directly. You can cycle through them using the Tab key, or your configured switch_agent keybind. These agents handle your main conversation and can access all configured tools.

codeflow comes with two built-in primary agents, Build and Plan. We’ll look at these below.

Subagents

Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by @ mentioning them in your messages.

codeflow comes with one built-in subagent, General. We’ll look at this below.

Built-in

codeflow comes with two built-in primary agents and one built-in subagent.

Build

Mode: primary

Build is the default primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations and system commands.

Plan

Mode: primary

A restricted agent designed for planning and analysis. We use a permission system to give you more control and prevent unintended changes. By default, all of the following are set to ask:

file edits: All writes, patches, and edits
bash: All bash commands

This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.

General

Mode: subagent

A general-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when searching for keywords or files and you’re not confident you’ll find the right match in the first few tries.

Usage

For primary agents, use the Tab key to cycle through them during a session. You can also use your configured switch_agent keybind.
Subagents can be invoked:
- Automatically by primary agents for specialized tasks based on their descriptions.
- Manually by @ mentioning a subagent in your message. For example.
```
@general help me search for this function
```
Navigation between sessions: When subagents create their own child sessions, you can navigate between the parent session and all child sessions using:
- Ctrl+Right (or your configured session_child_cycle keybind) to cycle forward through parent → child1 → child2 → … → parent
- Ctrl+Left (or your configured session_child_cycle_reverse keybind) to cycle backward through parent ← child1 ← child2 ← … ← parent
This allows you to seamlessly switch between the main conversation and specialized subagent work.

Configure

You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways:

JSON

Configure agents in your codeflow.json config file:

{
  "$schema": "https://codeflow.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

You can also define agents using markdown files. Place them in:

Global: ~/.config/codeflow/agent/
Per-project: .codeflow/agent/

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

The markdown file name becomes the agent name. For example, review.md creates a review agent.

Options

Let’s look at these configuration options in detail.

Description

Use the description option to provide a brief description of what the agent does and when to use it.

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

This is a required config option.

Temperature

Control the randomness and creativity of the LLM’s responses with the temperature config.

Lower values make responses more focused and deterministic, while higher values increase creativity and variability.

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Temperature values typically range from 0.0 to 1.0:

0.0-0.2: Very focused and deterministic responses, ideal for code analysis and planning
0.3-0.5: Balanced responses with some creativity, good for general development tasks
0.6-1.0: More creative and varied responses, useful for brainstorming and exploration

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

If no temperature is specified, codeflow uses model-specific defaults; typically 0 for most models, 0.55 for Qwen models.

Disable

Set to true to disable the agent.

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Specify a custom system prompt file for this agent with the prompt config. The prompt file should contain instructions specific to the agent’s purpose.

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

This path is relative to where the config file is located. So this works for both the global codeflow config and the project specific config.

Model

Use the model config to override the default model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

Tools

Control which tools are available in this agent with the tools config. You can enable or disable specific tools by setting them to true or false.

{
  "agent": {
    "readonly": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}

You can also use wildcards to control multiple tools at once. For example, to disable all tools from an MCP server:

{
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

If no tools are specified, all tools are enabled by default.

Available tools

Here are all the tools can be controlled through the agent config.

Tool	Description
`bash`	Execute shell commands
`edit`	Modify existing files
`write`	Create new files
`read`	Read file contents
`grep`	Search file contents
`glob`	Find files by pattern
`list`	List directory contents
`patch`	Apply patches to files
`todowrite`	Manage todo lists
`todoread`	Read todo lists
`webfetch`	Fetch web content

Permissions

Permissions control what actions an agent can take.

edit, bash, webfetch

Each permission can be set to allow, ask, or deny.

allow, ask, deny

Configure permissions globally in codeflow.json.

{
  "$schema": "https://codeflow.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "allow",
    "webfetch": "deny"
  }
}

You can override permissions per agent in JSON.

{
  "$schema": "https://codeflow.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "edit": "allow",
        "bash": {
          "*": "allow",
          "git push": "ask",
          "terraform *": "deny"
        },
        "webfetch": "ask"
      }
    }
  }
}

You can also set permissions in Markdown agents.

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

Only analyze code and suggest changes.

Bash permissions support granular patterns for fine-grained control.

{
  "$schema": "https://codeflow.ai/config.json",
  "permission": {
    "bash": {
      "*": "allow",
      "git push": "ask",
      "terraform *": "deny"
    }
  }
}

If you provide a granular bash map, the default becomes ask unless you set * explicitly.

{
  "$schema": "https://codeflow.ai/config.json",
  "permission": {
    "bash": {
      "git status": "allow"
    }
  }
}

Agent-level permissions merge over global settings.

Global sets defaults; agent overrides when specified

Specific bash rules can override a global default.

{
  "$schema": "https://codeflow.ai/config.json",
  "permission": { "bash": "ask" },
  "agent": {
    "build": {
      "permission": {
        "bash": { "git status": "allow", "*": "ask" }
      }
    }
  }
}

Permissions affect tool availability and prompts differently.

deny hides tools (edit also hides write/patch); ask prompts; allow runs

For quick reference, here are common setups.

{
  "$schema": "https://codeflow.ai/config.json",
  "agent": {
    "review": {
      "permission": { "edit": "deny", "bash": "deny", "webfetch": "allow" }
    }
  }
}

{
  "$schema": "https://codeflow.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny", "webfetch": "ask" }
    }
  }
}

See the full permissions guide for more patterns.

/docs/permissions

Mode

Control the agent’s mode with the mode config. The mode option is used to determine how the agent can be used.

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

The mode option can be set to primary, subagent, or all. If no mode is specified, it defaults to all.

Additional

Any other options you specify in your agent configuration will be passed through directly to the provider as model options. This allows you to use provider-specific features and parameters.

For example, with OpenAI’s reasoning models, you can control the reasoning effort:

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

These additional options are model and provider-specific. Check your provider’s documentation for available parameters.

Create agents

You can create new agents using the following command:

codeflow agent create

This interactive command will:

Ask where to save the agent; global or project-specific.
Description of what the agent should do.
Generate an appropriate system prompt and identifier.
Let you select which tools the agent can access.
Finally, create a markdown file with the agent configuration.

Use cases

Here are some common use cases for different agents.

Build agent: Full development work with all tools enabled
Plan agent: Analysis and planning without making changes
Review agent: Code review with read-only access plus documentation tools
Debug agent: Focused on investigation with bash and read tools enabled
Docs agent: Documentation writing with file operations but no system commands

Examples

Here are some examples agents you might find useful.

Documentation agent

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Security auditor

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues