# Running the agents This page shows how to run the [maintenance agents](/docs/maintenance-agents.html). You do not need to know the codebase to use them. Every command below is safe to copy and paste from the project root. > The golden rule: **check** never changes anything, **fix** does. When in doubt, > run check first and read the report. ## The easiest way: talk to Maestro Maestro is the conductor. You ask in plain language and it runs the right agent for you, then explains what it found. ```bash make maestro ``` That opens a prompt. Try asking: - `is my audit coverage complete?` - `check the security of the projects router` - `get the whole project in shape` You can also ask a single question without opening the prompt: ```bash python -m agents.maestro "is my documentation up to date?" ``` Maestro defaults to **check** (read-only) for questions and confirms with you before it makes any change. ## Running one agent yourself Every agent has its own command. By default an agent **fixes** what it finds; add `CHECK=1` to only report. ```bash make audit-agent # find and fix audit-log gaps make audit-agent CHECK=1 # only report them, change nothing ``` The full set of agent commands: ```bash make security-agent # data and role security make audit-agent # audit-log coverage make devii-agent # Devii capability and tool visibility make docs-agent # documentation accuracy make fanout-agent # feature wired across every layer make dry-agent # duplication and reuse make style-agent # naming, headers, typing, formatting make frontend-agent # JavaScript, components, CSS make seo-agent # search metadata and sitemap make test-agent # integration-test coverage ``` Add `CHECK=1` to any of them to report without changing files. ## Running the whole fleet ```bash make agents-all # run every agent in order and fix make agents-all CHECK=1 # run every agent in order, report only ``` This is the command to run before a release, or in a continuous-integration job (in `CHECK=1` mode it returns a non-zero exit code if anything is wrong). ## What you see while it runs The output is meant to be read live, so you always know what is happening: - **A start banner** for every agent: its name, a memorable codename (like `brave-otter`), what it is about to do, and where its report will be written. - **A timestamp and elapsed time** on every line, so you can see how long things take. - **A running cost** after each AI step (per call and total), with money icons. - **A diff** of every file change as it happens, so nothing is edited silently. - **Live command output** streamed line by line while a command runs. ## Reading the reports Every run writes its findings to `agents/reports/`, named `--` so a run is easy to refer to: - `--.json` - the machine-readable findings. - `--.md` - a readable summary grouped by file. - `fleet--.json` - the combined report when you run the whole fleet. A report marked `incomplete` means the run ran out of its step budget before finishing; its findings are partial and it is worth running again. ## Validating the code yourself The agents verify their own changes with a built-in validator that needs no extra tools. You can run it directly any time: ```bash make validate # check Python, JavaScript, CSS, and templates ``` ## Where to go next - [Maintenance agents](/docs/maintenance-agents.html) - what each agent does and why.