CodeLedger

Automatically keep a detailed, persistent work log of everything you do inside a workspace.

🎯 What It Does

CodeLedger automatically tracks all your coding activity and maintains a persistent log file in your workspace. Every file save, every code change, and periodic snapshots of your work are logged with timestamps, file names, line numbers, and descriptions of what changed.

Key Features:

• ✅ Auto-logging on every file save (manual or autosave)
• ⏱️ Periodic activity snapshots every 5 minutes
• 💾 Crash-resistant - survives power loss, VS Code crashes, and force closes
• 🚀 Extremely lightweight - no impact on typing, saving, or startup performance
• 📝 Detailed change tracking - logs timestamps, file names, line numbers, and change descriptions
• 🔄 Persistent storage - all logs are appended, never overwritten

📦 Installation

From VS Code Marketplace

1. Open VS Code
2. Press Ctrl+Shift+X (or Cmd+Shift+X on Mac)
3. Search for: CodeLedger
4. Click Install and reload VS Code

Manual Installation

1. Download the .vsix file from the releases page
2. Open VS Code
3. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
4. Type: Extensions: Install from VSIX
5. Select the downloaded .vsix file

From Source

# Clone the repository
git clone https://github.com/Z-TechX/codeledger.git
cd codeledger

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package the extension (optional)
npm install -g @vscode/vsce
vsce package

🚀 Usage

Automatic Operation

Once installed and a workspace is open, CodeLedger works automatically:

1. Opens/creates worklog file: [workspace-name]-worklog.txt in your workspace root
2. Logs on every file save: Captures what changed, where, and when
3. Periodic snapshots: Every 5 minutes, logs any pending changes
4. Crash recovery: If VS Code crashes, pending changes are recovered on restart

Manual Commands

Access these commands via Command Palette (Ctrl+Shift+P or Cmd+Shift+P):

• CodeLedger: Open Worklog File - Opens the worklog file in the editor
• CodeLedger: Clear Worklog (Backup First) - Clears the worklog after creating a backup

Example Worklog Entry

[2026-02-03T14:23:45.123Z] SAVE
  File: src/extension.ts
  Lines: 45-52
  Changes: Modified content (3 change(s)) near: "export function activate(context..."
  Stats: +5 -2 lines

[2026-02-03T14:28:45.234Z] PERIODIC LOG
  File: src/worklogManager.ts
  Lines: 120-135
  Changes: Added content (8 line(s)) near: "private async processWriteQueue()..."
  Stats: +8 -0 lines

⚙️ Configuration

Access settings via: File > Preferences > Settings → Search for "CodeLedger"

Example Configuration

{
  "codeledger.enabled": true,
  "codeledger.periodicLogInterval": 600000,  // 10 minutes
  "codeledger.maxChangeDescription": 150
}

🏗️ How It Works

Architecture

The extension uses several VS Code APIs to achieve lightweight, reliable logging:

1. onStartupFinished activation - Doesn't slow down VS Code startup
2. onDidChangeTextDocument - Tracks changes in memory (non-blocking)
3. onDidSaveTextDocument - Triggers log writing on save
4. Batched writes - Multiple log entries are batched to reduce I/O
5. Workspace state - Pending changes are persisted for crash recovery
6. Async I/O - All file operations are asynchronous and queued

Performance Optimizations

• No main thread blocking - All operations are async or deferred
• Efficient debouncing - Changes are tracked but not immediately written
• Batched writes - Multiple entries are combined into single write operations
• Smart filtering - Ignores non-file documents (output, debug, etc.)
• Minimal memory footprint - Only tracks metadata, not full document content

Crash Resistance

The extension ensures no data loss even during unexpected shutdowns:

1. On every change: Metadata is stored in workspace state (persisted by VS Code)
2. On crash/power loss: VS Code's workspace state survives
3. On restart: Extension reads workspace state and logs recovered changes
4. Async writes: Queued writes complete before extension deactivation

📋 What Gets Logged

Each log entry includes:

• Timestamp - ISO 8601 format (e.g., 2026-02-03T14:23:45.123Z)
• Event Type - SAVE, PERIODIC LOG, or RECOVERY LOG
• File Name - Workspace-relative path
• Line Numbers - Affected line ranges (e.g., 45-52 or 120, 135, 140)
• Change Description - Auto-generated summary with context
• Statistics - Lines added/deleted (e.g., +5 -2 lines)

🛡️ Privacy & Permissions

The extension requires minimal permissions:

• ✅ Read workspace files - To track changes
• ✅ Write to workspace - To create/update the worklog file
• ❌ No network access - All data stays local
• ❌ No telemetry - No data is sent anywhere
• ❌ No AI services - Change descriptions are generated locally using heuristics

🐛 Troubleshooting

Worklog file not created

Solution: Ensure a workspace folder is open (not just loose files). The extension requires a workspace to create the worklog file.

Changes not being logged

Solution:

1. Check that worklog.enabled is true in settings
2. Verify the file is a real file (not untitled or output)
3. Ensure the file is not the worklog file itself

Performance issues

Solution:

• Increase worklog.periodicLogInterval to reduce periodic logging frequency
• Check that the worklog file isn't extremely large (>100 MB)
• Try disabling and re-enabling the extension

Worklog file too large

Solution: Use the Worklog: Clear Worklog (Backup First) command to archive and restart the log.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• GitHub Repository
• VS Code Marketplace
• Report Issues
• Changelog

👨‍💻 Author

Created by Z-TechX

🙏 Acknowledgments

Built with:

• VS Code Extension API
• TypeScript
• Node.js File System API

Made with ❤️ by Z-TechX - Making development tracking effortless! 🚀