# GUIJam for Jira

> Turn Jira UI tickets into GUIJam prompts, and post every kept change back to its ticket with before/after screenshots, the file and line, and the diff.

GUIJam for Jira connects your running app to your team's tickets. A ticket's text and screenshots become your prompt, and whatever you apply, whether a direct edit or an AI variant, is posted back to the ticket once Undo is no longer offered. PMs, QA and designers see the result in Jira without running GUIJam.

- **Tickets in.** Link a ticket to an element in the Select or Draw panel. Its summary, description and up to four images fill your prompt.
- **Results out.** Before and after screenshots, the element's `file:line`, the diff, who applied it and how, and optionally a status move such as In Review.
- **Report to Jira.** Anyone running the app can file a ticket from an element, with its screenshot and source location already in it.
- **For the team in Jira.** A GUIJam panel on every ticket, a **Send to GUIJam** action, and JQL such as `guijamStatus = queued`.

## How the pieces fit

GUIJam runs on the developer's machine while they work on their app. The GUIJam for Jira app runs inside Jira Cloud. They talk over one HTTPS connection, set up once by pairing.

On the developer's machine: the app in the browser with the GUIJam toolbar, the dev server with the guijam plugin, the gjd daemon (the only writer to files, which holds posts for the undo window and keeps the pairing token), and the AI coding CLI for AI requests. In Jira Cloud: the GUIJam for Jira app (GUIJam panel, Send to GUIJam, JQL, MCP tools; no AI) and the team, who see results without GUIJam. They talk over HTTPS with a pairing token.

## The whole flow

1\. Jira admin: Installs GUIJam for Jira. 2. PM, QA, designer: Creates a project and UI tickets. 3. Developer: Runs guijam init and pairs. 4. Developer: Links a ticket to an element. 5. GUIJam: Fills the prompt with the ticket text and images. 6. Developer: Edits directly or asks AI, then applies. 7. GUIJam: Writes the file and waits 10 seconds. 8. Jira: Gets before/after, file:line, the diff and the status. 9. PM, QA, designer: Reviews it in the GUIJam panel.

## A ticket's GUIJam status

Not linked, then Sent to GUIJam (Send to GUIJam), then In progress (a developer links it), then Applied (the change is posted), then Reverted (undone after posting).

A developer can also link a ticket that was never sent to GUIJam.

## The 10-second undo window

After Apply, Undo is offered for 10 seconds and nothing is posted if you undo. Then the change is posted. Undo later and the ticket is marked Reverted.

## Who does what

| Role                 | What they do                                                                                                                                                                       | Where                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| **Jira admin**       | Installs GUIJam for Jira once per site and approves its permissions.                                                                                                               | Jira                                 |
| **PM, QA, designer** | Writes UI tickets with screenshots, sends them to GUIJam, reviews results in the ticket's GUIJam panel. QA and designers running the app can also report to Jira from any element. | Jira, and optionally the running app |
| **Developer**        | Installs GUIJam in the project, pairs it with Jira once, links tickets to elements, and applies changes by editing directly or asking their AI CLI.                                | Their app and a terminal             |

## What you need

- A **Jira Cloud** site where someone is an admin, to [install GUIJam for Jira](https://developer.atlassian.com/console/install/9f6e7bd4-561f-42c1-967c-534533ca84fd?signature=AYABeNHZxmIIzqskV6bj6ZDb2BwAAAADAAdhd3Mta21zAEthcm46YXdzOmttczp1cy13ZXN0LTI6NzA5NTg3ODM1MjQzOmtleS83MDVlZDY3MC1mNTdjLTQxYjUtOWY5Yi1lM2YyZGNjMTQ2ZTcAuAECAQB4CxqLTo9l4lqXuFjNim1xJM%2Bp%2F3TVP9xHS2BrU5DRRucB9X7SgA05cnObTkvhYN1xbQAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDNEhzAe7TPWDBVqk6wIBEIA7keQSd6CapbYmtUGdkeKKsGD9awYJ3ooCpMpwMF2EDUNbpBp%2F9PeiHpLYzLpKRCnH1ToDtNvaJyOei0kAB2F3cy1rbXMAS2Fybjphd3M6a21zOmV1LXdlc3QtMTo3MDk1ODc4MzUyNDM6a2V5LzQ2MzBjZTZiLTAwYzMtNGRlMi04NzdiLTYyN2UyMDYwZTVjYwC4AQICAHi9bVMAkme4qVQX1fQHo6ePw3H40A7cGfz7yrmSfBWMXgEaeJ%2BkdCobmSDv47DLtIySAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMGEExVBpjK5bbUYmTAgEQgDvy5cWJv19sweBbrSFr5C3xdwywv%2BBv20pRtihL1aMr7o8uQnVvR9vasue1xGfDidyWyh8RzUzmiGXFBQAHYXdzLWttcwBLYXJuOmF3czprbXM6dXMtZWFzdC0xOjcwOTU4NzgzNTI0MzprZXkvNmMxMjBiYTAtNGNkNS00OTg1LWI4MmUtNDBhMDQ5NTJjYzU3ALgBAgIAeDYASx0XCjkny4iLV6vz%2BKtEGSGT6kdt0QRpkn6D%2FlVEAWqyfoA4bYp55SbOGUdCdOkAAAB%2BMHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwmXimEV%2FsYgm0GihwCARCAO2yT52i7N%2B%2BDNBN%2F2F87pJutoitrvTBVazhVeMuRbv%2BmP8xV9sDbTccsGcHKl%2BfdohjSFjjtL%2BQGx983AgAAAAAMAAAQAAAAAAAAAAAAAAAAAKlWUN4JXPX85evX3RKxCVz%2F%2F%2F%2F%2FAAAAAQAAAAAAAAAAAAAAAQAAADLbFlcEhVS0TGlPnle4N%2FWi6ZPs4%2FxogfU6%2BLKHwDp0vbTyhpPRk4JYHRWIvoxpoJGa%2F4o%2Fn8CSg1cuvGh0MKv91WQ%3D\&product=jira) once. A free developer site works: [go.atlassian.com/cloud-dev](https://go.atlassian.com/cloud-dev).
- **Node** `^20.19.0` or `>=22.12.0`, and a [supported framework](https://guijam.francistinao.com/docs/frameworks/vite).
- An **AI coding CLI**, only for AI requests. Direct edits of text, color and corner radius need no AI at all.

Next: [Set up GUIJam for Jira](https://guijam.francistinao.com/docs/jira/setup).
