What you can do with Task State Guard

3 use cases

• Preview restart cleanup of stuck tasks before applying it

  Dry-run a SQLite task ledger, review aggregate counts, then apply timeouts and delivery closures.

  • Task State Guard
  • Software and DevOps
  • Intermediate
  View prompt

  Using the MaxHu-xuan/task-state-guard repo, run the reconcile command with --dry-run against <ledger-path> using --active-grace-seconds 600 and --delivery-grace-seconds 600, then report the aggregate counts. Verify that the output shows dry_run true and applied false before you run any apply step.

  Share Save

• Record task and delivery closures only from real outcomes

  Write terminal task states and delivery states from a Python worker without guessing success.

  • Task State Guard
  • Software and DevOps
  • Intermediate
  View prompt

  Using the MaxHu-xuan/task-state-guard repo, write a short Python script that creates a task in <ledger-path>, starts it, and closes it as succeeded only after your worker reports success. Verify that you call set_delivery with delivered only after a real transport acknowledgement, and report the final task and delivery states.

  Share Save

• Check a workflow ledger's health before trusting its history

  Run a counts-only doctor check on a SQLite task ledger and read its exit code.

  • Task State Guard
  • Software and DevOps
  • Intermediate
  View prompt

  Using the MaxHu-xuan/task-state-guard repo, run the doctor command against <ledger-path> and report the aggregate counts and the exit code. Verify that the output contains only counts and no task IDs, prompts, or message bodies.

  Share Save

How to use Task State Guard

1. Check you have what it needs: CPython 3.11 to 3.14; A SQLite ledger file on a local filesystem, not a network or mapped drive; A virtual environment with task-state-guard installed from PyPI.
2. Open MaxHu-xuan/task-state-guard on GitHub and read the README and license.
3. Create and activate a virtual environment, then run python3 -m venv .venv and . .venv/bin/activate.
4. Install the package with python -m pip install task-state-guard.
5. Preview the changes with task-state-guard --db ./private-state/tasks.sqlite reconcile --active-grace-seconds 600 --delivery-grace-seconds 600 --dry-run. (inferred, check the README)
6. Review the returned counts, then apply with task-state-guard --db ./private-state/tasks.sqlite reconcile --active-grace-seconds 600 --delivery-grace-seconds 600. (inferred, check the README)

These steps come from our top use case, Preview restart cleanup of stuck tasks before applying it, which also has a copy-paste agent prompt.

Task State Guard alternatives · Best AI repos for Software and DevOps

About this repo

• Who it is forDevelopers and operators running AI agents, background workers, or local workflows that need to recover task state after a restart or timeout.
• Why it is hot
• LanguagePython
• Sourcegithub.com/MaxHu-xuan/task-state-guard · Back to Hot repos

Requirements

• CPython 3.11 to 3.14
• A SQLite ledger file on a local filesystem, not a network or mapped drive
• A virtual environment with task-state-guard installed from PyPI

Related repos

• #1 this week Harness2 Harness² is a Python framework from Google Research that refines the harness around a fixed model (prompts, tools, memory, skills, orchestration) so it performs better on agent tasks.
• #8 this week iFixAi iFixAi is an open-source Python tool that audits whether an AI agent is doing the job it is supposed to do, using 60 inspections that combine red-teaming with operational checks.
• #9 this week Orca Orca is a desktop app, with a mobile companion, for running several CLI coding agents side by side, each in its own git worktree, and tracking them in one place.