Major Features / Custom Agents

Custom Agents

Custom agents let you choose the role Heddle should use for a specific turn: ask a question, write code, review changes, or run a project-defined specialist.

What a custom agent is

A custom agent is a named runtime profile. It does not replace Heddle's default system prompt; it appends role-specific instructions and carries tool, approval, and runtime settings for the accepted turn.

Heddle's quick modes are built on the same foundation: Ask is a read-only inspection agent, Code is the default coding agent, and Review is a read-only reviewer. Users can switch between them inside one saved session because agent choice is turn-scoped, not session-scoped.

This gives teams a practical way to encode roles such as Repo Reviewer, Docs Writer, Release Operator, or Incident Investigator without creating a separate product surface for every workflow.

What the profile controls

Prompt appendix

Extra instructions appended after Heddle's normal system instructions.

Tool profile

Which tools the model can see for the turn, such as normal coding tools or read-only inspection tools.

Approval profile

Whether the turn asks interactively, stays read-only, or uses trusted auto-approval behavior.

Runtime defaults

Optional defaults such as maxSteps, model, or reasoning effort.

Built-in modes

Ask

Inspect the workspace and answer without making changes.

Code

Use the normal Heddle coding profile for implementation work.

Review

Review code and diffs without applying fixes.

Where definitions live

Custom agent definitions are markdown files with YAML frontmatter. Project agents are shared with the repository; user agents live in your home directory.

.agents/agents/<agent-id>/AGENT.md     # Project agents
~/.agents/agents/<agent-id>/AGENT.md   # User agents

Create an agent

Create a project definition at .agents/agents/repo-reviewer/AGENT.md:

---
schemaVersion: 1
id: repo-reviewer
name: Repo Reviewer
description: Review repository changes without applying fixes.
modeAlias: review
runtime:
  maxSteps: 80
tools:
  preset: inspect
approval:
  preset: read_only
---

You are a repository review agent.

Prioritize correctness, reliability, missing tests, and maintainability.
Lead with actionable findings grounded in file paths, diffs, command output, or trace evidence.
Do not edit files or run mutation commands.

Use an agent

In the browser control plane, open Settings -> Agents to create or inspect project agents.

In chat, open the composer plus menu and choose Upload image, Permission mode, Agent, or Semantic drift. Under Agent, pick Ask, Code, Review, or a custom agent for the next prompt.

For one-shot terminal usage, pass --agent <id> or --mode ask|code|review to heddle ask.

CLI examples

heddle ask --agent repo-reviewer "Review the current workspace changes"
heddle ask --mode ask "Explain this repository"
heddle ask --mode review "Review the current diff"

Safety model

Custom agents do not bypass Heddle policy. Tool visibility is filtered by the runtime tool profile, and sensitive actions still go through the approval profile and Heddle approval enforcement. A read-only agent should use an inspection tool profile and read-only approval profile; a coding agent can use normal tools with interactive or trusted auto approval.

Custom agents versus Agent Skills

Agent Skills are reusable instructions and resources the agent can load when relevant. Custom agents choose the role for the turn. A custom agent can still use active skills when its tool profile includes read_agent_skill.