Skip to content
Shipper

shipper_create_issue

shipper_create_issue

Section titled “shipper_create_issue”

Create a new store-backed Shipper issue from a plain-text request. Runs the headless shipper new workflow; the agent drafts under .shipper/output/, then Shipper validates, writes the local record, and returns its local identity. When issue mirroring is enabled, Shipper also creates a GitHub issue with shipper:new and returns its GitHub number and URL. The default-false layered assignMirroredIssuesToSelf preference can additively assign the current GitHub account to that new mirror; assignment failure returns a warning, not an error, and is not retried or maintained. Store-only mode never assigns. Requires a non-empty request.

When to use

Section titled “When to use”

On macOS, this tool prevents idle system sleep through validation, repository preparation, and issue creation. See Keep the Mac awake during active work. Use this when the user has a plain-language request that should become a researched issue rather than immediate code changes. The headless agent writes a draft under .shipper/output/; Shipper validates it, writes the full title/body to the local issue-state store, and always returns the local S#<localId> identity. When issue mirroring is enabled, Shipper also creates the GitHub mirror with shipper:new and returns its GitHub number and URL. assignMirroredIssuesToSelf defaults to false, is eligible at user-global, repository, and personal scopes with most-specific precedence, and in mirror-on mode additively assigns the current GitHub account without replacing assignees. Assignment is best-effort and write-once: failure is an issue-specific Warning rather than a tool error, store-only mode never assigns, and later commands or reconciliation do not retry or maintain assignees. The same preference also covers grooming-created issues, adoption and PR tracking issues, and mirrors first created by reconcile. The transcript is used only for the final-message wrap-up.

Behavior hints

Section titled “Behavior hints”
  • openWorldHint: true — The tool reaches GitHub or other external systems outside the MCP server.

Input schema

Section titled “Input schema”
NameTypeRequiredDefaultDescription
requeststringyes-Plain-text request for the issue creation agent.

Example call

Section titled “Example call”
{
  "request": "Add generated MCP reference pages for the docs site"
}

Example result

Section titled “Example result”
Mirror-on result:
Created issue: S#42 (GitHub #123): Add generated MCP reference pages for the docs site
URL: https://github.com/owner/repo/issues/123


---
Created a scoped implementation issue.


Session log: /tmp/shipper/session.log


Store-only result:
Created issue: S#42: Add generated MCP reference pages for the docs site


---
Created a scoped implementation issue.


Session log: /tmp/shipper/session.log

Error modes

Section titled “Error modes”
  • Timed out worker: [timed out] shipper new —mode headless
  • Failed worker: [exit ] shipper new —mode headless
  • Mirror-on repair required: When issue mirroring is enabled, Shipper can fail to create or attach the GitHub mirror. Run shipper issue reconcile --repair.
Section titled “Related tools”