Todo Sync

Todo Sync Plugin

This plugin automatically synchronizes your todos and plans from the global Claude directory (~/.claude/) to your current project's .claude/ directory.

How It Works

The plugin uses a PostToolUse hook that triggers after every TodoWrite tool call:

1. When you create or update todos using TodoWrite, the hook fires
2. The sync script finds your session's todo file in ~/.claude/todos/
3. It merges the todos into .claude/todos/ in your project
4. It also syncs any plan files from ~/.claude/plans/ to .claude/plans/

File Locations

Source (Global)

• Todos: ~/.claude/todos/{session-id}.json
• Plans: ~/.claude/plans/{plan-name}.md

Destination (Project)

• Todos: .claude/todos/{session-id}.json
• Plans: .claude/plans/{plan-name}.md

Merge Behavior

Todos: When both source and destination files exist, todos are merged by deduplicating on the content field. This prevents duplicate todo entries.

Plans: Plans are copied if the source is newer than the destination or if the destination doesn't exist.

Troubleshooting

Todos not syncing

1. Check if ~/.claude/todos/ contains files for your session
2. Verify the plugin is enabled: look for it in /plugins command output
3. Check hook execution with claude --debug

Permission errors

The script creates directories automatically. If you see permission errors:

1. Ensure you have write access to your project directory
2. Check that .claude/ isn't gitignored with restrictive permissions

Empty todo files

Files containing only [] (empty arrays) are skipped during sync to avoid cluttering the project.

Integration with Git

The plugin automatically adds patterns to ~/.config/git/ignore (the global gitignore) for .claude/todos/ and .claude/plans/ directories. This prevents synced files from being committed in any project by default.

If you want to track todos in version control for a specific project, add explicit !.claude/todos/ pattern to that project's .gitignore.

Manual Sync

The sync happens automatically on TodoWrite. If you need to manually trigger it, simply update your todos:

TodoWrite: [your todos here]

The hook will fire and sync will occur.