Junie native reference
Start with the Junie setup.
Native mappings
Junie uses the first guidelines source it finds and does not merge (IDE plugin, guidelines):
.junie/AGENTS.md(preferred).- The root
AGENTS.mdplus.junie/playbook.mdand every.junie/rules/*.md, when.junie/has nothing. - The legacy
.junie/guidelines.mdor.junie/guidelines/.
Sync always writes .junie/AGENTS.md, so Junie uses it exclusively and step 2 never applies.
Rules
A ## Rules block follows the instructions that point to source specs, marked so sync can find it. Each rule is a ### <name> section: source comment, optional description, full body. Every tool that puts rules in instruction files uses this shape.
Agents
Docs. Junie reads .junie/agents/ (the vendor's preferred location and the default here) or .agents/. Junie CLI offers to import .cursor/agents/, .claude/agents/, and .codex/agents/. Set outputs.junie.agents-dir: .agents for the shared alternative, like Codex's outputs.codex.agents-dir: .agents/agents.
- Names (and filenames when
nameis missing) must match[a-z0-9][a-z0-9_-]*. Leading digits and underscores are allowed, unlike the OpenCode and Zed skill rule. - An invalid name such as
Deploy_Botfails sync with the required format. Sync does not rename it. - Frontmatter is copied as written. Documented fields:
name,description,tools,disallowedTools,mcpServers,model,permissionMode,reasoningLevel,maxTurns,skills,allowPromptArgument. They use the spec spelling, andtoolsanddisallowedToolsstay YAML lists. - Tool group labels match the Claude names for each documented group, including
WebFetch, plusAskUserQuestion. There is noTask,TodoWrite, orNotebookEdit. reasoningLevelalso accepts the aliaseffort, which wins when both are set. Both are copied as written.- Agent bodies are not copied into
.junie/AGENTS.md, as with Augment and Kilo Code. - Early Access covers only the automatic model-selection toggle (
/settings → Subagents), not the file format or how Junie finds agents.
Commands
Project commands folder. Junie documents description and allowPromptArgument (free-form text through a $prompt placeholder). Other keys are copied as written. Junie fills $argumentName placeholders in the body when you run the command.
CLI and ACP clients
Junie CLI and compatible Agent Client Protocol (ACP) clients use the same command files. In ACP sessions, /commands lists available commands and how to invoke them with /name. Create or edit commands through their Markdown files or the CLI's interactive /commands screen (command docs).
On a Junie build that supports standalone agents, have the ACP client pass --agent <name> at launch. On macOS arm64, Junie EAP 26.11.3 (build 4171.3) accepts the flag. Stable 26.11.2 (build 4100.10) rejects it before the ACP session starts. Check junie --help on the binary your client launches. Junie standalone agents
IDE AI Chat uses the CLI-backed integration, where command reuse depends on ACP support in the client. The separate Junie tool window is a different integration; its documentation does not describe custom command or subagent file support.
Skills
- Bundled files are copied as they are. A flat file never loads as a skill.
- Junie CLI also loads
.agents/skills/in a trusted project (agent-skills). Another tool that writes it gives Junie a harmless second copy.
MCP
.junie/mcp/mcp.json uses the standard mcpServers schema: command/args/env for local servers, url/headers for remote.
- The per-server
timeoutis kept in milliseconds for local and remote servers.x-junie.timeoutoverrides it. - Junie defaults to 60000 ms and accepts 1000 through 3600000 ms (request timeout). It ignores a value outside that range and uses 60 seconds.
lintwarns (LINT059) and sync prints a note for a value above 3600000. disabledanddescriptionare dropped with a sync note. Seedisabledsupport by target.- Junie enables imported servers by default. Disable one with
/mcp, then → Disable.
Settings
- A settings spec's default
modelandeffortmerge into.junie/config.json. Other keys are kept. - Junie loads this file only in a trusted project.
effortpasses through as written.x-junie.effortoverrides it (effort by target).x-junieadds project-config keys that have no portable field.
Ignore
.aiignore in the project root, in .gitignore syntax (IDE plugin). Specs are joined. Override the path with outputs.junie.ignore-file.
- Junie asks before it views or edits a listed file. It does not block, and it protects contents, not names.
- Brave Mode, or an allowlisted command that names the path, skips the prompt.
- Only the IDE plugin docs mention
.aiignore. No CLI page does.
With The IDE plugin reads an optional Custom path (Settings | Tools | Junie | Project Settings) before Older versions wrote rules and agents to sync.target-overview off and another tool that reads AGENTS.md enabled, .junie/AGENTS.md and the root AGENTS.md are identical.IDE plugin Custom path
.junie/AGENTS.md. The CLI has --guidelines-filename and JUNIE_GUIDELINES_FILENAME for a custom guidelines file in .junie/ at the project root (environment variables).Files from older versions
.junie/rules/, which .junie/AGENTS.md hides. Sync removes generated leftovers there and keeps hand-written files. It also drops an older ## Agents block, because it rewrites .junie/AGENTS.md in full.
Config keys
| Key | Default | Notes |
|---|---|---|
outputs.junie.agents-dir | .junie/agents | |
outputs.junie.skills-dir | .junie/skills | |
outputs.junie.commands-dir | .junie/commands | |
outputs.junie.mcp-file | .junie/mcp/mcp.json | |
outputs.junie.ignore-file | .aiignore | |
outputs.junie.rules-dir | .junie/rules | legacy: only changes where leftover files are removed, for projects that set it |
.junie/AGENTS.md is a fixed path.
Import
agnostic-ai import junie reads:
- The Rules block in
.junie/AGENTS.md. - Agents from
.junie/agents/<name>.md(or.agents/<name>.md). - Commands from
.junie/commands/<name>.md. - Skills and bundled files from
.junie/skills/<name>/SKILL.md, then.agents/skills/for names not already found. - The default
modelandeffortin.junie/config.json, restored tosettings/junie.yaml. - MCP servers from
.junie/mcp/mcp.json, including request timeouts.
Older layouts still import:
- With no native agent files, the older Agents block in
.junie/AGENTS.md. .junie/rules/, when it exists, wins over.junie/AGENTS.md. Each file is sorted by filename prefix.- A legacy flat
.junie/rules/skill-<name>.mdimports as a skill.