gadak

package module

v0.14.0 Latest Latest Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/midagedev/gadak

Links

Open Source Insights

README ¶

gadak 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 macOS 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. 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.

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.

Measured against a live Cloud site (2,853 issues; medians, CLI startup included — method and the losing rows):

Question	REST API	`gadak`
Simple filter, 100 issues	706 ms	17 ms	42×
Open issues per epic (`GROUP BY`)	3,924 ms · 7 API pages	24 ms · one query	162×
Reopened-issue count	≈ 20 min (every changelog)	14.5 ms	—

And the other side: the first full sync takes minutes, every watch tick costs ~6.6 s, and the mirror trails Jira by one sync interval.

▶ 90-second tour of the paper list (GIF, 7 MB)

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

Download Gadak-<version>-arm64.dmg and open the window — or, from a terminal:

brew install midagedev/tap/gadak        # the app — the bundled CLI lands on PATH too
# or, CLI only (macOS + Linux):
brew install midagedev/tap/gadak-cli
gadak init && gadak sync    # Jira (and Confluence) -> ~/.gadak/gadak.db
gadak serve                # http://gadak.localhost:7777

Status: 0.13, still 0.x. Sync, read API, write-through, desktop, web, CLI, and MCP are verified against a live site. Honest inventory: docs/STATE_OF_PLAY.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

	For	Looks like
App + Web UI	all-day triage	macOS app (no port) or `gadak serve`. `j`/`k` walk, `x` selects, `s`/`a`/`l`/`c` change status, assignee, labels, or comment from the list.
CLI + SQL	agents, scripts	`gadak issue`, `gadak search` (FTS, `--jql`, or a Jira URL), `gadak sql`, plus the file

Writes go through to Jira, then the mirror refreshes. App and web: comment, transition, assign, labels, priority, title. CLI today: comment, transition, assign. Wiki mirror is read-only. Hierarchy, item_refs, attachments: docs/CONCEPT.md.

For agents

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

gadak skill install         # schema + query patterns, no extra process
# or, for hosts without a shell (Claude Desktop):
gadak mcp install claude    # pins this binary and profile into the registration

SQL answers; the window presents. And if you already have the JQL, skip the SQL — the clauses land as chips:

gadak sql "select key from issues_full where reopen_count > 1" \
  | tail -n +2 | gadak views open --keys -
gadak views open --jql 'project = NMA AND priority = High AND resolution is EMPTY'

_{gadak views open writes a one-shot hash; the running app or serve tab applies it. Generated from e2e/demo/agent-demo.spec.ts.}

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.

Claude Code registers gadak as an MCP server, is asked to search Jira and the wiki for idempotency, calls gadak, and answers with an issue and the Confluence brief that drove it
_{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.

Install

Atlassian Cloud only. One API token covers Jira and Confluence on the same site.

1. The macOS app. 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 or for the same UI in a browser tab:

brew install midagedev/tap/gadak-cli     # macOS + Linux
gadak init && gadak sync
gadak serve      # http://gadak.localhost:7777

Install script, release archive, source, Docker, wiki mirroring, profiles, 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, wiki authoring, or a minute of staleness — stay in Jira. docs/CONCEPT.md.

How it compares. jira-cli talks to the live API per command. Linear is a different tracker. 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

docs/INSTALL.md · docs/DESKTOP.md — install, first run, the macOS app
AGENTS.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/decisions/ · specs/000-product/ — why, and the contracts

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.

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.

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.

Documentation ¶

Overview ¶

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.

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

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).

Types ¶

This section is empty.

Source Files ¶

View all Source files

embed.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
gadak command export-static freezes the demo mirror into static JSON + attachment bytes for the zero-install hosted demo (GitHub Pages).	export-static freezes the demo mirror into static JSON + attachment bytes for the zero-install hosted demo (GitHub Pages).
internal
atlhttp Package atlhttp is the shared HTTP transport for Atlassian Cloud clients (Jira, Confluence): retries, backoff, path safety, and optional usage meters.	Package atlhttp is the shared HTTP transport for Atlassian Cloud clients (Jira, Confluence): retries, backoff, path safety, and optional usage meters.
attachcache Package attachcache stores attachment bytes on local disk.	Package attachcache stores attachment bytes on local disk.
clitool Package clitool installs the gadak binary onto PATH via a symlink.	Package clitool installs the gadak binary onto PATH via a symlink.
config Package config loads and saves ~/.gadak/config.json.	Package config loads and saves ~/.gadak/config.json.
confluence Package confluence is a thin REST client for Confluence Cloud: enough of the API to fill the page mirror, and nothing else.	Package confluence is a thin REST client for Confluence Cloud: enough of the API to fill the page mirror, and nothing else.
fields Package fields classifies and discovers Jira custom fields for the mirror.	Package fields classifies and discovers Jira custom fields for the mirror.
jira Package jira is a thin REST client for Jira Cloud: enough of the API to fill the mirror, and nothing else.	Package jira is a thin REST client for Jira Cloud: enough of the API to fill the mirror, and nothing else.
jql Package jql translates a documented JQL subset to and from gadak's in-memory filter (the same shape the web UI serializes into the URL).	Package jql translates a documented JQL subset to and from gadak's in-memory filter (the same shape the web UI serializes into the URL).
mcp Package mcp implements a thin stdio MCP server over the local gadak mirror.	Package mcp implements a thin stdio MCP server over the local gadak mirror.
secretscan Package secretscan holds the credential-shaped string patterns that every outbound artifact is checked against before it is written.	Package secretscan holds the credential-shaped string patterns that every outbound artifact is checked against before it is written.
selfupdate Package selfupdate answers one question — is a newer release published? — with one GitHub API call a day, cached on disk.	Package selfupdate answers one question — is a newer release published? — with one GitHub API call a day, cached on disk.
server Package server serves the HTTP read API the web UI already speaks (specs/000-product/contracts/api.md).	Package server serves the HTTP read API the web UI already speaks (specs/000-product/contracts/api.md).
snapshot Package snapshot builds shareable mirror copies for demos and benchmarks.	Package snapshot builds shareable mirror copies for demos and benchmarks.
store Package store owns the SQLite mirror: schema, migrations, transactions, full-text index and the derived fields the source does not provide.	Package store owns the SQLite mirror: schema, migrations, transactions, full-text index and the derived fields the source does not provide.
sync Package sync fills the mirror from Jira.	Package sync fills the mirror from Jira.
teamconfig Package teamconfig builds and applies team-shareable gadak configuration files (views, field maps, group rules, …) without credentials or personal machine prefs.	Package teamconfig builds and applies team-shareable gadak configuration files (views, field maps, group rules, …) without credentials or personal machine prefs.
uifocus Package uifocus is the one-shot handoff from the CLI to a running UI.	Package uifocus is the one-shot handoff from the CLI to a running UI.
workspace Package workspace mounts additional gadak profiles under /w/<name>/ and lists them at GET /api/v1/workspaces.	Package workspace mounts additional gadak profiles under /w/<name>/ and lists them at GET /api/v1/workspaces.
tools
bench-fixture command Command bench-fixture builds a deterministic synthetic gadak.db for latency benchmarks (T6.7 / G5).	Command bench-fixture builds a deterministic synthetic gadak.db for latency benchmarks (T6.7 / G5).
seed-demo command Command seed-demo populates a throwaway Jira Cloud site with a realistic demo backlog for gadak screenshots and examples/demo.db.	Command seed-demo populates a throwaway Jira Cloud site with a realistic demo backlog for gadak screenshots and examples/demo.db.