Custom agents

Create and deploy specialised AI agents for your workflows

Custom agents provide a way to customise Mind behaviour by defining specific configurations for different use cases. Each custom agent is defined by a configuration file that specifies which tools the agent can access, what permissions it has, and what context it should include.

Capability	IDE	CLI	Web
Project-level agents (`.mind/agents/`)	✓	✓	✓
Global agents (`~/.mind/agents/`)	✓	✓	—
Agent switching via UI	✓	✓	—
Modify agent settings	✓	✓	—

By default, Mind provides access to all available tools but requires user confirmation for most operations. This approach prioritizes security but can interrupt your workflow with frequent permission prompts.

Custom agents solve this by allowing you to:

Pre-approve specific tools — Define which tools can run without prompting
Limit tool access — Restrict which tools are available to reduce complexity
Include relevant context — Automatically load project files, documentation, or system information
Configure tool behaviour — Set specific parameters for how tools should operate

Benefits of using custom agents

Workflow optimization — Create custom agents tailored to specific tasks like cloud infrastructure management, code reviews, or debugging sessions.
Team collaboration — Share custom agent configurations with team members to ensure consistent development environments.
Security control — Limit tool access to only what's needed for specific workflows, reducing potential security risks.

Relationship to MCP and built-in tools

Custom agents work with both built-in tools and external tools from MCP servers. Use the tools field to specify exactly which tools from each source are available, and toolAliases to handle naming conflicts.

Configuration file formats

Agent configurations support two formats — JSON and Markdown. Both support identical fields. Use Markdown when your system prompt is long or benefits from human readability; JSON works well for programmatically generated configs.

.mind/agents/my-agent.json:

{
  "name": "my-agent",
  "description": "A custom agent for my workflow",
  "tools": ["read", "write", "shell"],
  "excludedTools": ["knowledge"],
  "includeMcpJson": true,
  "includePlugins": false,
  "resources": [
    "file://./ARCHITECTURE.md",
    "skill://backend-patterns"
  ],
  "permissions": {
    "rules": [
      { "capability": "shell", "match": ["npm *", "git *"], "effect": "allow" }
    ]
  },
  "prompt": "You are a helpful coding assistant",
  "model": "claude-sonnet-5",
  "welcomeMessage": "Ready to help. What are you working on?"
}

Storage locations

Workspace agents (project-specific): .mind/agents/[name].json or .mind/agents/[name].md — shared via version control, loaded only if the workspace is trusted
Global agents (user-wide): ~/.mind/agents/[name].json or ~/.mind/agents/[name].md — available across all projects

When both locations have agents with the same name, workspace agents take precedence. Nested directories are supported: ~/.mind/agents/team/planner.md becomes team/planner.

Surface behaviour

The IDE and CLI can select a custom agent as the primary session agent. Mind Web loads project-level custom agents committed to .mind/agents/ and can invoke them for sub-agent delegation.

To use personal custom agents in cloud sessions, upload them from Settings > Sync in Mind Web, then manage them under Settings > Agents.

Tip: Custom agents control what tools are available and what they can do. If you want to influence how the agent thinks and responds without changing tool access, use Steering files instead. You can combine both — a custom agent that includes steering via the resources field.