GO — Healthy across the board

• Last commit today
• 12 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Hatchet is a distributed orchestration engine for background tasks, AI agents, and durable workflows that persists execution state and provides automatic retries, real-time monitoring, and horizontal scalability. It exposes a unified API across Python, TypeScript, Go, and Ruby SDKs backed by a PostgreSQL-based state store and serves as either a self-hosted platform or managed cloud service (Hatchet Cloud). The core capability is deterministic, fault-tolerant workflow execution with built-in observability — workflows survive process crashes, network failures, and infrastructure changes. Monorepo organized by language: cmd/hatchet-* and internal/ contain the Go engine and gRPC services, python-sdk/, typescript-sdk/, go-sdk/, and ruby-sdk/ are self-contained per-language implementations, and examples/ and quick-start repos (sync-*-quickstart.yml workflows) hold sample code. State and schema live in SQL migrations (PLpgSQL files likely in a migrations/ directory referenced by the .github/workflows/). The engine is a gRPC server (orchestration core) that SDKs speak to via a well-defined API.

Backend engineers and full-stack developers building production systems that require reliable background job processing, AI agent orchestration, or long-running workflows where data consistency and visibility are critical. Also targets platform teams operating multi-language microservices who want a single orchestration layer instead of per-language job queues.

Production-ready and actively developed: the repo shows 4.1M Go LOC, 3.5M Python LOC, 2.8M TypeScript LOC, and 2.6M Ruby LOC indicating mature multi-language SDKs. CI/CD is comprehensive (.github/workflows/ has 20+ test and release pipelines), and the presence of dependabot.yml, security scanning (osv-scanner), and versioned releases (sdk-*.yml workflows) shows professional maintenance. Last activity appears recent based on the structured CI setup and active documentation (docs.yml workflow).

Moderate production risk: the monorepo spans 5 languages requiring expertise across Go (engine), Python/TS/Ruby (SDKs), and PostgreSQL migrations (PLpgSQL), increasing the surface area for bugs. The polyglot nature means SDKs may drift in feature parity or have language-specific bugs. No information is visible about current open issue count or maintainer headcount from the provided data, but the complexity suggests you should check contributor count and issue triage velocity before deep dependency.

Active multi-language SDK maintenance and infrastructure work: separate workflows for sdk-python.yml, sdk-typescript.yml, sdk-go.yml, and sdk-ruby.yml suggest ongoing releases. The presence of cli-e2e-tests.yml, cli-release.yaml, and vscode-release.yml indicates work on tooling (CLI and VS Code extension). Recent workflow additions like openvsx-release.yml (VS Code marketplace) and the pre-release.yaml suggest a coordinated release cadence with feature branches.

Clone the repo and use Docker with the Hatchet CLI:

git clone https://github.com/hatchet-dev/hatchet.git
cd hatchet
curl -fsSL https://install.hatchet.run/install.sh | bash
hatchet server start

This requires Docker. For SDK development, use the language-specific directories: cd python-sdk && pip install -e . for Python, cd typescript-sdk && npm install for TypeScript, etc.

Daily commands: For local development:

hatchet server start         # Starts the full platform locally (requires Docker)

For SDK development:

• Python: cd python-sdk && pip install -e . && python -m pytest
• TypeScript: cd typescript-sdk && npm install && npm run build && npm test
• Go: cd go-sdk && go test ./... (or run examples in cmd/examples/)
• Ruby: cd ruby-sdk && bundle install && bundle exec rake Check the .github/workflows/ files for the exact CI test commands (test.yml, sdk-*.yml).

• api-contracts/openapi/openapi.yaml — Central API specification defining all endpoints, request/response schemas, and data contracts that the entire SDK ecosystem depends on
• api-contracts/dispatcher/dispatcher.proto — Protobuf contract for dispatcher communication layer; defines the core RPC interface between workers, engine, and orchestrator
• .github/workflows/sdk-typescript.yml — TypeScript SDK CI/CD pipeline that gates all SDK releases; critical for understanding multi-SDK release coordination
• .github/workflows/sdk-python.yml — Python SDK CI/CD pipeline that ensures Python bindings are compatible with core orchestration engine
• .github/workflows/sdk-go.yml — Go SDK CI/CD pipeline; Go is the primary implementation language for the orchestration engine itself
• Taskfile.yaml — Build and development task definitions; entry point for understanding local development workflow and task automation
• CONTRIBUTING.md — Contribution guidelines and code standards that all changes must follow, especially for multi-language SDKs

Add a new OpenAPI endpoint

1. Define the new endpoint path, method, request/response schemas in the OpenAPI specification (api-contracts/openapi/openapi.yaml)
2. Create or update the corresponding schema file under api-contracts/openapi/components/schemas/ for request/response objects (api-contracts/openapi/components/schemas/_index.yaml)
3. Create the endpoint path definition file under api-contracts/openapi/paths/ following existing naming conventions (api-contracts/openapi/paths/info/version.yaml)
4. Update SDK code generation by running build tasks in Taskfile.yaml to regenerate client libraries (Taskfile.yaml)
5. Add integration tests for the new endpoint in the appropriate SDK test suite (.github/workflows/test.yml)

Add a new Dispatcher RPC method

1. Define the new RPC service method, request, and response messages in the dispatcher protobuf contract (api-contracts/dispatcher/dispatcher.proto)
2. Generate code from protobuf by running proto compiler commands in the build system (Taskfile.yaml)
3. Implement the handler in the appropriate SDK (Go, Python, TypeScript) following existing RPC handler patterns (.github/workflows/sdk-go.yml)
4. Add unit and integration tests covering the new dispatcher method (.github/workflows/test.yml)

Integrate a new external service webhook

1. Define the webhook schema under api-contracts/openapi/components/schemas/ (see slack.yaml and sns.yaml as examples) (api-contracts/openapi/components/schemas/slack.yaml)
2. Add the webhook endpoint definition to the OpenAPI spec under api-contracts/openapi/paths/ (api-contracts/openapi/openapi.yaml)
3. Create webhook handling logic in the engine, following existing patterns for event publishing (api-contracts/events/events.proto)
4. Add E2E tests for the webhook integration in the test suite (.github/workflows/test.yml)

Release a new SDK version

1. Update the hatchet-sdk version constraint in package dependencies and lock files (.github/workflows/sdk-typescript.yml)
2. Ensure all CI checks pass by running the language-specific SDK workflow (.github/workflows/sdk-python.yml)
3. Trigger the appropriate SDK release workflow which handles versioning and package publishing (.github/workflows/sdk-typescript-manual-publish.yml)
4. Verify release artifacts in the corresponding package registry (NPM, PyPI, pkg.go.dev) (.github/workflows/release.yaml)

• Protocol Buffers (gRPC) — Efficient binary serialization and RPC framework for low-latency dispatcher-to-engine communication; language-agnostic contract definition
• OpenAPI/Swagger — RESTful API specification enabling automatic code generation across TypeScript, Python, Go, and Ruby SDKs; vendor-neutral API documentation
• Multi-language SDKs (Go, Python, TypeScript, Ruby) — Enables developers in any language to define and execute workflows; reflects polyglot application ecosystem
• GitHub Actions CI/CD — Native GitHub integration for automated testing, linting, and releasing across multiple SDKs and platforms

• Separate OpenAPI and Protobuf contracts

  • Why: OpenAPI for REST APIs (external-facing), Protobuf for internal dispatcher RPC (performance-critical)
  • Consequence: Dual schema maintenance burden; requires careful synchronization between contracts

• Polyglot SDK support (4+ languages)

  • Why: Maximizes developer accessibility and language flexibility for workflow definitions
  • Consequence: Complex release coordination; each SDK needs independent CI, testing, and versioning

• Centralized Taskfile-based build system

  • Why: Unified development experience across Go, TypeScript, and Python codebases
  • Consequence: Developers must learn Taskfile syntax in addition to language-specific tools

• Does not handle authentication/authorization at the SDK level (delegated to tenant/workspace layer)
• Not a real-time database; event sourcing and state storage are delegated to pluggable backends
• Does not provide UI dashboards or visualization (that is a separate service)
• Does not implement language-specific ORMs or database drivers (workflows are language-agnostic)

Multi-language state sync: SDKs must stay synchronized with the Go engine's gRPC API schema; breaking changes in internal/services/ require coordinated releases across all four SDKs or you risk SDK incompatibility. Docker dependency: hatchet server start fails silently if Docker daemon is not running; errors are not always obvious. PostgreSQL migrations: Schema changes are one-way; rolling back requires manual SQL or recreating the database. gRPC code generation: If you modify .proto definitions, you must regenerate stubs for all languages (check if there's a protoc script in the Makefile or a make generate target). Example repos out of sync: The sync-*-quickstart.yml workflows suggest example repos are separate; if you add a feature, you may need to update hatchet-dev/quickstart-{python,typescript,go} separately. Development vs. Cloud: The server is designed to work with Hatchet Cloud for multi-tenant scenarios; self-hosted mode has different configuration (check for environment variables like HATCHET_ENV=dev vs. prod).

• Durable execution / workflow durability — Core feature of Hatchet: workflows survive process restarts and network failures by checkpointing state in PostgreSQL; you need to understand this to reason about what happens when a worker crashes mid-step
• gRPC and protocol buffers — Hatchet's engine-to-SDK communication is gRPC-based; understanding how the protobuf contracts work across languages is essential for extending the API or debugging SDK compatibility
• Deterministic execution — Workflows in Hatchet are designed to be replayed deterministically if they fail; random seeds and timestamps must be handled carefully or retries will produce different results
• PostgreSQL LISTEN/NOTIFY and event sourcing — Hatchet likely uses PostgreSQL's built-in pub/sub (LISTEN/NOTIFY) and/or event sourcing patterns to coordinate workflows across workers; understanding this helps debug timing issues and state inconsistencies
• Idempotent operations and exactly-once semantics — With automatic retries and distributed execution, workflow steps must be idempotent; Hatchet likely uses idempotency keys to avoid duplicate side effects on retry
• Decorator-based task definition (Python/TypeScript) — All SDKs use decorators/function attributes to annotate steps and workflows; this is syntactic sugar over the underlying gRPC contract, but the mapping is critical for understanding how code becomes executable tasks
• Multi-tenant scheduling — Hatchet Cloud requires isolation between customer tenants; the engine must handle tenant-aware scheduling, secret storage, and quota enforcement — this shapes the internal API design

• temporalio/temporal — Direct competitor in the durable workflow space; offers similar guarantees (deterministic execution, failure recovery) but with Temporal-specific semantics and a heavier operational footprint
• prefecthq/prefect — Python-first workflow orchestration with built-in observability; targets data pipelines more than general background jobs, but overlaps in durability and multi-step execution
• facebookincubator/flux — Alternative orchestration engine with polyglot SDK support; less mature than Hatchet but explores similar architecture patterns for distributed task scheduling
• hatchet-dev/cloud — The managed cloud offering of Hatchet; if you self-host, this repo shows the production deployment configuration and multi-tenant infrastructure
• hatchet-dev/quickstart-python — Official Python quickstart template kept in sync via the sync-python-quickstart.yml workflow; the canonical example for onboarding new Python users

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for proto contract changes in api-contracts/

The repo has proto definitions (dispatcher.proto, events.proto) but no visible integration tests validating that changes to these contracts don't break SDK code generation or API compatibility. New contributors could add a CI workflow that runs proto linting, generates code from proto files, and validates the generated SDK code compiles across all SDKs (Go, Python, TypeScript, Ruby). This catches breaking changes early and is critical for an orchestration engine with multiple SDK implementations.

• [ ] Add GitHub workflow file .github/workflows/proto-validation.yml to run protolint and buf on api-contracts/
• [ ] Create test script to generate code from api-contracts/dispatcher/dispatcher.proto and api-contracts/events/events.proto
• [ ] Validate generated code compiles in each SDK directory (sdk-go, sdk-python, sdk-typescript, sdk-ruby)
• [ ] Document the workflow in CONTRIBUTING.md with steps for validating proto changes locally

Add end-to-end CLI tests for real workflow scenarios

The repo has .github/workflows/cli-e2e-tests.yml but no visible test files in the repository structure. Given that Hatchet is an orchestration engine, comprehensive CLI e2e tests for common workflows (creating workflows, triggering jobs, checking status, viewing logs) would catch regressions and provide examples for users. This is high-value since CLI is often the first user touch point.

• [ ] Create test directory structure cli/e2e-tests/ with scenario-based test files
• [ ] Add tests for: creating a workflow definition, deploying it, triggering execution, monitoring job status, and viewing logs
• [ ] Integrate tests with existing .github/workflows/cli-e2e-tests.yml workflow
• [ ] Document expected setup (local server/database) in cli/e2e-tests/README.md

Add OpenAPI spec validation workflow and SDK generation tests

The repo has api-contracts/openapi/ with schema definitions but no visible workflow validating OpenAPI spec validity or testing that SDK code generation from these specs doesn't break. A new contributor could add a workflow that validates the OpenAPI spec against the OpenAPI 3.0 standard, tests SDK client generation, and ensures backward compatibility. This is critical since breaking API changes directly impact all SDK users.

• [ ] Create .github/workflows/openapi-validation.yml to run openapi-generator validation on api-contracts/openapi/
• [ ] Add tests to validate generated TypeScript/Python/Go/Ruby clients can instantiate and have expected methods
• [ ] Add a schema breaking change detection step (e.g., using openapi-diff or similar tool)
• [ ] Document OpenAPI contribution guidelines in .cursor/rules/ or CONTRIBUTING.md

• Add missing error handling tests in python-sdk/src/hatchet_sdk/ for connection failures and malformed workflow definitions; currently it's unclear what user-facing errors are tested.
• Expand .cursor/rules/typescript-e2e-tests.mdc with concrete examples of testing async workflow steps; the rule file exists but may lack guidance on SDK-specific patterns.
• Create example workflows in examples/ that demonstrate common patterns (fan-out/fan-in, conditional branches, retries with exponential backoff) that are not yet covered; check what's in examples/ first to avoid duplication.

The Hatchet codebase demonstrates a reasonable security foundation with established vulnerability reporting channels (SECURITY.md), CI/CD scanning workflows (osv-scanner.yml), and organized infrastructure. However, key gaps exist: loose dependency version constraints (>=1.20.2), incomplete documentation of security controls, and limited visibility into secrets management practices. The project would benefit from stricter dependency pinning, enhanced security policy documentation, implementation of automated SCA (Software Composition Analysis) with lock files, and explicit secrets management strategies. No critical vulnerabilities are apparent from the visible file structure, but runtime and deployment configurations require further review.

• Medium · Missing SECURITY.md Implementation Details — SECURITY.md. While SECURITY.md exists and establishes a responsible disclosure policy, the document lacks specific security controls, vulnerability management timelines, and patch release procedures. It mentions security@hatchet.run but provides no SLA or response time commitments. Fix: Expand SECURITY.md to include: (1) specific response time SLAs for vulnerability reports, (2) patch release timeline expectations, (3) details on security scanning and testing practices, (4) cryptography standards used, (5) authentication/authorization mechanisms, (6) data handling practices.
• Medium · Dependency Version Pinning Not Strict — Package dependency specification (hatchet-sdk>=1.20.2). The hatchet-sdk dependency is specified as '>=1.20.2' which allows any version above 1.20.2 without upper bound constraints. This could lead to unexpected breaking changes or security issues from transitive dependencies in minor/major version upgrades. Fix: Use stricter version pinning: either pin to a specific version (e.g., '1.20.2') or use a tilde/caret range with upper bounds (e.g., '~1.20.2' or '^1.20.0' with careful testing of upgrades). Implement automated dependency scanning and regular update reviews.
• Medium · Missing Dependency Scanning Configuration — .github/workflows, dependency management. While .github/workflows contains scanning workflows (e.g., osv-scanner.yml), the partial file structure doesn't show evidence of automated dependency vulnerability scanning in the main dependency management pipeline. No lock files mentioned. Fix: Ensure all dependencies use lock files (package-lock.json, go.sum, Gemfile.lock, etc.). Integrate SBOM generation, implement Dependabot or similar for automated vulnerability alerts, and enforce scanning in CI/CD pipeline.
• Low · Potential Unencrypted Configuration Exposure — Configuration management (root level config files). Multiple configuration files exist (.editorconfig, .env patterns mentioned conceptually) but lack evidence of encryption for sensitive data. No clear indication of secrets management strategy in visible config files. Fix: Implement a secrets management solution (e.g., HashiCorp Vault, AWS Secrets Manager). Ensure .env files are never committed (verify .gitignore), use environment variables for secrets, and implement secret rotation policies.
• Low · Missing CODEOWNERS and Branch Protection Validation — .github/. While .github directory contains workflows and templates, there's no evidence of a CODEOWNERS file or documented branch protection policies for security-sensitive code areas. Fix: Create a CODEOWNERS file to enforce code review requirements for security-critical paths (authentication, crypto, API handlers). Enable branch protection rules requiring reviews from security owners before merge.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hatchet-dev/hatchet shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hatchet-dev/hatchet repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hatchet-dev/hatchet.

What it runs against: a local clone of hatchet-dev/hatchet — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hatchet-dev/hatchet | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hatchet-dev/hatchet. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hatchet-dev/hatchet.git
#   cd hatchet
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hatchet-dev/hatchet and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hatchet-dev/hatchet(\\.git)?\\b" \\
  && ok "origin remote is hatchet-dev/hatchet" \\
  || miss "origin remote is not hatchet-dev/hatchet (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "api-contracts/openapi/openapi.yaml" \\
  && ok "api-contracts/openapi/openapi.yaml" \\
  || miss "missing critical file: api-contracts/openapi/openapi.yaml"
test -f "api-contracts/dispatcher/dispatcher.proto" \\
  && ok "api-contracts/dispatcher/dispatcher.proto" \\
  || miss "missing critical file: api-contracts/dispatcher/dispatcher.proto"
test -f ".github/workflows/sdk-typescript.yml" \\
  && ok ".github/workflows/sdk-typescript.yml" \\
  || miss "missing critical file: .github/workflows/sdk-typescript.yml"
test -f ".github/workflows/sdk-python.yml" \\
  && ok ".github/workflows/sdk-python.yml" \\
  || miss "missing critical file: .github/workflows/sdk-python.yml"
test -f ".github/workflows/sdk-go.yml" \\
  && ok ".github/workflows/sdk-go.yml" \\
  || miss "missing critical file: .github/workflows/sdk-go.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hatchet-dev/hatchet"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.