Agents

Agents are Markdown files that provide system instructions for Claude Code. AgentFlow manages agents alongside pipelines, keeping everything in the native Claude Code format.

File Format

Agents are stored as plain Markdown files at .claude/agents/{name}.md in your project. There is no required frontmatter or structure — any valid Markdown works.

.claude/agents/code-reviewer.md

markdown

# Code Reviewer

You are a senior code reviewer. Review all changed files for:

- Security vulnerabilities (OWASP Top 10)
- Performance issues and N+1 queries
- Missing error handling
- Code style violations

## Output Format

Provide a summary of findings as a numbered list, grouped by severity:
1. **Critical** - Must fix before merge
2. **Warning** - Should fix, but not blocking
3. **Info** - Suggestions for improvement

Always explain *why* something is an issue, not just *what* is wrong.

Info

Agent files are directly compatible with Claude Code CLI. Running claude --agent code-reviewer --print "your prompt" from the terminal uses the exact same file.

Naming Conventions

Pattern	Origin	Description
`{name}.md`	`manual`	User-created agents with any alphanumeric name
`_pipeline--{name}.md`	`pipeline`	Auto-generated from pipeline. Prefix stripped in UI.

Names are sanitized for the filesystem: lowercased, spaces converted to hyphens, special characters removed.

Agent Data Structure

Property	Type	Description
`name`	`string`	Filename without .md extension.
`display_name`	`string`	Name with "_pipeline--" prefix stripped.
`path`	`string`	Absolute filesystem path to the .md file.
`description`	`string`	Auto-extracted from the first non-empty, non-heading line. Truncated to ~120 chars.
`origin`	`"manual" \| "pipeline"`	Whether created by user or auto-generated from a pipeline.

Description Extraction

When listing agents, AgentFlow automatically extracts a short description from the Markdown content:

Scans lines from top to bottom
Skips empty lines and lines starting with # (headings)
Takes the first non-empty, non-heading line as the description
Truncates to ~120 characters with "..." suffix if longer

Agent Management

Auto-Discovery

When a project is loaded, AgentFlow scans .claude/agents/ for all .md files and populates the agent library. The file watcher monitors this directory for changes.

Agent Library

The agent library panel provides:

Searchable, filterable list of all agents
Filter by origin (manual vs pipeline-generated)
Quick preview of agent description
Click to open in the Markdown editor

Markdown Editor

The built-in editor provides:

Full Markdown editing with syntax highlighting
Live preview panel (rendered via the Marked library)
Auto-save on changes
Create new agents with a name and initial content
Delete agents with confirmation

IPC Commands

list_agents(projectPath)→ AgentInfo[]

List all agents in the project.

read_agent(path)→ { name, path, content }

Read full agent content.

write_agent(path, content)→ void

Update agent content.

create_agent(projectPath, name, content)→ string (path)

Create a new agent file.

delete_agent(path)→ void

Delete an agent file.

Using Agents in Pipelines

Reference an agent in an AI Task node by setting the agent field to the agent's name (without .md):

{
  "id": "node-1",
  "type": "ai-task",
  "name": "Security Review",
  "agent": "code-reviewer",
  "instructions": "Review the latest changes for security issues",
  ...
}

At execution time, this translates to:

claude --agent code-reviewer --print "Review the latest changes for security issues"

CLI compatibility

Because agents are standard Claude Code Markdown files, teammates who prefer the CLI can use them directly without AgentFlow: claude --agent code-reviewer.

Node Types

Execution & Runs