Multi-Manus Planning

Multi-project Manus-style planning with coordinator pattern for Claude Code.

A Claude Code skill that extends the planning-with-files pattern with support for multiple projects, separate planning/source paths, and cross-machine sync via git.

What's Different?

The Coordinator Pattern

Instead of planning files in your working directory, use a .planning/index.md coordinator:

~/scripts/                          # Your CWD
├── .planning/
│   ├── index.md                    # Coordinator (active project, registry)
│   └── projects/
│       ├── project-a/
│       │   ├── task_plan.md
│       │   ├── findings.md
│       │   └── progress.md
│       └── project-b/
│           └── ...

Or store planning files anywhere (Obsidian, Dropbox, etc.) with the coordinator pointing to them.

Coordinator Format

# Planning Coordinator

active: project-a
default_path: ~/Planning

## Projects

| Name      | Planning Path                 | Source Path      | Description  |
| --------- | ----------------------------- | ---------------- | ------------ |
| project-a | {default}/project-a           | ~/code/project-a | Main project |
| project-b | ~/Obsidian/Planning/project-b | ~/code/project-b | Side project |

Installation

Prerequisites

• Claude Code CLI installed
• Git configured with GitHub access

Per-Machine Installation (Required)

Install on each machine where you want to use multi-manus planning:

# Step 1: Add the marketplace
claude plugin marketplace add kmichels/multi-manus-planning

# Step 2: Install the plugin
claude plugin install multi-manus-planning@multi-manus-planning

# Step 3: Copy the command file (enables /multi-manus-planning slash command)
cp ~/.claude/plugins/cache/multi-manus-planning/multi-manus-planning/*/commands/multi-manus-planning.md ~/.claude/commands/

# Step 4: Restart your Claude session
# Exit and start a new session for the plugin to load

What gets installed:

• ✅ The multi-manus-planning skill (available via Skill tool)
• ✅ The /multi-manus-planning command (after Step 3)
• ❌ NO automatic hooks
• ❌ NO SessionStart configuration

Note: Plugins provide skills (invoked via Skill tool), not commands (invoked via /slash). Step 3 copies the command wrapper so you can use /multi-manus-planning.

Multi-machine setup: Repeat steps 1-4 on each machine. The plugin installs locally and does not sync between machines.

Optional: SessionStart Hook (Separate Setup)

To automatically sync planning files when starting a session:

Note: The hook walks up the directory tree to find .planning/, similar to how git finds .git/. This means it works from any subdirectory of your workspace.

1. Copy the hook:

   cp ~/.claude/skills/multi-manus-planning/scripts/planning-sync.sh ~/.claude/hooks/
   chmod +x ~/.claude/hooks/planning-sync.sh
   

2. Add to ~/.claude/settings.json:

   {
     "hooks": {
       "SessionStart": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "~/.claude/hooks/planning-sync.sh"
             }
           ]
         }
       ]
     }
   }
   

Optional: SessionEnd Hook (Session Cleanup)

To automatically clean up session-local override files when ending a session:

1. Copy the hook:

   cp ~/.claude/skills/multi-manus-planning/scripts/planning-cleanup.sh ~/.claude/hooks/
   chmod +x ~/.claude/hooks/planning-cleanup.sh
   

2. Add to ~/.claude/settings.json:

   {
     "hooks": {
       "SessionEnd": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "~/.claude/hooks/planning-cleanup.sh"
             }
           ]
         }
       ]
     }
   }
   

Note: This hook removes .active.override.$SESSION_ID files created by "switch to" commands. Without it, stale files accumulate but are harmless.

Usage

Project Commands

Adding a Project

You: add project my-app

Claude: Where should I store the planning files?
        ○ Default location (~/Planning/my-app/) [Recommended]
        ○ Somewhere else (I'll specify)

You: [select default]

Claude: What's the source/working folder for this project?

You: ~/code/my-app

Claude: Created project "my-app":
        - Planning: ~/Planning/my-app/
        - Source: ~/code/my-app
        - Files: task_plan.md, findings.md, progress.md

Switching Projects

You: switch to project-b

Claude: Switched to project-b (this session)
        Planning: ~/Obsidian/Planning/project-b/
        Source: ~/code/project-b

        [Reads task_plan.md and shows current status]

Session Isolation (v1.4.1)

Multiple Claude Code sessions can work on different projects in the same workspace without conflicts:

• "switch to X" writes to a session-local override file (.active.override.$CLAUDE_CODE_SESSION_ID)
• Other sessions are unaffected by your project switches
• SessionEnd hook cleans up the override file automatically
• "set default X" updates index.md (the workspace default for new sessions)

Priority cascade when reading active project:

1. $MANUS_PROJECT environment variable (explicit override)
2. .active.override.$CLAUDE_CODE_SESSION_ID (session-local state)
3. active: in index.md (workspace default)

Note: v1.4.0 used TTY detection which doesn't work in Claude Code (Bash tool runs without TTY). v1.4.1 uses $CLAUDE_CODE_SESSION_ID which is available in all Claude Code contexts.

Recommended .gitignore addition:

.planning/.active.override.*

Backward Compatibility

• No coordinator? Works exactly like planning-with-files (files in CWD)
• Existing task_plan.md? Still works, just won't have multi-project features
• Single project? Use default as your only project

File Structure

multi-manus-planning/
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest
├── skills/multi-manus-planning/
│   ├── SKILL.md                 # Main skill definition
│   ├── reference.md             # Manus principles
│   ├── examples.md              # Usage examples
│   ├── templates/
│   │   ├── index.md             # Coordinator template
│   │   ├── task_plan.md         # With Source header
│   │   ├── findings.md
│   │   └── progress.md
│   └── scripts/
│       ├── init-session.sh
│       ├── check-complete.sh
│       ├── planning-sync.sh     # SessionStart hook
│       └── planning-cleanup.sh  # SessionEnd hook (v1.4.0)
├── CHANGELOG.md
├── LICENSE
└── README.md

Testing

Run the hook test to verify the SessionStart hook works:

./skills/multi-manus-planning/scripts/test-hook.sh

Manual test checklist:

• list projects shows registered projects
• switch to X changes active project
• add project Y creates files in correct location
• SessionStart hook displays active project
• Backward compatible (no index.md = CWD behavior)

Attribution

Based on planning-with-files by OthmanAdi (MIT License).

The original implements the Manus context engineering pattern. This fork adds multi-project coordination.

License

MIT License - see LICENSE

---

Author: kmichels