███╗   ███╗ ██████╗        █████╗  ██████╗ ███████╗███╗   ██╗████████╗
████╗ ████║██╔═══██╗      ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
██╔████╔██║██║   ██║█████╗███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║
██║╚██╔╝██║██║▄▄ ██║╚════╝██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║
██║ ╚═╝ ██║╚██████╔╝      ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║
╚═╝     ╚═╝ ╚══▀▀═╝       ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝

mq-agent

Terminal-native AI agent orchestrator for the mq ecosystem.
CI GitHub Actions Python 3.11+ Status v1.18.0 stable · v1.20.0 done License MIT

What it is

A controlled terminal workflow for AI agent work — explicit planning, tool routing, verification, persistent memory and safety gates. Every action is traceable. The model never runs unsupervised.

Planner

Decomposes goals into ordered steps via structured JSON output.

MQ_AGENT_MODEL

Executor

Routes steps through a typed tool registry with dry-run support.

Verifier

Checks each step result before advancing.

MQ_AGENT_VERIFIER_MODEL

Safety

Four modes: read-only → suggest → execute → dangerous.

Memory

Persistent JSON store — carries context across sessions.

MCP Bridge

Routes tool calls to mq-mcp with safety classification.

Quick start

$ uv pip install -e ".[dev,signal]"

$ mq-agent doctor        # check environment
$ mq-agent score .       # README + publish score
$ mq-agent dashboard     # operator snapshot
$ mq-agent signal .      # repo-signal assessment
$ mq-agent audit .       # read-only repo audit

Commands

No API key needed

mq-agent doctor               # environment check
mq-agent score .              # README + publish score
mq-agent repo-summary .       # repo overview
mq-agent tools                # list registered tools
mq-agent dashboard            # operator snapshot
mq-agent stack loop           # controlled loop plan
mq-agent tui                  # refreshable Textual dashboard

AI-powered (needs OPENAI_API_KEY)

mq-agent audit .              # read-only repo audit
mq-agent docs-audit .         # audit README, CHANGELOG and /docs
mq-agent signal .             # repo-signal + AI improvement plan
mq-agent plan "goal"          # decompose a goal into steps
mq-agent release-check        # validate release readiness
mq-agent fix-ci               # diagnose CI failures

MCP local tools

mq-agent mcp status           # check mq-mcp reachability
mq-agent mcp tools            # list tools with safety classes
mq-agent run-tool <tool>      # run tool through safety gates

Links