Multi-Manus Planning

January 11, 2026 · View on GitHub

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.

License: MIT Claude Code Skill Version

What's Different?

Featureplanning-with-filesmulti-manus-planning
ProjectsSingle (CWD)Multiple via coordinator
Planning locationCWD onlyConfigurable (e.g., Obsidian vault)
Source pathSame as planningSeparate (code can live elsewhere)
Cross-machineManualSessionStart hook with git sync
Project switchingN/ANatural language ("switch to X")
Session isolationN/ASession-scoped (v1.4.1) - no conflicts

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

SayAction
"list projects"Show all registered projects
"switch to [name]"Change active project (this session only)
"set default [name]"Set workspace default for new sessions
"which project?"Show current project and path
"add project [name]"Interactive project creation
"where are planning files?"Show resolved planning path

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