Skill

Todo Sync

Automatically syncs todos and plans from ~/.claude/ to the current project. Use this skill when asking about todo sync behavior, troubleshooting sync issues, or understanding where todos are stored.

Install

npx claudepluginhub nsheaps/ai-mktpl --plugin todo-sync

Tool Access

This skill uses the workspace's default tool permissions.

Preview

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

SKILL.md

Similar Skills

agent-eval

Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.

everything-claude-code

157.7k

agent-harness-construction

Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.

everything-claude-code

157.7k

accessibility

Designs, implements, and audits WCAG 2.2 AA accessible UIs for Web (ARIA/HTML5), iOS (SwiftUI traits), and Android (Compose semantics). Audits code for compliance gaps.

everything-claude-code

157.7k

Stats

Parent Repo Stars1

Parent Repo Forks0

Last CommitJan 21, 2026

Actions

View Source View Plugin View on GitHub View README

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:

When you create or update todos using TodoWrite, the hook fires
The sync script finds your session's todo file in ~/.claude/todos/
It merges the todos into .claude/todos/ in your project
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

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

Permission errors

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

Ensure you have write access to your project directory
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.