repo-signal

What problem does this solve? You have a local repo — maybe a prototype, a side project, or a tool in progress. It works, but the README is thin, the docs are missing, the version is out of sync, and you don't know if it's actually ready to publish. repo-signal tells you exactly what's wrong and what to fix next.

Who is this for? Developers who build small tools and want structured signals for when something is actually ready. Works standalone or as a backend contract for AI agent workflows.

repo-signal turns local repository state into clear analysis reports, publish-readiness signals, and machine-readable JSON contracts for AI-assisted development workflows.

MQ stack architecture

repo-signal is part of the MQ stack. It produces repo intelligence and observations; it does not own durable memory. Whole-stack architecture and the memory loop are documented in mqobsidian (source of truth): docs/architecture/mq-stack.md.

---

Install

Recommended for the MQ stack:

uv tool install repo-signal

Verify the CLI is available:

repo-signal --version

If the uv tool bin directory is not on PATH, run:

uv tool update-shell

pipx install repo-signal remains a supported alternative.

Current local development install:

git clone https://github.com/MCamner/repo-signal.git
cd repo-signal
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[ai]"

See PyPI publishing guide for the release workflow.

---

Usage

Use repo-signal from the root of any local Git repository. The normal loop is:

repo-signal analyze              # orient around repo type, stack and focus areas
repo-signal inspect              # fast status and recommended next commit
repo-signal review-export .      # write repo-review.v1 to mqobsidian/reviews
repo-signal doctor               # static repo health, docs, release and AI-readiness signals
repo-signal publish-checklist .  # public release-readiness gate

For automation, prefer JSON outputs such as repo-signal inspect --json, repo-signal doctor --json, and repo-signal publish-checklist . --format json.

---

Try this in 60 seconds

# Get a high-level overview
repo-signal analyze

# Fast status report and next commit suggestion
repo-signal inspect

# Machine-readable status for integrations
repo-signal inspect --json

# Full readiness diagnosis
repo-signal doctor

# Check public-readiness signals
repo-signal publish-checklist .

---

Command Surface

Stable commands:

repo-signal
├── analyze            # Front-door orientation
├── inspect            # Fast status and next commit
├── inspect --json     # Machine-readable inspect.v1 contract
├── doctor             # Full readiness diagnosis
├── publish-checklist  # Public signal quality gate
├── report             # Unified report — inspect + publish-checklist in one
├── report --json      # Machine-readable report.v1 contract
├── suggest            # Safe patch suggestions — read-only, no mutations
├── suggest --json     # Machine-readable suggest.v1 contract
├── repoaware          # AI context export
└── demo               # Generate example reports

Stable JSON contracts: inspect.v1 · doctor.v1 · report.v1 · suggest.v1

See the Command Reference and Roadmap for full details.

---

Screenshots

---

Examples

• Report (text)
• Report (JSON — report.v1)
• Suggest (text)
• Suggest (JSON — suggest.v1)
• Inspect (text)
• Inspect (JSON — inspect.v1)
• Doctor (text)
• Doctor (JSON — doctor.v1)
• Analyze

Generate your own local demo reports:

repo-signal demo --generate

---

Use with AI agents

repo-signal is designed as a backend contract for AI agent workflows. All stable commands have JSON output that agent tools can consume safely:

# Check schema before parsing
repo-signal inspect --json . | python3 -c "
import json, sys
d=json.load(sys.stdin)
assert d['schema'] == 'inspect.v1'
print(d['recommended_next_commit'])
"

See Integrations for mqlaunch, mq-agent, mq-mcp, and mq-hal patterns.

---

Documentation

Live docs: mcamner.github.io/repo-signal

Contracts:

• Inspect Schema — inspect.v1 field reference
• Doctor Schema — doctor.v1 field reference
• Report Schema — report.v1 field reference
• Suggest Schema — suggest.v1 field reference, no-mutation guarantee
• Review Export Schema — repo-review.v1 Markdown contract
• Memory Observation Schema — memory-observation.v1 producer fields
• mqobsidian Boundary — who owns what across both export paths, and how each fails

Usage:

• Command Reference — Detailed CLI usage and flags
• Integrations — How mqlaunch, mq-mcp, mq-hal, and Bridget consume JSON contracts
• RepoAware — High-signal AI context ranking and export
• Semantic Memory — Uploading symbol maps to vector stores

Publishing:

• Packaging — PyPI / CLI tool readiness plan and packaging smoke tests
• PyPI — Real PyPI publishing guide and Trusted Publisher values
• Generated Examples — How examples are generated and verified before release
• Roadmap — Release direction and stability checklist

---

Roadmap

Current focus is keeping the v1.x contracts stable while improving the quality of repo-aware context for AI tools. Near-term work:

• keep inspect.v1, doctor.v1, report.v1, and suggest.v1 stable
• exclude generated noise such as backup folders from entrypoint detection
• improve symbol extraction for non-Python repos, especially PowerShell-heavy tools
• keep examples and generated reports current for downstream agents

See ROADMAP.md for the full roadmap.

---

Contributing

Contributions should preserve the stable JSON contracts and keep commands safe for automation. Before opening a PR, run:

pytest
repo-signal doctor . --json
repo-signal publish-checklist . --format json

When changing CLI output, update the matching docs and examples so agent integrations keep a reliable contract.

---

Local verification evidence (development)

repo-signal doctor . --verification --json separates structural scores from mq-agent's validation of an existing changed-file receipt. Without this opt-in, verification is NOT_VERIFIED. Tests and CI are never inferred to have passed from file presence or a 100/100 score. mq-agent with verify-changes support must be installed; no checks are executed by doctor. See Doctor schema.

v1.9.0 status

• 4 stable JSON contracts: inspect.v1, doctor.v1, report.v1, suggest.v1
• 2 documented export contracts: repo-review.v1, memory-observation.v1
• Full test suite passes — 431 passed, 221 subtests on Python 3.11 and 3.12, and from a checkout directory that is not named repo-signal
• Schema checks in release.sh for all four stable contracts, plus an mqobsidian export contracts section covering both export paths
• Contract docs: INSPECT_SCHEMA.md, DOCTOR_SCHEMA.md, REPORT_SCHEMA.md, SUGGEST_SCHEMA.md, REVIEW_EXPORT_SCHEMA.md, MEMORY_OBSERVATION_SCHEMA.md
• Generated examples: examples/report/, examples/suggest/, examples/inspect/, examples/doctor/, examples/review-export/
• No machine-local path reaches an exported artifact — a shape invariant in repo_signal/redaction.py, not a convention
• A scan describes the repository, not the machine: it asks git what belongs to the repo, so gitignored local tool directories cannot reach a generated example. Held by a test that asks git for the ignored set rather than hard-coding it
• The mqobsidian boundary is proven end to end against a temporary vault: ownership, both export paths, and what each does when the vault is missing, unwritable or the wrong shape — docs/MQOBSIDIAN_BOUNDARY.md
• The 26 top-level commands are declared once in repo_signal/commands.py; help, the unknown-command fallback and docs/COMMANDS.md are held to it
• CLI surface frozen for v1.x
• GitHub Actions green (Tests on 3.11 and 3.12, the renamed-checkout run, Docs consistency, Packaging, Generated examples, Publish checklist)

See CHANGELOG.md for full release history.

---

Author

Mattias Camner

Infrastructure / Platform Architect
Builder of command surfaces, endpoint readiness prototypes, and structured workflow systems.

---

License

MIT