# Running the agents How to run the [maintenance agents](/docs/maintenance-agents.html). You do not need to know the codebase to use them. Every command below runs 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. Ask in plain language and it runs the right agent, then explains what it found. ```bash make maestro ``` That opens a prompt. Try: - `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 the prompt: ```bash python -m agents.maestro "is my documentation up to date?" ``` Maestro defaults to **check** (read-only) for questions and confirms before any change. When you ask it to review the whole project, it runs each agent **once** and reuses those results to answer follow-up questions, never repeating a sweep. ## 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. A **fix** run goes one agent at a time in dependency order, so file changes never collide. Run this 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 want the fleet to look only at the files you just touched. 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, 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 edit only the files in that changed set. 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: - **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 `--`: - `--.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, so run it 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: ```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.