Custom Modes

In the IDE and CLI, custom behavioral profiles are called agents instead of modes. Agents are defined as Markdown files with YAML frontmatter or as entries in the agent key of your config file.

What's Included in a Custom Agent?

Methods for Creating and Configuring Agents

1. Ask CFactory! (Recommended)

Ask CFactory to create an agent for you:

Create a new agent called "docs-writer" that can only read files and edit Markdown files.

CFactory will generate the agent definition and write it to .cfactory/agent/ in your project.

2. Using the Settings UI

You can manage agents through the Settings → Agent Behaviour → Agents subtab in the extension. This lets you view, create, and edit agent configurations — including the agent's prompt, model, permissions, and other properties.

3. Markdown Files with YAML Frontmatter

Create .md files in any of these directories:

.cfactory/agents/my-agent.md
.cfactory/agent/my-agent.md
.cfactory/agents/my-agent.md

For global agents, place files in your global config directory:

~/.config/cfactory/agent/my-agent.md

The filename (minus .md) becomes the agent name. Nested directories create namespaced names (e.g., agents/backend/sql.md becomes agent backend/sql).

Example agent file (.cfactory/agents/docs-writer.md):

---
description: Specialized for writing and editing technical documentation
mode: primary
color: "#10B981"
permission:
  edit:
    "*.md": "allow"
    "*": "deny"
  bash: deny
---

You are a technical documentation specialist. Your expertise includes:

- Writing clear, well-structured documentation
- Following markdown best practices
- Creating helpful code examples

Focus on clarity and completeness. Only edit Markdown files.

4. Config File (cfactory.jsonc)

Define agents under the agent key in your project's cfactory.jsonc:

{
  "agent": {
    "docs-writer": {
      "description": "Specialized for writing and editing technical documentation",
      "mode": "primary",
      "color": "#10B981",
      "prompt": "You are a technical documentation specialist...",
      "permission": {
        "edit": {
          "*.md": "allow",
          "*": "deny",
        },
        "bash": "deny",
      },
    },
    // Override a built-in agent
    "code": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
    },
  },
}

Agent Property Reference

mode

Controls where the agent appears:

permission

An ordered set of rules controlling tool access. Permissions support three actions: allow, deny, and ask (prompt the user). You can use glob patterns to scope rules to specific files or commands:

permission:
  edit:
    "*.md": "allow"
    "*": "deny"
  bash: deny
  read: allow

Known permission types include: read, edit, bash, glob, grep, task, webfetch, websearch, codesearch, todowrite, todoread, and more.

model

Pin a specific model using the provider/model format:

model: anthropic/claude-sonnet-4-20250514

The model selector also remembers the last model you picked for each agent across sessions. A config-pinned model acts as the default when no manual pick exists. To reset a pick and let the config take over, use the reset button in the model selector (visible when your active model differs from what the config specifies).

steps

Limits the number of agentic iterations (tool call rounds) before the agent is forced to respond with text only. Useful for preventing runaway agents:

steps: 25

Configuration Precedence

Agent configurations merge from lowest to highest priority:

1. Built-in (native) agent defaults
2. Global config (~/.config/cfactory/cfactory.jsonc)
3. Project config (cfactory.jsonc at project root)
4. .cfactory/ / .cfactory/ directory configs and agent .md files
5. Environment variable overrides (CFACTORY_CONFIG_CONTENT)

When the same agent name appears at multiple levels, properties are merged (not replaced wholesale), so you can override just a model or temperature without redefining the entire agent.

Overriding Built-in Agents

Override any built-in agent (code, plan, debug, ask, explore, general) by defining an agent with the same name:

// cfactory.jsonc — override the built-in "code" agent
{
  "agent": {
    "code": {
      "model": "openai/gpt-4o",
      "temperature": 0.2,
      "permission": {
        "edit": {
          "*.py": "allow",
          "*": "deny",
        },
      },
    },
  },
}

Or as a .md file (.cfactory/agents/code.md):

---
model: openai/gpt-4o
temperature: 0.2
permission:
  edit:
    "*.py": "allow"
    "*": "deny"
---

You are a Python specialist. Only edit Python files.

Migration from Legacy IDE Modes

If you have existing .cfactorymodes or custom_modes.yaml files from the IDE, the IDE automatically migrates them on startup. The migration converts:

• slug to the agent name (key)
• roleDefinition + customInstructions to prompt
• groups (e.g., ["read", "edit", "browser"]) to permission rules
• whenToUse / description to description
• Mode is set to primary

Default legacy mode slugs (code, build, architect, ask, debug, orchestrator) are skipped during migration since they map to built-in agents (build → code, architect → plan).

Legacy File Locations

The current IDE reads the legacy custom_modes.yaml file from its own global storage directory. Helpful for inspecting or fixing the file before the one-time migration runs:

Project-level .cfactorymodes and workspace-scoped files are handled by the CLI backend that the extension delegates to — see the CLI tab for the full load-order table. After the extension migrates on startup, the legacy file is no longer consulted; remove new modes through the extension UI instead of editing custom_modes.yaml directly.

The extension uses permission rules with glob patterns instead of regex. Permissions are defined per-tool (e.g., edit, bash, read) and support allow, deny, and ask actions with glob matching:

permission:
  edit:
    "*.md": "allow"
    "*": "deny"

The Legacy fileRegex rules from older CFactory setups are automatically converted to permission rules during migration.

Common Issues

• Agent not appearing: Ensure the .md file is in a recognized directory (.cfactory/agents/, .cfactory/agent/, .cfactory/agents/). Check that the mode property is primary or all if you expect it in the agent picker.
• Permission errors: Permission rules are evaluated last-match-wins. If an agent can't use a tool you expect, check that an allow rule appears after any deny rules for that permission.
• YAML frontmatter parse errors: Ensure the frontmatter block starts and ends with --- on its own line. Validate that YAML keys match expected property names (e.g., top_p not topP).
• Agent overrides not working: Config merges from global to project level. If a global config sets a property, your project config can override it, but both must use the same agent name.

Tips for Agent Definitions

• Keep prompts focused: The markdown body is your system prompt — write it as if briefing a colleague
• Use mode: subagent for helper agents that shouldn't be directly selectable by users
• Use the Settings UI to view and edit agents through the Settings → Agent Behaviour → Agents subtab
• Legacy modes are auto-migrated: If you have .cfactorymodes files, they'll be converted on startup — no manual migration needed