# TaskPanel: A Robust Interactive Terminal Task Runner
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
TaskPanel is a professional-grade, terminal-based tool designed to run, monitor, and manage multi-step parallel tasks defined in a simple CSV file. It provides a highly responsive and fault-tolerant TUI (Text-based User Interface) for complex workflows.
## Key Features
### Core Functionality
- **Parallel Execution**: Runs each task (row in the CSV) in a parallel worker thread
- **Sequential Steps**: Executes the steps (columns) within each task sequentially
- **Interactive TUI**: A full-screen, responsive `curses`-based interface to monitor task status
- **Detailed Views**: Context-aware panels show task information and step output
- **Advanced Navigation**:
- Vertical scrolling for hundreds of tasks
- Horizontal scrolling for tasks with many steps
### Robustness & Reliability
- **State Persistence**: Intelligent resume capability after crashes or interruptions
- **Task State Management**: Completed tasks preserved, interrupted tasks reset appropriately
- **Concurrency Control**: Configurable worker limits to prevent resource exhaustion
- **Safe Threading**: Deadlock-free threading with proper synchronization
### Performance & Debugging
- **Log Management**: Structured logging with unique directories per task
- **Efficient UI**: Smart refresh mechanism for minimal CPU usage
- **Debug Features**: Toggleable debug panel with detailed lifecycle information
### New
- **YAML Workflow Support**: Load workflows from YAML files with strict schema validation
- **CSV → YAML Conversion**: Convert CSV workflows to YAML via CLI (requires PyYAML)
## Installation
```bash
pip install taskpanel
```
or from source:
```bash
git clone https://github.com/Wenutu/TaskPanel.git
cd TaskPanel
pip install -e .
```
> Note: UI runtime requires a POSIX-like OS (Linux/macOS).
#### Quick Start
1. Define your workflow
- CSV:
```csv
TaskName,Info,Checkout,Build,Test
MyApp,v1.0.0,./scripts/1_checkout.sh,./scripts/2_build.sh,./scripts/3_test.sh
```
- YAML:
```yaml
steps: [Checkout, Build, Test]
tasks:
- name: MyApp
info: v1.0.0
steps:
Checkout: "./scripts/1_checkout.sh"
Build: "./scripts/2_build.sh"
Test: "./scripts/3_test.sh"
```
2. Run from command line
```bash
# CSV
taskpanel tasks.csv
# YAML
taskpanel tasks.yaml
```
3. Or use as a Python library
```python
import taskpanel
taskpanel.run(
workflow_path="tasks.csv", # or "tasks.yaml"
max_workers=4,
title="My Workflow"
)
```
#### Example Project Structure
```
your_project/
├── tasks.csv # or tasks.yaml
├── scripts/
│ ├── 1_checkout.sh
│ ├── 2_build.sh
│ ├── 3_test.sh
│ └── 4_deploy.sh
└── app.py
```
## Task Definition Format
Define your workflow using CSV or YAML. In both formats, each task has sequential steps.
### CSV
- Header row with at least: TaskName, Info
- Subsequent columns are step names; each cell is a shell command (empty means no step)
Example:
```csv
TaskName,Info,Checkout,Build,Test,Deploy
WebApp,v1.2.0,./scripts/1_checkout.sh,./scripts/2_build.sh,./scripts/3_test.sh,./scripts/4_deploy.sh
API-Server,v1.2.0,./scripts/1_checkout.sh,./scripts/2_build.sh --api,./scripts/3_test.sh --integration,./scripts/4_deploy.sh --api
```
### YAML (strict schema)
Top-level keys:
- steps: optional list of step names
- tasks: required list of task objects
Each task:
- name: string (required)
- info or description: string (optional; use description for multiline)
- steps: mapping of step_name (string) to command (string, nullable)
Example:
```yaml
steps: [Checkout, Build, Test, Deploy] # optional; will be derived if omitted
tasks:
- name: WebApp
info: v1.2.0
steps:
Checkout: "./scripts/1_checkout.sh"
Build: "./scripts/2_build.sh"
Test: "./scripts/3_test.sh"
Deploy: "./scripts/4_deploy.sh"
- name: API-Server
description: |
Version: v1.2.0
Owner: Bob
steps:
Checkout: "./scripts/1_checkout.sh"
Build: "./scripts/2_build.sh --api"
Test: "./scripts/3_test.sh --integration"
Deploy: "./scripts/4_deploy.sh --api"
```
Validation rules:
- Only top-level keys steps and tasks are allowed
- Only task keys name, info, description, steps are allowed
- steps mapping must have string keys and string or null values
## Usage
### Command Line Interface
```bash
# Basic usage (CSV or YAML)
taskpanel tasks.csv
taskpanel tasks.yaml
# Options
taskpanel tasks.csv --workers 8 --title "My Build Pipeline"
# Convert CSV to YAML (requires PyYAML)
taskpanel tasks.csv --to-yaml tasks.yaml
```
--to-yaml notes:
- Input must be a CSV file
- Output YAML contains only steps and tasks at top level
- Single-line Info becomes info; multiline Info becomes description
- Empty step cells are omitted from a task’s steps mapping (still listed in top-level steps)
### Python Library
```python
#!/usr/bin/env python3
import taskpanel
def main():
try:
taskpanel.run(
workflow_path="tasks.csv", # or "tasks.yaml"
max_workers=4,
title="My Workflow Runner"
)
except FileNotFoundError as e:
print(f"Error: Task file not found - {e}")
except KeyboardInterrupt:
print("Interrupted by user")
if __name__ == "__main__":
main()
```
### Interactive Controls
| Key | Action |
|-----|--------|
| ↑ ↓ | Navigate tasks |
| ← → | Navigate columns |
| Home / End | Jump to first/last task |
| PgUp / PgDn | Page scroll |
| r | Rerun selected step and subsequent steps |
| k | Kill currently running task |
| d | Toggle debug panel |
| [ / ] | Scroll output log |
| { / } | Scroll debug log |
| q | Quit |
## Project Architecture
- Model (`src/taskpanel/model.py`): Task execution, state management, persistence
- View (`src/taskpanel/view.py`): Terminal UI rendering with curses
- Controller (`src/taskpanel/runner.py`): Event loop and user input handling
- CLI (`src/taskpanel/cli.py`): Command-line interface
## Development
```bash
git clone https://github.com/Wenutu/TaskPanel.git
cd TaskPanel
pip install -e ".[dev]"
# or
make install-dev
```
### Make Commands
- `make test` - Run tests
- `make lint` - Run linting tools
- `make format` - Format code
- `make build` - Build package
- `make clean` - Clean build artifacts
## Compatibility
- OS: POSIX-like only (Linux, macOS)
- YAML: Parsing and conversion require PyYAML (`pip install pyyaml`)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- [PyPI Package](https://pypi.org/project/taskpanel/)
- [GitHub Repository](https://github.com/Wenutu/TaskPanel)
- [Latest Release](https://github.com/Wenutu/TaskPanel/releases/latest)
- [Download Packages](https://github.com/Wenutu/TaskPanel/releases)
- [Documentation](https://github.com/Wenutu/TaskPanel#readme)
- [Issues](https://github.com/Wenutu/TaskPanel/issues)
Raw data
{
"_id": null,
"home_page": "https://github.com/Wenutu/TaskPanel",
"name": "taskpanel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "terminal task runner workflow parallel execution curses tui",
"author": "Wenutu",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/3c/b7/ae670fa3335ceb23f89c9ab6a640a4d3703621ec4f1bb7ca1decd84faef5/taskpanel-1.0.2.tar.gz",
"platform": null,
"description": "# TaskPanel: A Robust Interactive Terminal Task Runner\n\n[](https://www.python.org/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\nTaskPanel is a professional-grade, terminal-based tool designed to run, monitor, and manage multi-step parallel tasks defined in a simple CSV file. It provides a highly responsive and fault-tolerant TUI (Text-based User Interface) for complex workflows.\n\n## Key Features\n\n### Core Functionality\n- **Parallel Execution**: Runs each task (row in the CSV) in a parallel worker thread\n- **Sequential Steps**: Executes the steps (columns) within each task sequentially\n- **Interactive TUI**: A full-screen, responsive `curses`-based interface to monitor task status\n- **Detailed Views**: Context-aware panels show task information and step output\n- **Advanced Navigation**: \n - Vertical scrolling for hundreds of tasks\n - Horizontal scrolling for tasks with many steps\n\n### Robustness & Reliability\n- **State Persistence**: Intelligent resume capability after crashes or interruptions\n- **Task State Management**: Completed tasks preserved, interrupted tasks reset appropriately\n- **Concurrency Control**: Configurable worker limits to prevent resource exhaustion\n- **Safe Threading**: Deadlock-free threading with proper synchronization\n\n### Performance & Debugging\n- **Log Management**: Structured logging with unique directories per task\n- **Efficient UI**: Smart refresh mechanism for minimal CPU usage\n- **Debug Features**: Toggleable debug panel with detailed lifecycle information\n\n### New\n- **YAML Workflow Support**: Load workflows from YAML files with strict schema validation\n- **CSV \u2192 YAML Conversion**: Convert CSV workflows to YAML via CLI (requires PyYAML)\n\n## Installation\n\n```bash\npip install taskpanel\n```\n\nor from source:\n\n```bash\ngit clone https://github.com/Wenutu/TaskPanel.git\ncd TaskPanel\npip install -e .\n```\n\n> Note: UI runtime requires a POSIX-like OS (Linux/macOS).\n\n#### Quick Start\n\n1. Define your workflow\n - CSV:\n ```csv\n TaskName,Info,Checkout,Build,Test\n MyApp,v1.0.0,./scripts/1_checkout.sh,./scripts/2_build.sh,./scripts/3_test.sh\n ```\n - YAML:\n ```yaml\n steps: [Checkout, Build, Test]\n tasks:\n - name: MyApp\n info: v1.0.0\n steps:\n Checkout: \"./scripts/1_checkout.sh\"\n Build: \"./scripts/2_build.sh\"\n Test: \"./scripts/3_test.sh\"\n ```\n\n2. Run from command line\n ```bash\n # CSV\n taskpanel tasks.csv\n\n # YAML\n taskpanel tasks.yaml\n ```\n\n3. Or use as a Python library\n ```python\n import taskpanel\n\n taskpanel.run(\n workflow_path=\"tasks.csv\", # or \"tasks.yaml\"\n max_workers=4,\n title=\"My Workflow\"\n )\n ```\n\n#### Example Project Structure\n\n```\nyour_project/\n\u251c\u2500\u2500 tasks.csv # or tasks.yaml\n\u251c\u2500\u2500 scripts/\n\u2502 \u251c\u2500\u2500 1_checkout.sh\n\u2502 \u251c\u2500\u2500 2_build.sh\n\u2502 \u251c\u2500\u2500 3_test.sh\n\u2502 \u2514\u2500\u2500 4_deploy.sh\n\u2514\u2500\u2500 app.py\n```\n\n## Task Definition Format\n\nDefine your workflow using CSV or YAML. In both formats, each task has sequential steps.\n\n### CSV\n- Header row with at least: TaskName, Info\n- Subsequent columns are step names; each cell is a shell command (empty means no step)\n\nExample:\n```csv\nTaskName,Info,Checkout,Build,Test,Deploy\nWebApp,v1.2.0,./scripts/1_checkout.sh,./scripts/2_build.sh,./scripts/3_test.sh,./scripts/4_deploy.sh\nAPI-Server,v1.2.0,./scripts/1_checkout.sh,./scripts/2_build.sh --api,./scripts/3_test.sh --integration,./scripts/4_deploy.sh --api\n```\n\n### YAML (strict schema)\nTop-level keys:\n- steps: optional list of step names\n- tasks: required list of task objects\n\nEach task:\n- name: string (required)\n- info or description: string (optional; use description for multiline)\n- steps: mapping of step_name (string) to command (string, nullable)\n\nExample:\n```yaml\nsteps: [Checkout, Build, Test, Deploy] # optional; will be derived if omitted\ntasks:\n - name: WebApp\n info: v1.2.0\n steps:\n Checkout: \"./scripts/1_checkout.sh\"\n Build: \"./scripts/2_build.sh\"\n Test: \"./scripts/3_test.sh\"\n Deploy: \"./scripts/4_deploy.sh\"\n - name: API-Server\n description: |\n Version: v1.2.0\n Owner: Bob\n steps:\n Checkout: \"./scripts/1_checkout.sh\"\n Build: \"./scripts/2_build.sh --api\"\n Test: \"./scripts/3_test.sh --integration\"\n Deploy: \"./scripts/4_deploy.sh --api\"\n```\n\nValidation rules:\n- Only top-level keys steps and tasks are allowed\n- Only task keys name, info, description, steps are allowed\n- steps mapping must have string keys and string or null values\n\n## Usage\n\n### Command Line Interface\n\n```bash\n# Basic usage (CSV or YAML)\ntaskpanel tasks.csv\ntaskpanel tasks.yaml\n\n# Options\ntaskpanel tasks.csv --workers 8 --title \"My Build Pipeline\"\n\n# Convert CSV to YAML (requires PyYAML)\ntaskpanel tasks.csv --to-yaml tasks.yaml\n```\n\n--to-yaml notes:\n- Input must be a CSV file\n- Output YAML contains only steps and tasks at top level\n- Single-line Info becomes info; multiline Info becomes description\n- Empty step cells are omitted from a task\u2019s steps mapping (still listed in top-level steps)\n\n### Python Library\n\n```python\n#!/usr/bin/env python3\nimport taskpanel\n\ndef main():\n try:\n taskpanel.run(\n workflow_path=\"tasks.csv\", # or \"tasks.yaml\"\n max_workers=4,\n title=\"My Workflow Runner\"\n )\n except FileNotFoundError as e:\n print(f\"Error: Task file not found - {e}\")\n except KeyboardInterrupt:\n print(\"Interrupted by user\")\n\nif __name__ == \"__main__\":\n main()\n```\n\n### Interactive Controls\n\n| Key | Action |\n|-----|--------|\n| \u2191 \u2193 | Navigate tasks |\n| \u2190 \u2192 | Navigate columns |\n| Home / End | Jump to first/last task |\n| PgUp / PgDn | Page scroll |\n| r | Rerun selected step and subsequent steps |\n| k | Kill currently running task |\n| d | Toggle debug panel |\n| [ / ] | Scroll output log |\n| { / } | Scroll debug log |\n| q | Quit |\n\n## Project Architecture\n\n- Model (`src/taskpanel/model.py`): Task execution, state management, persistence\n- View (`src/taskpanel/view.py`): Terminal UI rendering with curses\n- Controller (`src/taskpanel/runner.py`): Event loop and user input handling\n- CLI (`src/taskpanel/cli.py`): Command-line interface\n\n## Development\n\n```bash\ngit clone https://github.com/Wenutu/TaskPanel.git\ncd TaskPanel\npip install -e \".[dev]\"\n# or\nmake install-dev\n```\n\n### Make Commands\n\n- `make test` - Run tests\n- `make lint` - Run linting tools\n- `make format` - Format code\n- `make build` - Build package\n- `make clean` - Clean build artifacts\n\n## Compatibility\n\n- OS: POSIX-like only (Linux, macOS)\n- YAML: Parsing and conversion require PyYAML (`pip install pyyaml`)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Links\n- [PyPI Package](https://pypi.org/project/taskpanel/)\n- [GitHub Repository](https://github.com/Wenutu/TaskPanel)\n- [Latest Release](https://github.com/Wenutu/TaskPanel/releases/latest)\n- [Download Packages](https://github.com/Wenutu/TaskPanel/releases)\n- [Documentation](https://github.com/Wenutu/TaskPanel#readme)\n- [Issues](https://github.com/Wenutu/TaskPanel/issues)\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A Robust Interactive Terminal Task Runner Library",
"version": "1.0.2",
"project_urls": {
"Bug Reports": "https://github.com/Wenutu/TaskPanel/issues",
"Documentation": "https://github.com/Wenutu/TaskPanel#readme",
"Homepage": "https://github.com/Wenutu/TaskPanel",
"Source": "https://github.com/Wenutu/TaskPanel"
},
"split_keywords": [
"terminal",
"task",
"runner",
"workflow",
"parallel",
"execution",
"curses",
"tui"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1aa8ee6c6975aafaffa45c377b1671ff98118b8e63c457774fe0a76f80a7cdb6",
"md5": "c56d055d71046252ea18601dcb7528ae",
"sha256": "e91b76614d22a195b7fe94140a3119ae6d8eb4b8d6c48d4c51efe3bfe2d64e84"
},
"downloads": -1,
"filename": "taskpanel-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c56d055d71046252ea18601dcb7528ae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 23411,
"upload_time": "2025-10-23T13:37:43",
"upload_time_iso_8601": "2025-10-23T13:37:43.264732Z",
"url": "https://files.pythonhosted.org/packages/1a/a8/ee6c6975aafaffa45c377b1671ff98118b8e63c457774fe0a76f80a7cdb6/taskpanel-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3cb7ae670fa3335ceb23f89c9ab6a640a4d3703621ec4f1bb7ca1decd84faef5",
"md5": "69d0b12ed46343ebb724f5d686ea3372",
"sha256": "7771709c0052983408a7c8a48ff2759645be0f881d63edc53f145f796081661d"
},
"downloads": -1,
"filename": "taskpanel-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "69d0b12ed46343ebb724f5d686ea3372",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 52566,
"upload_time": "2025-10-23T13:37:44",
"upload_time_iso_8601": "2025-10-23T13:37:44.416704Z",
"url": "https://files.pythonhosted.org/packages/3c/b7/ae670fa3335ceb23f89c9ab6a640a4d3703621ec4f1bb7ca1decd84faef5/taskpanel-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 13:37:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Wenutu",
"github_project": "TaskPanel",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "taskpanel"
}
JSON
