taskhelm

v0.1.13

Published

4 days ago

Local-first visual workbench for parallel git-worktree work — manage tasks, branches, worktrees, ports, and pooled dev servers from one dashboard on your machine.

0High
0Medium
0Low

vantienkhai

git-worktree developer-tools local-first task-management dev-server workbench parallel-development monorepo nextjs cli sqlite

TaskHelm

Local-first visual workbench for parallel git-worktree work.

Stop juggling git worktree add, lsof -i, and four terminal tabs. Manage every task, branch, worktree, port, and dev server from one dashboard on your machine.

Why TaskHelm

The git-worktree workflow is the right answer for running multiple branches in parallel — but the existing tooling is all CLI. You memorize commands, juggle terminals, and keep a private mental map of which branch lives at which path on which port. As soon as you have four or five tasks in flight, the coordination layer becomes a person. You.

TaskHelm replaces that mental map with a UI. It's the local control plane for parallel-worktree development:

| Without TaskHelm | With TaskHelm | |---|---| | git worktree add ../foo feat/foo, cd ../foo, pnpm i, lsof -i :3001, … repeat per task | One click creates branch + worktree + port for a task | | Which task is on which branch? Which worktree is at which path? Which port? | All visible in a single dashboard, sortable per project | | Dev servers eat all your laptop's RAM | Pooled with max concurrency — warm vs sleeping, kill external port squatters from the UI | | External process squatting your port? kill -9 $(lsof -ti :3001) | Modal shows PID / command / user / cwd, one-click Kill & Start | | Plans and notes live in chat sessions and die with them | Each task owns a Markdown folder on disk that survives crashes, restarts, and tool resets |

TaskHelm is built for single operators running many things at once — solo CTOs, technical founders, staff engineers acting as their own manager. Open source, MIT, works entirely offline against your local filesystem.

Read docs/01-product-vision.md for the full design rationale.

Quick start

Install the workbench (CLI + dashboard):

npm i -g taskhelm
taskhelm
# → boots the dashboard at http://127.0.0.1:4100 and opens your browser

CLI only (no dashboard auto-launch):

npm i -g @taskhelm/cli
taskhelm-cli project list

Requires Node.js ≥ 22.14. State lives at ~/.taskhelm/taskhelm.db (override with TASKHELM_DB), runtime cache at ~/.taskhelm/runtime/<version> (override with TASKHELM_HOME), default port 4100 (override with TASKHELM_PORT or PORT).

On first run the launcher prepares the local Next.js standalone runtime from assets shipped inside the npm tarball — about 60–90 seconds, then cached for subsequent boots. No external services, no telemetry.

What you get

Worktree-aware task list

Per project, every task shows its branch, worktree path, and allocated port at a glance. Sortable, searchable, and the source of truth for "what's running where".

Workspace isolation

Per-task branch + worktree + allocated port, created from the dashboard or CLI. Subrepos detected automatically. Existing unassigned worktrees can be attached instead of recreated.

Pooled dev servers

Max concurrency per project, warm vs sleeping states, health checks, and graceful shutdown. When an external process is squatting your port, the dashboard pops a modal showing PID / command / user / cwd with a one-click Kill & Start.

Task context capsules

Each task has its own folder on disk: context.md, plan.md, handoff.md, plus a free-form artifacts/ tree. Versionable in Git, readable without TaskHelm, and survive any crash or restart.

Context vault preview

Link any folder into a task and TaskHelm renders Markdown notes inline with embedded images, videos, and diagrams. [@path] references resolve across the linked tree.

CLI parity

Every dashboard action is also a CLI command — project, task, workspace, dev groups. The CLI and the dashboard read/write the same SQLite file, so you can mix freely.

Screenshots

How it works

┌──────────┐  ┌───────────────┐
│   CLI    │  │   Dashboard   │   equal first-class surfaces
└────┬─────┘  └───────┬───────┘
     │                │
     └────────┬───────┘
              ▼
      ┌──────────────┐
      │  SQLite (WAL)│   runtime state — projects, tasks,
      ├──────────────┤   dev_servers, locks, events, notifications
      │ Disk capsules│   Markdown + YAML — context, plan, handoff,
      └──────────────┘   artifacts (per-task folders)

Two complementary storage layers — SQLite for runtime truth, Markdown/YAML for human-readable context that survives outside the tool. Every dashboard mutation updates SQLite first; capsule files on disk are kept in sync alongside.

| Package | npm | Role | |---|---|---| | taskhelm | | Launcher — preps runtime, opens dashboard | | @taskhelm/cli | | Commander CLI (project, task, workspace, dev) | | @taskhelm/core | | Domain model, SQLite repos, migrations, workspace utils | | @taskhelm/supervisor | | Dev-server pool + crash recovery |

Stack: Next.js 15 + React 19 (dashboard) · Commander (CLI) · better-sqlite3 (state, WAL) · TypeScript 5.7 strict · pnpm + Turborepo · Vitest + Playwright (tests).

Autonomy boundary

| Allowed by default | Not allowed by default | |---|---| | Create branch / worktree | Push branches | | Allocate ports & start dev servers | Merge or rebase shared branches | | Edit code inside worktrees | Open / close PRs | | Run local dev / test commands | Mutate external ticket systems | | Update task capsules and notes | Anything that touches a remote you didn't explicitly authorize |

The line is intentional. TaskHelm is built so you'd trust running it unattended on your laptop, not so it can ship to prod for you.

Development

git clone https://github.com/Kaka-123-D/TaskHelm.git
cd TaskHelm
pnpm install
pnpm run typecheck   # tsc --noEmit across all packages
pnpm run test        # Vitest in every package
pnpm run build       # core → supervisor → cli → web (sequenced)
pnpm --filter @taskhelm/web run dev   # dashboard at :4100

See CONTRIBUTING.md for the full guide and CLAUDE.md for the architectural conventions agents must follow when editing this repo.

Documentation

| Doc | What it covers | |---|---| | docs/01-product-vision.md | Why this exists, success criteria, non-goals | | docs/02-v1-architecture.md | System layers and boundaries | | docs/06-domain-model.md | Entities and state machines | | docs/07-sqlite-schema.md | All runtime tables | | docs/08-task-capsule-spec.md | Markdown/YAML capsule format | | docs/10-cli-spec.md | CLI command groups | | docs/11-web-dashboard-spec.md | Dashboard screens | | docs/04-init-roadmap.md | Phased implementation plan |

Status

TaskHelm is in active early development — building toward a stable v1 cut. The runtime, dashboard, CLI, dev pool, and context vault are functional today. APIs may change between minor versions until v1.0.0.

What's next: richer worktree visualization (graph view), better stale-worktree cleanup, multi-repo projects, and a "switch task" command palette. See docs/04-init-roadmap.md.

Star history

If TaskHelm helps you, a star is the cheapest way to say so — and it makes the project visible to the next person fighting the same coordination problem.

Contributing

Issues, ideas, and PRs are all welcome. Especially valuable:

Bug reports with a ~/.taskhelm/taskhelm.db path and the steps that reproduced
UX improvements to the worktree task list and dev-pool views
Better stale-worktree detection / cleanup heuristics
Multi-repo / monorepo subrepo handling

Start with CONTRIBUTING.md. For larger changes, open an issue first so we can align on shape before you build.