idlergear

IdlerGear Knowledge Management

IdlerGear provides structured knowledge persistence across AI sessions.

Session Start (MANDATORY)

Call this MCP tool at the start of EVERY session:

idlergear_session_start()

This returns:

• Project vision and goals
• Current plan and open tasks
• Recent notes and session state
• Recommendations for what to work on

Quick Reference

Creating Knowledge

Retrieving Knowledge

Task Labels

• bug - Something broken
• enhancement - New feature
• tech-debt - Code to improve later
• decision - Architectural choice made

Note Tags

• explore - Research questions
• idea - Future possibilities
• bug - Bug observations

Forbidden Actions

DO NOT create files:

• TODO.md, NOTES.md, SESSION_*.md, SCRATCH.md

DO NOT write comments:

• // TODO:, # FIXME:, /* HACK: */

INSTEAD: Use idlergear_task_create() or idlergear_note_create()

Session End

Before ending a session, consider:

idlergear_session_end(notes="what was accomplished")

This saves state for the next session.

Python Documentation (API Exploration)

Quickly explore Python APIs with token-efficient summaries:

Token-Efficient Summaries ⚡

idlergear_docs_summary(package="requests", mode="minimal")   # ~500 tokens
idlergear_docs_summary(package="requests", mode="standard")  # ~2000 tokens
idlergear_docs_summary(package="requests", mode="detailed")  # ~5000 tokens

Other Docs Tools

Requires: pip install 'idlergear[docs]'

Health Check (Doctor)

To check if IdlerGear is properly configured and up-to-date:

idlergear_doctor()

This checks:

• Configuration health (version, initialization)
• File installation status (MCP, hooks, rules, skills)
• Legacy files from older versions
• Unmanaged knowledge files (TODO.md, NOTES.md)

To auto-fix issues:

idlergear_doctor(fix=True)

Sudo Handling

When a command requires sudo, IdlerGear provides assistance:

Pre-authentication (Preferred)

If a GUI prompt isn't available, ask the user to pre-authenticate:

"Please run 'sudo -v' in another terminal, then I'll run the command."

GUI Password Prompt (Automatic)

If zenity, kdialog, or osascript is available, a GUI password dialog will appear automatically when sudo is needed. The pre-tool-use hook detects sudo commands and:

1. Checks if already authenticated (sudo -n true)
2. If not, checks for GUI askpass availability
3. Informs user if a password dialog will appear

Manual Execution

For complex commands or when no GUI is available:

"Please run this command directly in your terminal:
  sudo <command>"

Utility Scripts

IdlerGear installs helper scripts in .claude/scripts/:

• ig-askpass - Multi-platform GUI password prompt (zenity, kdialog, osascript)
• ig-sudo - Wrapper that auto-uses askpass when available

For detailed documentation, see references/ in this skill directory.