scitex-todo — canonical YAML task store with pluggable adapters

scitex-todo keeps your tasks in one validated YAML store (a top-level tasks: list) and renders that single source of truth through pluggable adapters: a mermaid dependency-graph PNG, a read-only React-Flow web board, and a plain task listing. Part of SciTeX.

The store is resolved in precedence order: an explicit --tasks path → $SCITEX_TODO_TASKS → project <git-root>/.scitex/todo/tasks.yaml → user ~/.scitex/todo/tasks.yaml → the bundled generic example.

Interfaces

Interface	Description
Python API	import scitex_todo as todo — scitex_todo — Python API
CLI	scitex-todo <command> — CLI Reference
MCP	AI-agent tools via fastmcp (on the roadmap)
Skills	AI-agent knowledge pages bundled at _skills/scitex-todo/

Getting Started

• Installation
  • Extras
  • Rendering backends
  • Verify
• Quick Start
  • Task schema
  • Where your task data lives

User Guide

• CLI Reference
  • Universal flags

API Reference

• scitex_todo — Python API
  • Quick Start
  • TaskValidationError
  • RenderError
  • build_mermaid()
  • bundled_example()
  • find_chromium()
  • load_tasks()
  • save_tasks()
  • render()
  • render_with_kroki()
  • render_with_mmdc()
  • resolve_tasks_path()

Quick example

Python API:

import scitex_todo as todo

tasks = todo.load_tasks("tasks.yaml")    # validates id / title / status
mermaid_src = todo.build_mermaid(tasks)  # YAML -> flowchart TB
engine = todo.render(mermaid_src, "tasks.png")
print(f"rendered via {engine}")

CLI:

scitex-todo render-graph -o tasks.png      # YAML -> dependency PNG
scitex-todo list-tasks --json              # resolved tasks, machine-readable
scitex-todo board --port 8051              # read-only web board (needs [web])

Four Freedoms for Research

0. The freedom to run your research anywhere – your machine, your terms.

1. The freedom to study how every step works – from raw data to final manuscript.

2. The freedom to redistribute your workflows, not just your papers.

3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 – because research infrastructure deserves the same freedoms as the software it runs on.

Indices and tables

• Index

• Module Index

• Search Page