shipper_monitor

shipper_monitor

Return one complete, fresh snapshot of current Shipper workflow conditions without mutation. Each call independently captures the repository-wide or requested single-issue baseline; include_progress optionally adds ordinary progress. The tool does not paginate, replay, continue, or wait. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.

When to use

Omit repository_path to use the active repository, or supply a local checkout path in repository_path to select that repository for this call only. Explicit targets remain usable when active startup is degraded, do not count as active-repository work, and never change ambient server state. The successful response shape is identical for active and targeted calls. Use this read-only tool for one complete current baseline of actionable workflow conditions across the repository or for one issue. Every call independently makes a fresh stable capture and returns the entire applicable snapshot in one response. include_progress controls whether current ordinary forward progress appears in that snapshot. The tool does not wait and provides no continuation or replay; use shipper monitor --jsonl for continuous, replay-oriented, or waiting workflows.

Behavior hints

• readOnlyHint: true — The tool only reads state and does not intentionally modify the repository.
• idempotentHint: true — Retrying the same call is expected to be safe once the target state is reached.
• openWorldHint: false — The tool does not reach GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
issue	string | integer	no	-	Optional Shipper/GitHub issue reference that limits this complete current snapshot to one issue.
include_progress	boolean	no	-	Include ordinary forward workflow progress in this current snapshot.
repository_path	string	no	-	Optional repository path to an existing local git checkout to select for this read only. Omit it to read the active repository.

Output schema

Name	Type	Required	Default	Description
schemaVersion	number	yes	-	-
attachment	object	yes	-	-
observedAt	string	yes	-	-
records	array	yes	-	-
context	object	yes	-	-
classifiedOutcome	enum: clean, workflow_regression, human_action_required, monitor_integrity_failure	yes	-	-
terminationReason	enum: observing, target_reached, operator_interrupted, stop_condition, resync_required	yes	-	-
error	object | null	yes	-	-

Example call

{
  "issue": "S#42",
  "include_progress": true,
  "repository_path": "/absolute/path/to/selected/checkout"
}

Example result

{
  "structuredContent": {
    "schemaVersion": 1,
    "attachment": {
      "schemaVersion": 1,
      "attachmentId": "attachment-id",
      "attachedAt": "2026-09-04T12:00:00.000Z",
      "scope": {
        "kind": "issue",
        "repository": { "kind": "named", "repo": "owner/repo", "storageKey": "owner-repo" },
        "issue": {
          "localId": 42,
          "githubIssueNumber": 2156,
          "displayRef": "S#42",
          "title": "Example issue"
        }
      },
      "includeProgress": true,
      "startStage": "shipper:planned"
    },
    "observedAt": "2026-09-04T12:00:00.000Z",
    "records": [],
    "context": { "suppression": null },
    "classifiedOutcome": "clean",
    "terminationReason": "observing",
    "error": null
  }
}

Error modes

• Invalid issue input: The issue value is malformed, unknown, foreign to the selected repository, or cannot be resolved. Correct the issue input and retry.
• Monitor integrity failure: A required source is incompatible or authoritative durable facts disagree. The error batch contains no partial records.
• Invalid or unready repository target: Repository identity could not be established for . The repository has no commits. Create an initial commit. Correct this condition and retry the repository read with repository_path.

Related tools

• shipper_status
• shipper_get_issue