Project Commands

Use `AGENTS.md`, `agent.json`, custom slash commands, and per-project permission files to make Mogplex behave like part of the repository.

Several repo-local layers shape how the CLI behaves inside a checked-out repo:

AGENTS.md and AGENTS.override.md — durable instructions for any agent operating in this codebase
agent.json — structured project config for prompt suffix and related project metadata
.agents/commands/**/*.md — project-scoped custom command templates for builds that expose custom command loading
~/.mogplex/projects/<repo-slug>/permissions.json — per-project permission overrides

All of these are optional. They make the experience better when the repo has stable conventions, repeatable commands, or different gates than your global default.

`AGENTS.md`

AGENTS.md is the repo-local instruction layer. Place it at the project root, or add narrower files in subdirectories when a monorepo package needs different guidance.

Good content includes:

project purpose and architecture notes
build, test, lint, and typecheck commands
layout and ownership conventions
naming or error-handling patterns
repo-specific guardrails the assistant should follow

Keep it durable. If guidance changes hourly, it belongs in the task prompt instead.

The CLI runtime reads discovered AGENTS.md fragments into the assembled system prompt. It can also discover $MOGPLEX_HOME/AGENTS.md for user-level guidance and AGENTS.override.md when a directory needs an explicit override.

For the full discovery model, see Repo Instructions.

`agent.json`

agent.json is a strict project-local JSON file. Use it sparingly for short structured context such as a prompt suffix.

For behavior that has first-class controls, prefer the product surface that owns it:

model defaults in Available Models or the CLI Model Picker
tool policy in Permissions
repeatable prompts in Custom Slash Commands

Project custom commands

Project commands live in:

.agents/commands/**/*.md

They are the repo-local authoring format for reusable prompt templates. Example:

.agents/commands/review-staged.md -> /review-staged
.agents/commands/release/notes.md -> /release:notes

The legacy .mogplex/commands/**/*.md path is part of the loader's supported discovery model, but .agents/commands is the preferred project path.

Before relying on a project command, confirm the running cockpit exposes it in /help. Some current builds still expose only the built-in registry.

See Custom Slash Commands.

Per-project permissions

Permission rules can be set globally or per-project. The project file lives at:

~/.mogplex/projects/<repo-slug>/permissions.json

It can override the mode and add allow / deny / ask rules that are layered on top of the global rules. Projects can only be more permissive than the global file — a project deny cannot tighten something the global file (or the mode default) already allows. See Concepts → Permissions for the resolver rules.

Example — make a single sandbox repo run unattended while the global policy stays strict:

{
  "version": 1,
  "rules": {
    "allow": ["bash:*", "write:**", "read:**"]
  }
}

See Concepts → Permissions for the schema, resolution rules, and how /permissions reports each rule's source.

Verify what loaded

In the composer:

/permissions

Without an argument, /permissions shows the resolved mode and rules and explains where each pattern came from (default, global, or project).

Recommended split

put long-lived repo rules in AGENTS.md
put repeatable prompt templates in .agents/commands
put per-repo permission overrides in ~/.mogplex/projects/<repo-slug>/permissions.json
keep personal-only defaults in ~/.mogplex/permissions.json (global)
use /permissions <mode> for one-off mode flips that don't deserve a config file

Anti-patterns

putting volatile task notes in AGENTS.md
putting secrets, tokens, or personal paths in project commands
relying on a per-project permissions.json to restrict something the global already allows (the merge can only add allows; deny rules need to be set explicitly per scope)
editing permissions.json while the cockpit is mid-run — wait until /permissions confirms the next state, then /run again