gadak

Follow the thread.

_{English · 한국어}

A local SQLite file of your Jira — so "which epic is stuck?" is one query, not an unaskable one.

gadak mirrors Jira and Confluence into one local SQLite file — issues, comments, history, wiki pages — indexed together and searchable locally. This window is where that work lives on your machine: triage it in the desktop app or a browser tab, or let a coding agent ask in plain SQL and point the same window at the answer. One binary, one app, no gadak account.

The mirror is a cache you can throw away. On a connected workspace, if this project stops tomorrow, you delete a directory and have lost nothing: Jira stays the source of truth.

▶  Open the live demo  —  534 issues, in your browser, right now.
Changelog  —  what shipped.

A connected site needs one API token — it covers Jira and Confluence on the same site. A standalone workspace needs no Atlassian account at all.

macOS app, CLI included:

brew install --cask midagedev/tap/gadak

CLI only — same UI in a browser tab via gadak serve:

brew install midagedev/tap/gadak-cli

Windows: from the latest release, download gadak_<version>_windows_amd64.zip (or windows_arm64), unzip, put gadak.exe on PATH. The desktop zip (Gadak-<version>-windows-x64.zip) is unsigned — if SmartScreen or Smart App Control blocks it, that is a missing signature, not a virus finding; use the CLI zip. Do not turn Smart App Control off.

Connect to Jira:

gadak init && gadak sync && gadak serve

Or start with no tracker:

gadak init --standalone
gadak create "the thing I just noticed"
gadak serve

gadak serve prints the address — open http://gadak.localhost:7777 and you should see your issues. Linux tarball, pairing, the signed macOS dmg: Install.

gadak sql "select epic_key, count(*) from issues_full where resolved_at is null
           and epic_key <> '' group by epic_key order by 2 desc"

That last query is the point: JQL has no GROUP BY. "Which epic is actually stuck?" is not a hard question — it is an unaskable one, until the data is a file. docs/RECIPES.md has the rest.

Run that query now, nothing installed: Datasette Lite loads the demo snapshot in this tab and the SQL runs client-side.

Measured 2026-08-23 against a live Cloud site (7,166 issues; medians, CLI startup included — method, the re-measurement history, and the losing rows):

The last row is the point: past a page size, JQL answers stop being slow and start being unaskable. GROUP BY is the same story — on the 2026-08-15 corpus the epic rollup measured 3,924 ms across 7 API pages against one 24 ms query; this run the REST aggregation matched no rows at all, because the project's epic shape had changed, so that comparison stands on the August 15 numbers.

And the other side: the first full sync measured 26.4 s for 534 issues and 7.2 min for 2,865 (method and the losing rows), every watch tick costs ~4.7 s on a quiet site even when nothing changed, and the mirror trails Jira by one sync interval.

Status: 0.17, still 0.x. Sync, read API, write-through, desktop, web, CLI, and MCP are verified against a live site. CHANGELOG.md.

Why

Jira search is a network round trip, and the wiki is a second search. An agent asked "what did we already fix, and what did we decide?" pages two REST APIs. Same cause: the data is not a file. docs/CONCEPT.md · docs/PAIN_POINTS.md.

⌘K is the one index — titles, bodies, comments, issues and pages. The chips on the list do not apply. That is why a comment-only word still finds the row.

_{Generated from e2e/demo/search-demo.spec.ts against the demo snapshot.}

Two surfaces, one store

Writes go through the origin, then the mirror refreshes. App and web: comment, transition, assign, labels, priority, title. CLI: create (single or --batch), attach, edit, comment, transition (--resolution), assign, link, dev link / dev scan, fields --apply, issue --editmeta, project create, and page create / page edit / page comment for the wiki (pages, titles, bodies and comments all through the origin). Hierarchy, item_refs, attachments: docs/CONCEPT.md. The window keeps one paper metaphor across four palettes — light, a neutral-cool dark, blue-black ink, and warm ember. The theme follows the system unless you pick one, and it belongs to the workspace, not the browser: gadak config set appearance.theme ink.

And two surfaces is not a closed list. Reading the mirror is one binary call (gadak search --json, ~20 ms), and opening anything in the app is one URL (gadak://view?issue=… — the scheme), so whatever can do those two things becomes a surface. A launcher, say:

_{Each keystroke is one gadak search --json; Enter is the deep link. A saved view travels the same way — gadak views open prints its link.}

That launcher exists: a Raycast extension that searches issues and wiki documents as you type, submitted to the Raycast Store. Until the review lands, one command installs it from the binary you already have (embedded, no checkout):

gadak raycast install

The macOS app has the same install as a button — Settings → Integrations lists Raycast, the agent skill and MCP, shows what is already installed, and runs the exact command it prints. Building on the extension itself: contrib/raycast/. And with no extension at all, a Raycast Quicklink pointed at gadak://view?issue={argument} covers the open-by-key half.

What's covered

Connected talks to Atlassian Cloud. Standalone (from 0.16) is a workspace with no Atlassian account — a minimal Jira origin that travels with the app. The mirror is a cache either way; every write goes through the origin. On standalone the durable file is the origin's persist file — issuetap.db in the workspace's origin folder (SQLite, WAL). Copy it while gadak is not running (include the -wal/-shm sidecars), or sqlite3 origin/issuetap.db ".backup dest.db".

1. SQL and FTS are local. --jql / a Jira URL maps a documented subset onto the in-memory filter; clauses gadak cannot express are listed, never dropped. Sprint-by-name, WAS, cross-field OR, and custom fields are among the refusals; numeric sprint = / sprint in and sprint in openSprints() are in the subset (decision 0007).
2. Dedicated endpoints for due date and description. Custom fields: kinds text, number, date, option, user, multi_option / version_array, gated by the issue's editmeta and the configured field allowlist. Cascading selects and textarea custom fields have no editor.
3. Epic grouping (epic_key, nearest hierarchy-level-1 ancestor) is first-class. Setting a parent is CLI create --parent / edit --parent only — there is no REST PUT {key}/parent. Sub-task create-meta flags are not surfaced, so create cannot tell that a type requires a parent.
4. Confluence Cloud is mirrored; page create, edit (title/body) and page comments write through it — gadak page create|edit|comment, POST pages/, PUT pages/{id}/edit, POST pages/{id}/comment.
5. Pages sync from the in-process origin. gadak page create|edit|comment and the REST verbs work here too; the UI has a page comment composer but no page editor yet.
6. Changelog is mirrored. Time in status is computed from status_changed_at, not stored as a column.
7. Jira's notification inbox, rules, and email are not mirrored. gadak has its own watch-feed OS alerts on macOS and Linux.
8. No board UI and no sprint column on the list. Sprint fields (sprint_id / sprint_name / sprint_state) are in the mirror; SQL and JQL (sprint = / sprint in openSprints()) can query them. The versions catalog and fix_version_ids join the same way.

Linear. A Linear workspace mirrors and writes through the same verbs: add a "linear" block (apiKey, optional teamIds) to the workspace's config.json and run gadak sync --source linear. Writes route by the mirror's source for the key — comment, transition (the team's workflow states, id-keyed), summary/priority/due-date edits, assign/unassign, and file attachments all pass through Linear's API and refresh the mirror row. Not yet: label edits, clearing a due date, and state history (status_changed_at stays NULL) each refuse honestly rather than half-applying; inline comment media attaches the file and drops only the body embed. Field mapping: internal/linear/MAPPING.md.

For agents

This is half the reason gadak exists. Reference: docs/MIRROR.md. One paste per host: docs/AGENT_SETUP.md.

gadak skill install

Schema and query patterns, no extra process. For hosts without a shell (Claude Desktop):

gadak mcp install claude

Pins this binary and workspace into the registration.

gadak init and gadak install-cli install that skill automatically when ~/.claude already exists. A file gadak did not write is left in place.

Both installs (and the Raycast one) are also buttons in the macOS app, with install state shown honestly: Settings → Integrations.

Setup is not a screen an agent has to click, either. Every field the settings dialog edits is a CLI verb over the same validation:

gadak config list

Every editable path and its value.

gadak config set appearance.theme ink

Per workspace, applied live.

SQL answers; the window presents. Filter on status_category / priority_rank (1 = most urgent, 0 = unset), never on a display name — Jira translates those per account, so priority = High is silently zero rows on a Korean-language site. --jql is Jira's own language and stores the literal, so prefer gadak sql when the filter is a rank or category:

gadak sql --no-header "select key from issues_full where status_category = 'inprogress'
                       order by status_changed_at asc limit 5" | gadak views open --keys -

If you already have JQL, the clauses land as chips. This one keys on a project key and emptiness, not a localized name:

gadak views open --jql 'project = NMA AND resolution is EMPTY'

_{gadak views open writes a one-shot hash; the running app or serve tab applies it. The recording adds a priority clause — in --jql a priority or status name is matched as the literal string your Jira stores, which is localized, so the example above leaves it out. Generated from e2e/demo/agent-demo.spec.ts.}

When the answer is a wall rather than a list, author a dashboard — one HTML document plus registered datasources, rendered sandboxed in the web tab: docs/DASHBOARDS.md.

For hosts without a shell (Claude Desktop), the same mirror is an MCP server. Ask the thing Jira cannot answer at all, because the wiki is a second search: "what do we know about X?" One index holds both, so the answer can put a ticket and the design doc that drove it in the same sentence.

_{Five tools; no writes to the mirror or to Jira. A host with a shell can use gadak sql instead. Setup: docs/MCP.md.}

gadak views open is the "open in gadak" verb; gadak open KEY leaves for Jira. The list box takes the same JQL paste as gadak search --jql; clauses gadak cannot express are listed, never dropped. What JQL still cannot ask stays in gadak sql and docs/RECIPES.md. gadak sql opens the file mode=ro; MCP's gadak_query rejects anything that is not a SELECT. gadak api is the pass-through for endpoints the mirror does not model — read-only unless --write, never on MCP.

An agent that reads your mirror sends what it reads to whatever model it talks to. gadak itself sends nothing (SECURITY.md). Scope the mirror to what the agent should see. When gadak does touch the network — sync, writes, the pairing model that lets a tailnet or a whole team share one workspace — docs/NETWORK.md walks every connection and its off switch.

Install

Atlassian Cloud, or (from 0.16) a standalone workspace with no Atlassian account. A connected site needs one API token — it covers Jira and Confluence on the same site.

1. The desktop app.

macOS: download Gadak-<version>-arm64.dmg from the latest release, drag to Applications. Signed and notarized. First launch walks through site, email, token, and projects. The CLI is inside the bundle; macOS does not put an app on your PATH:

/Applications/Gadak.app/Contents/Resources/bin/gadak install-cli

2. The CLI, on Linux, Windows, or for the same UI in a browser tab.

macOS + Linux:

brew install midagedev/tap/gadak-cli

Windows: from the latest release, download gadak_<version>_windows_amd64.zip (or windows_arm64) and checksums.txt. Unzip, put gadak.exe on PATH. This is the reliable Windows route. How to check the sha256: docs/WINDOWS-SIGNING.md.

The desktop zip (Gadak-<version>-windows-x64.zip, or windows-arm64) is unsigned (signing is GDK-211). If Windows shows Windows protected your PC or Smart App Control blocked an app that may be unsafe, that is a missing signature, not a virus finding — use the CLI zip above. Do not turn Smart App Control off. Install: docs/INSTALL.md. Code signing policy (why the warning, SHA256): docs/WINDOWS-SIGNING.md.

No Atlassian account:

gadak init --standalone
gadak create "the thing I just noticed"
gadak serve

gadak serve prints the address — open http://gadak.localhost:7777 and you should see your issues.

Already have Jira:

gadak init && gadak sync && gadak serve

gadak serve prints the address — open http://gadak.localhost:7777 and you should see your issues.

Pair another machine. Home gadak serve is the origin. On the home machine, mint an offer (stdout is one offer line):

gadak pairing mint --label laptop

On the remote, paste the offer:

gadak --workspace laptop init --pairing-code-stdin

Confirm with gadak --workspace laptop status (paired with "laptop"). gadak pairing list is the token table on home and one status line on the remote. gadak pairing revoke laptop is home only.

_home is this machine's routing token, not a device (revoke refuses it; mint --label _home rotates). Same verbs on the remote; a pairing: error is the whole message. --profile is an alias of --workspace. The gate is in SECURITY.md.

A Scoop manifest lives in contrib/scoop. The bucket is not published and scoop install has not been run on a Windows machine (docs/INSTALL.md).

Linux without Homebrew: from the latest release, download gadak_<version>_linux_amd64.tar.gz (or linux_arm64) and checksums.txt. One archive is the whole install — the web UI is inside the binary. Replace <version> with the tag from that release, without the leading v. Verify, unpack, and put gadak on PATH:

sha256sum --ignore-missing -c checksums.txt
tar -xzf gadak_<version>_linux_amd64.tar.gz

gadak serve

gadak serve prints the address — open http://gadak.localhost:7777 and you should see your issues.

Optional, to survive reboot (systemd --user):

gadak install-service

Arch Linux: a checked PKGBUILD lives in contrib/aur/gadak-bin — makepkg -si there. Not in the AUR yet; upstream registration is closed (docs/INSTALL.md).

On Omarchy, the bar can answer the one question no cloud plugin can — what changed in your mirror. A shell-plugin widget in contrib/omarchy shows open·stuck straight from the local mirror (no token, no network) and click-opens the app. Run once on a real guest.

Install script, release archive, source, Docker, wiki mirroring, workspaces, upgrades: docs/INSTALL.md.

The rest

Making it yours. Two axes, no forking: docs/EXTENDING.md. Config: docs/CONFIGURATION.md. Enrichments: docs/PLUGINS.md.

How it works. One binary, one SQLite file; incremental sync plus a reconcile pass. docs/ARCHITECTURE.md. Why not an extension or Forge app: docs/decisions/0003-local-process.md.

Good fit / bad fit. Daily search latency, an agent over tracker and wiki, offline reads — yes. Boards, admin, a page editor in the UI, or a minute of staleness — stay in Jira. CLI and REST already write wiki pages. docs/CONCEPT.md.

How it compares. jira-cli talks to the live API per command. Linear is a different tracker, and also a gadak source (see above). Rovo MCP searches both sources too, but it is hosted: no aggregate, no offline, and every call spends tokens. docs/FAQ.md.

More sources later. Confluence proved the spine is neutral. Next source, ranked by demand: docs/ROADMAP.md.

Documentation

• CHANGELOG.md — what shipped
• docs/INSTALL.md · docs/DESKTOP.md — install, first run, the desktop app
• docs/MIRROR.md · docs/MCP.md · docs/AGENT_SETUP.md — SQL, CLI, REST, MCP, one paste per host
• docs/RECIPES.md — questions JQL cannot ask, as SQL
• SECURITY.md · docs/FAQ.md · MAINTENANCE.md — threat model, site load, who maintains this
• docs/EXTENDING.md · docs/PLUGINS.md — fitting gadak to your team
• docs/STATE_OF_PLAY.md · docs/CONCEPT.md · docs/PAIN_POINTS.md
• docs/ARCHITECTURE.md · docs/UX_PRINCIPLES.md
• docs/README.md — the rest of the docs

Who makes this

One person, currently. Weigh that — and the other side: the mirror is a disposable cache of your own Jira, the 0.x contract is the three promises in data-model.md (issues_full and the RECIPES queries, gadak sql stdout, and gadak views open --keys -), the license is Apache-2.0, and the file is plain SQLite. Hard questions: docs/FAQ.md. What you do not have to take on trust, each with the command that checks it: PROMISES.md.

Contributing and feedback

CONTRIBUTING.md — and docs/GOOD_FIRST_ISSUES.md to start. Bug reports need your Jira deployment type (Cloud), the gadak commit, and the command you ran. Never paste real issue data, tokens, or site URLs into a public issue.

Commit GDK-nnn keys resolve on the public backlog. To file something, open a GitHub issue — the maintainer mirrors it into the backlog.

Using gadak with an agent and hitting friction? Open an issue with the question you asked and what the agent did.

License

Apache-2.0. See LICENSE and NOTICE.