MagicWork: A Markdown-First Parallel Workflow System for AI-Assisted Development

MagicWork is a Markdown-first parallel workflow system for AI-assisted development. Its core goal is to address the management challenges of multiple parallel coding tasks after the popularization of AI programming assistants. Centered on Markdown task cards, it uses mechanisms like Git worktree isolation, recoverable sessions, and terminal automation to help developers efficiently manage multiple parallel AI tasks, avoid context confusion and progress tracking difficulties, and improve development collaboration efficiency.

After the popularization of AI programming assistants, developers face the challenge of organizing multiple parallel AI coding tasks: the traditional single-session mode easily leads to context confusion and difficulty in tracking progress. MagicWork's vision is to become a daily operating system for AI-assisted development, not just a simple tool. Each day starts with date-grouped Markdown task cards, where each card corresponds to an independent Git worktree, branch, terminal space, and recoverable session. It supports free switching between multiple tasks, just like collaborating with multiple teammates.

Core Design Principles

1. Markdown First: Task cards are in Markdown format, serving as both documentation and configuration, eliminating the separation between configuration and documentation.
2. Strict Path Separation: Distinguish between osRoot (configuration/state), recordsDir (task cards/index), and codeDir (worktree) with clear boundaries.
3. Recoverable Sessions: As a core capability, it stores session IDs to support accurate state recovery after interruptions.
4. Terminal-Level Signal Integration: When AI waits for input, it sends a signal via the terminal to avoid missing the opportunity for manual intervention.

Key Commands

• init: Initialize the daily workspace and generate task cards;
• sync: Rebuild the index to ensure consistency between the overview and tasks;
• run: Create an isolated worktree and terminal space, and start unstarted tasks;
• restore: Restore active task sessions without reinitialization;
• clean: Clean up the worktree and can generate a summary;
• report: Generate or append a summary;
• config: Manage path and hook configurations.

Codex+kitty Reference Implementation

• Shared Socket: All task windows connect to a unified kitty socket, supporting unified control;
• Wait-for-Input Detection: Listen for Codex wait events, update tab markers, and trigger notifications;
• Quick Switching: Use the kls assistant (kitty + fzf) to quickly jump to task windows.

Lifecycle Hooks

Through configurations like onCodeTabOpen/onClean to inject scripts, separate core logic from project-specific customization processes, and support repository-specific initialization and resource release.

Automatic Summary

Generate summaries based on intelligent agent conversation history, bound to clean/report commands, ensuring reliable work traces without relying on terminal output capture.

MagicWork适用于以下场景：

1. Parallel Feature Development: Multiple independent features evolve in isolated worktrees without interfering with each other;
2. Long-Cycle Task Management: Recoverable sessions support interrupting and resuming tasks that span days/weeks;
3. Team Collaboration Preparation: Provide a complete review and summary mechanism before merging;
4. Experimental Exploration: Quickly verify multiple ideas—failed tasks can be cleaned up, and successful ones retain records.

MagicWork represents a new paradigm for AI-assisted development: treating AI as a collaborative partner that requires specialized infrastructure support. Through Markdown-first design, isolation mechanisms, session management, and terminal integration, it empowers developers to manage multiple parallel AI workflows. In the future, such workflow systems will become the core of developers' toolchains, laying the foundation for more complex AI collaboration models.