operation-logger

Operation Logger

A multi-IDE skill that creates and maintains a persistent operation-log.md file, recording every step, decision, error, and file change during complex tasks.

Problem: In long conversations, earlier operations get compressed or dropped from context. The AI forgets what it already tried, repeats failed approaches, and loses track of modified files.

Solution: Treat the filesystem as long-term memory. Every meaningful operation gets recorded in operation-log.md — a single, chronological document that serves as the complete history of what happened.

Platform Support

| IDE / Tool | Status | Hooks | Installation | |------------|--------|-------|-------------| | Claude Code | Full | Native | claude plugin install operation-logger@operation-logger-skill | | Cursor | Full | Pre/Post/Stop | Copy .cursor/ to project root | | GitHub Copilot | Full | Session/Pre/Post/Stop | Copy .github/hooks/ to project root | | Mastra Code | Full | Pre/Post/Stop | Copy .mastracode/ to project root | | OpenCode | Full | Frontmatter | Copy .opencode/skills/ to ~/.config/opencode/skills/ | | Codex | Full | Frontmatter | Copy .codex/skills/ to ~/.codex/skills/ | | CodeBuddy | Full | Frontmatter | Copy .codebuddy/skills/ to ~/.codebuddy/skills/ | | KiloCode | Full | Frontmatter | Copy .kilocode/skills/ to ~/.kilocode/skills/ | | Gemini CLI | Skills | No | Copy .gemini/skills/ to ~/.gemini/skills/ | | Continue | Skills | No | Copy .continue/skills/ to ~/.continue/skills/ | | Kiro | Steering | No | Copy .kiro/ to project root | | OpenClaw | Skills | No | Copy .openclaw/skills/ to ~/.openclaw/skills/ | | Pi Agent | Skills | No | Copy .pi/skills/ to ~/.pi/skills/ | | FactoryAI | Skills | No | Copy .factory/skills/ to ~/.factory/skills/ | | AdaL CLI | Skills | No | Copy .adal/skills/ to ~/.adal/skills/ | | Agent Spec | Skills | No | Copy .agent/skills/ to ~/.agent/skills/ |

Installation

Claude Code

claude plugin install operation-logger@operation-logger-skill

Or add to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "operation-logger-skill": {
      "source": {
        "source": "github",
        "repo": "1nv1s1b1e/operation-logger-skill"
      }
    }
  }
}

Quick Install (User Commands)

For immediate /log, /log-status, /log-export access in Claude Code:

cp commands/*.md ~/.claude/commands/

Cursor

Copy the .cursor/ directory to your project root. Hooks activate automatically.

GitHub Copilot

Copy .github/hooks/ to your project root. Works with Copilot CLI, VS Code, and Coding Agent.

Kiro

Copy .kiro/ to your project root. Steering files provide persistent guidance.

Other Platforms

Copy the corresponding .{platform}/skills/operation-logger/ directory to your platform's skills location.

Usage

Slash Commands (Claude Code)

| Command | Description | |---------|-------------| | /log | Start operation logging for the current task | | /log-status | Show current log status and recent operations | | /log-export | Export statistics summary from the log |

Auto-Triggering

The skill triggers for multi-step tasks involving:

• Multi-file refactoring or codebase migration
• Complex debugging sessions
• Building features spanning multiple modules
• Security audits, performance optimization
• Any work touching 3+ files

Example Log Entry

#### [OP-007] EDIT | Add validation to PUT endpoint
- **Action**: Added express-validator middleware to PUT /api/users/:id/profile
- **Result**: Validation now rejects invalid input with 400 status
- **Files**: src/routes/profile.ts (modified)
- **Context**: Resolves OP-005 (missing input validation)

Log Structure

The operation-log.md has three sections:

1. Running Summary — Live-updated snapshot of current state (updated every 5 ops) 2. Session Entries — Each conversation gets its own section 3. Operation Entries — Chronological record with type, action, result, files, context

Operation Types

SEARCH READ EDIT CREATE DELETE TEST BUILD COMMAND DECISION ERROR FIX RESEARCH PLAN REVIEW

Hook Behavior

For platforms with hook support, the operation-logger provides 4 lifecycle hooks:

| Hook | Trigger | Action | |------|---------|--------| | userPromptSubmit / sessionStart | Every user message / session start | Remind to read operation-log.md if it exists | | preToolUse | Before Write/Edit/Bash/Read | Inject Running Summary into context | | postToolUse | After Write/Edit | Remind to log the operation | | stop / agentStop | Agent tries to stop | Check Final Summary is filled; continue if not |

Scripts

| Script | Description | |--------|-------------| | scripts/init-log.sh / .ps1 | Initialize a new operation log | | scripts/add-session.sh / .ps1 | Add a new session to existing log | | scripts/export-summary.py | Generate statistics summary | | scripts/check-log-complete.sh / .ps1 | Check if Final Summary is filled (used by hooks) | | scripts/sync-ide-folders.py | Sync shared files across all IDE directories |

Development

After modifying shared files (templates, references, scripts), run the sync script:

python scripts/sync-ide-folders.py          # Sync all
python scripts/sync-ide-folders.py --dry-run # Preview changes
python scripts/sync-ide-folders.py --verify  # Check for drift

License

MIT