Module Sync

Capabilities

1. Dynamic Sync

Recursively discovers:

• Git submodules (.gitmodules)
• Top-level PARA folders (\d{2}_ pattern)
• Nested module structures

2. Java-Free View

Prevents IDEA from misdetecting as Java project:

• Uses EMPTY_MODULE type
• Adds root exclusions
• Avoids nested content root errors

3. Auto-Grouping

Organizes modules in IDEA:

• Groups by PARA category (00-90)
• Groups by submodule hierarchy
• Custom group names from path

4. Blacklisting

Automatically ignores:

• node_modules/
• .git/
• .smart-env/
• tmpclaude-*/
• Other temp directories

Commands

/idea sync-modules

Full module synchronization workflow:

1. Discover submodules:

   git config --file .gitmodules --get-regexp path
   

2. Scan PARA folders:

   • Match \d{2}_* directories at project root
   • Register each as IDEA module

3. Update modules.xml:

   • Add new modules
   • Remove orphaned modules
   • Configure module groups

4. Update workspace.xml:

   • Set module groups
   • Configure root exclusions

/idea create-scope

Generate file scopes from current module structure:

• Creates scope for each PARA folder
• Creates scope for each submodule path
• Adds composite scopes (e.g., "Active Work")

Module XML Format

modules.xml

<project version="4">
  <component name="ProjectModuleManager">
    <modules>
      <module
        fileurl="file://$PROJECT_DIR$/00_Inbox/00_Inbox.iml"
        filepath="$PROJECT_DIR$/00_Inbox/00_Inbox.iml"
        group="PARA/00 Inbox" />
    </modules>
  </component>
</project>

Module .iml File

<?xml version="1.0" encoding="UTF-8"?>
<module type="EMPTY_MODULE" version="4">
  <component name="NewModuleRootManager">
    <content url="file://$MODULE_DIR$">
      <excludeFolder url="file://$MODULE_DIR$/node_modules" />
    </content>
  </component>
</module>

PARA Module Groups

Submodule Handling

Discovery

Reads .gitmodules to find:

• Submodule paths
• Remote URLs (GitHub/GitLab filtering)

Filtering

Optional filters by remote host:

• github.com - Only GitHub submodules
• gitlab.com - Only GitLab submodules
• all - All submodules (default)

Registration

Each submodule becomes an IDEA module:

• Path: relative to project root
• Group: based on parent directory
• Type: EMPTY_MODULE (Java-free)

Blacklist Patterns

Directories always excluded:

node_modules/
.git/
.smart-env/
.pnpm-store/
tmpclaude-*/
dist/
build/
.cache/

Failure Modes & Recovery

Security & Permissions

• Required tools: Read, Write, Bash
• Files modified: .idea/modules.xml, .idea/*.iml
• Confirmations: Before removing existing modules

References

• Module XML Format - Full XML specification
• Blacklist Patterns - Exclusion patterns

Metadata