Grow beyond Codex + Claude: prioritized render-adapter roadmap (Gemini CLI, Cursor, opencode, Copilot CLI)

[kelos-bot]

🤖 Kelos Strategist Agent @gjkim42

Grow Kanon beyond Codex + Claude: a prioritized render-adapter roadmap

Area: Integration Opportunities (new render targets)

Kanon's tagline is "Manage multiple coding-agent settings across multiple diverse machines" — but today it renders for exactly two agents: Codex and Claude (adaptersFor in internal/core/render.go:34). The biggest growth lever for the project is turning that "multiple" into reality. The codebase is already well-positioned for it:

• A clean Adapter interface (internal/core/types.go:128): Name(), Render(), Import().
• A neutral schema (instructions, skills, MCP servers, hooks, permissions) that already maps onto two very different native formats (TOML for Codex, JSON for Claude).
• Kanon already renders AGENTS.md — which has quietly become a cross-tool standard.

I researched the config storage of 8 candidate agents (web research, 2025–2026 sources). This issue proposes a prioritized adapter roadmap, a concrete schema→native mapping for the #1 pick, and the (small) set of code/schema changes needed — including one backward-compatibility trap that must be handled before any adapter is added.

---

Key insight: AGENTS.md gives instructions away for free; the differentiated value is MCP + permissions

Many agents now read AGENTS.md natively (Cursor, GitHub Copilot coding agent & CLI, opencode, Sourcegraph Amp; Gemini CLI and Cline/Roo via a flag). Because Kanon already emits AGENTS.md, instruction propagation to much of the ecosystem is already solved. The real, un-met value of a new adapter is the part AGENTS.md can't carry: MCP servers, permissions/approvals/sandbox, hooks, and skills/commands. Adapters should be ranked by how cleanly those map — not by instruction support.

---

Proposed adapter priority

Ranked by popularity × mapping fit (all file locations below come from the research and are flagged where uncertain):

#	Agent	Fit	Why
1	Gemini CLI	low effort	A single ~/.gemini/settings.json (+ project .gemini/settings.json) carries MCP (mcpServers, Claude-style), permissions (tools.allowed/tools.exclude, tools.sandbox, general.defaultApprovalMode), and hooks (a hooks object, ~9 lifecycle events). Instructions → GEMINI.md (or set context.fileName: AGENTS.md). Skills use SKILL.md dirs; commands are TOML. Almost the entire neutral schema maps cleanly. Google-backed, growing fast.
2	Cursor	medium	Highest install base of the dedicated AI editors. AGENTS.md (free instructions) + .cursor/mcp.json (Claude-style mcpServers, global ~/.cursor/mcp.json) + .cursor/hooks.json (beta). Gap: permissions are UI/allowlist-driven, not a committed file.
3	opencode (sst)	medium	Excellent fit if we accept a distinct schema: AGENTS.md + a single opencode.json (~/.config/opencode/ global) carrying mcp (note: key is mcp, with type: local|remote, not mcpServers) and a permission block (edit/bash/webfetch → allow|ask|deny). All file-addressable. Rising fast in the OSS terminal-agent space.
4	GitHub Copilot CLI	medium	Largest installed base of any assistant. The CLI surface is cleaner than expected: ~/.copilot/ holds settings.json, mcp-config.json ({"mcpServers": …}), hooks/*.json (8 events), agents/, skills/, instructions/, copilot-instructions.md; reads AGENTS.md. (The cloud/coding-agent surface is UI-driven and fragmented — treat as a separate, lower-priority target.)

Lower priority / poor fit (documented so we don't chase them):

• Windsurf — MCP at ~/.codeium/windsurf/mcp_config.json (Claude-style) is fine, but permissions are UI-driven and AGENTS.md support is unconfirmed.
• Cline / Roo Code — instructions map cleanly (.clinerules / .roo/rules/), but MCP lives deep inside VS Code extension globalStorage paths that vary by extension ID and OS — awkward to target reliably.
• Aider — poor fit: no MCP, no allow/deny permission model, no skills/hooks; instructions are reference-by-config (.aider.conf.yml read:) rather than a fixed file. An adapter could only emit a CONVENTIONS.md + a config entry. Skip for now.

---

#1 pick — Gemini CLI: schema → native mapping

Kanon neutral field	Gemini CLI target
instructions.files	~/.gemini/GEMINI.md (concatenated), or project .gemini/; optionally set context.fileName: AGENTS.md to reuse Kanon's existing AGENTS.md output
mcp.servers	~/.gemini/settings.json → mcpServers (Claude-style command/args/env, or httpUrl/url + headers; supports ${VAR} expansion — aligns with Kanon's env_vars/env_headers)
permissions.allow / deny	settings.json → tools.allowed / tools.exclude
permissions.approval_policy / default_mode	settings.json → general.defaultApprovalMode
permissions.sandbox_mode	settings.json → tools.sandbox (docker/podman/…)
hooks	settings.json → hooks object (map Kanon event/command/matcher/async/timeout)
skills	SKILL.md directories (same shape Kanon already renders for Claude/Codex)

Uncertainties to verify before implementing (flagged by research): Gemini has a legacy-vs-nested key skew (coreTools/autoAccept vs tools.*/general.*) across versions; AGENTS.md auto-detection is not default (tracked upstream as an open issue), so the adapter should default to GEMINI.md and offer the context.fileName override; confirm the exact hooks schema and the version it became stable.

---

Code & schema changes required (small, localized)

1. Register the adapter — add a case in adaptersFor (internal/core/render.go:34) and a new geminiAdapter implementing the Adapter interface.

2. Extend the agent allowlist in two places: validateTargets (internal/core/config.go:145) and the --agent flag check (internal/cli/root.go:283), plus the Agent* constants in types.go:5.

3. ⚠️ Backward-compatibility trap — handle before adding any adapter. Today targets: [] / targets: [all] means "every adapter," and adaptersFor("all") returns codex+claude. If a new adapter joins the default set, every existing kanon.yaml would suddenly start writing Gemini/Cursor files on the next kanon apply — surprising and potentially destructive. New adapters must be opt-in. Proposed: a top-level enable list, e.g.

   version: 1
   agents: [codex, claude, gemini]   # absent => current default (codex, claude) for back-compat
   instructions:
     files: [instructions/shared.md]
   mcp:
     servers:
       github:
         type: http
         url: https://api.githubcopilot.com/mcp/
         targets: [claude, gemini]   # per-setting targeting still works

   adaptersFor/RenderAll would intersect the registry with the agents: list; --agent gemini still works explicitly. Configs without an agents: key keep rendering exactly codex+claude — no behavior change for existing users.

4. Import parity (optional, later): geminiAdapter.Import can lift settings.json + GEMINI.md back into neutral config, reusing the existing sanitizeMap/normalize* machinery.

---

Suggested scope for a first PR

Land Gemini CLI as the third adapter (Render-only), together with the agents: opt-in mechanism (item 3) since that must exist before any third adapter ships. Cursor, opencode, and Copilot CLI then follow the same pattern in separate PRs. This proves the multi-agent story end-to-end with the lowest-effort, highest-fit target, while fixing the back-compat semantics once for all future adapters.

---

Research method: 8 parallel web-research passes (one per candidate agent) on 2025–2026 sources, with explicit uncertainty flagging; synthesized against the current internal/core adapter code. Facts marked "uncertain/flagged" above should be re-verified against primary docs at implementation time.

[kelos-bot]

🤖 Kelos Task Status

Task kanon-triage-issues-6ac0a638f52f has succeeded. ✅

[kelos-bot]

🤖 Kelos Strategist Agent @gjkim42

Correction / refinement after a fuller research pass — one claim in the table above understated Cursor, so flagging it before anyone scopes work off this:

Cursor's permissions ARE file-based (for the CLI surface). I wrote "permissions are UI/allowlist-driven, not a committed file" — that's only true of the IDE's global user rules. The Cursor CLI (cursor-agent) reads a committed JSON permissions file:

• Project: <project>/.cursor/cli.json, global: ~/.cursor/cli-config.json
• Shape: {"permissions":{"allow":[...],"deny":[...]}} with Shell(git) / Shell(curl:*), Read(glob), Write(glob), WebFetch(domain), Mcp(server:tool) tokens; deny takes precedence over allow.

This maps almost directly onto Kanon's permissions.allow / permissions.deny, so Cursor's mapping fit is better than the table implies — instructions (AGENTS.md), MCP (.cursor/mcp.json, mcpServers), permissions (.cursor/cli.json), hooks (.cursor/hooks.json), and Skills (.cursor/skills/<name>/SKILL.md, since Cursor 2.4 — and it already reads .claude/skills / .codex/skills, which Kanon's existing skill output lands in) are all file-renderable. Cursor is arguably co-#1 with Gemini CLI.

Caveats that remain real: (1) global user rules are stored in Cursor's settings DB, not a file, so an adapter can only render project-scoped instructions + AGENTS.md; (2) there's a known 2026 bug where an interactive grant writes to ~/.cursor/cli-config.json even when a project .cursor/cli.json exists (project precedence then ignores it) — worth a note in adapter docs; (3) .cursor/rules/*.mdc activation modes (alwaysApply / globs / description) are richer than Kanon's flat instruction model, so emitting plain AGENTS.md (not .mdc) is the clean first step.

Everything else in the roadmap held up under the fuller pass (Gemini CLI: hooks object with 9 events + AGENTS.md via context.fileName; opencode's distinct mcp/permission keys; Copilot CLI's ~/.copilot/ layout).

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kanon Triage Report

Kind: kind/api
Priority: priority/important-longterm — Highest-leverage growth direction for the project, but it's a multi-PR roadmap requiring schema design, not an urgent bug or blocker.
Actor: actor/human — This is a kind/api change: it introduces a new top-level agents: key in kanon.yaml and extends the --agent allowlist. User-facing surface must be reviewed/discussed with a maintainer before implementation.

Status: STILL VALID

Evidence:

• Confirmed against current main (5a31eb7). adaptersFor (internal/core/render.go:34-43) still returns only codexAdapter{} + claudeAdapter{}, with the default case rendering both — exactly the targets: [all] back-compat semantics the issue flags.
• The agent allowlist is duplicated in the two spots cited: validateTargets (internal/core/config.go:145, checks AgentAll/AgentCodex/AgentClaude) and the --agent flag check (internal/cli/root.go:283). The Agent* constants live at internal/core/types.go:5-9 (AgentCodex, AgentClaude, AgentAll). All references in the issue are accurate.
• No merged PR or commit addresses this (gh pr list --state merged empty for adapters; git log shows only the merge of docs: simplify README quick start usage #6). The MCP rendering is still hardcoded per-agent (codexMCPServers/claudeMCPServers), so no Gemini/Cursor/opencode/Copilot adapter exists.
• The backward-compatibility trap is real: adding any adapter to the default set in adaptersFor would make existing kanon.yaml files (with empty/all targets) immediately write new agent files on the next apply. The proposed opt-in agents: list is a sound mitigation but is itself a schema addition needing maintainer sign-off.

Duplicates found: None found — open issues #2 (apply backup plan), #3 (interactive import/apply), #4 (kelos taskspawners) are unrelated.

Recommendation: KEEP OPEN — Valid, well-scoped roadmap. Because it defines new config schema (agents:) and CLI behavior, it needs human review of the API design before a PR. Suggest landing the agents: opt-in + Gemini CLI adapter as the first increment, as the issue proposes.

[gjkim42]

/kelos pick-up

[kelos-bot]

🤖 Kelos Task Status

Task kanon-workers-issue-comment-a84fac96359c has succeeded. ✅