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)
Pause/resume and a focus timer with countdown in the status bar
Optional session comments on stop
Goals side panel to add/complete/delete goals; completed goals attach to sessions
Multi-sink export to CSV, Jira, and Notion
Guided credential prompts stored securely
CSV menu in the status bar for quick access
Quick link to Clockit Cloud from the CSV menu

Installation

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

Marketplace: octech.clockit

Offline install

Use a bundled VSIX if you are offline.

Download clockit-x.y.z.vsix from your release bundle.
Run code --install-extension clockit-x.y.z.vsix.
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.

Goals

Manage goals from the Clockit Goals side panel: add, complete, delete, or import from Jira. Completed goals attach to your next session and clear after a successful CSV write.

Add goals: Use “Add goal…” in the Goals panel. Enter a title or choose “Import from Jira issue” to search issues and pull subtasks as goals.

Jira integration: Searches use your Jira credentials; subtasks become goals with their summaries as titles. When imported from an issue, the issue key is remembered so you do not have to type a session comment again.

Completion: Mark goals done in the panel; completion time is captured. On session stop, completed goals populate the session comment automatically (“Complete goals set”) and are flushed after a successful CSV write.

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.

Sign in at clockit.octech.dev/dashboard and open Profile → API Tokens.
Create a token (optional expiry) and copy it once.
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)
Stop a session: Clockit writes CSV locally and also uploads to your account for aggregated stats.
Custom ingest: If you deploy your own ingest function, set CLOCKIT_INGEST_URL in your environment and update clockit.cloud.apiUrl if needed.
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.

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.
Pick the issue
When exporting, search by key (TP-12) or summary. Clockit caches search results briefly for faster picks.
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

Go to Notion integrations and create a new internal integration. Copy the token (starts with ntn_).
Share the target page or database with the integration so it has access.
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.
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, authorName, authorEmail, machine, ideName, workspace, repoPath, branch, issueKey, comment, goals

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

Configuration Options

Setting	Default	Description
clockit.enabledSinks	["csv"]	Select which sinks to use for exporting sessions.
clockit.askSinksEachTime	true	Always prompt which sinks to use before exporting.
clockit.enableJira	false	Enable 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.addHeaderIfMissing	true	Add header row to CSV file if it is missing.
clockit.csv.ensureDirectory	true	Automatically 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.autoStartOnLaunch	true	Automatically start time tracking when VS Code launches.
clockit.idleTimeoutMinutes	5	Number of idle minutes before pausing time tracking.
clockit.showNotifications	true	Show notifications for time tracking events.
clockit.notion.enableNotion	false	Enable 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.enabled	true	Periodically checkpoint the active session to a backup CSV and flush on shutdown or errors.
clockit.backup.intervalSeconds	0	How 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

Command	Title
clockit.startTimeTracking	Clockit: Start Time
clockit.stopTimeTracking	Clockit: Stop Time
clockit.pauseTimeTracking	Clockit: Pause Time Tracking
clockit.resumeTimeTracking	Clockit: Resume Time Tracking
clockit.setFocusTimer	Clockit: Set Focus Timer
clockit.goals.openView	Clockit: Open Goals
clockit.goals.add	Clockit: Add Goal
clockit.goals.toggle	Clockit: Toggle Goal
clockit.goals.delete	Clockit: Delete Goal
clockit.showTimeLog	Clockit: Show Time Log
clockit.clearTimeLog	Clockit: Clear Time Log
clockit.toggle	Clockit: Toggle Time Tracking
clockit.openCsv	Clockit: Open CSV Log
clockit.chooseCsvFolder	Clockit: Choose CSV Output Folder
clockit.chooseSinks	Clockit: Choose Sinks
clockit.editCredentials	Clockit: Edit Credentials
clockit.clearCredentials	Clockit: Clear Credentials
clockit.signIn.jira	Clockit: Sign in to Jira (Coming Soon)
clockit.signIn.notion	Clockit: Sign in to Notion (Coming Soon)

FAQ

Does Clockit send my data anywhere?

CSV is written locally. Cloud backup only runs if you enable it and set an API token. Goals stay local and clear after export.

How do goals work?

Add goals in the Goals side panel; import subtasks from Jira issues if connected. Completed goals attach to the next session comment and are cleared after a successful CSV write.

What about the focus timer?

Run “Clockit: Set Focus Timer” with mm:ss or minutes. The status bar shows the countdown, and you get a notification when it ends.

Can I disable CSV export?

CSV is always enabled (default sink) to keep a local record. You can add Jira/Notion alongside it.

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.