VSCODE

Overview

The Codaro VS Code Extension is a productivity tracking tool that monitors coding activity in your IDE and sends anonymized events to the Codaro Alerts API. This document explains how the extension works, what data is collected, and how your privacy is protected.

How It Works

Event Tracking

The extension listens to text editing events in your VS Code editor and tracks:

Editing Started: When you begin editing a file (typing, opening, or saving)
Editing Stopped: When you stop editing (switch files, close file, or after inactivity timeout)

These events help Codaro understand your coding patterns and generate productivity insights.

Event Transmission

Events are sent to the Codaro Alerts API endpoint:

https://api.codaro.io/events/editing

Each event contains:

User ID: Your unique identifier (UUID)
Event Type: editingStarted or editingStopped
File Hash: A cryptographic hash of the file path (see Privacy section below)
Timestamp: When the event occurred

Privacy Protection

File Path Hashing

The extension NEVER sends actual file names or file contents to the server.

Instead, it uses SHA-256 cryptographic hashing to protect your privacy:

Path Normalization: The absolute file path is normalized (e.g., C:\Users\John\project\src\app.ts)
Hash Generation: A SHA-256 hash is computed from the normalized path
Hash Transmission: Only the hash is sent to the server (e.g., a3f5b8c9d2e1...)

Example:

Original Path:  C:\Users\John\Documents\MyProject\src\components\Button.tsx
SHA-256 Hash:   7d8e9f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e

What the server knows:

✅ That you're editing some file (via its hash)
✅ When you started and stopped editing
✅ Your user ID

What the server CANNOT know:

❌ The actual file name (e.g., Button.tsx)
❌ The file path (e.g., src/components/)
❌ The project name
❌ Any file contents

Sensitive File Exclusion

The extension automatically excludes sensitive files from tracking to protect your credentials and secrets.

Excluded File Types:

Environment files: .env, .env.local, .env.production, etc.
Configuration files: config.json, secrets.json, credentials.json, etc.
Keys & certificates: .key, .pem, .crt, .p12, .pfx, etc.
Password files: .htpasswd, passwords.txt, secrets.txt
Database files: .db, .sqlite, .sqlite3
Log files: .log, debug.log, error.log
Temporary files: .tmp, .temp, .cache
Backup files: .bak, .backup, .old

Excluded Directories:

secrets/, private/, confidential/, secure/
keys/, certificates/, auth/, credentials/
passwords/, tokens/, api-keys/
backup/, logs/, temp/, tmp/, cache/

You can also configure custom exclusion patterns in the extension settings.

Offline Mode & Event Queue

Automatic Offline Handling

Event Buffering

When the API is unreachable, events are stored in a local queue.

Persistent Storage

The queue is saved to disk and survives VS Code restarts.

Automatic Retry

Events are automatically retried when connectivity is restored.

Smart Retry Logic

Uses exponential backoff to avoid overwhelming the server.

Queue Configuration

Maximum Queue Size: 1,000 events (configurable via codaro.activeEditing.queueMaxSize)
Retry Attempts: Up to 3 retries per event
Retry Delays: 200ms → 500ms → 1000ms (with random jitter)
Queue Processing: Every 1 second

Queue Behavior

When offline:

Events are queued locally
No data is lost
Queue is persisted to disk

When back online:

Events are sent automatically
Oldest events are sent first (FIFO)
Failed events are retried with exponential backoff

Queue full:

Oldest events are dropped first
You'll see a warning in the logs
Recent activity is prioritized

Configuration

Extension Settings

Open VS Code Settings (Ctrl+, or Cmd+,) and search for "Codaro" to configure:

User Identification

User UUID: Set your unique user identifier in the Codaro sidebar settings panel

Active Editing Tracking

Enable Tracking (codaro.activeEditing.enabled): Enable/disable event tracking (default: true)
Stop Delay (codaro.activeEditing.stopDelaySeconds): Seconds of inactivity before sending editingStopped (default: 10, range: 5-60)
API Endpoint (codaro.activeEditing.endpoint): Alerts API endpoint URL
Drop Unknown Projects (codaro.activeEditing.dropIfUnknownProjectId): Drop events when project ID cannot be resolved (default: true)

Queue Configuration

Queue Max Size (codaro.activeEditing.queueMaxSize): Maximum events to queue before dropping oldest (default: 1000, range: 100-10000)

Privacy & Security

Sensitive Globs (codaro.activeEditing.sensitiveGlobs): Custom glob patterns for files to exclude (e.g., ['**/.env*', '**/secrets/**'])
Enable Default Denylist (codaro.activeEditing.sensitiveGlobsDenylistEnabled): Use built-in sensitive file patterns (default: true)

Debugging

Debug Mode (codaro.debug): Show full file paths in logs (⚠️ use only for troubleshooting)
Debug Payload (codaro.debugPayload): Show payload details without absolute paths

Setting Your User UUID

Open the Codaro sidebar in VS Code (click the Codaro icon in the Activity Bar)

Enter your User UUID in the settings panel

The extension will automatically start tracking your activity

Data Transmission Details

Event Payload Structure

Each event sent to the API contains:

Event Payload.json

{
  "user": "your-user-uuid",
  "event": "editingStarted",
  "file": "7d8e9f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e"
}

Fields:

user: Your unique user identifier (UUID or username)
event: Event type (editingStarted or editingStopped)
file: SHA-256 hash of the file path (64 hexadecimal characters)

Network Requests

Protocol: HTTPS (encrypted)
Method: POST
Content-Type: application/json
Timeout: 2 seconds
Retry Policy: 3 attempts with exponential backoff

Rate Limiting

The extension includes built-in rate limiting to prevent overwhelming the API:

Requests are throttled to prevent excessive API calls
Save events are throttled to 1 per 2 seconds per file
Rate limiter statistics are available for debugging

Security Considerations

What Data Is Sent?

✅ Sent to Server:

User UUID
Event type (started/stopped)
File path hash (SHA-256)
Timestamp

❌ NOT Sent to Server:

File names
File paths
File contents
Project names
Directory structure
Any sensitive information

Cryptographic Hashing

The extension uses SHA-256, a cryptographically secure one-way hash function:

One-way: Cannot be reversed to get the original path
Deterministic: Same path always produces the same hash
Collision-resistant: Virtually impossible for two different paths to produce the same hash
Fixed length: Always 64 hexadecimal characters (256 bits)

Local Storage

The extension stores data locally in VS Code's global state:

Queue: Pending events waiting to be sent
Configuration: Your settings and preferences
Team Info: Selected team information (if applicable)

All local storage is managed by VS Code and follows VS Code's security model.

Transparency & Control

What You Can Control

✅ Enable/disable tracking entirely
✅ Configure inactivity timeout
✅ Add custom file exclusion patterns
✅ View debug logs to see what's being sent
✅ Clear the event queue at any time
✅ Uninstall the extension to stop all tracking

Viewing Extension Activity

Enable debug mode to see what the extension is doing:

Open VS Code Settings
Enable codaro.debugPayload (safe - doesn't show full paths)
Open the Output panel (View > Output)
Select "Codaro" from the dropdown

You'll see logs like:

[Codaro] Sending editingStarted event
[Codaro] File hash: 7d8e9f1a2b3c4d5e6f7a8b9c0d1e2f3a...
[Codaro] Event sent successfully

Frequently Asked Questions

Q: Can the server see my file names?

A: No. Only cryptographic hashes are sent. The server cannot reverse the hash to get the original file name.

Q: What happens if I'm offline?

A: Events are queued locally and sent automatically when you're back online. The queue persists across VS Code restarts.

Q: How do I stop tracking?

A: Set codaro.activeEditing.enabled to false in VS Code settings, or uninstall the extension.

Q: Are my credentials tracked?

A: No. The extension automatically excludes sensitive files like .env, .key, secrets.json, etc.

Q: Can I see what's being sent?

A: Yes. Enable codaro.debugPayload in settings and check the Output panel.

Q: What if the queue fills up?

A: The oldest events are dropped first. You can increase the queue size via codaro.activeEditing.queueMaxSize.

Q: Is the connection secure?

A: Yes. All communication uses HTTPS (TLS encryption).

Q: Can I exclude specific files or folders?

A: Yes. Use codaro.activeEditing.sensitiveGlobs to add custom exclusion patterns.

Technical Architecture

Components

Active Editing Tracker: Monitors text editing events

Active Editing Sender: Handles API communication and retry logic

Path Utilities: Normalizes paths and generates hashes

Event Queue: Persistent storage for offline events

Rate Limiter: Prevents API overload

Event Flow

User Types in Editor
        ↓
Event Detected (onDidChangeTextDocument)
        ↓
Check if Sensitive File → [YES] → Drop Event
        ↓ [NO]
Generate File Path Hash (SHA-256)
        ↓
Create Event Payload
        ↓
Send to API → [SUCCESS] → Done
        ↓ [FAILURE]
Add to Queue
        ↓
Retry with Exponential Backoff

Support & Contact

For questions, issues, or feedback:

Website: https://codaro.dev
GitHub: https://github.com/codaro/codaro-time-tracker
Documentation: https://codaro.dev/docs

License

This extension is licensed under the MIT License. See LICENSE file for details.

Last Updated: November 2024 Extension Version: 3.5.0

PreviousSQLWRITER NextWEBAPP

Good afternoon

Overview

How It Works

Event Tracking

Event Transmission

Privacy Protection

File Path Hashing

Sensitive File Exclusion

Offline Mode & Event Queue

Automatic Offline Handling

Event Buffering

Persistent Storage

Automatic Retry

Smart Retry Logic

Queue Configuration

Queue Behavior

Configuration

Extension Settings

Setting Your User UUID

Data Transmission Details

Event Payload Structure

Network Requests

Rate Limiting

Security Considerations

What Data Is Sent?

Cryptographic Hashing

Local Storage

Transparency & Control

What You Can Control

Viewing Extension Activity

Frequently Asked Questions

Technical Architecture

Components

Event Flow

Support & Contact

License