Clockit Documentation

v1.x (current)Stable docs for the current extension line.

Clockit helps developers log coding sessions automatically, add session comments, and export tracked time to CSV, Jira, or Notion, all within VS Code.

Features

  • Automatic time tracking when you start coding
  • Idle detection and trimming for accurate duration
  • Per-file and per-language focus time captured automatically
  • Line changes counted (added and deleted)
  • Optional session comments on stop
  • Multi-sink export to CSV, Jira, and Notion
  • Guided credential prompts stored securely
  • CSV menu in the status bar for quick access

Installation

  1. Open VS Code and go to the Extensions view.
  2. Search for Clockit or use the marketplace link below.
  3. Install the extension and reload VS Code when prompted.

Marketplace: octech.clockit

Offline install

Use a bundled VSIX if you are offline.

  1. Download clockit-x.y.z.vsix from your release bundle.
  2. Run code --install-extension clockit-x.y.z.vsix.
  3. Reload VS Code and open the command palette to start tracking.

Session Tracking

Start a session

Clockit: Start Time Tracking

Starts a timer linked to your current workspace. You can also enable auto-start on launch in settings.

Pause and resume

Clockit: PauseClockit: Resume

Idle detection trims time automatically after the configured idle timeout.

Stop and comment

Clockit: Stop

When you stop, add an optional comment (for example, "Refactored API routes").

What gets tracked

Start and end time
Duration after idle trimming
Workspace name and machine
Git repository and branch
Per file and per language focus time
Lines added and deleted
Optional comment and Jira issue key

Clockit keeps this data local until you choose an export sink. If you only export to CSV, nothing leaves your machine.

Credentials and Storage

Clockit stores secrets in VS Code Secret Storage (encrypted by your OS keychain). Settings that are not secrets stay in your workspace settings.

Jira

  • Stored: domain, email, API token (token is secret).
  • Usage: used only when you export a session to Jira.
  • Retention: stays until you run Clockit: Clear Credentials or uninstall.

Notion

  • Stored: internal integration token (secret) and destination (database or page).
  • Usage: lets you browse pages shared with the token and creates database columns automatically.
  • Retention: remains in Secret Storage until you clear credentials.

CSV

  • Stored: export folder and filename (no secrets required).
  • Usage: writes a local CSV that the Clockit website can read to visualize your stats.

Clearing and editing

  • Use Clockit: Edit Credentials to update values.
  • Use Clockit: Clear Credentials to remove one sink or all stored secrets.

IDE Cloud sync

Turn on automatic backups from the Clockit VS Code plugin to your account using an API token. Local CSV exports remain unchanged.

  1. Sign in at clockit.app/dashboard and open Profile → API Tokens.
  2. Create a token (optional expiry) and copy it once.
  3. In VS Code settings, set:
    • clockit.cloud.enabled: true
    • clockit.cloud.apiUrl: defaults from CLOCKIT_INGEST_URL (built-in); override only if you host your own ingest
    • clockit.cloud.apiToken: the token you created (stored as a secret)
  4. Stop a session: Clockit writes CSV locally and also uploads to your account for aggregated stats.
  5. Custom ingest: If you deploy your own ingest function, set CLOCKIT_INGEST_URL in your environment and update clockit.cloud.apiUrl if needed.
  6. Rate limits: Ingest enforces per-token limits (defaults: minute limit 60, day limit 5000). If exceeded, the endpoint returns 429; local CSV is still written.

Jira Export

Automatically logs your work as a Jira worklog entry.

  1. Configure Jira credentials
    • Run Clockit: Configure Jira.
    • Domain: your-team.atlassian.net (no protocol).
    • Email: your Atlassian account email.
    • API token:
      1. Visit id.atlassian.com/manage/api-tokens.
      2. Click Create API token, name it "Clockit", and create.
      3. Copy the token and paste it when prompted.
  2. Pick the issue

    When exporting, search by key (TP-12) or summary. Clockit caches search results briefly for faster picks.

  3. Auto-detection

    If your branch or comment includes a key (for example, TP-123), Clockit detects it automatically.

Notion Export

Logs each session as a new row in a Notion database or appends to a page.

Clockit inspects your database and creates missing properties (Duration, Started, Workspace, IssueKey, and more) before writing entries.

How to get the token and database

  1. Go to Notion integrations and create a new internal integration. Copy the token (starts with ntn_).
  2. Share the target page or database with the integration so it has access.
  3. Grab the database ID:
    • Open the database in a browser; the ID is the 32-character part of the URL.
    • Clockit also lets you search and pick a database or page directly from the prompt.
  4. Run Clockit: Configure Notion and paste the token and database.

Once connected, Clockit lets you browse pages shared with the token. For databases, it creates or updates columns such as Duration, Started, Repo, Branch, IssueKey, and Author so entries stay structured.

CSV Export

Every completed session is appended to a CSV file for local analysis.

startedIso, endedIso, durationSeconds, idleSeconds, linesAdded, linesDeleted, perFileSeconds, perLanguageSeconds, comment, issueKey, repoPath, branch

The CSV stays on disk and can be opened through the status bar menu. The Clockit website can read this CSV to show charts of your focus time, repos, branches, and issues without sharing data externally.

Configuration Options

SettingDefaultDescription
clockit.enabledSinks["csv"]Select which sinks to use for exporting sessions.
clockit.askSinksEachTimetrueAlways prompt which sinks to use before exporting.
clockit.enableJirafalseEnable Jira integration for time tracking.
clockit.jira.apiToken""Jira API token for authentication.
clockit.jira.email""Email associated with your Jira account.
clockit.jira.domain""Your Jira domain (for example, your-team.atlassian.net).
clockit.csv.outputDirectory""Directory to save CSV time logs. Leave empty to use the current working directory.
clockit.csv.filename"time_log.csv"Filename for the CSV time log.
clockit.csv.addHeaderIfMissingtrueAdd header row to CSV file if it is missing.
clockit.csv.ensureDirectorytrueAutomatically create the output directory if it does not exist.
clockit.author.name""Your name to include in CSV and backup logs. Falls back to git config user.name.
clockit.author.email""Your email to include in CSV and backup logs. Falls back to git config user.email.
clockit.machineName""Machine identifier to include in logs. Defaults to the OS hostname.
clockit.autoStartOnLaunchtrueAutomatically start time tracking when VS Code launches.
clockit.idleTimeoutMinutes5Number of idle minutes before pausing time tracking.
clockit.showNotificationstrueShow notifications for time tracking events.
clockit.notion.enableNotionfalseEnable Notion integration for time tracking.
clockit.notion.pageId""Notion Page ID where time logs will be recorded.
clockit.notion.apiToken""Notion API token for authentication.
clockit.notion.databaseId""Notion Database ID for logging time entries.
clockit.backup.enabledtruePeriodically checkpoint the active session to a backup CSV and flush on shutdown or errors.
clockit.backup.intervalSeconds0How often to checkpoint the in-progress session. 0 disables checkpoints.
clockit.backup.directory""Directory for backups. If empty, uses this directory or the workspace root.
clockit.backup.filenamePrefix"clockit_backup_"Prefix for backup CSV files. Final name is prefix + YYYYMMDD + .csv.

Command Summary

CommandTitle
clockit.startTimeTrackingClockit: Start Time Tracking
clockit.stopTimeTrackingClockit: Stop Time Tracking
clockit.showTimeLogClockit: Show Time Log
clockit.clearTimeLogClockit: Clear Time Log
clockit.toggleClockit: Toggle Time Tracking
clockit.openCsvClockit: Open CSV Log
clockit.chooseCsvFolderClockit: Choose CSV Output Folder
clockit.chooseSinksClockit: Choose Sinks
clockit.editCredentialsClockit: Edit Credentials
clockit.clearCredentialsClockit: Clear Credentials
clockit.signIn.jiraClockit: Sign in to Jira (Coming Soon)
clockit.signIn.notionClockit: Sign in to Notion (Coming Soon)

Troubleshooting

Jira 400 or 401 error

Invalid token or domain. Refresh the API token at id.atlassian.com and re-run Configure Jira.

Notion 400 Bad Request

Missing title field or wrong property type. Ensure your database has a title property and the integration is shared to it.