{"id":40610235,"url":"https://github.com/hack-dance/hack","last_synced_at":"2026-04-02T10:33:47.651Z","repository":{"id":332406032,"uuid":"1124779639","full_name":"hack-dance/hack","owner":"hack-dance","description":"Opinionated local-dev orchestration for running multiple projects at the same time without port conflicts.","archived":false,"fork":false,"pushed_at":"2026-02-13T19:24:28.000Z","size":280902,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-14T00:52:00.283Z","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/hack-dance.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2025-12-29T15:48:49.000Z","updated_at":"2026-02-13T19:24:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hack-dance/hack","commit_stats":null,"previous_names":["hack-dance/hack-cli","hack-dance/hack"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/hack-dance/hack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Fhack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Fhack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Fhack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Fhack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hack-dance","download_url":"https://codeload.github.com/hack-dance/hack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hack-dance%2Fhack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29637400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-01-21T05:09:14.893Z","updated_at":"2026-04-02T10:33:47.643Z","avatar_url":"https://github.com/hack-dance.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hack\n\n```text\n █████   █████   █████████     █████████  █████   ████\n░░███   ░░███   ███░░░░░███   ███░░░░░███░░███   ███░\n ░███    ░███  ░███    ░███  ███     ░░░  ░███  ███\n ░███████████  ░███████████ ░███          ░███████\n ░███░░░░░███  ░███░░░░░███ ░███          ░███░░███\n ░███    ░███  ░███    ░███ ░░███     ███ ░███ ░░███\n █████   █████ █████   █████ ░░█████████  █████ ░░████\n░░░░░   ░░░░░ ░░░░░   ░░░░░   ░░░░░░░░░  ░░░░░   ░░░░\n```\n\nHack is a local-first platform for developers and agents who need to run more than one project, branch, or workflow at once.\n\nIt makes three promises: **run projects in parallel**, **normalize all your tickets**, and **manage project env safely**.\n\nWhen local dev breaks down, it usually breaks down in the same places: ports collide, work gets split across too many ticket systems, and env setup turns into tribal knowledge. Hack is the opinionated layer that makes those problems boring again.\n\nSessions and integrations support those promises directly: sessions keep terminal work durable, and integrations let agents, ticket systems, and remote surfaces plug into the same project model.\n\n## The Three Core Promises\n\n### 1. Run projects in parallel\n\nHack lets each repo or branch run as its own isolated local environment instead of fighting over `localhost`, shared Docker networks, or ad-hoc port maps.\n\n- Run multiple repos at the same time.\n- Run multiple branches or worktrees of the same repo at the same time.\n- Keep service defaults like Postgres and Redis on their normal container ports.\n- Open stable HTTPS hostnames like `https://\u003cproject\u003e.hack` and `https://api.\u003cproject\u003e.hack`.\n\nCore commands:\n\n```bash\nhack up --detach\nhack up --branch feature-x --detach\nhack open\nhack logs --pretty\n```\n\n### 2. Normalize all your tickets\n\nHack keeps a local-first, git-backed ticket substrate in your repo, then lets external systems like Linear sync into that substrate instead of forcing your workflow to live in five different places.\n\n- Track work in git with lightweight hack tickets.\n- Sync issues and projects with Linear when you need shared coordination.\n- Preserve ownership and provenance so local and synced tickets stay understandable.\n- Give the CLI, agents, and the macOS app one normalized ticket model to work against.\n\nCore commands:\n\n```bash\nhack tickets setup\nhack tickets create --title \"Investigate flaky auth flow\"\nhack tickets list\nhack linear project-bind --project-id \"\u003clinear-project-id\u003e\"\nhack linear sync-project --from linear --project-id \"\u003clinear-project-id\u003e\"\n```\n\nDocs:\n\n- [Tickets guide](docs/guides/tickets.md)\n- [Linear integration architecture](docs/guides/linear-integration-architecture.md)\n\n### 3. Manage project env safely\n\nHack separates shareable env structure from secret values so teams and agents can understand what a project needs without leaking sensitive material into git.\n\n- Commit `.hack/hack.env.default.yaml` and optional `.hack/hack.env.\u003coverlay\u003e.yaml`.\n- Keep `.hack.secret.key` out of git, or provide `HACK_ENV_SECRET_KEY` in CI.\n- Let Hack inject resolved env directly into runtime commands by default.\n- Materialize `.hack/.env` only when you explicitly need a compatibility file.\n\nCore commands:\n\n```bash\nhack env list\nhack env add AWS_PROFILE dev\nhack env add --secret DATABASE_URL postgres://...\nhack host exec --env qa --scope api -- bun db:migrate\nhack host exec --env qa --scope api --target compose -- bun test\nhack host shell --env qa --scope api\nhack exec api -- bun test\n```\n\n`hack host exec` and `hack host shell` run on your host machine with Hack-resolved env injected.\nUse `--scope` when you want service-scoped values without running inside that service container.\nUse `--target compose` when you explicitly want the container-oriented addresses from the compose\nview instead of the default host-local rewrites.\n\nDocs:\n\n- [Env and secrets](docs/env.md)\n\n## First Run\n\n### Prerequisites\n\n- macOS\n- Docker + Compose via [OrbStack](https://docs.orbstack.dev/quick-start) or [Docker Desktop](https://www.docker.com/get-started/)\n\n### 1. Install Hack\n\nCLI only:\n\n```bash\ncurl -fsSL \\\n  https://github.com/hack-dance/hack/releases/latest/download/hack-install.sh \\\n  | bash\n```\n\nManaged Codex or CI container:\n\n```bash\ncurl -fsSL \\\n  https://github.com/hack-dance/hack/releases/latest/download/hack-codex-install.sh \\\n  | bash\n```\n\nThis slim install path skips `hack global install`, Caddy/CoreDNS, and Loki/Grafana.\n\nCLI + desktop app:\n\n- Download the latest DMG from [GitHub Releases](https://github.com/hack-dance/hack/releases/latest)\n- Install the CLI from the DMG\n- Optionally keep the macOS app for the beta desktop surface\n\n### 2. Set up your machine\n\n```bash\nhack global install\n```\n\n### 3. Start your first project\n\n```bash\ncd /path/to/your-repo\nhack init\nhack up --detach\nhack open\n```\n\nWhat those commands do:\n\n- `hack global install` boots the machine-level DNS, TLS, and logging services\n- `hack init` creates the `.hack/` project config\n- `hack up --detach` starts your stack on an isolated network\n- `hack open` opens the project URL in your browser\n\nUseful next commands:\n\n```bash\nhack logs --pretty\nhack run \u003cservice\u003e \u003ccommand...\u003e\nhack status\nhack down\n```\n\nIf you want the shortest non-interactive path for an existing repo, use `hack init --auto`.\n\n### 4. Optional: install agent integrations\n\nUse these when you want Cursor, Claude, or Codex to understand Hack workflows directly.\n\n```bash\nhack setup cursor\nhack setup claude\nhack setup codex\nhack setup sync --all-scopes\nhack agent init --client codex\n```\n\nIf your agent does not have shell access, use MCP instead:\n\n```bash\nhack mcp install --all --scope project\nhack setup mcp\nhack mcp serve\n```\n\nDocs:\n\n- [Initialize a project](docs/guides/init-project.md)\n- [CLI reference](docs/cli.md)\n- [GitHub workflows](docs/guides/github-workflows.md)\n\n## Adjacent capabilities at a glance\n\nNot every repo needs every `hack` capability on day one. These are the common adjacent tools people run\ninto after `hack init`, `hack up`, and `hack open` are already working:\n\n- **GitHub**: Connect GitHub when you want `hack` to help with pull requests and branch handoff from the\n  same place you run local work. It becomes relevant once you are ready to open, update, or share PRs.\n  Docs: [`docs/guides/github-workflows.md`](docs/guides/github-workflows.md)\n- **Linear**: Connect Linear when your team plans work there and you want Hack to bridge repo work with\n  project and issue tracking. It becomes relevant when a repo maps to a Linear project or when you want\n  sync between Linear issues and repo-local work. Docs:\n  [`docs/guides/linear-integration-architecture.md`](docs/guides/linear-integration-architecture.md)\n- **Tickets**: Use tickets when you want lightweight task tracking that stays with the repo and works\n  well for solo work, small teams, or agents. It becomes relevant as soon as you want to capture work\n  items without pushing everyone into a separate tracker. Docs:\n  [`docs/guides/tickets.md`](docs/guides/tickets.md)\n- **Sessions**: Use sessions when you want a terminal workspace you can come back to, share over SSH,\n  or hand off to an agent without rebuilding context. It becomes relevant when you keep long-running\n  shells, multiple projects, or multiple branches alive at once. Docs:\n  [`docs/sessions.md`](docs/sessions.md)\n- **Env**: Use env when a project needs local configuration like API keys, database URLs, or per-service\n  settings that should be explicit instead of tribal knowledge. It becomes relevant as soon as `hack up`,\n  `hack run`, or remote workflows depend on values that should not be hardcoded into the repo. Docs:\n  [`docs/env.md`](docs/env.md)\n- **Browser control plane**: Use the routed account surface when you want browser-based visibility into\n  auth context, org/team/project administration, integration status, and env management without giving\n  up CLI parity. It becomes relevant after `hack up` and `hack open` are already working and you want a\n  local web UI at `https://\u003cproject\u003e.hack/account` alongside the existing repo-bound CLI flows.\n\n## Supporting Capabilities\n\n### Sessions\n\nSessions keep terminal work durable. They are not the headline promise, but they are a first-class support capability for parallel project work, remote access, and long-running agents.\n\n- Backed by `tmux` or `zellij`\n- Started from the project root, not from `.hack/`\n- Useful for remote attach, agent execution, and multi-terminal workflows\n\n```bash\nhack session\nhack session start my-project --up\nhack session start my-project --env qa --service api --detach\nhack session attach my-project\nhack session exec my-project \"bun test\"\n```\n\nDocs:\n\n- [Sessions](docs/sessions.md)\n\n### Integrations\n\nIntegrations make the core promises more usable without changing what Hack is.\n\n- Agent integrations via `hack setup`\n- MCP for no-shell clients via `hack mcp`\n- Linear as a ticket-normalization extension, not the center of the product\n- GitHub when you want PR automation, PR updates, and private-repo bootstrap help\n\nIf your agent has shell access, prefer the CLI. Use MCP only when shell access is unavailable.\n\nDocs:\n\n- [Extensions](docs/extensions.md)\n- [Gateway overview](docs/gateway.md)\n\n## Beta Capabilities\n\n\u003e Beta surfaces are real and useful, but they are not the core promise of Hack yet.\n\n### Remote control plane\n\nThe gateway, supervisor, and remote shell flows let you control Hack over HTTP and remote transports. This is the foundation for off-device control, but it is still a secondary surface.\n\nDocs:\n\n- [Gateway overview](docs/gateway.md)\n- [Gateway API](docs/gateway-api.md)\n- [Supervisor](docs/supervisor.md)\n\n### Multi-node\n\nHack can pair remote nodes, bootstrap workspaces, and dispatch work across machines. This is useful when your local machine is not enough, but it is still beta-level product surface area.\n\nDocs:\n\n- [Remote node quickstart](docs/guides/remote-node-quickstart.md)\n- [Remote node container guide](docs/guides/remote-node-container.md)\n- [Remote supervisor guide](docs/guides/remote-supervisor.md)\n\n### macOS app\n\nHack Desktop gives you a native dashboard for projects, tickets, sessions, and integrations. It is a beta companion to the CLI, not the primary entry point.\n\nDocs:\n\n- [macOS app README](apps/macos/README.md)\n\n## How Hack Works\n\n- Project config lives in `.hack/`.\n- Each project or branch instance gets its own isolated Docker network and compose identity.\n- A global Caddy proxy gives routed services stable local HTTPS hostnames.\n- `hack logs` uses Compose for the fast path and Loki/Grafana for history and querying.\n- `hackd` is an optional daemon for faster `projects` and `ps` snapshots.\n\nUseful commands:\n\n```bash\nhack help\nhack projects\nhack status\nhack daemon start\nhack open logs\n```\n\n## Documentation\n\nDocs are split into three paths:\n\n- [Docs hub](docs/README.md)\n- [Core docs](docs/core.md) for the default local product story\n- [Beta workflows](docs/beta.md) for remote and control-plane flows\n- [Extensions \u0026 reference](docs/reference.md) for commands, APIs, and integrations\n\n## Develop From Source\n\n```bash\nbun install\nbun run install:dev\nhack --help\n```\n\nUseful repo commands:\n\n```bash\nbun test\nbun x ultracite check\n```\n\nUseful repo-level commands:\n\n- `bun run build`\n- `bun run test`\n- `bun run check`\n- `bun run macos:build`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhack-dance%2Fhack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhack-dance%2Fhack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhack-dance%2Fhack/lists"}