Custom agents

A custom agent is a work mode you wrote. It sits next to Agent, Plan, and Ask. It is not a permission mode, and it is not a skill.

Agent is the normal coding mode: it can read, edit, and run tools, subject to your permission mode. Plan writes a plan before it edits. Ask is read-only, so it will not save a new agent file. Always-Approve skips tool prompts. Auto-Review lets a classifier approve tools it treats as safe and still asks on the rest.

Create one from the chat

/new_agent

/new-agent is the same command. You can also paste the prompt on the same line:

/new_agent You are a reviewer. First line of every reply is REVIEW. Do not edit files.

The chat asks at most five things, and it skips any you already answered:

1. Use your words as the full prompt, or draft one from a short description.
2. Name.
3. One-line description.
4. Save for every project, or only this project.
5. What the agent must always do, and what it must not do.

Stay on Agent while it writes. Ask will not create the file. When the file exists, Shift+Tab until the banner says Switched to mode: <name>.

Create one from the form

/agents

Press n. The form asks for a name, a description, and the instructions. Space toggles user (every project) and project (this repo only). Enter saves. Esc cancels.

/agents lists only agents you created. Skills, plugin agents, and bundled agents are not in that list and not in the Shift+Tab ring.

Name rules

• Lowercase letters, numbers, and hyphens.
• Starts with a letter.
• At most 64 characters.
• Rejected: default, plan, ask, browser_use, and built-in agent names such as explore and plan.

Description is optional and capped at 200 characters. Empty becomes Custom agent. Instructions are required and capped at 8000 characters. Saving again under the same name in the same folder fails until you remove or rename the file.

The file

SUPERCHARGE_HOME moves the user folder. A project file shadows a user file with the same name.

The writer saves this shape. The custom: true line is what puts the agent on the menu. A hand-written file without that exact line in the frontmatter stays hidden.

---
name: reviewer
description: "Reviews diffs and does not edit"
custom: true
---

Comment on the diff. Do not edit files. Start every reply with REVIEW.

Switch to it

From Agent, Shift+Tab walks:

1. Plan
2. Ask
3. Each custom agent, in discovery order
4. Always-Approve
5. Auto-Review
6. Agent again

The banner is Switched to mode: Plan, Switched to mode: reviewer, Switched to mode: Always-Approve, or Switched to mode: Auto-Review. A file written during this session shows up on the next Shift+Tab. You do not need a new process.

Selecting a custom agent keeps the coding tool loop (the same prompt mode as Agent) and replaces the agent definition with that markdown. Always-Approve and Auto-Review clear the custom agent and return the work mode to Agent, then change only the permission mode. Ctrl+O still toggles Always-Approve on its own.

The displayed custom name is for this process. After you quit and resume, the session comes back as Agent, Plan, or Ask. Open Shift+Tab again to reselect the custom agent. The markdown file is still on disk.

Built-in Lean agent

Supercharge ships one built-in alternate agent besides Plan and Ask: Lean (Leancharge). It is a coding agent specialized for Lean 4 — the programming language and proof assistant where mathematics is written as code and every theorem is checked by the compiler. A proof either compiles or it does not, so "done" in Lean is machine-verified, not claimed.

The agent's system prompt is ported 1:1 from the upstream lean.md agent definition (kept verbatim so behavior matches the reference; see NOTICE-UPSTREAM.md in the CLI source for attribution). It replaces the normal system prompt entirely rather than layering on top of it.

What it is for

• Proof assistance and theorem proving — writing and repairing Lean 4 proofs with tactics such as grind (preferred on Lean >= 4.22.0).
• Lean codebase work — analyzing, editing, and building projects that use Lean 4 and the mathlib4 library.
• General coding tasks in the same oriented style, with Lean-specific guardrails (see below).

How it works

The agent runs a strict three-phase loop:

1. Orient — restates your goal in one line, classifies the task as investigate (read-only: explain, audit, review, diagnose) or change (edit code), and explores before touching anything. On complex tasks it proposes a plan and waits for your confirmation before reading files.
2. Plan (change tasks only) — lists the files to change and the specific change per file; multi-file changes become a numbered checklist.
3. Execute & verify (change tasks only) — edits one logical unit at a time and verifies each one by running tests or reading the file back. It never claims completion without verification.

Lean-specific rules it follows

• Creates projects with mathlib as a dependency via lake +leanprover-community/mathlib4:lean-toolchain new <name> math, or plain lake init otherwise.
• Runs lake exe cache get after adding dependencies and before building — never builds an uncached dependency tree.
• Checks correctness with lake build (whole repo) or lake build <file> (one file).
• Prefers the grind tactic on Lean 4.22.0+.
• Uses lean-lsp-mcp for interactive checking, but only after a successful lake build, and always re-reads files instead of trusting the LSP view.
• Avoids native_decide.

Hard rules

• Never stages, commits, or pushes proactively — saving files is the default; you commit.
• Respects constraints like "no writes", "just analyze", or "plan only" as hard stops.
• Changes only what was asked; does not rewrite or restructure unrelated code.
• Stops and changes strategy after two failed attempts on the same region instead of flip-flopping.
• Answers are structured first (code, ASCII trees, tables, file:line references) and brief — no filler.

Start it

At launch:

supercharge --lean

Or switch the current chat:

/lean

--lean applies to the whole process. Lean is not a custom agent file: /agents does not list it and it does not join the Shift+Tab ring. To go back to the standard agent, quit and start a new session without --lean.

Studio

Studio's chat menu sends the same fields to the CLI over ACP (supercharge/agents/create and supercharge/agents/list). The CLI writes the markdown. The next session/set_mode loads that file. Editing the file by hand and editing it in Studio are the same store.