# Connect your agent app

Add the MiniCut skill and its allow and ask-first rules to your coding agent app, then check that the app has them.

MiniCut supports 11 coding agent apps: 10 with a skill folder, and WorkBuddy by upload. Do this for each one you use. The install prompt in [Install with your agent](/docs/cli/install-with-your-agent) already adds the skill and runs `minicut agent-rules`. Use this page to add another app later, or to repair one.

Every command here needs MiniCut installed. `minicut install-skill` and `minicut agent-rules` work on a computer that is not signed in.

## Check which apps have the skill

1. Run this command:

```bash Terminal
minicut install-skill --status
```

It lists every agent app whose home folder is on this computer. Each line says `installed` with the skill folder, or `not installed` with the command to run.

2. For a script, add `--json`. It prints every app below, with `found`, `installed` and `path`. With no agent app on this computer, `--status --json` prints JSON. The line `No agent app home folder found under` your home folder is printed without `--json`.

## Add the skill to one app

1. Pick the app from the table. The id is the value for `--app`.

| App | Id | Skill folder in your home folder |
|---|---|---|
| Claude Code | `claude-code` | `.claude/skills` |
| Codex | `codex` | `.agents/skills` |
| OpenCode | `opencode` | `.agents/skills` |
| CodeBuddy Code | `codebuddy` | `.codebuddy/skills` |
| TRAE | `trae` | `.trae-cn/skills` |
| Qoder and Qoder CN | `qoder` | `.qoder/skills` |
| Qwen Code | `qwen` | `.qwen/skills` |
| Kimi Code | `kimi` | `.agents/skills` |
| Cursor | `cursor` | `.agents/skills` |
| Cline | `cline` | `.cline/skills` |
| WorkBuddy | `workbuddy` | none, it loads skills by upload |

2. Run the command with that id:

```bash Terminal
minicut install-skill --app claude-code
```

3. If the app is open, restart it so it loads the skill.

The command copies the skill into a folder named `miniharness-short-drama` in the skill folder. If that folder holds your own earlier copy, add `--force` to replace it. If it holds a different skill, the command does not touch it.

Several apps share `.agents/skills`. One copy there serves all of them.

For WorkBuddy, `minicut install-skill --app workbuddy` prints the command that builds a ZIP file. Upload that ZIP in WorkBuddy under 技能 > 添加技能 > 上传技能.

## Add the skill to every app on this computer

1. Run this command:

```bash Terminal
minicut install-skill --all-found
```

```text Output
Claude Code: skill written to ~/.claude/skills/miniharness-short-drama. Restart Claude Code if it is open, so it loads the skill.
Codex: skill written to ~/.agents/skills/miniharness-short-drama. Restart Codex if it is open, so it loads the skill.
Claude Code: added the loop hooks (Stop, PreToolUse) to ~/.claude/settings.json
Codex: added the loop hooks (Stop, PreToolUse) to ~/.codex/hooks.json
Codex: open Codex and type /hooks once to trust the two MiniCut hooks; until then Codex skips them.
```

2. Restart each app that is open.
3. In Codex, open Codex and type `/hooks` once to trust the two MiniCut hooks. Codex skips them until you do.

## Hooks for Claude Code and Codex

For Claude Code and Codex, the install adds two hooks next to the skill. They keep your agent inside the [loops](/docs/cli/checks-and-loops):

| Hook | Runs | What it does |
|---|---|---|
| Stop | `minicut loop guard --hook` | Sends your agent back to work while a loop is mid-round, a job of the project still runs, or real video takes wait for the Videos loop |
| Before a write or a command | `minicut loop guard --pre-tool` | Refuses a direct write to the episode timeline and names the `minicut timeline` command to use |

Claude Code keeps its hooks in `~/.claude/settings.json`, and Codex in `~/.codex/hooks.json`. The install merges them with your other hooks, and a second run changes nothing. OpenCode has no stop hook, so it gets no loop guard. The skill tells its agent to run `minicut loop next` instead.

## Add the rules for Claude Code and Codex

1. Run this command:

```bash Terminal
minicut agent-rules
```

```text Output
Claude Code: added to ~/.claude/settings.json:
  permissions.allow: Bash(~/.minicut/bin/minicut *)
  permissions.ask: Bash(~/.minicut/bin/minicut uninstall*)
  permissions.ask: Bash(~/.minicut/bin/minicut * --yes*)
  sandbox.excludedCommands: ~/.minicut/bin/minicut *
Codex: added to ~/.codex/rules/default.rules:
  prefix_rule(pattern=["~/.minicut/bin/minicut"], decision="allow")
  prefix_rule(pattern=["~/.minicut/bin/minicut", "uninstall"], decision="prompt")
  prefix_rule(pattern=["~/.minicut/bin/minicut", "gen"], decision="prompt")
  prefix_rule(pattern=["~/.minicut/bin/minicut", "board", "run"], decision="prompt")
  prefix_rule(pattern=["~/.minicut/bin/minicut", "check", "8"], decision="prompt")
  prefix_rule(pattern=["~/.minicut/bin/minicut", "write"], decision="prompt")
  Codex reads its rules when it starts: restart Codex to use them.
```

2. Restart Codex if it is open.

The command writes one edit for each app it finds, with the full path of `minicut` on this computer. It keeps everything already in the file and never writes a rule twice. Run again, it prints `already has every Minicut rule. Nothing changed.`

| App | File | Runs without asking | Asks first |
|---|---|---|---|
| Claude Code | `~/.claude/settings.json` | Every `minicut` command | `uninstall`, and any command with `--yes` |
| Codex | `~/.codex/rules/default.rules` | Every `minicut` command | `uninstall`, `gen`, `board run`, `check 8` and `write` |

On macOS and Linux, the Claude Code rules also list `minicut` as a command that runs outside the app's sandbox.

To see the rules without writing them, add `--dry-run`. To write for one app, add `--app claude-code` or `--app codex`. Add `--json` for one JSON object.

## Check it worked

Run `minicut install-skill --status` again.

```text Output
Claude Code: installed, ~/.claude/skills/miniharness-short-drama
Codex: installed, ~/.agents/skills/miniharness-short-drama
```

## Errors

| Message | What to do |
|---|---|
| `unknown app "<app>". Apps:` and a list | Use an id from the table above. Exit code 2 |
| `<folder> already exists. Add --force to copy the pack over it.` | Add `--force` to replace the earlier copy |
| `<folder> exists and is not this skill ... Not touching it.` | Move or rename that folder, then run the command again |
| `No agent app home folder found under <folder>. Nothing written.` | Start the app once so it makes its home folder, or use `--app` |
| `agent-rules writes rules for claude-code and codex only. Got: <app>` | Use `--app claude-code` or `--app codex`, or leave `--app` out |
| `<file> is not valid JSON (...), so it was not changed. Add these by hand:` | Fix the file, or add the lines the command prints |
| A line that starts with `这一行需要你自己运行：` | Your agent app's sandbox blocks the write. The line is Chinese for "run this line yourself". Run the command after it in your own terminal |

## Next

[Make the mock](/docs/cli/make-the-mock) [Checks and loops](/docs/cli/checks-and-loops) [Overview](/docs/cli/overview)