pi-workflow-hub: Ticket-Driven Workflow Management Terminal Dashboard for Pi

Core Introduction to pi-workflow-hub

pi-workflow-hub is a terminal workflow management extension developed by masta-g3 and released on GitHub in June 2026, designed specifically for Pi. Its core features include using YAML-formatted feature files as the sole data source, integrating tmux session management and Skills/MCP status tracking, and providing a unified ticket-first development experience. Project link: pi-workflow-hub

Core Objectives

Solve problems such as context fragmentation, inconsistent states, and skill drift in AI-assisted development, allowing developers to maintain organization and efficiency when collaborating with Pi.

Three Challenges in AI-Assisted Development

With the popularity of large-model programming assistants like Pi and Claude Code, traditional project management tools (Jira, Linear, etc.) cannot adapt to Agent execution requirements, leading to the following issues:

1. Context Fragmentation: A feature development involves multiple Pi sessions scattered across different tmux windows/terminal tabs, making it difficult to track the corresponding task stages.
2. State Inconsistency: Project plans (Notion/Linear), code (GitHub), and AI session history (local) are separated, making it hard to sync all relevant sessions when plans change.
3. Skill Drift: Manually managing Skills (e.g., database migration) or MCP servers (e.g., PostgreSQL) required for different features is tedious and error-prone.

pi-workflow-hub was created to address these problems.

Design Philosophy

YAML as the sole data source, Ticket as the work unit, tmux as the execution environment.

YAML Data Source

All feature definitions are stored in agent-work/features.yaml. Each ticket includes ID, status, description, priority, and other information. Advantages: version-controllable (Git-managed), human-readable (directly editable), machine-parsable (CLI quick processing), decentralized (runs locally).

Ticket Work Unit

Each feature corresponds to a ticket, and each ticket corresponds to one/group of tmux sessions. Using wf-pi open-ticket <id> allows direct attachment to the corresponding Pi session, solving context fragmentation.

tmux Execution Environment

Reasons for choosing tmux: mature and stable (tested for over a decade), observable (real-time AI output viewing), recoverable (session recovery after system restart), and rich ecosystem (complete plugins/configurations).

Core Components

1. CLI Tool (wf-pi): Key commands include wf-pi (create/attach dashboard), wf-pi tui (run TUI), wf-pi open-ticket <id> (open ticket session), wf-pi dispatch <id> <action> (send workflow instructions).
2. TUI Dashboard: Terminal control center that displays tickets grouped by epic, supporting keyboard navigation (↑↓/j/k to select, ←→ to switch epics, etc.).
3. Pi Extension: After installation, Pi gains the /wf command, enabling seamless switching between terminal and Pi sessions.

Standardized Workflow Stages

Define lifecycle stages: prime (initialization), plan (plan formulation), execute (coding), review (review), reflect (summary), commit (submit), blocked (blocked), done (completed). Trigger corresponding stage prompt templates via wf-pi dispatch (e.g., wf-pi dispatch feature-123 execute).

Skills and MCP Management

• Project-level Configuration: Each project has independent Skills/MCP configurations, which are automatically injected when opening a ticket. Different tickets can enable different capability sets (e.g., database migration tickets use PostgreSQL MCP + SQL Skill).
• Configuration Change Detection: The Dashboard monitors configuration changes and prompts to restart sessions for application (running Pi sessions do not hot-reload).

Session Lifecycle

• Persistence: Session data is saved in agent-work/tickets/<ticket-id>/, including heartbeat, history, and configuration snapshots.
• Recovery Strategy: restart-ticket provides two modes: resume (retain history) and new (fresh session).
• Isolation: Each ticket session is independent; crashes do not affect others, and multiple sessions can be processed in parallel.

Diagnosis and Observability

The wf-pi doctor command provides comprehensive health checks: verify feature file syntax, pi-workflow-hub installation status, tmux/Pi availability, and detect "orphan" sessions (records exist in the registry but not in tmux).

Comparison with Traditional Tools

Dimension	pi-workflow-hub	Traditional Project Management Tools
Data Source	Local YAML File	Cloud Database
Execution Environment	Local tmux	None (pure management)
AI Integration	Natively supports Pi	Requires plugins/integration
Offline Capability	Fully available	Limited
Learning Curve	Medium (requires tmux knowledge)	Low (Web UI)
Customizability	High (code as configuration)	Medium (configuration interface)
Collaboration Capability	Low (single user)	High (multi-user)

Positioning: Fills the gap in workflow management for individual/small-team AI-assisted development, not a replacement for Jira/Linear.

Potential Improvement Directions

1. Collaboration Enhancement: Git-based collaboration, session sharing, ticket-level comments.
2. Integration Extensions: GitHub/Linear/Notion synchronization, CI/CD Hooks.
3. AI Capability Enhancement: Intelligent feature splitting, dependency suggestions, workload estimation.
4. Visualization Improvements: Burndown Chart, dependency graph, Heatmap.

Summary

pi-workflow-hub provides a lightweight yet fully functional AI-assisted development workflow solution through the trinity design of YAML + Ticket + tmux. It is suitable for developers who are comfortable with the command line, value data sovereignty, and primarily collaborate with AI. The project has complete documentation (User Guide, Dashboard Reference, etc.), reflecting the maintainer's focus on user experience.