{"id":50488349,"url":"https://github.com/tone4hook/agent-dock","last_synced_at":"2026-06-02T00:30:32.073Z","repository":{"id":357266307,"uuid":"1233549914","full_name":"tone4hook/agent-dock","owner":"tone4hook","description":"A Neutralino wrapped app that drives Claude Code (and other coding-agent CLIs if you customize) for Atlassian-grounded engineering work","archived":false,"fork":false,"pushed_at":"2026-05-12T02:53:23.000Z","size":581,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T04:36:27.191Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tone4hook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-09T04:45:12.000Z","updated_at":"2026-05-12T02:53:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tone4hook/agent-dock","commit_stats":null,"previous_names":["tone4hook/agent-dock"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tone4hook/agent-dock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tone4hook%2Fagent-dock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tone4hook%2Fagent-dock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tone4hook%2Fagent-dock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tone4hook%2Fagent-dock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tone4hook","download_url":"https://codeload.github.com/tone4hook/agent-dock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tone4hook%2Fagent-dock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33800675,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T00:30:29.749Z","updated_at":"2026-06-02T00:30:32.065Z","avatar_url":"https://github.com/tone4hook.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent*Dock\n\nA macOS desktop app that drives Claude Code (and other coding-agent CLIs) for Atlassian-grounded engineering work. Pick a workspace, link a Jira issue or Confluence page to a task, and a session runs an `investigate → plan → human-approval → implement → code-review` pipeline against a fresh git worktree.\n\nBuilt on React + shadcn/ui, an Express + SQLite API, and a Neutralino window. Single-user, local-first — no shared backend, no SaaS dependency for state.\n\n## Quick start (development)\n\nRequires **macOS 11+**, **Node 24+**, and a Claude Code (or Gemini / Codex) CLI on your PATH. The Node 24 floor is driven by `better-sqlite3`'s native bindings — older Node majors hit an ABI mismatch at first DB open.\n\n```bash\n# clone, then:\nexport NODE_AUTH_TOKEN=ghp_…              # see \"GitHub Packages auth\" below\nnpm install\nnpm run db:migrate\nnpm run dev\n```\n\n`npm run dev` starts the API, the Vite web app, and a Neutralino window together. The first launch opens an onboarding flow:\n\n1. **Workspace** — pick a parent directory containing your cloned repos. Agent*Dock auto-discovers first-level git repos. Worktrees go under `\u003cworkspace\u003e/worktrees/`.\n2. **Atlassian credentials** *(optional)* — Jira site URL, email, API token. Skip this and you can add it later in Settings; tasks will still run, just without Atlassian context.\n\n## Install (end users)\n\nIf someone has shipped you a `dist/agent-dock.dmg` from a release build:\n\n1. Double-click the DMG, drag `agent-dock` to Applications.\n2. Launch from Launchpad. The first-run dialog says *\"agent-dock is an app downloaded from the Internet…\"* — click **Open**.\n3. Complete the onboarding flow (workspace + optional Atlassian creds).\n\nThe app is signed with a Developer ID Application certificate and notarized by Apple, so Gatekeeper doesn't block it. No `xattr` workaround needed.\n\n**On the receiving Mac you'll also need:**\n\n- **Node 24+** on PATH. The launcher auto-discovers Homebrew, nvm, volta, fnm, and asdf installs; missing Node shows a critical alert with the install URL. Node 24 is a hard requirement: `better-sqlite3` (the API's SQLite driver) ships native bindings that fail to load on older Node majors, so the app will refuse to open its database on Node 20 / 22.\n- Whichever coding-agent CLIs the workflow invokes (`claude`, `gemini`, `codex`) plus `gh` and `git`, on PATH from a directory the launcher already prepends: the Node bin dir, `/opt/homebrew/bin`, `/usr/local/bin`, `~/.volta/bin`, `~/.local/bin`, or `~/.cargo/bin`.\n\n## GitHub Packages auth (developers only)\n\nAgent*Dock depends on `@tone4hook/headless-coding-agent-sdk`, hosted on GitHub Packages. **End users installing the DMG do not need this** — the package is bundled into the `.app`.\n\nTo install from source you need a **GitHub classic Personal Access Token** (not a fine-grained token — fine-grained tokens cannot read GitHub Packages npm registries on user-owned packages):\n\n1. https://github.com/settings/tokens/new → check **`read:packages`** only.\n2. Export the token (add to `~/.zshrc` to persist):\n\n   ```bash\n   export NODE_AUTH_TOKEN=ghp_your_token_here\n   ```\n\n3. Run `npm install`. The committed `.npmrc` handles the rest.\n\nIf you see `401 Unauthorized` from `npm.pkg.github.com`, your token is fine-grained — regenerate as a classic token.\n\n## Scripts\n\n| Script | Purpose |\n|---|---|\n| `npm run dev` | API + web + Neutralino, hot-reload. |\n| `npm run build` | Compile workspaces, web bundle, Neutralino resources. |\n| `npm run typecheck` | TypeScript verification across all packages. |\n| `npm run db:migrate` | Apply migrations to `~/.agent-dock/agent-dock.sqlite` (or `$AGENT_DOCK_DATA_DIR`). |\n| `npm run package:mac` | Build an ad-hoc-signed `dist/agent-dock.app` for local smoke. |\n| `npm run package:dmg` | Wrap the `.app` into `dist/agent-dock.dmg`. |\n| `npm run package:mac:signed` | Same as `package:mac` but Developer ID-signed with hardened runtime (requires `APPLE_DEVELOPER_ID`). |\n| `npm run package:dmg:signed` | Same as `package:dmg` but Developer ID-signed. |\n| `npm run notarize` | Submit `dist/agent-dock.app` to Apple's notary service, staple the ticket, then rebuild the DMG with the stapled `.app` and notarize+staple the DMG too. |\n| `npm run release:mac` | Full pipeline: `package:mac:signed` then `notarize`. |\n\n## Build a release DMG\n\n### One-time setup\n\n1. **Apple Developer Program** membership ($99/yr).\n2. **Developer ID Application certificate** in your login keychain — Keychain Access → Certificate Assistant → Request a Certificate; upload the CSR at developer.apple.com → Certificates → Software → **Developer ID Application**; install the resulting `.cer` plus Apple's [Developer ID G2 intermediate](https://www.apple.com/certificateauthority/DeveloperIDG2CA.cer). Confirm with `security find-identity -v -p codesigning`.\n3. **App-specific password** at [appleid.apple.com](https://appleid.apple.com/account/manage) → Sign-In and Security → App-Specific Passwords (label it `agent-dock-notarize`).\n4. **Store notarytool credentials** once:\n\n   ```bash\n   xcrun notarytool store-credentials agent-dock \\\n     --apple-id \u003cyour-apple-id-email\u003e \\\n     --team-id  \u003cYOUR-TEAM-ID\u003e \\\n     --password \u003capp-specific-password\u003e\n   ```\n\n### Every release\n\n```bash\nexport APPLE_DEVELOPER_ID=\"Developer ID Application: Your Name (TEAMID12)\"\nnpm run release:mac\n```\n\nApple's notary verdict typically lands in 1–5 minutes. The result is `dist/agent-dock.dmg` ready to drag-install on any Mac with no Gatekeeper friction.\n\n## Architecture overview\n\n- `apps/api` — Express server, SSE event bus, SQLite repos. Composition root at `apps/api/src/buildContainer.ts`.\n- `apps/web` — React + shadcn/ui frontend. Boots from `apps/web/src/main.tsx`.\n- `packages/shared` — Zod schemas + types shared across API and web.\n- `packages/db` — better-sqlite3 wrappers + migrations.\n- `packages/agents` — `ProviderAdapter` per CLI (`claude`, `gemini`, `codex`).\n- `packages/orchestrator` — `RunCoordinator` (single-run lifecycle, no HTTP).\n- `packages/workflows` — feature-flow pipeline definition.\n- `packages/worktrees` — git worktree lifecycle per Session.\n- `packages/atlassian` — Jira + Confluence clients, ADF parsing, Keychain-backed creds.\n- `packages/artifacts` — on-disk artifact store mirroring the `artifacts` table.\n- `scripts/build-mac.mjs`, `scripts/make-dmg.mjs`, `scripts/sign-mac.mjs`, `scripts/notarize-mac.mjs` — packaging.\n- `scripts/launcher.swift` — Mach-O `CFBundleExecutable` (compiled at package time; locates Node, spawns the API, then exec's Neutralino).\n\nSee `CONTEXT.md` for the domain vocabulary used across the codebase.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftone4hook%2Fagent-dock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftone4hook%2Fagent-dock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftone4hook%2Fagent-dock/lists"}