Profiles

Agent profiles: named presets combining a system prompt, a tool allowlist, and behavior rules. See Agent Profiles for the built-in profiles and custom profile files.

Agent profiles for pre-configured system prompts and tool access.

Profiles combine:

• System prompt customization (behavioral guidance)

• Tool access restrictions (hard-enforced when used via subagent tool)

• Behavior rules (read-only, no-network, etc.)

Tool restrictions are hard-enforced in subagent thread mode: only allowed tools are loaded into the execution context, so the LLM cannot call restricted tools even if it tries. CLI mode (–agent-profile) also hard-enforces via the tool allowlist. Behavior rules (read_only, no_network) remain soft/prompting-based.

This enables creating specialized agents like “explorer” (read-only), “researcher” (web access), or “developer” (full capabilities).

User profiles can be defined in ~/.config/gptme/profiles/ as either:

• TOML files (.toml): Traditional key-value format

• Markdown files (.md): YAML frontmatter for metadata, body as system_prompt

class gptme.profiles.Profile

Agent profile combining system prompt, tools, and behavior rules.

name

Unique profile identifier

description

Human-readable description

system_prompt

Additional system prompt text (appended to base)

tools

List of allowed tools (None = all tools, empty = no tools)

behavior

Behavior rules for the profile

__init__(name: str, description: str, system_prompt: str = '', tools: list[str] | None = None, behavior: ~gptme.profiles.ProfileBehavior = <factory>) → None

classmethod from_dict(data: dict) → Profile

Create a Profile from a dictionary (e.g., TOML config).

Note: This method does not mutate the input dictionary.

validate_tools(available_tool_names: set[str]) → list[str]

Validate that profile tool names exist in the available tools.

Returns list of unknown tool names (empty if all valid).

class gptme.profiles.ProfileBehavior

Behavior rules for a profile.

__init__(confirm_writes: bool = False, read_only: bool = False, no_network: bool = False) → None

gptme.profiles.get_profile(name: str) → Profile | None

Get a profile by name.

Checks user profiles first, then falls back to built-in profiles.

gptme.profiles.get_user_profiles_dir() → Path

Get the directory for user-defined profiles.

gptme.profiles.list_profiles() → dict[str, Profile]

List all available profiles (built-in and user-defined).

User profiles override built-in profiles with the same name.

gptme.profiles.load_user_profiles() → dict[str, Profile]

Load user-defined profiles from config directory.

Profiles are stored as TOML (.toml) or Markdown (.md) files in ~/.config/gptme/profiles/. Markdown files override TOML files with the same profile name.