Add Zed Agent render adapter for instructions, skills, MCP, and tool permissions

[kelos-bot]

🤖 Kelos Strategist Agent @gjkim42

Area: Integration Opportunities

Summary

Add a Zed Agent render adapter so Kanon can manage Zed's native AI configuration from the same source repo that already feeds Codex and Claude.

Zed is now a better Kanon target than it was in the earlier adapter roadmap. Its current docs show file-backed support for the exact surfaces Kanon already models well:

• Always-on personal/project instructions via AGENTS.md
• SKILL.md skill directories under ~/.agents/skills/ or project .agents/skills/
• MCP servers in Zed settings.json under context_servers
• Agent profiles that enable/disable built-in and MCP tools
• Tool permissions that allow/deny/confirm built-in, skill, and MCP tool calls

This is distinct from existing adapter issues for Cursor/opencode/Copilot, Continue, Roo, Cascade/Windsurf, Junie, Goose, and Kiro. I searched existing issues for Zed / Zed Agent and found no dedicated Zed adapter proposal.

Why this is strategically useful

Zed is not just another editor-specific settings file. It is becoming an agent host:

• Zed Agent uses Zed-managed instructions, skills, MCP servers, profiles, and permissions.
• Zed can also host External Agents over ACP, including Claude, Codex, OpenCode, Copilot, Cursor, Gemini CLI, and Pi Coding Agent.
• Zed-configured MCP servers can be forwarded to External Agents over ACP, while those agents may also read their own native config.

That makes Zed a useful bridge target for Kanon: one Kanon source can configure the native Zed Agent and keep the editor-hosted Codex/Claude/OpenCode experience aligned with the same skills, instructions, and MCP server set.

Evidence from the current codebase

• Kanon's schema already has the core primitives: instructions, skills, mcp, hooks, and metadata (internal/core/types.go).
• The current adapter registry only returns Codex and Claude (internal/core/render.go, adaptersFor). The CLI --agent validation and validateTargets allow only codex, claude, and all.
• renderSkills already copies SKILL.md directories, remote git skill providers, and nested assets. That maps directly to Zed's skill folder format.
• Codex already renders skills to ~/.agents/skills globally and .agents/skills for projects (internal/core/codex.go). Zed uses the same paths, which is useful but creates a duplicate-path hazard when both adapters are active.
• Co-owned config merging already exists for Codex TOML and Claude JSON files (internal/core/merge.go), but Zed's settings.json supports // comments. The existing parseJSONDocument uses Go's standard encoding/json, so a Zed merge strategy will need JSONC support or a comment-preserving approach.
• PlanFiles currently does not de-duplicate multiple RenderedFile entries with the same destination path. A Zed adapter would hit this for project AGENTS.md and .agents/skills if Codex is also active.

External evidence

Primary docs checked:

• Zed instructions: ~/.config/zed/AGENTS.md, Windows %APPDATA%\Zed\AGENTS.md, and project instruction files including AGENTS.md: https://zed.dev/docs/ai/instructions
• Zed skills: skill folders contain SKILL.md, optional scripts/references/assets, and install under ~/.agents/skills/ or project .agents/skills/: https://zed.dev/docs/ai/skills
• Zed MCP: custom servers live in settings.json under context_servers with local command/args/env or remote url/headers: https://zed.dev/docs/ai/mcp
• Zed tool permissions: agent.tool_permissions.default and per-tool rules support allow, confirm, and deny; MCP tool keys use mcp:<server>:<tool_name>: https://zed.dev/docs/ai/tool-permissions
• Zed profiles: agent.profiles controls built-in tools and MCP tool availability: https://zed.dev/docs/ai/agent-profiles
• Zed settings files: user settings live at ~/.config/zed/settings.json on macOS/Linux, %APPDATA%\Zed\settings.json on Windows, project settings at .zed/settings.json, and the syntax is JSON with // comments: https://github.com/zed-industries/zed/blob/main/docs/src/configuring-zed.md
• Zed External Agents: Zed hosts ACP agents and has explicit configuration boundaries between Zed Agent, External Agents, and terminal threads: https://zed.dev/docs/ai/external-agents

Proposed adapter mapping

Add a new zed agent target, gated the same way other post-Codex/Claude adapters should be gated. If the agents: opt-in mechanism from the earlier roadmap is not present in this branch, this should ship with or depend on it. Do not make existing targets: [] configs suddenly write Zed files.

User-scope render:

Kanon source	Zed destination
instructions.files	~/.config/zed/AGENTS.md (%APPDATA%\Zed\AGENTS.md on Windows)
skills	~/.agents/skills/<name>/...
mcp.servers	~/.config/zed/settings.json -> context_servers
MCP default_approval / tools	settings.json -> agent.tool_permissions entries
MCP enabled/disabled tools	Optional generated agent.profiles support; defer if too large
hooks	No native Zed mapping in current docs; warn or fail for targets: [zed] rather than silently dropping

Project-scope render with --project:

Kanon source	Zed destination
instructions.files	<project>/AGENTS.md
skills	<project>/.agents/skills/<name>/...
mcp.servers / permissions	<project>/.zed/settings.json if Zed supports these AI settings at project scope; otherwise render only user settings and document the unsupported project fields

Example config

version: 1
agents: [codex, claude, zed]

instructions:
  files:
    - instructions/shared.md
    - instructions/go-service.md

skills:
  - name: code-review
    targets: [codex, claude, zed]

mcp:
  servers:
    github:
      type: http
      url: https://api.githubcopilot.com/mcp/
      targets: [claude, zed]
      default_approval: confirm
      tools:
        create_issue:
          approval: deny

    local-postgres:
      command: npx
      args: [-y, "@modelcontextprotocol/server-postgres"]
      env:
        DATABASE_URL: ${LOCAL_DATABASE_URL}
      targets: [zed]
      default_approval: confirm

Expected Zed settings.json fragment:

{
  "context_servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "local-postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${LOCAL_DATABASE_URL}"
      }
    }
  },
  "agent": {
    "tool_permissions": {
      "default": "confirm",
      "tools": {
        "mcp:github:create_issue": {
          "default": "deny"
        },
        "mcp:local-postgres": {
          "default": "confirm"
        }
      }
    }
  }
}

Guardrails to handle up front

1. Opt-in adapter activation: Existing configs without zed must keep rendering exactly as they do today.
2. Shared destination paths: Zed and Codex both use project AGENTS.md and .agents/skills. Add a render de-duplication step that permits identical content for the same path and fails on divergent content, or make the shared ownership explicit in the adapter design.
3. JSONC settings merge: Zed settings support comments. Do not use the current strict JSON merge path against real Zed settings unless comments are stripped/preserved safely.
4. Co-owned settings preservation: Zed writes many unrelated editor settings into the same file. The merge strategy should update only Kanon-owned keys (context_servers, selected agent.tool_permissions, optional generated profiles) and preserve unmanaged fields.
5. MCP auth: Zed may prompt OAuth for remote MCP servers without an Authorization header. Kanon should not invent auth behavior; just render the supported fields and let Make MCP authentication onboarding first-class #87-style MCP auth onboarding handle a broader flow.
6. External Agent boundary: Be explicit that this adapter configures Zed Agent. External Agents may receive forwarded MCP over ACP, but their native instructions/skills/model/auth remain owned by those agents' own adapters.
7. Unsupported hooks: Zed docs do not show a native hook lifecycle comparable to Codex/Claude. Zed-targeted hooks should produce an actionable warning or validation error.

Suggested MVP scope

1. Add AgentZed, CLI target validation, and render registration behind an opt-in agent list or explicit --agent zed.
2. Render user-scope AGENTS.md, ~/.agents/skills, and ~/.config/zed/settings.json context_servers.
3. Add a FileMergeZedSettings strategy that can preserve Zed JSONC comments or at least fails with a clear path-specific message if JSONC support is not ready.
4. De-duplicate same-path rendered files before planning/apply, or add adapter-level logic that does not emit duplicate shared files when another active adapter already owns the same exact content.
5. Map MCP per-tool approval policies to agent.tool_permissions.tools["mcp:<server>:<tool>"] where values are unambiguous.
6. Add render tests for global instructions, project instructions, shared skills, local and remote MCP servers, JSONC merge preservation, and duplicate-path conflict behavior.
7. Defer import support, profiles, model/provider defaults, and native External Agent installation until the render path is stable.

Non-goals

• Do not manage Zed LLM provider API keys in this adapter.
• Do not install Zed extensions or ACP External Agents in v1.
• Do not claim Zed profiles control External Agents; Zed's docs state that profiles apply to Zed Agent unless an external integration says otherwise.
• Do not add a Zed hook schema unless Zed documents a native hook surface.

[kelos-bot]

🤖 Kelos Task Status

Task kanon-triage-issues-d4ca5f75c771 has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kanon Triage Report

Kind: kind/api
Priority: priority/important-longterm — Valuable new render target, but it is not a blocking bug and depends on maintainer-reviewed adapter opt-in/API semantics.
Actor: actor/human — This adds a new zed agent target and likely touches CLI/config schema behavior, so it needs maintainer review before implementation.

Status: STILL VALID

Evidence:

• No merged PRs referencing 92 were found with gh pr list --state merged --search "92", and recent commit searches for 92 / Zed adapter keywords returned no matches.
• Current code still only defines codex, claude, and all in internal/core/types.go; internal/core/render.go registers only Codex and Claude adapters; internal/core/config.go and internal/cli/root.go still reject any target/agent outside those values.
• internal/core/apply.go still plans rendered files one entry at a time without same-path de-duplication, and internal/core/merge.go only has Codex TOML plus Claude JSON merge strategies, so the JSONC/shared-path guardrails remain unresolved.
• Current Zed docs still support the issue premise: AGENTS.md instructions (https://zed.dev/docs/ai/instructions), .agents/skills skills (https://zed.dev/docs/ai/skills), context_servers MCP config (https://zed.dev/docs/ai/mcp), agent.tool_permissions including MCP tool keys (https://zed.dev/docs/ai/tool-permissions), agent.profiles (https://zed.dev/docs/ai/agent-profiles), JSON settings with // comments (https://github.com/zed-industries/zed/blob/main/docs/src/configuring-zed.md), and ACP External Agent boundaries (https://zed.dev/docs/ai/external-agents).
• Open issue scan found related adapter roadmap work (Grow beyond Codex + Claude: prioritized render-adapter roadmap (Gemini CLI, Cursor, opencode, Copilot CLI) #7, Render adapters: Cursor, opencode, Copilot CLI (+ Gemini import parity) #23) and other separate adapter requests (Add Continue render adapter for IDE and CLI rules + MCP blocks #62, Add Roo Code render adapter for project rules, skills, and MCP #66, Add Cascade (Devin/Windsurf) render adapter for rules, skills, MCP, and hooks #72, Add VS Code Copilot workspace adapter for file-backed customizations #73, Add JetBrains Junie render adapter for guidelines, skills, MCP, and startup hooks #74, Add Goose render adapter for hints, skills, MCP extensions, and hook plugins #79, Add Kiro CLI render adapter for steering, skills, MCP, and custom agents #91), but no other open issue requests a Zed Agent render adapter.

Duplicates found: None found

Recommendation: KEEP OPEN