lhtask

LHTask — Autonomous TODO Workflow for Claude Code

Turn a rough idea into a reviewed, tested implementation — automatically.

LHTask gives Claude Code a three-stage autonomous workflow: refine an idea into a structured task, then let a git-hook chain plan → implement → review it. The implementer runs as a subagent team (planner, navigator, implementer, deterministic gate, reviewers — in a bounded loop) inside an isolated worktree on a branch that is never auto-merged — or, opt-in (LHTASK_DELIVERY=apply), converged work lands as staged changes that you commit. A deterministic gate (lint/typecheck/test/build, plus fallow static analysis when installed) and fail-closed reviewers catch problems before you ever see them. Language-agnostic and config-driven, so it drops into any repo.

graph LR
    A["💡 Idea"] --> B["/lhtask:lh-task"]
    B --> C["TODO.md"]
    C --> D["git commit"]
    D --> E["🔧 PLAN"]
    E --> F["🧭 NAVIGATE"]
    F --> G["⚙️ IMPLEMENT"]
    G --> H{"✅ GATE"}
    H --"red"--> G
    H --"green"--> I["👀 REVIEW"]
    I --"blocker"--> G
    I --"pass"--> J["📋 TODO.review.md"]

How it works (30 seconds)

1. Capture — /lhtask:lh-task "your idea" refines it into one structured TODO.md item.
2. Commit — git add TODO.md && git commit -m "task: …" triggers the chain.
3. Done — The chain plans, implements, gates, and reviews. You get a TODO.review.md with findings. Nothing is auto-merged — you stay in control.

Install & use

# one-time (GitHub is the only install channel — see docs/DISTRIBUTION.md):
claude plugin marketplace add leonhoffmann86/lhtask-plugin
claude plugin install lhtask@lhtask-marketplace

# inside any repo you want to enable:
/lhtask:bootstrap                               # writes hooks + lhtask.conf + starters
/lhtask:lh-task "your idea"                     # capture the first task
git add TODO.md && git commit -m "task: ..."    # starts the chain

Pick up a new release later: claude plugin marketplace update lhtask-marketplace && claude plugin update lhtask, then /lhtask:update inside each bootstrapped repo.

Kill switch: touch .git/autoplan.disabled · live trace: tail -f TODO.run.log (streams every agent tool call in real time).

Security

LHTask installs a git post-commit hook that launches headless claude processes. This is powerful — and taken seriously:

Concern	How LHTask addresses it
Unintended recursion	Agent commits are flagged with AUTOPLAN_AGENT=1; the hook skips them — no infinite loops
Destructive operations	git push, git reset --hard, git rebase, rm -rf, Task/Agent delegation — hard-denied per role via --settings
Escaping the sandbox	Planner, navigator, and reviewers are read-only (dontAsk + allowlist); only the implementer is commit-capable
Runaway agents	Bounded loop: max 3 implement→gate→review iterations per run
Stuck locks	mkdir-based locks with automatic stale-reaping prevent deadlocks from killed runs
Emergency stop	touch .git/autoplan.disabled — instant kill switch for the entire chain
Human oversight	The impl branch is never auto-merged; opt-in apply delivery only stages converged work — the commit is always yours; high-risk items are deferred to ## 🚧 Deferred and never touched autonomously
Silent degradation	Cross-vendor model fallbacks and every missing tool the chain touches (codegraph, fallow, jq, timeout, gate tools like eslint/pytest, curl & notifier when relevant) are reported in every TODO.review.md (### Model fallbacks / ### Tooling) — graceful, never silent

Before installing any git-hook-based plugin, audit its scripts and understand what it does on your machine. LHTask is MIT-licensed and the full source is right here. Start with templates/githooks/README.md for a stage-by-stage walkthrough of the installed chain.

Documentation

The deep documentation is the source of truth and stays current automatically (see Doc automation below) — start here: