Warp (`warp`)

Set up this tool

Warp reads AGENTS.md, .agents/skills/, and .warp/.mcp.json, plus optional workflows.

Set outputs.warp.agents: skill to write agents as on-demand skills; see agents as skills.

First rule

Install the client using the official setup guide, then open your project in it.

Select warp in agnostic-ai.yaml, then follow First rule to add the shared commit-prefix rule and sync it. With the default paths, it reaches AGENTS.md.

Optional agent-to-workflow output runs the agent body as a shell command. Use skills for prompt procedures.

For existing files, check what import warp reads before syncing.

Verify

Run agnostic-ai sync --check and inspect AGENTS.md for the commit-prefix rule. Open the project in Warp and ask for a commit subject for a small fix; it should use fix:.

Next, add a skill.

Output

AGENTS.md                              # canonical entry-point pointer body (written by sync, shared across the AGENTS.md consumers)
.agents/skills/<name>/SKILL.md         # one folder per skill (shared tree)
.warp/workflows/<name>.yaml            # one per agent, only when workflows-dir is set
.warp/.mcp.json                        # when MCP entries exist

Native mappings

Field mappings, discovery, and compatibility

Rules: root rules are included in AGENTS.md. Scoped rules go to <scope>/AGENTS.md (tools that share it).
Skills: Warp skills at .agents/skills/<name>/SKILL.md, the path Warp recommends. A skill in a scope folder moves under that scope, and import keeps it there. Identical root copies are written once.
- Warp documents no field that keeps a skill user-only: agents invoke any skill when relevant, and /{skill-name} runs it by hand. So disable-model-invocation is dropped with a note, and commands are skipped.
- Warp also scans .warp/skills/, .claude/skills/, .codex/skills/, .cursor/skills/, .gemini/skills/, .copilot/skills/, .factory/skills/, .github/skills/, and .opencode/skills/. agnostic-ai writes only .agents/skills/. Warp also picks up OpenCode's default .opencode/skills/, with no extra file.
- WARP_SKILL_DIRS adds directories outside the repo for Cloud agents to index skills from. It does not change which project folders Warp scans.
Workflows: with outputs.warp.workflows-dir set, each agent becomes a Warp Workflow at <dir>/<name>.yaml (name/command/description/tags). Warp now recommends Warp Drive workflows stored in the cloud, but {{path_to_git_repo}}/.warp/workflows/ still loads.
- command: is the agent body as written, so write it as a shell snippet Warp can run.
- Set shells, arguments, source_url, author, and author_url under x-warp. import warp reads them back.
MCP: mcpServers has only the keys in Warp's MCP docs:
- Stdio: command/args/env, plus working_directory (Warp's cwd). args is required, so a server with no arguments gets "args": [].
- Remote (HTTP/SSE/WS): url/headers, with no type, because Warp has no transport field.
- description, disabled, and roots are not written. disabled raises a sync note (Warp never starts project servers on its own). Set description and roots through x-warp.
- Warp also loads Claude Code's .mcp.json, Codex's .codex/config.toml, and .agents/.mcp.json, each after explicit approval (provider table). With claude or codex synced too, one server can appear in up to three files, and Warp documents no handling of same-name servers. Approve only one copy.
- import warp renames working_directory back to cwd. An entry missing command (stdio) or url (remote) is skipped, as in trae, antigravity, and windsurf.

Upgrading from WARP.md

Warp recommends AGENTS.md but still supports WARP.md, which wins in a directory holding both (Warp rules docs). The first sync after upgrading renames a WARP.md that agnostic-ai wrote at the configured root to WARP.md.bak. Sync leaves a WARP.md you wrote (no Generated by agnostic-ai marker) alone. It warns that Warp misses the synced rules until you rename or remove that file.

Config keys

Key	Default	Notes
`outputs.warp.skills-dir`	`.agents/skills`
`outputs.warp.agents`	unset (agents are dropped)	`skill` writes each agent as an on-demand skill. Sync keeps it off with a note while another tool with subagents writes the same skills folder; see agents as skills
`outputs.warp.workflows-dir`	empty	opt-in
`outputs.warp.mcp-file`	`.warp/.mcp.json`
`outputs.warp.rules-file`	unset	writes all rules into one legacy file and skips the write of instructions that point to source specs

Global configuration

agnostic-ai sync --global --only warp adds your home MCP specs to ~/.warp/.mcp.json, using the same fields as project output. The Warp app starts these global servers automatically. The Warp Agent CLI does not read this file; see Warp app and Agent CLI. Sync leaves out a spec with disabled: true and explains why.

agnostic-ai import --global warp reads this file and maps working_directory back to cwd. See global MCP ownership and name conflicts.

Voice dictation

Add portable voice settings to your home specs, then run agnostic-ai sync --global --only warp. Sync writes enabled and language choices into Warp's settings file:

macOS: ~/.warp/settings.toml.
Linux: $XDG_CONFIG_HOME/warp-terminal/settings.toml, or ~/.config/warp-terminal/settings.toml when unset.
Windows: %LOCALAPPDATA%\warp\Warp\config\settings.toml.

Warp takes a lowercase two-letter language code such as es, or "" for auto-detect. Sync skips broader values such as en-US and auto with a note. Warp has no capture-mode setting, so voice.mode also prints a note. The activation shortcut and other preferences stay in Warp.

Sync preserves comments and unrelated keys in [agents.voice], and removing portable voice restores the original values. Existing inline or dotted definitions of this table are left unchanged with an error asking for an explicit [agents.voice] table. explain --global settings/voice.yaml shows the file and keys for your platform.

Warp app and Agent CLI

The Warp app and the Warp Agent CLI keep separate MCP settings (CLI configuration):

Reader	Global MCP file	Project MCP file
Warp app	`~/.warp/.mcp.json`	`.warp/.mcp.json`
Warp Agent CLI	its own file (see below)	`.warp/.mcp.json`, listed as off in `/mcp` until you enable each server

Global servers written by sync reach the app only. sync --global does not write the CLI file, so the CLI gets your rules and skills but none of your global MCP servers. To copy your app setup to the CLI once, run /tui-migrate-setup in the CLI. Later changes to ~/.warp/.mcp.json do not follow.
CLI file paths. Warp documents only the macOS path, ~/.warp_cli/.mcp.json. For other systems the path comes from Warp's source, not its docs: cli/.mcp.json inside the Warp config directory. It is unconfirmed in a running CLI; the /mcp header shows the file the CLI reads.
Project servers. Warp's CLI page says project MCP files are not detected, but the shipped CLI lists servers from .warp/.mcp.json in /mcp. They stay off until you enable each one.

Import

agnostic-ai import warp reads AGENTS.md, workflows from .warp/workflows/, and MCP servers from .warp/.mcp.json.

Skills import, with all bundled files, from <root>/skills/ for each root Warp scans: .agents, .warp, .claude, .codex, .cursor, .gemini, .copilot, .factory, .github, and .opencode. Within a scope, an earlier root wins a duplicate name. Scoped paths stay together.

Protected paths

Not enforced. This target takes no settings specs, so sync reports a spec with a protected block as unsupported. See protected-path alternatives.

Warp (warp)