DIXI Spec Kit documentation Español · Source on GitHub

Automatic controls

Purpose

Explain what --controls installs, what each control blocks and what none of them covers. Without controls, the rules of DIXI are instructions that the agent is asked to follow. With them, five small scripts run inside the agent and stop it before it breaks one of those rules.

Turning them on

Controls are optional and exist for the two agents that can run hooks:

dixi init my-project --agent claude --controls
dixi init my-project --agent codex --controls

For a project that already exists, dixi upgrade --dry-run --controls shows what would be added and dixi upgrade --apply --controls adds it. They are not available with --agent skills or --agent none: those agents have no hooks that DIXI can install, and dixi init refuses the combination instead of installing something that would not run.

What gets installed:

What each control blocks

ControlWhat it blocksWhen it runs
protect_tests.pyChanging, moving or deleting a test that is already committed, through the edit tools or a shell command. Tests that are not committed yet can be written: that is how tests come first.Before every edit and every shell command
guard_secrets.pyReading .env* files, private keys, .aws/, .ssh/ and credential files, directly or through a shell command. Example files such as .env.example are allowed.Before every read, search and shell command
guard_attestation.pySigning off a commit, approving or merging a pull request, and ticking an attestation checkbox. The agent may commit without a sign-off; the person signs.Before every shell command
mode_gate.pyWith MODE set to prod: recursive deletes outside temporary folders, forced pushes, hard resets of a shared branch, infrastructure apply and destroy, cluster deletes and SQL DROP or TRUNCATE. With mvp it allows them.Before every shell command
verify_on_stop.pyEnding the turn when files changed and make verify fails. After one forced continuation it lets the agent stop and tells you, so the agent is never trapped in a loop.When the agent, or a subagent, is about to stop

Two of them have a setting, read from the environment in which you start the agent:

How to see that they are active

  1. dixi doctor reports whether the project was created with controls.
  2. The files are there: .dixi/hooks/ with the five scripts, and .claude/settings.json or .codex/hooks.json.
  3. Ask the agent for something a control blocks, for example to change a committed test. It is stopped with a message that starts with the name of the control, such as DIXI protect_tests, and the file does not change.

In Codex, also check that the project is trusted and that the hooks are approved; until then they do not run.

What the controls do not cover

A control is a second layer, never the last one.