Hook that injects todo list reminders into AI context before each turn.
Automatically injects current todo state into AI's context at the start of each turn, providing ephemeral reminders that keep AI focused on completing all planned steps.
Works with amplifier-module-tool-todo to create an AI accountability loop.
- Hook triggers on
prompt:submitevent (start of each turn) - Checks for
coordinator.todo_state(populated by tool-todo) - Formats todos like TodoWrite display (✓/→/☐ symbols)
- Injects as ephemeral context (not stored in history)
- AI sees reminder before generating response
uv add amplifier-module-hooks-todo-reminderAdd to your profile:
hooks:
- module: hooks-todo-reminder
source: git+https://github.com/microsoft/amplifier-module-hooks-todo-reminder@main
config:
inject_role: user # Role for injection (default: "user")
priority: 10 # Hook priority (default: 10)-
inject_role (default: "user")
- Context injection role
- Options: "user" | "system" | "assistant"
- Recommended: "user" (tested to work correctly)
-
priority (default: 10)
- Hook execution priority
- Higher numbers run after lower numbers
- Recommended: 10 (runs after status context at priority 0)
The hook injects a formatted reminder showing current plan state:
<current_plan>
✓ Completed task
→ In-progress task
☐ Pending task
☐ Another pending task
Remember: Complete all pending todos before finishing this turn.
</current_plan>Symbols:
- ✓ = completed
- → = in_progress (shows activeForm instead of content)
- ☐ = pending
User: "Implement feature X"
AI: [Creates 5-step plan using tool-todo]
1. Research requirements (pending)
2. Design solution (pending)
3. Implement code (pending)
4. Write tests (pending)
5. Document changes (pending)
[prompt:submit fires]
Hook injects:
<current_plan>
☐ Research requirements
☐ Design solution
☐ Implement code
☐ Write tests
☐ Document changes
Remember: Complete all pending todos before finishing this turn.
</current_plan>
AI: [Sees reminder, works on step 1, marks it completed]
[prompt:submit fires]
Hook injects:
<current_plan>
✓ Research requirements
☐ Design solution
☐ Implement code
☐ Write tests
☐ Document changes
Remember: Complete all pending todos before finishing this turn.
</current_plan>
AI: [Sees 4 steps remaining, continues to step 2]
Context injection is not stored in conversation history. It's injected fresh each turn, so:
- ✅ No context pollution from old states
- ✅ Only latest plan visible
- ✅ Automatic cleanup (nothing to persist)
Todos live only during the current session:
- Created when AI calls tool-todo
- Injected by hook each turn
- Cleared when session ends
- If tool-todo not loaded → hook returns
continue(no-op) - If no todos created yet → hook returns
continue - Hook failures don't crash session (non-interference)
This hook is designed to work seamlessly with amplifier-module-tool-todo:
tool-todo (storage) + hooks-todo-reminder (injection) = AI accountability
Without reminder hook:
- AI calls tool-todo ✓
- Tool stores todos ✓
- AI must manually check status ✗
- Risk: AI forgets to check, loses focus ✗
With reminder hook:
- AI calls tool-todo ✓
- Tool stores todos ✓
- Hook auto-injects reminders ✓
- AI sees status every turn ✓
- AI stays focused ✓
- ✅ Mechanism not policy: Hook provides injection mechanism, AI decides how to use todos
- ✅ Ruthless simplicity: Hooks one event, formats, injects - that's it
- ✅ Separation of concerns: Hook doesn't manage todos, just injects them
- ✅ Non-interference: Failures return continue, never crash
- ✅ Observability: Logs injection activity for debugging
Registers on prompt:submit event (start of each turn):
hooks.register("prompt:submit", self.on_prompt_submit, priority=10, name="hooks-todo-reminder")- Check
coordinator.todo_state - If empty → return
HookResult(action="continue") - If present → format and inject:
HookResult(
action="inject_context",
context_injection="<current_plan>...</current_plan>",
context_injection_role="user",
suppress_output=True
)- Completed: ✓ + content
- In progress: → + activeForm (present continuous)
- Pending: ☐ + content
Matches TodoWrite display format for consistency.
Integration tests verify:
# Basic integration
python test_todo_integration.py
# Multi-turn accountability
python test_todo_multi_turn.pyTests confirm:
- Hook triggers on prompt:submit
- Injection contains formatted todo list
- Context receives messages
- Format matches spec (✓/→/☐)
Note
This project is not currently accepting external contributions, but we're actively working toward opening this up. We value community input and look forward to collaborating in the future. For now, feel free to fork and experiment!
Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.