Factory native reference
Start with the Factory setup. For home configuration and ownership, see global configuration.
Agents
<name>.md has name, description, and optional model and tools. x-factory keys pass through.
- Empty body: skipped with a sync note (Droid CLI needs a system prompt).
- A portable
mcpServerslist is written as is.mcpServers: []excludes every MCP server, even global ones (mcpServers). - A read-only droid with no
mcpServerslist getsmcpServers: []. A list you set is kept. effortbecomesreasoningEffort:low,medium,highonly.xhigh,max, and integer budgets drop with a sync note. Ignored undermodel: inherit(effort).readonly: truewritestools: read-only, replacing a portabletoolslist. Sync notesx-factory.toolsfor a custom list.x-factory.toolswins overreadonly.readonly: falsedoes nothing.
Tools
The generic tools list maps to Droid CLI IDs: Read, LS, Grep, Glob, Create, Edit, ApplyPatch, Execute, WebSearch, FetchUrl. One unknown ID makes Factory reject the droid.
| Generic name | Result |
|---|---|
Bash | Execute |
Write | Create |
WebFetch | FetchUrl |
TodoWrite, Skill | Dropped silently (every droid has them) |
ExitSpecMode, GenerateDroid | Dropped (custom droids cannot enable them) |
| Anything else | Dropped with a sync note; the rest are written |
- Other names already match.
tools: allis never written. An omitted key allows every tool.x-factory.toolswrites Factory's own names and wins. Only it can set a category (read-only,edit,execute,web,mcp) or an MCP tool ID (tools).
Skills
Written once to the tree that codex, amp, zed, and crush share.
- Factory also reads
.agent/skills/**/SKILL.md. This adapter does not write it. - Scoped skills:
<scope>/.factory/skills/<name>/SKILL.md, with bundled files. - Unscoped skills:
.agents/skills/. outputs.factory.skills-dirreplaces the directory at the root and in each scope.
Commands
.factory/commands/<name>.md takes description and argument-hint. $ARGUMENTS is kept. Factory prefers skills for new workflows but still loads commands.
Hooks
.factory/hooks.json is the committed project file (hooks docs). sync replaces its own entries and keeps the rest. With builtins: [memory], a SessionStart hook adds the shared memory index.
- Events:
PreToolUse,PostToolUse,UserPromptSubmit,Notification,Stop,SubagentStop,PreCompact,SessionStart,SessionEnd. - Keyed by event,
{"<Event>": [{matcher, hooks: [...]}]}, with nohookswrapper (unlike Claude Code, Codex, Gemini, and Qoder). - Each entry:
type(always"command"),command, optionaltimeoutin seconds (default 60). failClosed: truewrites"onFailure": "block". A hook that fails, times out, or exits other than 0 or 2 then blocks the event.- Factory honors
onFailureonPreToolUse,PostToolUse,UserPromptSubmit, andPreCompact. Sync notes other events. - Another
onFailurevalue goes inx-factory.onFailure. x-factory.preserveRiskLevel: truekeeps the model'sriskLevelwhen aPreToolUsehook rewrites anExecutecommand. Sync notes it on other events.x-factory.commandRegexsets the group-levelcommandRegex. Different regexes never share a group.import factoryfills it.- Exact-name tool matchers accept Claude aliases:
BashselectsExecute,WriteselectsCreate, andWebFetchselectsFetchUrl. Sync keeps the matcher as written. - Regular expressions match Droid tool names only, and hook input reports those names. A script checking
tool_namemust handleExecute,Create, orFetchUrleven under a Claude alias. See Factory matchers.
MCP
.factory/mcp.json under mcpServers, the Claude Code and Cursor shape. Stdio: command, args, env, no type. Remote: type, url, headers.
syncrewrites the file whole. Factory's MCP docs say to edit it to remove servers, but sync undoes that. Remove the spec.disabled: truebecomes the per-server boolean (disabled).- Both transports keep
disabledTools,timeout, andconnectTimeout(milliseconds), zeros included. - Remote HTTP and SSE also take
oauth: falseor an OAuth object:scopes,resource,authorizationServerIssuer,clientId,clientSecret,clientMetadataUrl,tokenEndpointAuthMethod,callbackPort. x-factory.enabledToolsloads only the named tools. An empty list adds no restriction.disabledToolsexcludes named tools, even one also inenabledTools.- Sync keeps both lists as written, including
[]and overlaps (tool filtering). x-factoryoverrides each top-level option.type: wswrites no server and raises a sync note. Factory supports only stdio, HTTP, and SSE.
Settings
A portable model merges into <git-root>/.factory/settings.json, the project level of Factory's hierarchical settings.
effortmerges as top-levelreasoningEffort(CLI settings):none,dynamic,off,minimal,low,medium,high,xhigh,max. Each model accepts a subset. Other values raise a sync note.- The managed
sessionDefaultSettings.reasoningEffortis not written. - Sync sets only
model,reasoningEffort, the command lists, andx-factorykeys. Others (such asdisabledSkills) stay. x-factorysets keys with no portable field, mainlysandbox(OS-enforced file and process limits).x-factorycommand-list entries add to translated ones:x-factory.commandBlocklist: ["author-only"]besidedeny: ["Bash(rm:*)"]writes both.Bash(npm:*)becomes"npm *".Bash(curl)becomes"curl".
| Portable | Factory key | Effect |
|---|---|---|
allow | commandAllowlist | Runs without approval |
ask | commandDenylist | Always asks; you can approve |
deny | commandBlocklist | Never runs |
- Factory's denylist only prompts, so
denymaps to the blocklist. - Precedence: blocklist, then denylist, then allowlist.
- Rules scoping a path, URL, or MCP tool (such as
Read(src/**)) have no shell form and raise a sync note. - A list is written only when a rule feeds it. A hand-kept list stays unless a rule feeds that key, then sync replaces it.
- Factory deprecates the three lists for
permissionRulesbut still reads them (safety controls). - A permission rule needs a stable
id, amatch.prefixtoken list, andtests.matchandtests.noMatchexamples. Portable lists lack these. Put them underx-factory.permissionRules, copied as written.
Handoff from a linked worktree
With handoff or handoff-hook on, sync adds the main checkout's handoff store to sandbox.filesystem.allowWrite in .factory/settings.local.json. Factory's sandbox then lets handoff saves and the automatic snapshot reach it.
- The file stays out of Git. Sync never turns the sandbox on.
- See Write from a linked worktree.
Config keys
| Key | Default |
|---|---|
outputs.factory.agents-dir | .factory/droids |
outputs.factory.skills-dir | .agents/skills |
outputs.factory.commands-dir | .factory/commands |
outputs.factory.hooks-file | .factory/hooks.json |
outputs.factory.mcp-file | .factory/mcp.json |
outputs.factory.conf-file | .factory/settings.json |
Import
agnostic-ai import factory reads these back:
| Source | Becomes |
|---|---|
AGENTS.md ## Rules block (### <name> children) | <rules>/<name>.md per rule |
.factory/droids/<name>.md | <agents>/<name>.md |
.agents/skills/<name>/SKILL.md, .factory/skills/<name>/SKILL.md | <skills>/<name>/SKILL.md |
<scope>/.factory/skills/<name>/SKILL.md | <skills>/<scope>/<name>/SKILL.md |
.factory/commands/<name>.md | <commands>/<name>.md |
.factory/mcp.json (mcpServers.<name>) | <mcps>/<name>.yaml |
.factory/hooks.json, else legacy .factory/hooks/hooks.json | One spec per consecutive run of commands with the same timeout, onFailure, preserveRiskLevel. onFailure: "block" becomes failClosed: true. |
.factory/settings.json model, reasoningEffort, command lists | <settings>/factory.yaml. reasoningEffort becomes effort, or x-factory.reasoningEffort when another settings spec sets a different effort. |
AGENTS.md | .agnostic-ai/AGNOSTIC_AI.md |
Imported hook names start with their group and command-run positions, so sync keeps command order in each matcher group. Keep those prefixes when renaming.
- Droids:
toolsmap back (ExecutetoBash,CreatetoWrite,FetchUrltoWebFetch). A category (read-only) or MCP tool ID list goes underx-factory.toolsas written.reasoningEffortbecomeseffort. Other keys go underx-factory. - MCP servers:
enabledToolsgoes underx-factory.enabledTools. Empty lists and names shared withdisabledToolsstay. - Command lists:
commandAllowlistbecomesallow,commandDenylistbecomesask,commandBlocklistbecomesdeny, asBash(...)rules. A pattern ending in*becomesBash(x:*). Othersettings.jsonkeys stay.
Read-only droids on import
A tools: read-only from readonly: true also goes under x-factory.tools. Import does not restore readonly. Syncing again writes the same droid file.
Adopt a changed hook order
Existing hook specs win on re-import. To adopt an order edited in the native file, import it into a temporary project with no specs. From your project root, run this. Use your outputs.factory.hooks-file path in the copy if it differs from .factory/hooks.json.
factory_import_dir=$(mktemp -d) &&
mkdir -p "$factory_import_dir/.factory" &&
printf '%s\n' 'version: 1' 'targets: [factory]' > "$factory_import_dir/agnostic-ai.yaml" &&
cp .factory/hooks.json "$factory_import_dir/.factory/hooks.json" &&
(
cd "$factory_import_dir" &&
agnostic-ai import factory &&
agnostic-ai sync --only factory --dry-run --diff
) &&
printf 'Review hook specs in %s\n' "$factory_import_dir/.agnostic-ai/hooks"
Then:
- Compare the new specs with your hook source folder. Carry over comments, descriptions, target filters, and other spec-only edits.
- A command inserted inside a run can split one spec into several. Point references to each old hook at its replacements.
- Copy the affected matcher group's old specs outside your hook folder, remove only those, and copy in the reviewed ones. Keep unrelated specs.
- In the original project, validate and preview:
agnostic-ai validate &&
agnostic-ai sync --only factory --dry-run --diff
Check the diff for the order you want, then write and check the native file:
agnostic-ai sync --only factory &&
agnostic-ai sync --only factory --check