https://github.com/tone4hook/agent-dock
A Neutralino wrapped app that drives Claude Code (and other coding-agent CLIs if you customize) for Atlassian-grounded engineering work
https://github.com/tone4hook/agent-dock
Last synced: 1 day ago
JSON representation
A Neutralino wrapped app that drives Claude Code (and other coding-agent CLIs if you customize) for Atlassian-grounded engineering work
- Host: GitHub
- URL: https://github.com/tone4hook/agent-dock
- Owner: tone4hook
- License: mit
- Created: 2026-05-09T04:45:12.000Z (25 days ago)
- Default Branch: main
- Last Pushed: 2026-05-12T02:53:23.000Z (22 days ago)
- Last Synced: 2026-05-12T04:36:27.191Z (22 days ago)
- Language: TypeScript
- Homepage:
- Size: 567 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Agent*Dock
A 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.
Built on React + shadcn/ui, an Express + SQLite API, and a Neutralino window. Single-user, local-first — no shared backend, no SaaS dependency for state.
## Quick start (development)
Requires **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.
```bash
# clone, then:
export NODE_AUTH_TOKEN=ghp_… # see "GitHub Packages auth" below
npm install
npm run db:migrate
npm run dev
```
`npm run dev` starts the API, the Vite web app, and a Neutralino window together. The first launch opens an onboarding flow:
1. **Workspace** — pick a parent directory containing your cloned repos. Agent*Dock auto-discovers first-level git repos. Worktrees go under `/worktrees/`.
2. **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.
## Install (end users)
If someone has shipped you a `dist/agent-dock.dmg` from a release build:
1. Double-click the DMG, drag `agent-dock` to Applications.
2. Launch from Launchpad. The first-run dialog says *"agent-dock is an app downloaded from the Internet…"* — click **Open**.
3. Complete the onboarding flow (workspace + optional Atlassian creds).
The app is signed with a Developer ID Application certificate and notarized by Apple, so Gatekeeper doesn't block it. No `xattr` workaround needed.
**On the receiving Mac you'll also need:**
- **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.
- 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`.
## GitHub Packages auth (developers only)
Agent*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`.
To 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):
1. https://github.com/settings/tokens/new → check **`read:packages`** only.
2. Export the token (add to `~/.zshrc` to persist):
```bash
export NODE_AUTH_TOKEN=ghp_your_token_here
```
3. Run `npm install`. The committed `.npmrc` handles the rest.
If you see `401 Unauthorized` from `npm.pkg.github.com`, your token is fine-grained — regenerate as a classic token.
## Scripts
| Script | Purpose |
|---|---|
| `npm run dev` | API + web + Neutralino, hot-reload. |
| `npm run build` | Compile workspaces, web bundle, Neutralino resources. |
| `npm run typecheck` | TypeScript verification across all packages. |
| `npm run db:migrate` | Apply migrations to `~/.agent-dock/agent-dock.sqlite` (or `$AGENT_DOCK_DATA_DIR`). |
| `npm run package:mac` | Build an ad-hoc-signed `dist/agent-dock.app` for local smoke. |
| `npm run package:dmg` | Wrap the `.app` into `dist/agent-dock.dmg`. |
| `npm run package:mac:signed` | Same as `package:mac` but Developer ID-signed with hardened runtime (requires `APPLE_DEVELOPER_ID`). |
| `npm run package:dmg:signed` | Same as `package:dmg` but Developer ID-signed. |
| `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. |
| `npm run release:mac` | Full pipeline: `package:mac:signed` then `notarize`. |
## Build a release DMG
### One-time setup
1. **Apple Developer Program** membership ($99/yr).
2. **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`.
3. **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`).
4. **Store notarytool credentials** once:
```bash
xcrun notarytool store-credentials agent-dock \
--apple-id \
--team-id \
--password
```
### Every release
```bash
export APPLE_DEVELOPER_ID="Developer ID Application: Your Name (TEAMID12)"
npm run release:mac
```
Apple'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.
## Architecture overview
- `apps/api` — Express server, SSE event bus, SQLite repos. Composition root at `apps/api/src/buildContainer.ts`.
- `apps/web` — React + shadcn/ui frontend. Boots from `apps/web/src/main.tsx`.
- `packages/shared` — Zod schemas + types shared across API and web.
- `packages/db` — better-sqlite3 wrappers + migrations.
- `packages/agents` — `ProviderAdapter` per CLI (`claude`, `gemini`, `codex`).
- `packages/orchestrator` — `RunCoordinator` (single-run lifecycle, no HTTP).
- `packages/workflows` — feature-flow pipeline definition.
- `packages/worktrees` — git worktree lifecycle per Session.
- `packages/atlassian` — Jira + Confluence clients, ADF parsing, Keychain-backed creds.
- `packages/artifacts` — on-disk artifact store mirroring the `artifacts` table.
- `scripts/build-mac.mjs`, `scripts/make-dmg.mjs`, `scripts/sign-mac.mjs`, `scripts/notarize-mac.mjs` — packaging.
- `scripts/launcher.swift` — Mach-O `CFBundleExecutable` (compiled at package time; locates Node, spawns the API, then exec's Neutralino).
See `CONTEXT.md` for the domain vocabulary used across the codebase.
## License
MIT — see [LICENSE](LICENSE).