Examples

Examples

Audit a repository

Run a read-only audit of the current directory. The planner generates steps, the executor runs them, and the verifier checks each result.

mq-agent audit .

Audit a specific repo:

mq-agent audit ~/repo-signal

With JSON output (suitable for CI or piping):

mq-agent audit . --json

Dry-run (plan only, no tool execution):

mq-agent audit . --dry-run

---

Plan a goal

Ask the planner to decompose a goal into steps using available tools:

mq-agent plan "release repo-signal"

Output:

PLAN: release repo-signal
1. Run the test suite to confirm no regressions
2. Check git status for uncommitted changes
3. Read pyproject.toml to validate packaging configuration
4. Verify CHANGELOG.md is updated
5. Confirm working tree is clean

---

Show the release plan

mq-agent release-plan

---

Validate release readiness

Show plan only (suggest mode, default):

mq-agent release-check

Execute checks:

mq-agent release-check --approve

JSON output for CI:

mq-agent release-check --json

---

Run a command safely

Preview without executing:

mq-agent run "pytest tests/ -v" --dry-run

Execute with approval:

mq-agent run "pytest tests/ -v" --approve

Without --approve, the command is shown but not run.

---

Diagnose CI failures

mq-agent fix-ci

With JSON output:

mq-agent fix-ci --json

---

Repo summary

mq-agent repo-summary .

mq-agent repo-summary ~/repo-signal --json

---

Check environment

mq-agent doctor

Checks: OPENAI_API_KEY, git, uv, Python version, and mq-mcp availability. When mq-mcp is running, doctor also checks whether validate_orchestration_contract is available.

---

Review via mq-mcp

Review commands route through mq-mcp and pass findings through unchanged:

mq-agent review file README.md
mq-agent review diff
mq-agent review repo .

Forward review modes to mq-mcp:

mq-agent review file mq_agent/main.py --security
mq-agent review repo . --architecture
mq-agent review diff --json

Risk review is used only when the installed mq-mcp exposes the matching risk_review_* tool:

mq-agent review diff --risk

Preview what would be called without contacting mq-mcp:

mq-agent review file mq_agent/main.py --dry-run
mq-agent review diff --dry-run --security
mq-agent review repo . --dry-run --architecture --risk

Prefer fast Class A tools (mq-mcp routes internally):

mq-agent review file mq_agent/main.py --fast
mq-agent review diff --fast --security

Architecture context is shown automatically after review findings when list_architecture_decisions is available in mq-mcp.

---

Learned review patterns

Check learn system availability:

mq-agent learn status
mq-agent learn status --json

Search learned patterns:

mq-agent learn search "state mutation"
mq-agent learn search "guard clauses" --json

Fetch a pattern explanation:

mq-agent learn explain p-42
mq-agent learn explain p-42 --json

mq-agent does not implement severity scoring, architecture reasoning, risk classification, semantic retrieval, review heuristics or drift detection. It also does not extract or store learned patterns locally. Optional Ollama-backed learn extraction belongs in mq-mcp; mq-agent only surfaces read-only learn status, search and explain results.

---

List registered tools

mq-agent tools

---

Launch the TUI

mq-agent tui

Keyboard bindings:

• enter — run selected command
• c — clear log
• q — quit

---

---

Score a repo (no API key required)

Quick README score and publish checklist — no AI, instant result:

mq-agent score .

JSON output:

mq-agent score . --json

---

Full repo-signal assessment

Scan + README score + publish checklist + AI improvement plan:

mq-agent signal .

Dry-run (no AI call):

mq-agent signal . --dry-run

---

Declarative task workflows

List available YAML task workflows:

mq-agent task list
mq-agent task list --json

Preview a task without executing:

mq-agent task run repo-audit --dry-run
mq-agent task run suggest-patches --dry-run --json

Run a task (executes all steps via the tool registry):

mq-agent task run repo-audit
mq-agent task run suggest-patches

---

Browser-assisted verification

Inspect a URL (title, description, headings, links, word count):

mq-agent browser inspect https://github.com/MCamner/mq-agent

Plain-text summary:

mq-agent browser summarize https://github.com/MCamner/mq-agent

Verify a GitHub release page:

mq-agent browser verify-release https://github.com/MCamner/mq-agent/releases/tag/v0.9.0
mq-agent browser verify-release https://github.com/MCamner/mq-agent/releases/tag/v0.9.0 --tag v0.9.0

---

Controlled specialist orchestration

List available swarm configurations:

mq-agent swarm list

Dry-plan a swarm config (no API key, no execution):

mq-agent swarm plan audit
mq-agent swarm plan audit --json

Run the audit swarm (read-only, no --approve needed):

mq-agent swarm run audit .

Run the release-check swarm (requires --approve for write agents):

mq-agent swarm release-check .
mq-agent swarm release-check . --approve

---

Semantic repository memory

Check memory status:

mq-agent memory status
mq-agent memory status --json

Preview what would be uploaded (dry-run, default):

mq-agent memory build

Upload to vector store (requires explicit approval):

mq-agent memory refresh --approve

Diagnose the memory environment:

mq-agent memory doctor
mq-agent memory doctor --json

Search mq-mcp semantic memory (requires mq-mcp v1.4.0+):

mq-agent memory search "architecture decisions"
mq-agent memory search "safety gates" --json

Store an item in mq-mcp semantic memory (Class C write — requires --approve):

mq-agent memory store "arch-key" "Use MCPBridge for all tool routing." --approve
mq-agent memory store "arch-key" "value" --dry-run

---

MCP server management

Start the local mq-mcp tool server:

mq-agent mcp start

Check status and tool counts:

mq-agent mcp status
mq-agent mcp status --json

List available MCP tools with safety classes:

mq-agent mcp tools

Stop the server:

mq-agent mcp stop

Register an external MCP server:

mq-agent mcp connect MyServer http://localhost:9000
mq-agent mcp disconnect MyServer

---

See demo output

Sample output files are in docs/demo/.