{"id":28744766,"url":"https://github.com/hatchet-dev/pickaxe","last_synced_at":"2025-06-16T12:05:33.003Z","repository":{"id":298918098,"uuid":"1001531356","full_name":"hatchet-dev/pickaxe","owner":"hatchet-dev","description":"wip","archived":false,"fork":false,"pushed_at":"2025-06-13T15:55:52.000Z","size":181,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-13T16:25:54.819Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/hatchet-dev.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}},"created_at":"2025-06-13T14:39:41.000Z","updated_at":"2025-06-13T15:35:25.000Z","dependencies_parsed_at":"2025-06-13T16:36:12.507Z","dependency_job_id":null,"html_url":"https://github.com/hatchet-dev/pickaxe","commit_stats":null,"previous_names":["hatchet-dev/pickaxe"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hatchet-dev/pickaxe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatchet-dev%2Fpickaxe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatchet-dev%2Fpickaxe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatchet-dev%2Fpickaxe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatchet-dev%2Fpickaxe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hatchet-dev","download_url":"https://codeload.github.com/hatchet-dev/pickaxe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatchet-dev%2Fpickaxe/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260158325,"owners_count":22967226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2025-06-16T12:05:32.380Z","updated_at":"2025-06-16T12:05:32.988Z","avatar_url":"https://github.com/hatchet-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./static/pickaxe_dark.png\"\u003e\n  \u003cimg width=\"200\" alt=\"Hatchet Logo\" src=\"./static/pickaxe_light.png\"\u003e\n\u003c/picture\u003e\n\u003c/a\u003e\n\u003c/div\u003e\n\n## Pickaxe: a Typescript library for building distributed agents\n\nPickaxe is a library for building distributed agents, built on top of [Hatchet](https://github.com/hatchet-dev/hatchet). Pickaxe agents are:\n\n- **Distributed by default** - all agents and tools run across a fleet of machines, where scheduling is handled gracefully by Hatchet\n- **Scalable** - Pickaxe agents allow simple configuration for retries, rate limiting, concurrency control, and much more\n- **Durable by default** - all tools called by the agent are sent through a durable message boundary\n- **Agnostic to execution pattern** - Pickaxe agents can be written as loops, scatter/gather workflows, or directed acyclic graphs\n\n## Get started\n\nGetting started is as easy as two commands:\n\n```\npnpm i -g @hatchet-dev/pickaxe-cli\npickaxe create first-agent\n```\n\n## Concepts\n\n- **Agents** - an agent is simply a loop that calls **tools**\n- **Toolbox** - a collection of tools that are available to an agent\n- **Tools** - a tool is a function available to an agent. A tool can call other tools, agents, or integrations.\n- **Integrations** - an integration is a third-party API call made by a tool\n\n## Is Pickaxe a framework?\n\nYes and no. Pickaxe is **not opinionated** on how you should structure your LLM calls, business logic, prompts, or contexts. It is designed to be extended and modified -- for example, you could build your own agent library on top of Pickaxe.\n\nHowever, Pickaxe contains opinions on best practices for deploying agents into production, and lots of the decisions in the project are designed with these best practices in mind. See [agent best practices](#agent-best-practices) for more information.\n\n## Agent Best Practices\n\nWhen writing agents with Pickaxe, it's useful to follow these rules:\n\n1. Agents should be **stateless reducers** with **no side effects**. They should not depend on external API calls, database calls, or local disk calls; their entire state should be determined by the results of their tool calls. See the [technical deep-dive](#technical-deep-dive) for more information.\n\n2. All quanta of work should be invoked as a task or a tool call.\n\n## Technical Deep-Dive\n\nPickaxe is a utility layer built on top of [Hatchet](https://github.com/hatchet-dev/hatchet). Hatchet is a platform for async processing and background jobs, with features like:\n\n- Queues\n- Task Orchestration (DAGs and durable execution)\n- Flow Control (concurrency or rate limiting)\n- Scheduling (cron jobs and scheduled tasks)\n- Task routing (sticky execution and affinity)\n- Event triggers and listeners\n\nIt is built on the concept of a **durable task queue**, which means that every task which gets called in Hatchet is stored in a database. This is useful because tasks can easily be replayed and recover from failure, even when the underlying hardware crashes. Another way to look at it: Hatchet makes _distributed systems incredibly easy to deploy and maintain_.\n\nFor agents, this is particularly useful because they are extremely long-running, and thus need to be resilient to hardware failure. Agents also need to manage third-party rate limits and need concurrency control to prevent the system from getting overwhelmed.\n\nThe first rule of agents is that they should be _stateless reducers with no side effects_. To understand why, it's necessary to understand some concepts of durable execution. At its core, a function which executes durably stores an event log of all functions it has executed up to that point. Let's say an agent has called the tools `search_documents`, `get_document`, and is in the middle of processing `extract_from_document`. Its execution history looks like:\n\n```\nEvent log:\n-\u003e Start search_documents\n-\u003e Finish search_documents\n-\u003e Start get_document\n-\u003e Finish get_document\n-\u003e Start extract_from_document...\n```\n\nNow, let's say that the machine which the agent is running on crashes during the last step. In order to recover from failure, Pickaxe will automatically replay all steps up to this point in the execution history:\n\n```\nEvent log:\n-\u003e Start search_documents (replayed)\n-\u003e Finish search_documents (replayed)\n-\u003e Start get_document (replayed)\n-\u003e Finish get_document (replayed)\n-\u003e Start extract_from_document (replayed)\n-\u003e (later) Finish extract_from_document\n```\n\nIn other words, the execution history is cached by Pickaxe, which allows the agent to recover gracefully from failure, instead of having to replay a bunch of work. Another way to think about it is that the agent automatically \"checkpoints\" its state.\n\nThis execution model is much more powerful when there's a requirement to wait for external systems, like a human reviewer or external event. Building a system that's resilient to failure becomes much more difficult, because if the agent starts from scratch, it may have lost the event which allowed execution to continue. In this model, the event automatically gets stored and replayed.\n\nBeyond Hatchet, there are two other points of inspiration for Pickaxe:\n\n- [12-factor agents](https://github.com/humanlayer/12-factor-agents) -- this is the foundation for why Pickaxe advocates owning your control flow, context window, and prompts\n- Anthropic's [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) -- we have ensured that each pattern documented in this post are compatible with Pickaxe\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhatchet-dev%2Fpickaxe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhatchet-dev%2Fpickaxe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhatchet-dev%2Fpickaxe/lists"}