# Project Commands (/cli/guides/project-commands)



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` [#agentsmd]

`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](/configure-and-extend/repo-instructions).

## `agent.json` [#agentjson]

`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](/web/models) or the CLI Model Picker
* tool policy in [Permissions](/cli/concepts/permissions)
* repeatable prompts in
  [Custom Slash Commands](/configure-and-extend/custom-slash-commands)

## Project custom commands [#project-custom-commands]

Project commands live in:

```text
.agents/commands/**/*.md
```

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

```text
.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](/configure-and-extend/custom-slash-commands).

## Per-project permissions [#per-project-permissions]

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

```text
~/.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](/cli/concepts/permissions#how-rules-resolve) for the resolver rules.

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

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

See [Concepts → Permissions](/cli/concepts/permissions) for the schema, resolution rules, and how `/permissions` reports each rule's source.

## Verify what loaded [#verify-what-loaded]

In the composer:

```text
/permissions
```

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

## Recommended split [#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 [#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

## See also [#see-also]

* [Repo Instructions](/configure-and-extend/repo-instructions)
* [Custom Slash Commands](/configure-and-extend/custom-slash-commands)
* [Concepts → Permissions](/cli/concepts/permissions)
* [Concepts → Approvals](/cli/concepts/approvals)
* [Configuration and Flags](/cli/guides/configuration-and-flags)