Agent Profiles

Agent Profiles#

A profile is a named preset for an agent. It combines:

  • a system prompt addition that sets the agent’s role and focus,

  • a tool allowlist that limits which tools are loaded, and

  • behavior rules such as read-only or no network access.

Use a profile to run a restricted session, or to give a subagent a clear role.

Using a profile#

Start a session with a profile, and list or inspect the available profiles:

gptme --agent-profile explorer "summarize how authentication works in this repo"

gptme-util profile list
gptme-util profile show explorer

Subagents take a profile too:

subagent("reviewer", "Review the PR diff for correctness issues", profile="verifier")

Tool restrictions are hard-enforced in the CLI (--agent-profile) and for subagents in thread mode: only the allowed tools are loaded, so the model can’t call the others. Behavior rules such as read_only and no_network are soft — they’re expressed in the system prompt, not enforced at the tool level.

Built-in profiles#

Profile

Tools

Behavior

Use case

default

All

The standard gptme experience

developer

All

Full development capabilities

explorer

read, chats

Read-only, no network

Read-only exploration of a codebase

researcher

browser, read, screenshot, chats

Read-only

Web research without modifying local files

verifier

read, ipython, shell, chats

Read-only, no network

Review, test, and verify work done by other agents

isolated

read, ipython

Read-only, no network

Processing potentially untrusted content

computer-use

computer, browser, vision, ipython, shell

UI automation: structured browser interaction for web, screenshots for native apps

browser-use

browser, screenshot, vision, ipython, shell

Web browsing and testing

Run gptme-util profile show <name> to see a profile’s full system prompt.

Profiles for subagents#

A subagent’s profile is resolved in this order:

  1. An explicit profile= argument (highest priority).

  2. The profile for a role= argument, e.g. role="verify" → verifier.

  3. Auto-detection from the agent_id, when it matches a profile name or alias (e.g. "verify" → verifier).

  4. No profile: the subagent keeps the default tools.

So naming a subagent after a profile is enough to apply it:

# Desktop interaction (mouse, keyboard, screenshots)
subagent("computer-use", "Click the Submit button and screenshot the result")

# Typed delegation: verifier profile, run in a subprocess with a throwaway worktree
subagent("my-reviewer", "Check that the refactor passes all tests", role="verify")

role="verify" also sets use_subprocess=True and isolated=True by default, so the verifier can’t accidentally modify the parent workspace; explicit use_subprocess and isolated arguments override these defaults. The verifier’s read_only rule remains a soft, prompt-level rule.

Custom profiles#

Define your own profiles in ~/.config/gptme/profiles/ as Markdown or TOML files. If both define the same name, the Markdown file wins.

In a Markdown profile, YAML front matter holds the metadata and the body becomes the system prompt:

---
name: reviewer
description: Careful code reviewer
tools:
  - read
  - shell
behavior:
  read_only: true
---

You are a careful code reviewer. Focus on correctness and test coverage.

A TOML profile uses the same fields, with system_prompt as a key:

name = "reviewer"
description = "Careful code reviewer"
system_prompt = "You are a careful code reviewer. Focus on correctness and test coverage."
tools = ["read", "shell"]

[behavior]
read_only = true

name and description are required. Omit tools to allow all tools; an empty list allows none.

Contents