Zed's own agent loads personal instructions from ~/.config/zed/AGENTS.md and exactly one project file: the first match in .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md. MCP servers are context_servers in Zed's settings.json, and tool approvals are regex rules in agent.tool_permissions (allow, confirm, deny). External agents such as Claude Agent and Codex run through ACP with their own login, so a Claude or ChatGPT subscription works only inside those agents.
Zed at a glance
| Global instructions | ✓ Yes~/.config/zed/AGENTS.md |
|---|---|
| Project instructions | ✓ Yes First match of .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md |
| Nested / subfolder | ? Not documented Not documented |
| AGENTS.md | ◐ Partial Yes, but .rules, .cursorrules, .windsurfrules, .clinerules, copilot-instructions.md or AGENT.md take priority |
| Skills (SKILL.md) | ✓ Yes~/.agents/skills/ and <worktree>/.agents/skills/ (flat layout) |
| MCP config | ✓ Yescontext_servers in Zed settings.json, or MCP extensions |
| Permissions / allowlist | ✓ Yesagent.tool_permissions (v0.224+): default plus per-tool always_allow / always_confirm / always_deny regex patterns |
| Sandbox | ? Not documented Not documented |
| Hooks | ? Not documented Not documented |
| Claude Pro/Max login | ◐ Partial Only via the Claude Agent (ACP), which has its own login |
| ChatGPT Plus/Pro login | ◐ Partial Only via the Codex external agent |
| API key / own plan | ✓ Yes Zed's hosted models or your own provider keys |
Exact file paths
| Path | Scope | What it does |
|---|---|---|
~/.config/zed/AGENTS.md | User | Personal instructions |
.rules … GEMINI.md (first match) | Project | One project instruction file |
~/.config/zed/settings.json | User | agent.tool_permissions, context_servers |
.agents/skills/<name>/SKILL.md | Project | Skills (also ~/.agents/skills) |
Using a shared AGENTS.md with Zed
Native, but delete .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md and AGENT.md, which win over AGENTS.md. See one AGENTS.md for every agent, or generate one with the AGENTS.md generator.
Copy-paste examples
MCP server
File: ~/.config/zed/settings.json
{
"context_servers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://readonly@localhost/app"]
}
}
}
Safe permissions preset
Safe Zed tool permissions
File: ~/.config/zed/settings.json
{
"agent": {
"tool_permissions": {
"default": "confirm",
"tools": {
"terminal": {
"default": "confirm",
"always_allow": [
{ "pattern": "^git\\s+(status|diff|log)" },
{ "pattern": "^npm\\s+(test|run lint)" }
],
"always_deny": [
{ "pattern": "rm\\s+-[a-z]*r[a-z]*f" },
{ "pattern": "git\\s+push.*(--force|\\s-f)" },
{ "pattern": "drop\\s+(table|database)", "case_sensitive": false },
{ "pattern": "terraform\\s+destroy" }
],
"always_confirm": [
{ "pattern": "git\\s+push" },
{ "pattern": "sudo\\s" }
]
}
}
}
}
}
Patterns are regular expressions. always_deny blocks even when the global default is allow. These rules apply to Zed's own agent; external agents (Claude Agent, Codex) use their own permission settings.
Gotchas
- Only one project instruction file loads, and
.rulesor.cursorrulesbeats AGENTS.md. Delete stale legacy files or Zed will ignore your AGENTS.md. - Before v0.224 the setting was the boolean
agent.always_allow_tool_actions. - Skills must be direct children of the skills folder; nested groups are not discovered.
FAQ
Does Zed read AGENTS.md?
Where do MCP servers go in Zed?
Sources
Checked against these official pages on 2026-10-12. Cells marked "Not documented" mean we could not find the behaviour in these docs; it may still exist.