# 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. When you ask it to review the whole project, it runs each agent **once** and reuses those results to answer anything you ask next, so it never repeats the same sweep to look something up. ## 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 # fix: run every agent in dependency order make agents-all CHECK=1 # report only: run the whole fleet at once ``` Because reporting changes nothing, **`CHECK=1` runs every agent concurrently** for a fast, read-only health check of the whole project. A **fix** run goes one agent at a time in dependency order, so file changes never collide. 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). ## Checking only what you changed While you work, you usually only want the fleet to look at the files you just touched, not the whole project. These two targets run the whole fleet but limit it to the files git reports as modified or new (untracked) under `devplacepy/` and `tests/`, so a sweep takes seconds instead of minutes: ```bash make maintenance # report only, all agents at once, just your changed files make maintenance-fix # fix, just your changed files ``` `make maintenance` is read-only and concurrent, exactly like `make agents-all CHECK=1` but narrowed to your work in progress. `make maintenance-fix` fixes, and a built-in safety rule guarantees it can only edit the files in that changed set, never anything else. If nothing under `devplacepy/` or `tests/` has changed, the run prints "nothing to do" and exits cleanly. The same scope is available on a single agent with the `--changed` flag, for example `python -m agents.security --changed`. ## 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.