Agent profiles

An agent profile is a saved setup for one agent: the tools and MCP servers it can use, its permission mode, its model and reasoning effort, and instructions of its own. What a profile sets is what the agent gets. What it leaves out comes from the agent that started it. Run fx in a profile, or ask fx to start a subagent in one.

This profile describes a reviewer that can read the workspace but can't edit files or run commands:

{
  "description": "Reviews changes without editing files",
  "tools": ["read_file", "glob_files", "grep_files"],
  "mcp_servers": [],
  "effort": "high"
}

Save it as ~/.fx/agents/reviewer/profile.json, then ask fx:

Have a subagent in the reviewer profile review the parser change.

Where profiles live

Each profile is a folder named after the profile. It holds profile.json and, if you want one, prompt.md.

Folder	Available in
`~/.fx/agents/<name>/`	Every workspace
`.fx/agents/<name>/` in a repository	That repository

fx looks up a name in ~/.fx/agents first, then in the repository's .fx/agents, then among its built-in profiles. A profile in your home folder takes precedence over a repository profile with the same name.

A repository's profile decides an agent's tools, MCP servers, and prompt the same way yours do. It can give an agent tools its parent doesn't have, and with "prompt": "replace" it replaces fx's system prompt, including under a built-in name such as agent. Read the .fx/agents folder of a repository you clone before you let fx start subagents there, or keep a profile with the same name in ~/.fx/agents, which fx uses instead.

A repository's profile files must stay inside the repository. fx refuses a profile.json or prompt.md that links to a file outside it, and any profile file that isn't a regular file, such as a link to a terminal, and says which file and why. Your own profiles in ~/.fx/agents can link anywhere, such as into a dotfiles folder.

Profile names use lowercase letters, digits, -, and _, and are at most 64 characters long.

profile.json

Key	Value	If you leave it out
`description`	What the profile is for. fx shows it to the main agent when it chooses a profile for a subagent.	The profile doesn't load.
`tools`	The tools the agent can use	The tools of the agent that started it
`mcp_servers`	The MCP servers the agent can use	The servers of the agent that started it
`permission_mode`	`ask`, `auto`, or `full-access`	The parent's mode
`model`	A model ID	The model fx would use otherwise
`effort`	A reasoning effort	The effort fx would use otherwise
`prompt`	`append` or `replace`; see Instructions	`append`

In tools and mcp_servers, "*" stands for every tool or server fx has, and "!name" removes one. ["*", "!shell"] allows every tool except shell, and [] allows none.

fx ignores keys it doesn't know. A value it can't use, such as an unknown effort, stops the profile from loading.

Instructions

Write the agent's instructions in prompt.md, next to profile.json. With "prompt": "append", fx adds them after its own system prompt. With "prompt": "replace", they take its place.

Permission mode

An agent in a profile that sets permission_mode runs in that mode. A profile without one leaves the agent in its parent's mode: the mode you configured for fx --profile, or the mode of the agent that started a subagent.

A repository's profile can't set permission_mode. fx ignores the key there, so a repository you clone can't change how its agents' tool calls are approved. To give a profile a mode, keep it in ~/.fx/agents.

See Permissions.

Use a profile

Run the whole session in a profile:

$fx --profile reviewer

If no profile has that name, fx stops and lists the ones it found:

fx: no profile named 'reviwer'. Profiles: agent, main, reviewer

To run another fx instance in a profile next to your current one, use /launch reviewer.

Resuming a session brings back the profile it ran in, so fx --resume <session-id> on a session started with fx --profile reviewer runs in reviewer again.

A model you choose with --model or FX_MODEL, or an effort you choose with --effort, overrides the profile's, both for fx --profile and for instances you launch.

Subagents in a profile

fx gives the main agent the name and description of every profile. The main agent names one when a task needs it, and otherwise starts the subagent without a profile. Profiles from the repository are marked as the repository's. To choose one yourself, name it in your prompt.

A model or reasoning effort you ask for when you start the subagent overrides the profile's.

A subagent keeps the profile it started in. fx reads the profile the first time the subagent runs during a session, so an edit applies to subagents that start after it, and to existing ones the next time you start fx.

A profile decides the tools and MCP servers it lists, even ones the agent that started the subagent doesn't have. A subagent without a profile, or in fx's agent profile, is a copy of the agent that started it.

If a subagent's profile can't be loaded, the subagent can't use any tools.

To stop a subagent from starting subagents of its own, leave subagent out of its tools, for example with ["*", "!subagent"].

Built-in profiles

Name	Description
`main`	fx itself, with every tool. fx uses it when you don't pass `--profile`.
`agent`	A copy of the agent that starts it.

Neither sets anything, so an agent in either is a copy of the one that started it. A profile of yours with the same name replaces the built-in one wherever that name is used. A subagent started without a profile doesn't use agent, so your own agent profile doesn't change it.