An agent is a focused operator with its own instructions, model, and set of allowed tools. Every task in 100xprompt runs on one. Some agents build and edit your code, others plan without touching a file, and any agent can spin up subagents to fan work out in parallel. When the built-ins don’t fit, you define your own. This page covers:

​
The mental model

You always talk to one primary agent - the one driving your session. That agent delegates self-contained chunks of work to subagents, each running in its own isolated context. Your main conversation stays clean. Subagents report back a concise result; you keep the big picture.
A primary agent is one you steer directly in a session. A subagent is one the primary agent (or you, with an @-mention) hands a task to. The same agent can sometimes act as both - it depends on how it’s configured.

​
Built-in agents

100xprompt ships with five ready-to-use agents. Two are primary agents you drive directly; three are subagents built for delegation.
AgentTypeBest forCan edit files
BuildPrimaryMaking changes - writing code, editing files, running commands, and shipping real work.Yes
PlanPrimaryRead-only planning and design. Investigates your codebase and drafts a plan without modifying your source.No (plan notes only)
GeneralSubagentOpen-ended research and multi-step tasks you want run in parallel, off your main context.Yes
ExploreSubagentFast codebase exploration - finding files by pattern, searching for keywords, and answering “how does X work?” questions.No (read-only)
VerifierSubagentAdversarial verification. After non-trivial work, it re-runs builds, tests, and linters to confirm the change is actually correct before you report done.No (runs checks)
Reach for Plan when you want to think before you touch anything - it can read, search, and reason across your whole project but won’t change your files. When you’re ready to execute, switch to Build.

​
Choosing between Build and Plan

Build

Full read-and-write power. Use it when you know what you want and you’re ready to make it happen - refactors, features, fixes, and command runs.

Plan

Look-but-don’t-touch. Use it to scope large or risky work, produce a plan you can review, then hand that plan to Build.

​
Switch agents

Suppose you scoped a change in Plan and now want to execute it. Change which agent drives your session at any time.
  • Press Tab to cycle to the next agent, or Shift+Tab to go back.
  • Press your agent-list shortcut (default Ctrl+X then a) to open the full picker.
  • Type @ in the prompt to mention a subagent and hand it a task inline.
Switching the primary agent changes what the session is allowed to do - for example, moving to Plan locks writes for the rest of that turn until you switch back.

​
Fan work out with subagents

Suppose you need to modernize a module and it means exploring old code, researching a new API, and auditing tests all at once. Exploring a large codebase fills your context with file reads. Delegate it so only the findings come back. The primary agent launches subagents that each work independently and report back. Your main context stays lean, and several threads of work move at once.
Subagents are especially useful when you want to:
  • Search broadly across many files without flooding your main conversation.
  • Run independent tasks at once - research, exploration, and self-contained implementation in parallel.
  • Isolate risky work so a subagent’s edits never touch your working tree until you’re ready.
Long-running work can be sent to the background so you keep going. You’ll get a handle to check its status and read the result when it finishes - no need to sit and wait.
A subagent can run in an isolated git worktree, so its file changes stay separate from your main working tree until you choose to bring them in. If it makes no changes, the isolated workspace is cleaned up automatically.
Each subagent starts fresh with no memory of your conversation. The more context it gets - what you’re trying to do, what’s already ruled out, and exactly what to report back - the better its result.

​
Create your own agent

Suppose your team wants a reviewer that only reads, a migration bot with a tight tool set, or a docs writer that always uses one model. A custom agent bottles up that specialist. You author it in a Markdown file: YAML fields on top describe the agent, and everything below the frontmatter becomes its instructions.
1

Create an agent file

Add a Markdown file under an agent/ folder - .100xprompt/agent/ in your project for a repo-scoped agent, or the agent/ folder in your global 100xprompt config to make it available everywhere. The filename becomes the agent’s name, so agent/reviewer.md defines an agent called reviewer.
2

Describe it in the frontmatter

Fill in the fields that tell 100xprompt when and how to use the agent - its description, mode, model, and which tools it’s allowed to touch.
3

Write its instructions

Everything below the frontmatter is the agent’s system prompt: its role, priorities, and rules of engagement.
4

Use it

Your new agent shows up in the agent picker (for primary agents) or as an @-mentionable subagent. It’s also available to the built-in agents when they decide to delegate.

​
Example agent file

---
description: Reviews code for correctness and style. Read-only.
mode: subagent
model: 100xprompt/pro
temperature: 0.2
color: "#0ea5e9"
permission:
  edit: deny
  bash: deny
  read: allow
  grep: allow
  glob: allow
---

You are a meticulous code reviewer.

Focus on correctness, edge cases, and readability. Point out bugs and risky
patterns with specific line references. Never modify files - your job is to
review and report, not to change anything.

​
Fields you can set

FieldWhat it does
descriptionWhen to use this agent. This is what other agents read to decide whether to delegate to it.
modeprimary (drive it in a session), subagent (only delegated to / @-mentioned), or all (both).
modelWhich model powers the agent, as provider/model. Omit to inherit the session’s model.
temperature / top_pSampling controls for how focused or exploratory its responses are.
permissionFine-grained allow/ask/deny rules for what tools the agent may use (edits, shell, reads, and more).
colorA hex accent color for the agent in the interface.
hiddenKeep a subagent out of the @ autocomplete menu.
stepsCap how many work iterations the agent runs before it must respond.
Give each custom agent the narrowest tool set it needs. A review agent with edits and shell denied simply can’t change your code - the guardrail is built in, not just requested politely.
Prefer a single config file? You can also define agents under an agent section of your 100xprompt.json using the same fields.
The description is doing real work: when a primary agent decides whether to delegate to your subagent, it’s reading that description. Make it specific - say exactly when the agent should and shouldn’t be used.

​
Manage agents from the CLI

Prefer to scaffold and manage agent files from the terminal? The 100xprompt agent command handles the whole lifecycle.
CommandWhat it does
100xprompt agent createScaffold a new agent file. Prompts for a description, mode, and tool set, then drafts the frontmatter and starter instructions for you.
100xprompt agent listList every available agent - built-ins and your custom ones - with each agent’s mode and permissions.
100xprompt agent edit <name>Open a custom agent’s file in your $EDITOR.
100xprompt agent delete <name>Remove a custom agent. Built-in agents can’t be deleted.
100xprompt agent create also runs non-interactively - pass --description, --mode, --tools, and --model to generate an agent in one shot, handy for scripting or a team setup step.
  • Skills: package reusable know-how your agents pull in on demand.
  • Background Tasks: run subagents and long jobs while you keep working.
  • Models: give each agent its own model.

Skills

Package reusable know-how your agents can pull in on demand.

Background Tasks

Run subagents and long jobs in the background while you keep working.

Models

Pick the right model to power each agent.