mulch — Workspace Factory CLI

mulch is a lightweight CLI bootstrapper and right-click context menu tool. Use mulch to empower your file system. There are multiple use cases for enhanced directory scaffolding, both as an individual and in a shared drive with a team. Developers will enjoy quickly standing up Python projects, and end-users will enjoy right-clicking in the file browser to set up file organization the same way every time, customizable to each directory.

---

Features

• Benefit from introspective directory getters and file getters in the WorkspaceManager class, dictated by mulch.toml and protected by manager.lock.
• The hidden .mulch folder is leveraged for configuration.
• In --stealth mode, code can be stashed in .mulch, so that workplace directories shared with non-technical co-workers can be crisp while providing space to write localized analysis scripts.
• Easily installable and runnable via pipx
• Enforces a separation of source code and workspace files.
• The --here flag enables basic scaffolding for directory-only generation, no code included.
• The default workspace folder name is the date, if the --name flag is not provided.
• The mulch-context CLI command is registered with the system, as per tool.poetry.scripts, mulch-context = "mulch.scripts.install.install_context:app"

---

Installation

pipx (recommended)

pipx install mulch
mulch-context # or `mulch context`

git clone

git clone https://github.com/city-of-memphis/mulch.git
cd mulch
poetry install
poetry build
pipx install dist/mulch-*-py3-none-any.whl

The git source code includes .reg files which can be leveraged to register right-click commands with your context menu, to enjoy the full power of mulch in your file browser as a user-facing power tool.

Usage

# Set up a new directory, where you anticipate to organizing multiple projects
mkdir equipment-monitoring 
cd equipment-monitoring

# Generated a fresh .mulch\mulch.toml file, and edit the directory scaffold before running 'mulch src'.
mulch seed --edit

# Stealth mode, best for shared directories (`--stealth`)
mulch src --stealth
mulch workspace --name bioreactor-1-team-analysis --here 

# Standard mode, best for Python developers
mulch src 
mulch workspace --name API01toAPI05  

# User mode, for everyone (`--here`)
mulch workspace --name SummerPhotos2025 --here 

# Mimick new folder default naming convention, to invite the user to edit the workspace directory name manually
mulch workspace --pattern new --here # This is the installed context menu behavior, via `mulch-context`

# Use a date as a default new workspace naming convention, for low-friction useful naming. This matches my Obsidian templated date convention. 
# This is the default if the `--pattern` flag is not used explicitly and if an explicit name is not provided with the `--name` flag.
mulch workspace --pattern date --here 
mulch workspace --here # This does the same thing, as of 0.2.19.

Folder Stucture Options, using mulch src

Flag	Workspace Location	Source Location	Goal
(none)	workspaces/<name>/	src/<proj>/	Normal development use
--here	./<name>/	(none)	Clean, user-facing
--stealth	./<name>/	.mulch/src/<proj>/	Play nice with shared dirs

I am really excited about mulch src --stealth for mixed use directories. Business and engineering users can organize projects in a shared drive like SharePoint, while a dev can run custom analysis scripts catered to each type of project.

---

mulch context versus mulch-context

These do the same thing. mulch-context is an independant CLI tool to register mulch workspace behavior to the context menu. mulch context is a command in the mulch CLI, which also calls the app() function in install_context.py.

---

Notice: Deprecation of mulch workspace --stealth

The --stealth flag for the mulch workspace command will be deprecated in an upcoming release.

Background and Use Case

The --stealth option was originally introduced to allow creating an src directory inside the hidden .mulch folder. When mulch init split into mulch src and mulch workspace, the --stealth flag was maintained for each. The loose theory was that a stealth option for workspace might be useful in supporting workflows where non-technical users focus on visible workspaces while developers maintain custom local software with multiple configurations in hidden workspace folders.

This use case is valid and important for scenarios involving mixed user environments and evolving projects with increasing complexity. However, managing stealth workspaces via this flag can be unintuitive and may cause confusion about the current working directory context.

Recommended Alternative

To maintain clean and organized hidden workspace directories, if you must have them, we recommend identifying the target_dir to the .mulch folder by running:

mulch workspace --target-dir .\.mulch [options]

This approach clearly scopes the workspace creation inside the hidden folder without relying on the deprecated --stealth flag.

You can choose only one set of workspace references. You can run mulch src --force and it will break the references to the public workspace set and build them for the private set.

---

A Rule: Run mulch workspace at least once before running mulch src

(particularly if you want to run mulch workspace --here)

• For mulch src to make the proper references, if you plan to use --here flag, you must run mulch workspace --here at least once first, to contribute some truth to the .mulch/reference.lock file.
• If you run mulch src without first running mulch workspace, the workspace_manager.py references will include to the standard /workspaces/ reference, as if the --here flag was not used.
• If you end up running mulch workspace without the --here flag, I don't think you'll have any trouble.
• The reference.lock could hypthetically enforce consistency, not allowing you to mix --here workspaces with lackthereof workspaces in the same project.
  • Or, more likely, the reference.lock file will record wherever you place workspaces or src directories, to enable you to be inconsistent.
  • This has the added benfit of adjusting the behavior of the context menu mulch workspace, which is assumed to be mulch workspace --here --pattern new
  • With enforcement from the reference.lock file, the --here flag can be ignored, if it was initally not used. Is this what we want?
  • No warning will appear for the context menu use case. Choose wisely.

---

Workspace and Source Directory Layout Complexity

Due to the various workspace and source directory placement options and their interactions, path references in workspace_manager.py can become complex and confusing.

For a detailed explanation of this situation, recommended usage patterns, and guidance on managing hidden vs. public workspaces and source directories, please see the dedicated documentation file:

Workspace and Source Layout Complexity — mulch-layout.md

This document provides an in-depth discussion and best practices to help you navigate these nuances.

---

Videos

• mulch 0.2.39 overview (4:34): https://youtu.be/oUQyg_Uw-ec

• mulch 0.2.32 demo (18:10): https://youtu.be/HFK8fRe-E4Y