Qoder native reference
Start with the Qoder setup.
Native mappings
Rules
- Qoder reads
.qoder/rules/and rootAGENTS.md. The IDE lets per-rule files win, so sync writes rules there. The CLI loads both, in no documented order. - When another tool adds the
## Rulesblock toAGENTS.md, an always-on rule gets no file and loads once. A rule whose text differs for Qoder keeps its file. - The CLI reads
AGENTS.mdunlesscontext.fileNamenames other files. Keep it listed, or the CLI misses rules that have no file.
See Rule activation and target behavior.
Agents
Qoder Subagents reads .qoder/agents/<name>.md.
- Required:
name,description. Optional:model,tools,color,skills,mcpServers,effort,permissionMode,memory,hooks,maxTurns,background. - An agent-only MCP server goes in full under
mcpServers, not into.qoder/settings.json. efforttakes one value or a per-tool map; an integer budget stays a number. See per-targetmodelandeffortand agent policy support by target.coloris one ofred,blue,green,yellow,purple,orange,pink,cyan(CLI field reference).toolsis a comma-separated string (tools: Read, Grep, Bash);import qodersplits it back. Names are Claude-style (Bash,Edit,Write,Glob,Grep,Read,WebFetch,WebSearch), so the portable list is copied unchanged.skillsandmcpServerscome fromx-qoder.memoryis copied unchanged (Subagent memory).- Sync sets
name,description,model,tools,skills,mcpServers. Otherx-qoderkeys are copied as written.
Skills
- Path:
.qoder/skills/<name>/SKILL.md(Qoder Skills), with plainnameanddescriptionfrontmatter. - Bundled files (scripts, references, templates) are copied unchanged beside it.
sync --globalwrites personal skills under~/.qoder/skills/.- Qoder CLI 1.1.11 (August 1, 2026) turned on
.agents/skills/by default. Sync keeps the native path the IDE guide documents and does not use the shared skills folder.
Commands
- Path:
.qoder/commands/<name>.md, for the CLI and the IDE. - Sync always writes
description(default: the command's name) and nevername, since the path sets it. - On a name clash the CLI prefers your personal command (
~/.qoder/commands/); the IDE lists both with a scope label. Sync cannot see personal commands, so it cannot warn.
MCP
mcpServers is merged into .qoder/settings.json.
- stdio:
command,args,env,cwd, notype. Remote:type,url,headers. - Other keys (
mcp.enableAllProjectMcpServers, permissions, custom models) are kept. - Optional fields (MCP reference), written as declared:
timeout(ms),description,trust(skip confirmation),includeTools,excludeTools,alwaysAllow,disabled(keep config, server off),oauth. Seedisabledsupport by target. - Set
x-qoder.protocolVersionon an MCP spec to pin Qoder's protocol revision. Project and global imports store the revision there. Sync also reads the top-level field written by older imports. type: wsgets only a sync note: Qoder's ws transport takes a TCP host and port that a spec cannot express.- The file may be JSONC (settings). Sync keeps keys, drops comments and trailing commas, and warns.
Settings
- The shared default model becomes
model.name. permissions.allow,deny, andaskare copied directly. Anx-qodersettings block is merged in. Voice has no native key.approvalsset toreviewfor Qoder makessync --globalwritegeneral.defaultPermissionMode: "auto"to~/.qoder/settings.json, unless a settings spec setsx-qoder.general.defaultPermissionMode. See review through the tool's own reviewer.- With
memory.personal: repo, sync adds the personal store topermissions.additionalDirectories, so saves there are approved. Your entries stay. See repo mode.
Hooks
Hooks merge under hooks in the same file (Qoder hooks), in the nested form Claude Code, Codex, and OpenHands share.
- With
builtins: [memory], aSessionStarthook adds the shared memory index to the session. Its reply is{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": ...}}, the form Qoder documents. - 27 PascalCase events (hooks reference):
SessionStart,SessionEnd,UserPromptSubmit,PreToolUse,PostToolUse,PostToolUseFailure,PermissionRequest,PermissionDenied,Stop,StopFailure,SubagentStart,SubagentStop,PreCompact,PostCompact,Notification,InstructionsLoaded,ConfigChange,CwdChanged,FileChanged,WorktreeCreate,WorktreeRemove,Elicitation,ElicitationResult,TaskCreated,TaskCompleted,TeammateIdle,Setup. event:is copied as written. Listed events sort in Qoder's order, before unlisted ones.PreToolUseandPostToolUsematchers use Claude Code's tool names (Bash,Write,Edit,Read,Glob,Grep,mcp__server__tool).- Command entries:
command,type: command, and optionalargs,timeout(seconds, default 600),statusMessage,async,asyncRewake,shell(bashorpowershell),if(a permission rule filter such asBash(git *)),once. argsruns without a shell:commandis one program, each element one literal argument. Qoder then ignoresshell; sync still writes both and adds a note.oncehas no effect, and sync says so. Qoder honors it only for session-scoped hooks (Hooks, Subagent); portable hooks go in settings.- HTTP handlers:
url, optionalheaders,allowedEnvVars. Prompt handlers:prompt, optionalmodel. Both keep filters, timeouts in seconds, and matcher groups. - Other handler types get a sync note.
- Sync writes one
enventry,AGNOSTIC_AI_TARGET, and norewakeMessage,rewakeSummary, or agent handlers.
Unmanaged AGENTS.md
Listing AGENTS.md under sync.unmanaged makes every rule keep its file. See the effect on other targets sharing that file.
Leftover root .mcp.json
- Older versions wrote MCP servers to the root
.mcp.json, shared with Claude Code. The tools' per-server fields differed, so Qoder moved to.qoder/settings.json, which Claude Code never reads. - A leftover
.mcp.jsonstill loads and wins for a server with the same name. - Sync cannot remove it: it has no generated-file header and may belong to Claude Code. In a Qoder-only project, delete it by hand.
Config keys
| Key | Default |
|---|---|
outputs.qoder.rules-dir | .qoder/rules |
outputs.qoder.agents-dir | .qoder/agents |
outputs.qoder.skills-dir | .qoder/skills |
outputs.qoder.commands-dir | .qoder/commands |
outputs.qoder.mcp-file | .qoder/settings.json (also the hooks path) |
Rule activation
Rule frontmatter keeps description, alwaysApply, trigger, glob, and paths.
- Native
trigger,glob, andpathsimport underx-qoder;descriptionandalwaysApplyuse the rule's own fields. - A single selector stays single, a list stays a list.
x-qoderfields override top-level ones.
| Mode | Frontmatter |
|---|---|
| Always active | No activation fields, trigger: always_on, or alwaysApply: true |
| Manual | trigger: manual or alwaysApply: false |
| Model-selected | trigger: model_decision plus a non-empty description |
| File matching | trigger: glob plus glob, or paths |
triggerwins overalwaysApply.- A scoped rule gets
pathscovering the scope folder and file patterns, and no other activation fields. - Validation rejects selectors sync cannot keep.
A manual release rule:
---
name: release
x-qoder:
trigger: manual
---
Run release steps only on request.
Subagent memory
- The portable
memoryfield is copied unchanged to.qoder/agents/<name>.md, with the scopes Qoder's subagent reference accepts:user,project,local. The--agentsJSON format has nomemory. - It works only when top-level
autoMemoryEnabledis on in settings (defaultfalse). - Qoder documents this; it is not tested at runtime. Only Claude Code is confirmed to act on
memory.
Auto memory
Qoder's own memory store is separate from the field above (Qoder memory).
- Project store:
~/.qoder/projects/<project>/memory/. User store:~/.qoder/memory/. - Each is a
MEMORY.mdindex plus one file per topic./memoryshows them;/memory manageviews, edits, or deletes a topic. - A session loads the first 200 lines or about 25KB of each active
MEMORY.md. - Off by default; see each tool's own memory.
- agnostic-ai never writes that store. To copy its facts into shared personal memory, run
agnostic-ai memory import --path ~/.qoder/projects/<project>/memory.
Import
import qoder reads rules, agents, skill folders, commands, MCP servers, and portable settings fields.
mcpServerscomes from project.qoder/settings.json(JSONC allowed) into the MCP source directory. Env and header credentials become environment references.- A server with a literal OAuth credential is left out, and import names the field to fix.
- Portable settings go to
settings/qoder.yaml. Rule activation is kept. - Not imported: hooks, personal settings, the separate project
.mcp.json.