Build on Repowise

Repowise exposes the same index through several surfaces. Pick the one that matches what you are building, then rely on the contracts marked stable below.

Pick a surface#

REST API#

repowise serve publishes its own reference: /openapi.json, Swagger UI at /docs and ReDoc at /redoc, on http://127.0.0.1:7337 by default.

Each GitHub release carries the same document as an asset, so you can fetch the spec for the version you run without starting a server:

curl -L -o openapi.json \
  https://github.com/repowise-dev/repowise/releases/latest/download/openapi.json

Every operation in the release asset carries x-repowise-stability:

Things the schema cannot state, such as which routes make model calls, error shapes, the two SSE streams and shared conventions, are in the REST API notes.

Authentication#

Tokens are stored as SHA-256 hashes. The same check guards REST, the MCP streamable HTTP and SSE transports, and chat, which runs only the tools in the caller's scope. MCP over HTTP serves an RFC 9728 protected-resource document; set REPOWISE_PUBLIC_URL behind a proxy. Webhooks verify their own signatures. Details: environment variables and security.

# ~/.repowise/tokens.yaml
tokens:
  - id: ci-bot
    sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  # hex SHA-256 of the token
    repos: [payments-api]
    tools: [get_change_risk, get_risk]
    expires_at: 2027-01-31T00:00:00Z

Python change review#

repowise.core is importable on its own, with no server and no database session. A bot or CI job can review a change in one call, from a checkout or from bytes:

from repowise.core.analysis.change_review import ChangeReviewRequest, ChangeReviewService
from repowise.core.analysis.change_health import GitRevisionSource

service = ChangeReviewService(GitRevisionSource("."), repo_path=".")
bundle = service.review(ChangeReviewRequest(revspec="HEAD"))
print(bundle.directive.status, bundle.directive.headline)

Full reference: CHANGE_REVIEW_API.md.

Events#

Each repowise init and update snapshots every component and stores what moved as a typed event: ownership shift, owner inactive, bus factor drop, new hotspot, contract added or broken, decision stale, dead-code growth, test reach drop.

repowise events --since 7d --format jsonl     # CloudEvents 1.0.2, one per line
curl -H "Authorization: Bearer $KEY" \
  http://127.0.0.1:7337/api/repos/$REPO_ID/events

Events are also appended to .repowise/events.jsonl, and the event-sink seam delivers them anywhere else.

Versioned contracts#

These shapes carry a version number and change only with a version bump:

Plugins and seams#

An installed Python package extends Repowise through the repowise.plugins entry point, or through REPOWISE_PLUGINS=module:attr for a quick local test. Each extension point is a named seam with a local default:

# pyproject.toml of your plugin package
[project.entry-points."repowise.plugins"]
acme = "acme_repowise:register"

# acme_repowise/__init__.py
def register() -> None:
    from repowise.core.registry.plugins import SeamRegistry

    SeamRegistry("event-sink").register("acme", AcmeSink(), default=True)

repowise plugins lists what loaded, what failed and which implementation each seam uses. REPOWISE_SEAM_<NAME> picks an implementation by name. A plugin can add CLI commands but never replaces a built-in one, and a repository's .repowise/.env cannot select plugins.

For coding agents#

An agent building on Repowise needs three files:

• https://docs.repowise.dev/llms.txt: the index of these docs.
• openapi.json from the latest release: every REST route with its stability label.
• MCP tools: the tool surface and response fields.

Build on stable routes and versioned contracts only, and read _meta on every MCP response to know which commit the answer came from.