mq-agent

Terminal-native AI agent orchestrator for the mq ecosystem.

30 second demo

mq-agent doctor                    # check environment
mq-agent score .                   # README + publish score (no API key)
mq-agent audit . --dry-run         # repo audit plan
mq-agent release-check --dry-run   # release readiness plan

flowchart TD
    A[mqlaunch] --> B[mq-agent]
    B --> C[mq-hal\nreasoning]
    B --> D[mq-mcp\ntool layer]
    B --> E[repo-signal\nrepo intel]
    B --> F[Planner]
    B --> G[Executor]
    B --> H[Verifier]
    B --> I[Memory]
    B --> J[Safety]

Loading

Screenshots/gallery: the GitHub Pages demo page shows the current command surface and release proof.

Agent entrypoints

This README is the human-facing canonical project document and is intentionally complete. Agents should not use it as their first-read surface — read the thin, instructional entrypoints instead:

• AGENTS.md — Codex entrypoint (MQ memory read-order)
• CLAUDE.md — Claude Code entrypoint (MQ memory read-order)
• .mq/context/repo-card.md — repo identity, role, owns / does-not-own
• .mq/context/integration-map.md — reads-from / writes-to / use-when
• .mq/context/task-pack.md — task-specific context, generated per task (not committed)

How agents should read MQ memory — read order, truth boundary, and token budgets — is defined by the mqobsidian context contract: see mqobsidian docs/CONTEXT_CONTRACT.md and docs/TOKEN_BUDGET.md. mqobsidian owns the contract; mq-agent is a consumer.

Why

Most AI coding tools either wrap a model around shell commands or hide execution behind a chat UI.

mq-agent is different: it treats agent work as a controlled terminal workflow with explicit planning, tool routing, verification, memory and safety gates. Every action is traceable, every operation is gated, and the model never runs unsupervised.

Use cases

mq-agent is useful when you want to:

• audit a repository before publishing
• generate a release readiness plan with explicit approval gates
• score README and publish quality without an API key
• inspect and fix CI failures with AI-generated steps
• run safe terminal workflows where the model cannot act without permission
• combine repo-signal, mq-mcp and mq-hal into one local agent workflow

What it is

Not an AI wrapper script. An actual orchestrator with:

Layer	Responsibility
Planner	Decomposes goals into steps
Executor	Runs steps through tools
Verifier	Checks each result with AI
Memory	Session + persistent state
Safety	Enforces operation modes

Quick start

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

# Check environment
mq-agent doctor

# Score a repo (no API key needed)
mq-agent score .

# Full AI-backed repo assessment
export OPENAI_API_KEY=sk-...
mq-agent signal .

# Read-only audit
mq-agent audit .

Development flow

main is protected. Use a branch and pull request for all development and release-prep changes:

git switch -c chore/release-vX.Y.Z
mq-agent release-check --dry-run
git push -u origin chore/release-vX.Y.Z
gh pr create --base main --head chore/release-vX.Y.Z

Merge the PR only after CI is green. Create release tags from the merged main commit.

Install

Local development

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

From GitHub

pipx install git+https://github.com/MCamner/mq-agent.git

PyPI (planned)

pipx install mq-agent   # coming soon

Requires OPENAI_API_KEY for AI commands. score, doctor, repo-summary and tools work without it.

Demo

$ mq-agent score .
╭──────────────────────── README Score ─────────────────────────╮
│ README score: 100/100  [██████████]                           │
│ ✓ title  ✓ install  ✓ usage  ✓ examples  ✓ badges            │
│ ✓ license  ✓ roadmap  ✓ contributing  (none missing)          │
╰───────────────────────────────────────────────────────────────╯
╭──────────────────── Publish Checklist ────────────────────────╮
│ Publish checklist: 16/16  [PASS]                              │
│ Repo looks publish-ready from the static checklist.           │
╰───────────────────────────────────────────────────────────────╯

See docs/DEMO.md for the full end-to-end walkthrough.

CLI

mq-agent audit .                   # Read-only repo audit
mq-agent release-plan              # Show release plan
mq-agent release-check             # Validate release readiness (suggest mode)
mq-agent release-check --approve   # Execute checks
mq-agent repo-summary .            # Quick repo overview
mq-agent run "pytest" --approve    # Safe shell execution
mq-agent fix-ci                    # Diagnose CI failures
mq-agent doctor                    # Check environment
mq-agent tools                     # List registered tools
mq-agent tools --mcp               # Include discovered MCP tools
mq-agent tools --describe <name>   # Show tool metadata and safety class
mq-agent mcp status                # Check mq-mcp reachability and tool counts
mq-agent mcp tools                 # List all MCP tools with safety classes
mq-agent run-tool <tool>           # Run an MCP tool through safety gates
mq-agent review file <path>        # Review one file through mq-mcp
mq-agent review diff               # Review current diff through mq-mcp
mq-agent review repo [path]        # Review repo through mq-mcp
mq-agent review file <path> --fast # Prefer Class A tools (mq-mcp routes)
mq-agent review diff --fast
mq-agent review file <path> --architecture-image docs/arch.png
mq-agent learn status              # Check mq-mcp learn system
mq-agent learn search <query>      # Search learned review patterns
mq-agent learn explain <pattern>   # Fetch pattern explanation
mq-agent dashboard                  # Operator snapshot: stack, brain, Ollama, contracts
mq-agent stack loop                 # Controlled autonomous stack loop
mq-agent stack loop --execute --approve
mqlaunch agent → 19                 # Manual stack loop plan from the menu
mq-agent tui                       # Launch Textual dashboard

# All commands support --dry-run and --json
mq-agent audit . --dry-run
mq-agent run-tool read_repo_file --arg path=README.md --dry-run

Review commands are pass-through orchestration for mq-mcp review tools. They route to review_file, review_diff, review_repo, or supported risk review tools through MCPBridge; mq-agent does not implement local review logic, severity scoring, architecture reasoning, or risk classification.

Safety modes

read-only   → only read tools allowed
suggest     → plan shown, nothing executed (default for most commands)
execute     → runs after safety check (requires --approve for destructive ops)
dangerous   → no restrictions (requires explicit flag)

Architecture

mq_agent/
├── core/
│   ├── state.py          # AgentState, PlanStep, SafetyMode, StepStatus
│   ├── planner.py        # OpenAI-backed plan generation
│   ├── executor.py       # Tool routing + safety enforcement
│   ├── verification.py   # OpenAI-backed result verification
│   ├── memory.py         # Session + persistent memory
│   └── safety.py         # Safety gate (mode enforcement)
├── tools/
│   ├── git_tools.py      # git_status, git_log, git_diff, git_branch, git_remote
│   ├── shell_tools.py    # run_command (blocked pattern list)
│   ├── repo_tools.py     # repo_summary, list_files, read_file, find_files
│   ├── signal_tools.py   # repo_scan, repo_readme_score, repo_publish_checklist, repo_analyze
│   └── mcp_bridge.py     # HTTP bridge to mq-mcp
├── agents/
│   ├── audit_agent.py    # Repo audit (read-only)
│   ├── release_agent.py  # Release validation
│   ├── ci_agent.py       # CI failure diagnosis
│   ├── docs_agent.py     # Documentation audit
│   └── signal_agent.py   # repo-signal static scan + AI improvement plan
├── tui/
│   └── app.py            # Textual dashboard
├── prompts/
│   ├── planner.md        # System prompt for Planner
│   └── verifier.md       # System prompt for Verifier
└── tasks/
    ├── release.yaml      # Declarative release task
    ├── audit.yaml        # Declarative audit task
    └── fix_ci.yaml       # Declarative CI fix task

Proof

• 408+ tests pass — uv run pytest -v — no OpenAI calls required
• mq-agent score . — 100/100 README, 16/16 publish checklist [PASS]
• mq-agent doctor — all required checks pass
• mq-agent audit . --dry-run — safe, read-only plan generation
• mq-agent signal . --dry-run — repo-signal assessment without execution
• Safety modes documented and enforced — dangerous patterns blocked at tool level
• --dry-run and --json supported on all commands

uv run pytest tests/ -v

Docs

• Command reference
• Command surface
• Architecture
• MQ control plane
• Memory engine
• Safety contract
• Ollama-backed learn extraction
• mq ecosystem
• Skills
• Examples
• Safety
• Roadmap
• Release checklist
• Contributing
• Changelog

v1.18.0 status

• mq-agent memory ingest — local mqobsidian Markdown index
• mq-agent memory query / memory search-vault — read-only vault search
• mq-agent memory summarize — section summary across truth, reviews, learn, releases, architecture and decisions
• mq-agent memory link — read-only link candidates between notes
• docs/MEMORY_ENGINE.md
• Write-backed links deferred to a later explicit approval flow

v1.19.0 status

• mq-agent dashboard — read-only operator snapshot for stack health, contracts, mqobsidian truth freshness and Ollama profile status
• mq-agent tui — starts with the same operator snapshot before command execution

v1.17.0 status

• mq-agent models — first-class Ollama model runtime command group
• mq-agent models list/current/switch/bench
• Model profiles persisted in ~/.mq-agent/models.json
• mq-agent stack run surfaces the active model profile in the Ollama check
• v1.17.0 release docs/status sync
• Full suite and stack gates before PR

v1.16.0 status

• mq-agent stack run — one runtime gate for repo-signal, mq-mcp, Ollama, brain export rendering and release readiness
• mq-agent run --stack — canonical root alias for the stack runtime pipeline
• Runtime output supports --json and --markdown
• docs/MQ_CONTROL_PLANE.md — system map for signal, review, learn, memory and release
• v1.17.0 set as next focus: Ollama runtime

v1.15.0 status

• mq-agent stack cockpit — one merged view of the whole stack: version, branch, contract, release gate, brain-export freshness, next action per repo
• Flag contract enforced across the command surface: --dry-run never writes, --json machine-readable, --brain respects --dry-run, --approve required for write flows (locked by tests/test_flag_contract.py)
• mq-agent brain structure — standard mqobsidian export structure: check, --init --approve, legacy detection
• mq-agent stack brain-gate — pre-release checklist: contract-check + release-check + truth-export dry-run + vault structure + review→brain write path
• Fixed: signal --brain --dry-run no longer writes to the brain
• docs/STACK_COCKPIT.md, docs/VAULT_STRUCTURE.md, docs/BRAIN_GATE.md — reference docs
• 56 new tests (511 total)

v1.14.0 status

• mq-agent stack release --repo <name> — orchestrated single-repo release pipeline
• Dry-run by default; --execute applies; --bump patch|minor|major or explicit --version
• Release-check pre-gate, version bump, contract sync, changelog from release-notes draft
• Release commit, tag, push, closing truth-export to mqobsidian
• Abort on first failed step with pre-commit rollback — no half-released repos
• docs/STACK_RELEASE.md — reference doc
• 27 new tests (455 total)

v1.13.0 status

• mq-agent stack truth-export — durable stack truth note (contract + release gates) to mqobsidian
• mq-agent stack export kept as backwards-compatible alias
• Default note path: ~/mqobsidian/memory/stack-truth/YYYY-MM-DD-mq-stack-truth.md
• stack contract-check --ci / stack release-check --ci — CI mode with SKIPPED for missing repos
• mq-stack-gate.yml split: fast --ci gate on PRs, full multi-repo gate on main/nightly
• docs/STACK_TRUTH_EXPORT.md — reference doc
• 25 new tests (439 total)

v1.12.0 status

• .github/workflows/mq-stack-gate.yml — CI workflow for MQ stack gates
• CI checks out active MQ stack repos and links them to expected ~/... paths
• mq-agent stack contract-check --json runs on pull requests and pushes to main
• mq-agent stack release-check --json runs on pull requests and pushes to main
• Stack drift and release blockers now fail CI before merge

v1.11.0 status

• mq-agent stack contract-check — validates .mq/repo-contract.json across all stack repos
• mq-agent stack contract-check --json — machine-readable output
• _contract_entry() helper with READY / REVIEW / DRIFT / BLOCKED status model
• schemas/mq_stack_repo_contract.schema.json — JSON Schema for contract manifests
• .mq/repo-contract.json deployed to all 8 MQ stack repos
• docs/STACK_CONTRACT_GATE.md — reference doc
• 19 new tests (408 total)

v1.10.0 status

• mq-agent stack release-notes — draft notes from git commits since last tag, per repo
• mq-agent stack release-notes --repo <name> — single repo filter
• mq-agent stack release-notes --json — machine-readable output
• docs/STACK_RELEASE_NOTES.md — reference doc
• 13 new tests (389 total)

v1.9.0 status

• mq-agent stack report — score, trend, alert, readiness per repo in one table
• mq-agent stack report --json — machine-readable
• mq-agent stack release-check — local release gate across all stack repos (exit 1 on blocker)
• mq-agent stack release-check --json — GO/NO-GO with per-repo detail
• docs/STACK_REPORT.md — reference with example output and workflow
• 15 new tests (376 total)

v1.8.0 status

• mq-agent stack alert — exits 1 when a repo drops ≥ threshold or falls below min-score
• mq-agent stack sweep --alert — inline alert check at the end of a sweep
• --threshold N / --min-score N — configurable thresholds
• --json — machine-readable alert list, CI-friendly exit codes
• docs/STACK_ALERT.md — reference with CI integration examples
• 18 new tests (361 total)

v1.7.0 status

• mq-agent stack sweep appends every run to ~/.mq-agent/sweep-history.jsonl
• mq-agent stack history — tabular trend view across last N sweeps
• mq-agent stack history --diff — delta table between last two sweeps
• mq-agent stack history --json / --limit N — scripting and filtering
• docs/STACK_HISTORY.md — reference with example output and JSON scripting
• 13 new tests (343 total)

v1.6.0 status

• mq-agent stack sweep — loop repo-signal over all mq-stack repos in one pass
• mq-agent stack sweep --brain — write a brain note per repo to mqobsidian
• mq-agent stack sweep --decide — consolidated health ADR via brain_record_decision
• mq-agent stack sweep --dry-run — preview without writes
• mq-agent stack sweep --json — machine-readable summary table
• mqlaunch agent menu item 18 — Stack health sweep
• docs/STACK_HEALTH.md — multi-repo sweep reference with example output

v1.5.0 status

• End-to-end demo flow: mq-agent signal . --brain → mq-agent review repo . --brain → mq-agent release-check --dry-run
• mqlaunch/commands/demo-flow.sh — standalone chain script
• mqlaunch agent menu item 17 — Demo flow (full stack)
• docs/DEMO.md rewritten as canonical v1.5.0 reference

v1.4.0 status

• mq-image-analyze MCP endpoint registered for visual perception tools
• mq-agent run-tool observe_architecture routes through mq-image-analyze
• mq-agent run-tool image_ocr routes through mq-image-analyze
• mq-agent review file|diff|repo --architecture-image <path> adds visual_architecture_observation.v1 context
• Image-analysis tools remain delegated; mq-agent does not implement perception locally

v1.3.0 status

• Architecture-memory context surfaced automatically after review findings (list_architecture_decisions)
• --fast flag on all review commands — mq-mcp routes to Class A tools
• mq-agent learn status/search/explain — read-only access to mq-mcp learned patterns
• Optional Ollama-backed learn extraction documented as an mq-mcp-owned policy
• MultiMCPBridge._call_optional_tool() — silent None when tool not available
• 292 tests pass — uv run pytest -v — no OpenAI calls required

v1.1.0 status

• mq-agent review file/diff/repo — pass-through review orchestration via mq-mcp
• --security, --architecture, --risk flags forwarded to mq-mcp review contracts
• --dry-run on all review commands — shows planned mq-mcp call without executing
• validate_orchestration_contract in mq-agent doctor
• 252 tests pass — uv run pytest -v — no OpenAI calls required for test suite

v1.0.0 status

• Stable orchestration platform — all contracts locked, full docs, complete examples
• cli/render.py + core/diagnostics.py — orchestration logic extracted from main.py
• Planner wired to MqAgentConfig.effective_model() — config-driven model selection
• 237 tests pass — uv run pytest -v — no OpenAI calls required for test suite

v0.9.0 status

• 14-test orchestration contract suite locking PlanStep, StepResult, AgentManifest, AgentState, tool registry, and run_task delegation
• mq_agent/config.py — MqAgentConfig dataclass with load/save and MQ_AGENT_MODEL env override
• Docstrings clarifying PlanStep vs StepResult boundary and SwarmRunner's role as a separate runtime
• 218 tests pass — uv run pytest -v — no OpenAI calls required

v0.8.0 status

• Controlled task runner workflows — mq-agent task list/run
• Browser-safe URL inspection and release verification
• Multi-agent swarm planning and dry-run workflows
• Orchestration stabilization checkpoint — docs/ARCHITECTURE.md
• Contract tests for no-API command behavior and registry stability
• 211 tests pass — uv run pytest -v — no OpenAI calls required

v0.5.1 status

• Planner (OpenAI gpt-4o, structured JSON output)
• Executor (tool registry, dry-run, safety gate)
• Verifier (OpenAI gpt-4o-mini, per-step verification)
• Memory (session + persistent JSON)
• Safety (read-only / suggest / execute / dangerous)
• Git tools, shell tools, repo tools
• MCP bridge (mq-mcp over HTTP) with safety classification
• Audit agent, Release agent, CI agent, Docs agent, Signal agent
• Textual TUI, JSON output, --dry-run on all commands
• mq-agent doctor — full environment check
• mq-agent mcp status / mq-agent mcp tools — MCP inspection
• mq-agent tools --describe <name> — tool metadata and safety class
• mq-agent run-tool <tool> — MCP tool through safety gates
• MCP safety classes: read-only / write-capable / subprocess / dangerous / unknown
• mqlaunch bridge — 19-item agent menu + 6 direct prompt commands
• scripts/smoke-mqlaunch.sh — verifies mqlaunch agent ... reaches mq-agent
• docs/MQLAUNCH_INTEGRATION.md — bridge architecture and usage
• docs/COMMAND_SURFACE.md — single source of truth for command counts
• 94 tests pass — uv run pytest -v — no OpenAI calls required
• Semantic repository memory — mq-agent memory status / build / refresh
• mq-agent memory doctor — diagnose memory environment with actionable fixes
• mq-agent memory status --json / mq-agent memory doctor --json — machine-readable output

Semantic repository memory

mq-agent v0.5.0 adds semantic repository memory via repo-signal.

mq-agent memory status                # check vector store and repo-signal
mq-agent memory doctor                # diagnose environment with actionable fixes
mq-agent memory build .               # preview upload (dry-run default)
mq-agent memory refresh . --approve   # upload when ready
mq-agent memory status --json         # machine-readable output

Memory upload is explicit and gated. mq-agent never uploads silently.

Verified output

$ mq-agent memory status
╭────────────────────────────── Semantic Memory ───────────────────────────────╮
│ status:       missing-vector-store                                           │
│ vector store: (not set — export OPENAI_VECTOR_STORE_ID)                      │
│ repo-signal:  available                                                      │
│ repo:         /path/to/mq-agent                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

$ mq-agent memory build .
[dry-run] Would run: repo-signal semantic-upload
Add --no-dry-run to execute, or use memory refresh --approve.

$ mq-agent memory doctor
╭──────────────────────── Memory Doctor ───────────────────────────╮
│ ✗ OPENAI_VECTOR_STORE_ID: (not set)                              │
│   fix: export OPENAI_VECTOR_STORE_ID=vs_...                      │
│ ✓ repo-signal: available                                         │
│ ✓ repo path: /path/to/mq-agent                                   │
╰──────────────────────────────────────────────────────────────────╯

See docs/SEMANTIC_MEMORY.md.

mqlaunch integration

mq-agent is fully wired into mqlaunch as both a direct command surface and an interactive menu.

mqlaunch agent
mqlaunch agent score .
mqlaunch agent audit .
mqlaunch agent doctor
mqlaunch agent release-check --dry-run
mqlaunch agent mcp-status
mqlaunch agent mcp-tools

See docs/COMMAND_SURFACE.md for the canonical command surface and docs/MQLAUNCH_INTEGRATION.md for bridge details.

Roadmap

See docs/ROADMAP.md for the current roadmap.

Current direction:

• send stack gate results to the brain (--brain)
• keep mq-agent orchestration-only
• keep review logic, learn extraction, memory and risk reasoning in mq-mcp
• improve mq ecosystem integrations without adding hidden autonomy

Notes

Do not commit API keys, local secrets, or private environment files.