Autonomous task orchestration for Claude Code
Hearth is a hierarchical task management system that enables AI agents to break down complex coding tasks into smaller, manageable subtasks and execute them autonomously with full context preservation across the entire task tree.
Hearth solves the "telephone problem" in AI-driven development: when complex tasks are broken into subtasks, context is often lost. Hearth maintains full context throughout arbitrarily deep task hierarchies, enabling AI agents to:
- 📋 Break down complex work into manageable pieces
- 🔗 Share knowledge between sibling tasks
- 🎯 Stay aligned with root goals through deep hierarchies
- 📊 Automatically synthesize findings from subtasks
- 🔄 Execute tasks in correct depth-first order
Built on Atmos, providing complete audit trails and replay capability. All state changes flow through immutable events (TaskCreated, TaskStarted, TaskCompleted).
Tasks can have parent-child relationships forming trees of arbitrary depth. Parent tasks auto-complete when all children finish, triggering automatic result synthesis.
Child tasks automatically receive:
- Root goal - The ultimate objective from the top of the hierarchy
- Parent chain - Full lineage showing how this task fits in
- Sibling results - Findings from previously completed siblings
Every task stores its output to .hearth/results/<task-id>.md, creating a knowledge base that:
- Prevents duplicate work between siblings
- Enables progressive refinement
- Supports parent summarization
- Provides complete execution history
Tasks execute in proper hierarchical order - completing entire subtrees before moving to the next sibling, ensuring logical progression through complex workflows.
IMPORTANT: Hearth must be in your PATH for autonomous task creation to work. When Claude Code creates subtasks, it runs hearth add commands which require the binary to be accessible.
# Install directly to your GOPATH/bin (usually in PATH)
go install github.com/fmizzell/hearth/cmd/hearth@latest
# Verify it's accessible
hearth --help# Clone the repository
git clone https://github.com/fmizzell/hearth.git
cd hearth
# Build the binary
go build -o bin/hearth ./cmd/hearth
# Add to PATH (required, not optional!)
# Add this to your ~/.bashrc, ~/.zshrc, or equivalent:
export PATH="$PATH:$HOME/path/to/hearth/bin"
# Or create a symlink to a directory already in PATH:
ln -s "$(pwd)/bin/hearth" ~/.local/bin/hearth
# Verify it's accessible from any directory
cd ~
hearth --help# Initialize with a built-in preset
hearth run --preset hello
# Or create a custom task
hearth add -t "Refactor authentication" \
-d "Update login system to use OAuth2"hearth runHearth will:
- Get the next task
- Send its description to Claude Code
- Store Claude's response to
.hearth/results/<task-id>.md - Mark the task complete
- If Claude created subtasks, process them recursively
- Generate parent summaries when subtrees complete
- Repeat until all tasks are done
# List all tasks in execution order
hearth list
# Filter by status
hearth list --status todo
hearth list --status completed┌─────────────────────────────────────────────────────────┐
│ 1. Task Created │
│ - Store event to .hearth/events.json │
│ - Status: "todo" │
└────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 2. Task Execution │
│ - Build context (root goal, parent chain, siblings) │
│ - Call Claude Code with enriched prompt │
│ - Store response to .hearth/results/<task-id>.md │
└────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 3. Task Completion │
│ - If has children: Status stays "todo" │
│ - If no children: Status → "completed" │
│ - Check if parent needs summary │
└────────────────┬────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 4. Parent Summary (when all children complete) │
│ - Re-run parent with child result references │
│ - Overwrite parent result with synthesis │
│ - Mark parent complete │
│ - Recursively trigger grandparent summary if needed │
└─────────────────────────────────────────────────────────┘
When a child task executes, it sees:
ROOT TASK: Analyze codebase for security issues
ROOT GOAL: Identify vulnerabilities and create fix tasks
PREVIOUS SIBLING RESULTS:
Your siblings have already completed work. You can reference their findings:
- T-abc123 "Scan dependencies" → Result: .hearth/results/T-abc123.md
- T-def456 "Check input validation" → Result: .hearth/results/T-def456.md
You can read these files to avoid duplicating work and build on their findings.
---
CURRENT TASK: Review authentication code
...
Here's what happened when we ran hearth run --preset code-quality:
📋 Tasks:
✓ Code Quality Analysis
✓ Explore codebase structure
✓ Analyze file metrics
✓ Identify all Go files
✓ Run gocyclo
✓ Calculate metrics
✓ Generate metrics table
✓ Document dependencies
✓ Analyze test coverage
✓ Create analysis list
✓ Run static analysis
✓ Run gofmt
✓ Run go vet
✓ Run golangci-lint
✓ Additional tools
✓ Run staticcheck
✓ Run race detector
✓ Consolidate findings
✓ Consolidate all findings
✓ Identify quality issues
✓ Generate final report
Result: 20+ interconnected tasks, 4 levels deep, generated a comprehensive 586-line professional code quality report with zero context loss.
hearth run --preset code-qualitySystematically analyzes codebase, runs multiple tools, identifies issues, generates actionable report.
Create a task to refactor a module. Claude breaks it into file-by-file subtasks, each with context about the overall refactoring goal.
Implement features that span multiple files. Each file gets its own subtask, with access to what was done in other files.
Gather information from multiple sources, then synthesize into a comprehensive document. Each research task stores findings, final task combines them all.
Create comprehensive tests for a module. Claude creates subtasks for different test categories, each aware of tests already written.
hearth/
├── cmd/hearth/ # CLI application
│ ├── main.go # Entry point
│ ├── run.go # Task execution loop
│ ├── add.go # Task creation
│ └── list.go # Task display
├── prompts/ # Built-in task presets
│ ├── hello.txt
│ └── code-quality-analysis.txt
├── hearth.go # Core task management
├── events.go # Event definitions
├── reducers.go # State management
├── file_repository.go # Event persistence
└── .hearth/ # Runtime data (gitignored)
├── events.json # Event log
└── results/ # Task output files
Create a new task.
# Simple task
hearth add -t "Fix bug in login" -d "Add null check to user validation"
# With parent (creates subtask)
hearth add -t "Update tests" -p T-parent-id
# With dependency
hearth add -t "Deploy" -d "Deploy to production" --depends-on T-test-idExecute tasks autonomously.
# Run all pending tasks
hearth run
# Start with a preset
hearth run --preset code-quality
hearth run --preset helloView task status.
# All tasks in execution order
hearth list
# Filter by status
hearth list --status todo
hearth list --status completed
hearth list --status in-progressManually mark a task complete.
hearth complete T-12345Hearth uses your current directory as the workspace. The .hearth/ directory stores all state:
.hearth/
├── events.json # Event sourcing log
└── results/
├── T-abc123.md # Task results
└── T-def456.md
You can have multiple independent workspaces by running Hearth in different directories.
Add .txt files to prompts/ directory:
# prompts/my-custom-preset.txt
Analyze the database schema and create migration tasks for normalization issues.
Break this into:
1. Analyzing current schema
2. Identifying normalization violations
3. Creating migration subtasks
4. Generating rollback scriptsUse it:
hearth run --preset my-custom-presetRun in a different directory:
hearth run --workspace /path/to/projectAll state changes are events stored in .hearth/events.json. State is reconstructed by replaying events through reducers. This provides:
- Complete audit trail
- Time-travel debugging
- Crash recovery
- Concurrent safety (with file locking)
The GetNextTask() algorithm traverses the task tree depth-first:
- Find root tasks (no parent)
- Sort by creation time
- For each root, recursively search its subtree
- Return first eligible leaf task
This ensures logical execution order where subtrees complete before siblings.
Core algorithms like findNextTask(tasks) are pure functions that take task slices and return results, making them easy to test and reason about.
# Run all tests
go test ./...
# Run with coverage
go test -cover ./...
# Run specific test
go test -v -run TestFindNextTask_DepthFirstContributions welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing) - Write tests for new functionality
- Ensure all tests pass (
go test ./...) - Commit with descriptive messages
- Push to your fork
- Open a Pull Request
Apache License 2.0 - see LICENSE for details.
- Built with Atmos event sourcing framework
- Designed for Claude Code autonomous development
- Inspired by hierarchical task networks and event-driven architectures
Made with 🔥 for autonomous AI development