gadak

README

Find the thread in your backlog.

_{English · 한국어 · 日本語}

Query your Jira backlog with SQL.

gadak mirrors the Jira Cloud projects and Confluence spaces you select (issues, comments, history, wiki pages) into one SQLite file on your machine, indexed together and searchable with no network. Use the mirror through the desktop app, a browser tab (gadak serve), the CLI, or MCP. Writes go to Jira first. One binary, no gadak account. It is 0.x software from one maintainer; status and promises are below. Atlassian's own Rovo MCP server is hosted and needs nothing installed, but it has no aggregation tool and no offline reads; the trade is in alternatives.

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

Query Jira with SQL

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"

JQL has no GROUP BY. This query counts unresolved issues in each epic; the REST API returns the rows and leaves the counting to you. Datasette Lite runs this query on the demo snapshot in your browser with nothing installed. More questions JQL cannot ask, as SQL: docs/RECIPES.md.

Measured 2026-08-26 against a live Cloud site (3,296 issues; medians, CLI startup included):

Question	REST API	gadak
Simple filter, 100 issues	583 ms	19 ms	31×
One issue with its full history	710 ms	28 ms	25×
Free-text search	543 ms	41 ms	13×
Open issues per epic (GROUP BY)	4,761 ms — 8 API pages in this measurement, aggregated client-side	22 ms — one query	214×
A count over the change history	no native aggregate — ≈ 28 min to crawl the history and count client-side	14 ms	—

The method, the re-measurement history, and the rows where gadak loses (the first full sync, the watch tick on a quiet site, one sync interval of staleness) are in docs/BENCHMARKS.md.

▶ 20-second tour of the list (GIF)

_{The window, in twenty seconds. Generated from e2e/demo/web-demo.spec.ts against the demo snapshot.}

Install

macOS app, CLI included:

brew install --cask midagedev/tap/gadak

CLI only, on macOS or Linux. The same UI opens in a browser tab via gadak serve:

brew install midagedev/tap/gadak-cli

Connect to Jira Cloud, then open the address gadak serve prints (http://gadak.localhost:7777). The first sync runs inside serve, newest issues first, and the list fills while it runs:

gadak init && gadak serve         # mirror a Jira Cloud site
gadak init --local && gadak serve # no Jira — start on the tracker gadak ships with

A site needs one API token, a user token created with no scopes; it covers Jira and Confluence on the same site, and the mirror sees what your account sees. You pick what it mirrors: --projects for Jira, --spaces for the wiki, which stays off until you name spaces. Jira Server and Data Center connect with gadak init --server and a Personal Access Token; the wiki stays off there (no Confluence Server client).

gadak init --projects ENG,PROD --spaces ENG

Windows: the desktop app is on the Microsoft Store. The Store signs it, so neither SmartScreen nor Smart App Control objects, and a Store install puts the gadak command on PATH as well (since 0.20.2). For the CLI without the Store, take gadak_<version>_windows_amd64.zip (or arm64) from the latest release, unzip, put gadak.exe on PATH. The release's desktop zip (Gadak-<version>-windows-x64.zip) stays unsigned, and a SmartScreen block there is a missing signature, not a virus finding (why). If it blocks, install from the Store, and do not turn Smart App Control off.

The window follows the browser or OS language (English, Korean or Japanese; Settings switches it). The signed dmg, the Linux tarball, Docker, upgrades: docs/INSTALL.md.

Other workspaces. gadak --workspace <new> migrate --from <old> moves a synced workspace onto another origin; add --to linear to target a Linear team. A second machine pairs with a home serve: gadak --workspace laptop init --pairing-code-stdin.

Data and network

• How much is copied. The Cloud projects and spaces you named, as your account sees them; gadak adds no elevation and no service account.
• What stays local, and how fresh. One SQLite file. The first full sync is the slow part: 3.7 minutes for the benchmark site (3,514 issues and 462 pages). After that gadak serve syncs every 60 seconds by default (syncIntervalSec), plus an hourly reconcile that removes issues you can no longer see. Reads are one interval behind Jira.
• Where the token is. ~/.gadak/config.json, mode 0600. Credentials never reach SQLite, a log, or a snapshot.
• What leaves the machine. No telemetry. gadak talks only to what you configured; SECURITY.md is the complete list and docs/NETWORK.md walks every connection and its off switch. Four reads still ask Jira: viewing an attachment, gadak issue --editmeta, gadak fields, and gadak api (a passthrough).
• What a write does. It goes to Jira first; the mirror refreshes after Jira accepts. A write Jira rejects fails then and there. Nothing is queued.
• What changes with an agent. It sends what it reads to its model; see Agents.

The mirror is a cache you can throw away. Delete the directory and nothing is lost.

Agents

Let your coding agent query the same mirror through the CLI or MCP. Reference: docs/MIRROR.md; one paste per host: docs/AGENT_SETUP.md.

gadak skill install

That copies one SKILL.md for Claude Code and starts no process; the agent runs short-lived gadak commands. Name another host to install the same file there: gadak skill install codex, and the same for agents, cursor, gemini, opencode and grok. For Claude Desktop, which has no shell, register the same mirror as an MCP server (gadak mcp install claude is the Claude Code registration; Claude Desktop never sees it):

gadak mcp install claude-desktop

_{The shell is in the window (⌘K → Terminal, or Ctrl+`). gadak claim binds the pane to the issue, and a Claude Code session started in it filters the list, then saves and opens a dashboard in the same window. Nothing but the two prompts is scripted; the stretches where the agent is working are time-lapsed. The Korean and Japanese READMEs carry the same take recorded in their own language. Recorded from e2e/demo/terminal-claude-demo.spec.ts via record-terminal-claude.sh.}

Two rules carry most of the value. Filter on status_category and priority_rank rather than a display name: Jira translates those per account, so priority = High is silently zero rows on a Korean-language site. And open the issues a query returns in the gadak window: gadak sql --no-header "…" | gadak views open --keys - puts the agent's answer on your screen, and gadak views open --jql '…' lands pasted JQL as chips.

Writes (create, edit, comment, transition, claim, link, and the wiki's page verbs) go through the origin before the mirror refreshes. On Jira and Linear, an agent's comments and the issues it creates carry its name (off switch: gadak config set actor.trailer false). On the built-in tracker, the person at the machine has the same byline: gadak me set "Your Name" authors their own writes as them.

An agent that reads the mirror sends what it reads to whatever model it talks to. gadak itself sends nothing. Scope the mirror to what the agent should see.

The phone app (beta)

The iOS app pairs with a gadak serve you already run, over your own network. No gadak account, and nothing hosted in between. Whatever the cache holds, the phone shows: fields, attachments, linked issues, wiki pages, the active sprint and every sprint behind it. What is one line to say, the phone writes through the origin first, the way the desk does: a comment, a label, a due date, a photo, an issue filed under its epic. Editing a page or a custom field, authoring a view, laying out a dashboard and moving cards stay on the desktop, and the app says so where the control would be.

_{The writing half of one take — the whole clip plays on the site, because GitHub's markdown drops a <video>. Nothing here is staged: the demo snapshot is served as a tracker of its own, so every write lands.}

Beta, and that is the whole status. Builds go to TestFlight for internal testers, and there is no public download. An App Store listing waits on a way for a reviewer to see the app without joining your network.

Origins and limits

Four origins, one set of verbs: Atlassian Cloud, Jira Server / Data Center (gadak init --server and a Personal Access Token), Linear (a "linear" block in the workspace config and gadak sync --source linear), and the built-in tracker that travels with the app. Reads, writes, hierarchy, attachments, history and the board layout work on all four; the wiki on the three that have one. What each origin refuses, with the code citation behind every cell: docs/SUPPORT_MATRIX.md. Three things appear on no origin at all and stay in Jira: sprints as a UI, Jira dashboards, and Jira's notification inbox.

Good fit / bad fit. Yes to daily search latency, an agent over tracker and wiki, and offline reads. Sprint planning, admin, a page editor in the UI, or a minute of staleness that matters: keep those in Jira. docs/CONCEPT.md.

How it works. One binary, one SQLite file; incremental sync plus a reconcile pass: docs/ARCHITECTURE.md. Why a local process, not an extension or Forge app: docs/decisions/0003-local-process.md. Config, enrichments and SQL make it yours without forking: docs/EXTENDING.md.

Alternatives and prior work

jira-cli talks to the live API per command. Rovo MCP is hosted by Atlassian and searches Jira and Confluence; it has write tools, but no native aggregation tool and no offline reads. gadak runs SQL against a local mirror, and its cost is a local binary and an initial sync; reads come off your disk, so no rate limit applies to them, and the thing you are trusting is one maintainer under Apache-2.0 rather than Atlassian. Earlier projects in this area include Scrumdog, jira-offline and jira-cache; gadak combines a local Jira and Confluence mirror with SQL, desktop and browser interfaces, a CLI, and MCP. docs/FAQ.md.

Status, compatibility and maintenance

Status: 0.23, still 0.x. Sync, read API, write-through, desktop, web, CLI and MCP are verified against a live site. The project currently has one maintainer. During 0.x, compatibility is promised for three things, listed in specs/000-product/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 mirror is ordinary SQLite. The name is Korean: gadak (가닥) is a strand — a thread drawn out of a tangle. What you do not have to take on trust, each with the command that checks it: docs/PROMISES.md.

Documentation

• CHANGELOG.md: what shipped
• docs/INSTALL.md · docs/DESKTOP.md: install, first run, the desktop app
• SECURITY.md · docs/NETWORK.md: threat model, every connection and its off switch
• docs/MIRROR.md · docs/MCP.md · docs/AGENT_SETUP.md: SQL, CLI, REST, MCP, one paste per host
• docs/RECIPES.md · docs/DASHBOARDS.md: questions JQL cannot ask, as SQL; agent-authored dashboards
• docs/SHOWCASE.md: the window, the launcher, and agents driving both, on camera
• docs/FAQ.md · docs/MAINTENANCE.md: site load, comparisons, who maintains this
• docs/README.md: the rest of the docs

Feedback and contributing

If you used gadak on your own project, open a GitHub issue or email midagedev@gmail.com: what question did it answer, and did you go back to it? Reports of everyday use are welcome before any contribution.

Keep real issue data, tokens, and site URLs out of a public issue. A bug report needs your Jira deployment type (Cloud or Server), the gadak commit, and the command you ran. The maintainer mirrors issues to the public backlog, where commit GDK-nnn keys resolve.

To contribute: .github/CONTRIBUTING.md and docs/project/GOOD_FIRST_ISSUES.md. Why the next features are the ones they are, with sources: docs/project/THEORY.md.

License

Apache-2.0. See LICENSE and NOTICE.

Documentation

Overview

Vendor assets for agent-authored dashboards (GDK-792): the pinned chart library a dashboard may load from /api/v1/dashboards/vendor/ instead of a CDN. Embedding it keeps the dashboards CSP free of external hosts (no outbound rule change — the bytes ship inside the binary), and pinning the version once means every dashboard sees the same library instead of whatever a CDN serves that day.

[GDK-808] three.js no longer ships embedded (−750 KB): anything bigger or less universal than uPlot belongs in the user-managed lib cache (`gadak dashboards lib add <url>` — sha384-pinned at download, re-hashed at serve, see internal/dashboards/libs.go), not in every binary gadak ships. uPlot stays embedded: one chart library is the norm the example dashboard sets.

The HTTP whitelist is DashVendorFile's table, not the directory: the license is embedded for NOTICE/NPB purposes but is not served.

Package gadak embeds the built web UI so a release is one self-contained binary. `npm run build` writes web assets to dist/app before `go build`; without that step the embed carries only the committed placeholder and WebUI reports ok=false, which `gadak serve` turns into a helpful error.

It also embeds the Claude Code skill (skills/gadak/SKILL.md) so `gadak skill install` works for brew installs without a source checkout.

Index

• func DashVendorFile(name string) ([]byte, string, bool)
• func PhoneUI() (fs.FS, bool)
• func SkillMarkdown() []byte
• func WebUI() (fs.FS, bool)

Functions

func DashVendorFile

func DashVendorFile(name string) ([]byte, string, bool)

DashVendorFile returns the embedded bytes and content type for a whitelisted vendor filename. ok is false for anything not in the table — unknown names, subdirectories, license files — and the route answers 404 in that case. Callers must not modify the returned slice.

func PhoneUI

func PhoneUI() (fs.FS, bool)

PhoneUI returns the embedded phone bundle (GDK-1966) rooted at the phone directory. ok is false when the binary was built without `make phone` (placeholder only) — serve then answers /m/ with a 503 naming that fix. `make phone` must stay the only writer of index.html here (vite --emptyOutDir), for the same reason as the web bundle above.

func SkillMarkdown

func SkillMarkdown() []byte

SkillMarkdown returns the embedded Claude Code skill body (skills/gadak/SKILL.md). Callers must not modify the returned slice.

func WebUI

func WebUI() (fs.FS, bool)

WebUI returns the embedded web assets rooted at the app directory. ok is false when the binary was built without a web build (placeholder only).