Warp Terminal's Agent Mode: AI Rules and Config Files Explained (2026)

Warp is a terminal built around an “Agent Mode” that can write code, run commands, and fix errors autonomously — and like every serious AI coding tool in 2026, it needs a way to learn your project’s conventions instead of guessing at them. Warp solves this with a project rules file, and unlike some tools that reinvent the wheel, it deliberately converges on the format the rest of the ecosystem has already standardized around: AGENTS.md.

In one sentence: Warp’s Agent Mode reads project instructions from an AGENTS.md file (or a legacy WARP.md file) at your repository root, layers in directory-specific and global rules on top, and treats that combined context as the direct equivalent of Claude Code’s CLAUDE.md or Cursor’s .cursorrules.

This guide covers exactly how that system works, according to Warp’s own documentation, plus setup steps, a precedence breakdown, a comparison against other tools’ conventions, and working config examples.

Does Warp Support AGENTS.md?

Yes — directly and by design. Per Warp’s official documentation, project rules live in an AGENTS.md file (or WARP.md for backward compatibility) placed in your codebase. Warp’s own migration guide states it plainly: “Warp picks up project rules from an AGENTS.md (or WARP.md) at your repo root — the direct equivalent of Claude Code’s CLAUDE.md.”

A few specifics worth getting right, because they are easy to get wrong:

• Filename case matters. The filename must be written in all caps — AGENTS.md, not agents.md — for Warp to recognize it.
• WARP.md still works. It is the legacy filename from before Warp adopted the cross-tool AGENTS.md standard, and it is still fully supported. If both files exist in the same directory, WARP.md takes priority.
• Warp is not the only tool that reads AGENTS.md. The file format originated as a cross-vendor convention (backed by OpenAI, and adopted by tools including Codex CLI and others). Warp’s contribution is recognizing it natively in Agent Mode without any extra configuration, plus offering WARP.md as a Warp-specific alias.

Global Rules vs. Project Rules

Warp’s Rules system has two tiers, and understanding the difference determines where you should put a given instruction.

Global Rules

Global Rules apply across every project you work on in Warp. They live in Warp Drive under Personal > Rules and cover things that are about you, not about any one codebase — output format preferences, how verbose you want explanations, your preferred commit message style, or blanket safety constraints like “never run destructive git commands without confirming first.”

Project Rules

Project Rules live in the AGENTS.md/WARP.md file inside your repository. They are checked into version control and apply automatically to everyone who opens that project in Warp. This is where stack details, architecture notes, naming conventions, and test commands belong.

Critically, Warp also supports subdirectory-level rules. You can place an additional AGENTS.md inside a subfolder (say, apps/api/AGENTS.md) and Warp will apply it, on a best-effort basis, when the agent is working on files in that subtree — layered on top of the root file rather than replacing it.

Rules Precedence Order

When multiple rules files apply to the same task, Warp resolves conflicts using this priority order, from highest to lowest:

1. Current subdirectory’s project rules file — most specific wins
2. Root directory’s project rules file — repo-wide defaults
3. Global Rules — your personal, cross-project defaults

This mirrors the pattern most AI coding tools converge on: the more specific the file’s scope, the more it overrides broader defaults. If your Global Rules say “keep explanations brief” but a project’s root AGENTS.md says “explain your reasoning in detail for this codebase,” the project rule wins.

Step-by-Step Setup

1. Open Agent Mode in a project directory

Launch Warp and cd into your repository, or open the folder from Warp’s project picker. Switch to Agent Mode (as opposed to plain Terminal Mode) using the mode toggle or by starting a prompt in the input bar.

2. Run /init to generate or link your rules file

Type /init in the Agent Mode input. This does one of three things:

• Indexes your codebase and generates a new AGENTS.md with initial project context (stack, structure, commands) inferred from the repo.
• If you already have a rules file from another tool, offers to link it as AGENTS.md rather than duplicating content. Supported source files include CLAUDE.md, .cursorrules, AGENT.md, GEMINI.md, .clinerules, .windsurfrules, and .github/copilot-instructions.md.
• Begins or reports on codebase indexing, which powers the agent’s code search and understanding independently of the rules file.

$ warp
> /init

3. Edit AGENTS.md directly

Open the generated file and refine it. A minimal but useful starting point:

# AGENTS.md

## Stack
- Node.js 20, TypeScript 5.5
- Fastify for the API, Vite + React for the frontend
- pnpm workspaces (monorepo)

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Tests: `pnpm test`
- Lint: `pnpm lint`

## Conventions
- Named exports only, no default exports.
- All API routes validate input with Zod before touching business logic.
- Do not edit files under `src/generated/` — they are build output.

## Git
- Conventional Commits format for commit messages.
- Never force-push to `main`.

You can also open this file directly with the /open-project-rules slash command instead of navigating the filesystem.

4. Add subdirectory rules where needed (optional)

For a monorepo, drop a second AGENTS.md inside a specific app or package:

repo-root/
├── AGENTS.md              # repo-wide conventions
├── apps/
│   └── api/
│       └── AGENTS.md      # API-specific rules, layered on top of root
└── apps/
    └── web/

# apps/api/AGENTS.md

## API-specific rules
- All endpoints live under `apps/api/src/routes/`.
- Auth middleware is applied at the router level, never per-handler.
- Database access only through `packages/db` — never import the client directly.

5. Set your Global Rules once, separately

Use /add-rule to add a personal, cross-project rule, or manage the full list with /open-rules:

> /add-rule
"Always show a diff before applying multi-file changes."

6. Add Skills for repeatable, invocable tasks

Beyond passive rules, Warp supports Skills — markdown files with YAML frontmatter that agents can discover and invoke by name, similar in spirit to Claude Code’s Skills. Project-level skills live in .agents/skills/ inside the repo; global ones live in ~/.agents/skills/.

---
name: run-migration-check
description: Verify a new database migration is reversible and does not lock large tables.
---

1. Read the new migration file in `migrations/`.
2. Check for `NOT NULL` additions without a default on existing tables.
3. Check for missing `DOWN`/reversal logic.
4. Report any risky operations before the migration is applied.

Invoke it with /run-migration-check or by describing the task in natural language — Warp’s discovery walks up from the current directory to the repo root, picking up any skills along the way.

Warp vs. Claude Code vs. Cursor: Convention Comparison

The standout difference is that Warp treats AGENTS.md as a genuine interchange format — it will actively detect and link rules files from other tools rather than requiring a rewrite, which lowers the switching cost for teams that already maintain a CLAUDE.md or .cursorrules.

FAQ

Does Warp support AGENTS.md? Yes. It is the primary, natively-recognized project rules filename in Warp’s Agent Mode, per Warp’s official Rules documentation.

What is WARP.md, and is it different from AGENTS.md? WARP.md is the original, Warp-specific filename that predates the cross-tool AGENTS.md standard. Warp still supports it for backward compatibility. If a project has both files, WARP.md takes priority over AGENTS.md.

Does the filename need to be uppercase? Yes. Warp requires the filename in all caps (AGENTS.md, not agents.md) to recognize it as a rules file.

Can I reuse my existing CLAUDE.md or .cursorrules file in Warp? Yes. Run /init in Agent Mode and Warp will offer to link supported external files — including CLAUDE.md, .cursorrules, AGENT.md, GEMINI.md, .clinerules, .windsurfrules, and .github/copilot-instructions.md — into AGENTS.md instead of requiring you to duplicate the content by hand.

What happens if I have rules at the root, in a subdirectory, and globally, and they conflict? Warp resolves conflicts using a fixed precedence order: the current subdirectory’s project rules file wins first, then the root project rules file, then Global Rules.

Are Warp Skills the same thing as rules? No. Rules passively shape how the agent behaves on every task. Skills are discrete, named instruction sets the agent invokes for a specific job — either automatically when relevant or explicitly via /{skill-name}. Skills live in .agents/skills/ (project) or ~/.agents/skills/ (global).

Does Warp have anything equivalent to Claude Code Hooks? Warp’s public documentation, as of this writing, describes Rules, Skills, MCP server integration, and autonomy/permission profiles (which gate whether the agent can read files, run commands, or call MCP tools without prompting) as its primary mechanisms for controlling agent behavior. It does not document a lifecycle-hook system equivalent to Claude Code’s pre/post-tool-use hooks — permission profiles are the closer analog for constraining what an agent can do at each step.

Pair Your Terminal Workflow with Visual QA

Agent Mode in Warp is excellent at the parts of development that live entirely in a shell — writing code, running builds, chasing down stack traces. But once that code ships a UI, someone still has to catch the pixel-level regressions, broken layouts, and inconsistent states that never show up in a terminal log. That’s a visual problem, not a text one, and it needs a visual tool.

BugHerd closes that gap by letting anyone — developer or not — pin feedback directly onto a live webpage and have it land as a ticket with a screenshot, console logs, and browser metadata already attached. Pair a terminal-first, agent-driven backend workflow with a point-and-click frontend QA layer, and you cover both ends of the stack without asking non-technical teammates to describe a CSS bug in words.