Skip to content
AgentAtlas

Junie guidelines, MCP and the Action Allowlist

Where does Junie read guidelines from, and how do I configure MCP servers and command approvals?

Junie CLI reads project guidelines from .junie/AGENTS.md first, then a root AGENTS.md, and still supports the legacy .junie/guidelines.md file. MCP servers live in .junie/mcp/mcp.json for a project or ~/.junie/mcp/mcp.json for your user. Command approvals are controlled by brave mode and the ~/.junie/allowlist.json file.

Compare: rules and instruction files in every AI coding agent →

Guideline files and lookup order

When Junie CLI starts a task, it looks for guidelines in this order:

  • .junie/AGENTS.md in the project root.
  • AGENTS.md in the project root, combined with .junie/playbook.md and every .junie/rules/*.md file, if present.
  • .junie/guidelines.md or the .junie/guidelines/ folder, the legacy format that is still supported.

Global guidelines go in ~/.junie/AGENTS.md (on Windows, %USERPROFILE%\.junie\AGENTS.md). If both global and project guidelines exist, Junie includes both and project guidelines win on conflicts. Identical content is deduplicated.

The first time Junie CLI opens a project, it checks for guideline or memory files from other AI agents and offers to import them into .junie/AGENTS.md.

MCP configuration

Junie CLI uses the same mcp.json format as Junie in JetBrains IDEs. Project scope is .junie/mcp/mcp.json at the project root and can be committed, so keep secrets out of it. User scope is ~/.junie/mcp/mcp.json and stays private to your account. Run /mcp in the CLI to list, add, enable, disable or authorize servers.

.junie/mcp/mcp.json

{
  "mcpServers": {
    "Context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": { "ENV_VAR": "YOUR_VALUE" }
    },
    "RemoteServer": {
      "url": "https://mcp.example.com/v1",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

The --mcp-default-locations option (default true) turns the default locations on or off, and --mcp-location adds extra folders to search. It can be repeated. In the IDE plugin, MCP Settings opens the same mcp.json file for editing.

Approvals, brave mode and the allowlist

Junie CLI asks before running most terminal commands, editing files outside the project, or calling MCP tools. Choosing Always allow at a prompt adds the action to ~/.junie/allowlist.json, which you can also edit by hand.

  • Rule groups: fileEditing, executables, mcpTools, readOutsideProject and readSecretFile.
  • Each rule has either a prefix (a literal start string) or a pattern (glob syntax), plus an action of allow or ask.
  • Rules are evaluated top to bottom and the first match wins.
  • Chained and nested commands are checked part by part, and multi-line commands always ask.
  • Brave mode has three levels, Off, Auto and On, cycled with /brave or Ctrl+B. On runs all sensitive actions without approval.

~/.junie/allowlist.json

{
  "defaultBehavior": "ask",
  "allowReadonlyCommands": true,
  "rules": {
    "executables": {
      "rules": [
        { "prefix": "git", "action": "allow" },
        { "pattern": "npm install *", "action": "ask" }
      ]
    },
    "mcpTools": {
      "rules": [
        { "prefix": "github-server:", "action": "allow" }
      ]
    }
  }
}

In JetBrains IDEs, the Junie plugin has its own Action Allowlist settings page with rule types such as Terminal, RunTest, Build, MCP, Read outside project and Write outside project.

Junie CLI install and headless runs

Install Junie CLI on Linux, macOS or Windows, then run junie from your project root. For CI, generate a token at junie.jetbrains.com/cli and pass it with --auth along with your prompt. Non-interactive runs trust the project by design and load its MCP servers, hooks, agents, skills and guidelines, so only run them in projects you trust.

Install and run headless

curl -fsSL https://junie.jetbrains.com/install.sh | bash
junie --auth="$JUNIE_API_KEY" "Review and fix any code quality issues in the latest commit"

Sources

More Junie guides

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →