Icepick

Thin TypeScript wrapper over the Hatchet SDK. Adds agent, tool, and toolbox abstractions with Zod schemas and LLM-powered tool selection.

hatchet-dev/icepick · 562 ★ · MIT · evaluated 2026-04-03

Goals

Same as Hatchet — durable podcast pipeline execution. Icepick's higher-level agent/tool/toolbox model looked like it might map better onto the pipeline's structure than raw Hatchet tasks.

Effectiveness

Not adopted. Inherits all of Hatchet's infrastructure requirements (still needs the server) while adding abandonment risk on top: 96 commits, 2 contributors, last commit ~9 months ago, no releases since v0.1.9. The API design is genuinely good but the project shows no signs of active maintenance.

What made it effective

The pickAndRun → switch (result.name) → assertExhaustive(result) pattern is the best part. TypeScript discriminated unions on tool names force exhaustive handling of every tool case at compile time. Missed tool names become a type error. This is worth stealing regardless of whether you use Icepick.

Stateless reducer constraint makes replay safe. Icepick agents must be pure orchestrators — no side effects allowed in the fn, only tool calls. The discipline is valuable: the podcast pipeline's pipeline.ts mixes side effects (Antfly indexing, Ollama warmup, file writes) directly into the main function, making replay impossible without custom guard logic. Separating orchestration from effects would be an improvement with or without Icepick.

Zod schemas at agent boundaries. Input and output are parsed at runtime, not just type-checked. Mis-shaped LLM output surfaces immediately instead of propagating silently.

Friction / pain points / surprises

Requires a live Hatchet gRPC endpoint to do anything. Icepick.init() builds a client object without connecting, but icepick.start() immediately tries to register workflows over gRPC. Without a server, it logs UNAVAILABLE: No connection established on a retry loop indefinitely — it does not throw, it does not exit, it just sits there. No offline or embedded mode.

Deprecation noise on every import. Three stderr banners about the v0 Hatchet SDK print on startup, for code paths Icepick never uses:

Deprecation warning: The v0 sdk, including the step module has been deprecated...

Not suppressible.

defaultLanguageModel required at construction, throws before token check. Icepick.init() validates the language model before it checks for HATCHET_CLIENT_TOKEN. The error you see first is "defaultLanguageModel is required", which is confusing when you're trying to diagnose a token issue.

Toolbox's pickAndRun assumes an OpenAI-compatible model. Depends on @ai-sdk/openai and the Vercel AI SDK's LanguageModelV1 interface. Getting Ollama to work requires a community adapter. There's no way to pass in a custom callLLM function.

~300 lines of source over 121 npm packages. The value-add over the Hatchet SDK directly is thin. The toolbox's pickAndRun is the most unique feature; the agent/tool wrappers are just Zod validation over Hatchet's existing workflow API.

9 months stale. Would not stake a production workload on this. The Hatchet SDK it wraps is actively maintained; use that directly if you want the durability primitives without the abandonment risk.