Efficient Task Handler

Execute one-off tasks with automatic environment detection, dependency resolution, and structured output formatting for scripting and CI/CD integration.

When to Use This Command

Run this command when...

• You need to run a well-defined task (build, test, deploy, migrate) with a single command and want Claude to detect the correct tooling automatically
• Your CI/CD pipeline needs a generic task executor that adapts to any project type without per-language configuration
• You want structured JSON or machine-readable output from a task execution for downstream processing

Avoid this command when...

• The task requires interactive input or long-running watch mode (use dedicated development server commands instead)
• You need ongoing sync or monitoring rather than a one-shot execution (use sync or monitoring commands instead)

Quick Start

Copy
# .task-config.yaml
tasks:
  build:
    auto_detect: true
    output_format: json
  test:
    auto_detect: true
    fail_fast: true
  lint:
    auto_detect: true
    fix: true

Copy
claude -p "Run the build task and output results as JSON"

Expected output:
{
  "task": "build",
  "tool_detected": "npm",
  "command": "npm run build",
  "status": "success",
  "duration_ms": 12450,
  "artifacts": [
    { "path": "dist/index.js", "size": "142KB" },
    { "path": "dist/index.css", "size": "28KB" }
  ],
  "warnings": 2,
  "errors": 0
}

Core Concepts

Concept	Description
Auto-Detection	Scans project files (package.json, Makefile, build.gradle) to determine the correct build tool
Structured Output	Produces JSON, YAML, or table-formatted output for programmatic consumption
Fail-Fast Mode	Halts execution on first error rather than collecting all errors, useful for CI pipelines
Dependency Resolution	Installs missing dependencies before task execution if auto_install is enabled
Exit Code Mapping	Maps tool-specific exit codes to standard success/failure semantics

Project Root
     |
     v
[Auto-Detect] --> package.json? --> npm
              --> Makefile?     --> make
              --> build.gradle? --> gradle
              --> Cargo.toml?   --> cargo
                    |
                    v
              [Run Task]
                    |
                    v
             [Structured Output]
              { status, duration,
                artifacts, errors }

Configuration

Parameter	Type	Default	Description	Example
auto_detect	boolean	true	Automatically determine the build tool	false
output_format	string	text	Output format for results	json
fail_fast	boolean	false	Stop on first error	true
auto_install	boolean	false	Install missing dependencies before running	true
timeout	number	300	Task timeout in seconds	600

Best Practices

1. Use JSON output in CI/CD pipelines -- Machine-readable output lets downstream steps parse results without fragile text scraping.
2. Enable fail-fast for pull request checks -- Fast feedback on the first error saves CI minutes and gives developers quicker signals.
3. Pin tool versions in your config -- Auto-detection finds the tool but not the version. Specify tool versions to ensure reproducible builds across environments.
4. Set appropriate timeouts -- The default 300-second timeout works for most tasks, but builds with heavy compilation or integration tests may need more.
5. Capture artifacts in the output -- Configure the task to report generated artifacts (bundles, binaries, coverage reports) so downstream steps know what was produced.

Common Issues

1. Wrong build tool detected -- Projects with both package.json and Makefile may trigger the wrong detector. Set auto_detect: false and specify the tool explicitly.
2. Task fails because dependencies are missing -- Enable auto_install: true or run the dependency installation task separately before the main task.
3. Timeout on large projects -- Increase the timeout value or break the task into smaller sub-tasks. For monorepos, scope the task to a specific package or module.