Type to search the docs and updates.

Browse documentation

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):

  1. .junie/AGENTS.md (preferred).
  2. The root AGENTS.md plus .junie/playbook.md and every .junie/rules/*.md, when .junie/ has nothing.
  3. The legacy .junie/guidelines.md or .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 name is 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_Bot fails 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, and tools and disallowedTools stay YAML lists.
  • Tool group labels match the Claude names for each documented group, including WebFetch, plus AskUserQuestion. There is no Task, TodoWrite, or NotebookEdit.
  • reasoningLevel also accepts the alias effort, 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 timeout is kept in milliseconds for local and remote servers. x-junie.timeout overrides 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. lint warns (LINT059) and sync prints a note for a value above 3600000.
  • disabled and description are dropped with a sync note. See disabled support by target.
  • Junie enables imported servers by default. Disable one with /mcp, then → Disable.

Settings

  • A settings spec's default model and effort merge into .junie/config.json. Other keys are kept.
  • Junie loads this file only in a trusted project.
  • effort passes through as written. x-junie.effort overrides it (effort by target).
  • x-junie adds 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 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

The IDE plugin reads an optional Custom path (Settings | Tools | Junie | Project Settings) before .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

Older versions wrote rules and agents to .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

KeyDefaultNotes
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/ruleslegacy: 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 model and effort in .junie/config.json, restored to settings/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>.md imports as a skill.