Mycelium

A robust, production-grade task/plan manager CLI designed for reliability, agent usage, and git-trackable project management.

Features

• Single Binary: Statically compiled, no dependencies
• Git-Trackable: SQLite storage designed for version control
• Dependency Management: Task blocking with cycle detection
• Assignees: Local assignees with GitHub username linking
• External References: Link tasks to GitHub issues/PRs and URLs
• Agent-Optimized: One-shot CLI with JSON output support
• Fast: Sub-100ms response time for typical operations
• Safe: Comprehensive error handling and validation
• Smart List View: Tree visualization for dependencies, epic grouping for simple lists
• Task Notes: Add comments and notes to tasks
• Task Cloning: Duplicate tasks with all metadata
• Batch Operations: Close, tag, or move multiple tasks at once
• Follow-ups: Lightweight scratch table for non-blocking items captured mid-work

Installation

CLI (myc) via crates.io (recommended)

cargo install mycelium-manager

Installs the myc binary to ~/.cargo/bin/. Requires Rust 1.75+.

CLI (myc) from source

git clone https://github.com/tcsenpai/mycelium
cd mycelium
cargo build --release
# Binary will be at target/release/myc
sudo cp target/release/myc /usr/local/bin/

GUI (MycUI) pre-built download

Each tagged release ships desktop bundles on the GitHub Releases page: .dmg/.app (macOS), .deb/.AppImage (Linux), and .msi/.exe (Windows). Download the one for your platform and install it. Every release also attaches the myc CLI binaries, alongside the crates.io publish.

Note: macOS bundles are currently unsigned, so Gatekeeper may warn on first launch (right-click → Open to bypass).

GUI (MycUI) from source

MycUI is a Tauri desktop app built with React and TypeScript.

Prerequisites: Rust, Bun, and Tauri prerequisites for your platform.

cd mycui
bun install
bun run tauri:build

The built app will be in mycui/src-tauri/target/release/bundle/ with platform-specific installers (.deb, .AppImage, .dmg, .msi).

For development:

cd mycui
bun install
bun run tauri:dev

One-Line Install (Linux & macOS)

git clone https://github.com/tcsenpai/mycelium && cd mycelium && ./install.sh

The install script detects your platform, builds, and installs both myc (CLI) and MycUI (GUI). On macOS, MycUI is installed as /Applications/MycUI.app. On Linux, both binaries go to /usr/local/bin/.

./install.sh --cli       # Install only the CLI
./install.sh --gui       # Install only MycUI
./install.sh --all       # Install both (default)
INSTALL_DIR=~/.local/bin ./install.sh --cli  # Custom install path (CLI)

Versioning

The CLI (myc) and the desktop app (MycUI) are versioned independently and released on their own cadence. The CLI is published to crates.io as mycelium-manager; MycUI ships as a desktop bundle attached to GitHub Releases. There is no requirement to run matching version numbers.

They stay compatible because both are built on the same mycelium-core crate, so they share one schema, one set of migrations, and one data layer. You can run any released CLI alongside any released MycUI against the same project, use either tool on its own, or mix them freely. Neither depends on the other at runtime: the CLI is a standalone binary, and MycUI talks to the database directly through core rather than shelling out to myc.

Quick Start

# Initialize a new mycelium project
myc init

# Create an epic
myc epic create --title "Feature X" --description "Build feature X"

# Create tasks
myc task create --title "Design API" --description "Define the API surface and contracts" --epic 1 --priority high
myc task create --title "Implement backend" --description "Build the backend services and persistence layer" --epic 1 --priority critical --due 2025-06-01

# Set up dependencies (task 1 blocks task 2)
myc task link blocks --task 1 2

# View dependency tree
myc deps show 2

# Close tasks (blocked tasks prevent closing)
myc task close 1
myc task close 2

# Batch operations
myc task batch-op close 3 4 5              # Close multiple tasks
myc task batch-op tag urgent 1 2 3         # Tag multiple tasks
myc task batch-op move 2 6 7 8             # Move tasks to epic #2

# Task notes
myc task note 1 "Found edge case with auth"
myc task notes 1                           # View notes

# Clone a task
myc task clone 1 --title "API Design v2"

# View project summary
myc summary

Commands

Project

myc init                    # Initialize mycelium in current directory
myc summary                 # Show project overview
myc doctor                  # Check system health and configuration

Epics

myc epic create --title "..." [--description "..."]
myc epic list               # List all epics with task counts
myc epic show <id>          # Show epic details with tasks
myc epic update <id> [--title "..."] [--description "..."] [--status open|closed]
myc epic delete <id> [--force]

Tasks

myc task create --title "..." [options]
  --epic <id>               # Assign to epic
  --priority <low|medium|high|critical>
  --assignee <id>           # Assign to person
  --due <YYYY-MM-DD>        # Set due date

myc list [filters]          # List tasks and epics (shows tree view if dependencies exist)
  --epic <id>               # Filter by epic
  --status <open|closed>    # Filter by status (defaults to 'open')
  --priority <level>        # Filter by priority
  --assignee <id>           # Filter by assignee
  --blocked                 # Show only blocked tasks
  --overdue                 # Show only overdue tasks
  --all                     # Show all tasks including closed

myc task list [filters]     # Same as myc list, but task-specific

myc task show <id>          # Show task details
myc task update <id> [options]
myc task close <id> [--force]   # Close (blocked tasks need --force)
myc task reopen <id>
myc task delete <id> [--force]
myc task assign <task_id> <assignee_id|0>

Batch Operations

# Close multiple tasks at once
myc task batch-op close <id> [<id>...] [--force]

# Add a tag to multiple tasks
myc task batch-op tag <tag> <id> [<id>...]

# Move multiple tasks to an epic (use 0 for no epic)
myc task batch-op move <epic_id> <id> [<id>...]

Task Notes

myc task note <task_id> "Note content"    # Add a note to a task
myc task notes <task_id>                  # Show all notes for a task

Task Cloning

myc task clone <id> [--title "New Title"]  # Clone a task (copies description, priority, etc.)

Dependencies

myc task link blocks --task <blocker_id> <blocked_id>
myc deps show <task_id>     # Show dependency tree
myc deps unlink <task_id> <blocked_task_id>

Assignees

myc assignee create --name "..." [--email "..."] [--github "username"]
myc assignee list           # List with task counts
myc assignee show <id>
myc assignee delete <id> [--force]

External References

myc task link github-issue --task <id> "owner/repo#123"
myc task link github-pr --task <id> "owner/repo#456"
myc task link url --task <id> "https://..."
myc task unlink <ref_id>

Follow-ups

Lightweight scratch table for non-blocking items captured mid-work (bugs you noticed, questions, ideas). They are separate from tasks and carry no epic, priority, or dependencies. Body is required, title optional. Statuses: open, in_progress, done, wontfix.

myc followup add "body text" [--title "tag"]    # capture
myc fu add "short form alias works"

myc followup list                               # all items (default, alias -a)
myc followup list -o                            # only active (open + in_progress)
myc followup list -c                            # only closed (done + wontfix)
myc followup list --status done                 # exact status bucket
myc followup show <id>
myc followup next                               # lowest-ID active

myc followup start <id>                         # → in_progress
myc followup done <id> [--reason "..."]
myc followup wontfix <id> [--reason "..."]
myc followup reopen <id>

myc followup edit <id> --body "new body" [--title -|"new title"]
myc followup append <id> "more context"         # timestamped, additive
myc followup rm <id> [--force]
myc followup promote <id> [--epic N] [--priority high]   # convert to task
myc followup count                              # JSON: {open, in_progress, done, wontfix}

After myc task close, mycelium prints a one-line reminder if any active follow-ups exist. Agents using mycelium MUST run myc followup list at the end of every work unit and surface open items to the user before wrapping (see AGENTS.md).

Reporting & Export

myc summary                 # Project overview
myc export json [--output file.json]
myc export csv [--output file.csv]

Global Options

--format <table|json>       # Output format (default: table)
--quiet                     # Suppress non-error output
--help                      # Show help
--version                   # Show version

Data Model

Epic
├── id, title, description
├── status (open/closed)
└── Tasks[]

Task
├── id, title, description (optional)
├── status (open/closed), priority (low/medium/high/critical)
├── epic_id (optional), assignee_id (optional)
├── due_date (optional)
├── dependencies (blocks/blocked_by)
└── external_refs (GitHub issues/PRs, URLs)

Git Integration

Mycelium stores data in .mycelium/mycelium.db using SQLite with WAL mode. This makes it git-trackable:

# Add to your repo
git add .mycelium/
git commit -m "Add mycelium project tracking"

# The .mycelium/.gitignore excludes WAL files

For AI Agents

Mycelium is optimized for agentic workflows:

# Use --quiet to get just IDs
myc task create --title "New task" --quiet  # outputs: 42

# Include a description when useful
myc task create --title "New task" --description "Explain the work item"

# Use --format json for parsing
myc task list --format json

# Check blocked tasks
myc task list --blocked

# Export for analysis
myc export json

Claude Code follow-up hook (optional)

hooks/ ships a Claude Code Stop hook that enforces the end-of-task follow-up check, so it no longer relies on the agent remembering the AGENTS.md rule.

./hooks/install-hook.sh              # install into ~/.claude/
./hooks/install-hook.sh --uninstall  # remove it

The hook self-gates: it stays silent outside mycelium projects (detected via the myc:agents-start marker in AGENTS.md) and only fires when active follow-ups exist, feeding them back to the agent to surface to you. Requires jq.

Configuration

No configuration needed! All data is stored in the project-local .mycelium/ directory.

Safety Features

• Atomic operations: Database transactions ensure data integrity
• Dependency validation: Circular dependencies are prevented
• Blocker checks: Tasks with open blockers cannot be closed (without --force)
• Confirmation prompts: Destructive operations require --force or user confirmation
• Clear errors: All errors include actionable guidance

Performance

• Sub-100ms response time for typical operations
• SQLite with proper indexing
• WAL mode for concurrent read/write
• Single binary, no runtime dependencies

Development

# Clone
git clone https://github.com/tcsenpai/mycelium
cd mycelium

# Build & test the CLI
cargo build --release
cargo test
cargo run -- init

# Run MycUI in dev mode
cd mycui
bun install
bun run tauri:dev

Architecture

• Rust - Type-safe, performant, single binary
• mycelium-core - Shared crate (db, models, migrations, errors) consumed by both the CLI and MycUI, so they use one schema and data layer
• SQLite - Embedded, git-trackable, ACID-compliant
• Clap - Command-line parsing with derive macros
• Rusqlite - SQLite bindings with bundled lib
• Tauri - Desktop GUI framework (MycUI)
• React + TypeScript - MycUI frontend
• Hand-written CSS - MycUI styling (no CSS framework)

License

MIT License - see LICENSE file.

Contributing

Contributions welcome! Feel free to open issues and pull requests.

Acknowledgments

Inspired by beads and the need for a robust, git-trackable task manager that works seamlessly with AI agents.