Jira Timer
🇧🇷 Leia em português
Track Jira time without leaving VS Code — free alternative to Tempo/Clockify.

- ⏱️ One click to start, one to log. The timer lives in the status bar; stopping it creates native Jira worklogs.
- 🌿 Knows what you're working on. Reads the issue key from your git branch and offers to start or switch the timer.
- 📅 Drag-and-drop calendar. See your week, fill gaps and move worklogs by dragging, like a real calendar.
- ✅ Review the day in one screen. Logged, pending, timer and gaps side by side; log everything at once.
- 🔒 Free, no extra service. Talks straight to Jira Cloud with your own API token, stored in VS Code's secret storage.
Quick start
- Create an API token at https://id.atlassian.com/manage-profile/security/api-tokens → Create API token
(the plain one, not "with scopes") → copy it.
- Connect: click the stopwatch icon in the activity bar, fill in your Jira URL (
https://yourcompany.atlassian.net),
e-mail and token, then Test and connect.
- Start the timer: press
Ctrl+Alt+P (or click the status bar, or ▶ on any issue). If your branch is
feature/PROJ-123-login, PROJ-123 is suggested first.
- Stop and log:
Ctrl+Alt+S. Review time and description, and it's in Jira.
Full connection guide and troubleshooting: Connect to Jira.
Where it shows up
- Status bar (bottom left): current issue and running time. Click it to open the menu.
- Sidebar: stopwatch icon in the activity bar, with the compact panel.
- Full view: opens in the editor area, like a file. Use the ⤢ button in the sidebar, the status bar menu or the
Jira Timer: Open full view command.
- Claude Code: run Jira Timer: Install in Claude once (see below).
In Claude Code
The Jira Timer: Install in Claude command installs a mod in Claude Code (terminal, desktop app and the VS Code
extension). Open a new Claude session and:
- Claude's status bar shows the issue and time, just like VS Code's;
/timer shows the timer, /timer pausar and /timer retomar pause and resume, and /timer parar pauses and asks
VS Code to log it (dialog, direct or "Review the day", per jiraTimer.stopAction) as soon as it's open;
/nota Group: what you did adds to the daily (! at the end = done), linked to the timer issue, and
/nota alone lists today's daily. When Claude finishes a task you asked for, it suggests the ready-made /nota
line; nothing is noted until you run it;
- Claude knows which issue you're on and uses the key in commits, branches and PRs when it makes sense.
They talk through files in ~/.jira-timer/ (state.json for the timer, notes.json for the daily). The Jira token stays in VS Code only: starting a timer and
logging to Jira are still done by it. With VS Code closed, Claude keeps the timer running.
When the extension updates, the mod updates with it.
- Timer card: key, title, clock, progress against the estimate, Pause/Resume, Stop and log and ⇄ Switch
(quick switch with keys 1–4, adjust start, open in Jira, discard). When paused it lists the periods; a forgotten
timer (no activity in VS Code) offers "Stop at HH:MM and log".
- No timer: shows how long you've gone unlogged during work hours and suggests the issue from your branch, including
"Start counting from HH:MM" (the elapsed time goes into the timer).
- Summary: today's bar (logged, timer, pending, gaps and "now"), the week with per-day bars and a gaps warning
with "Fill".
- Issues tab: search (
/), filters and the On your branch, Pinned and Recent groups, with ▶ to start.
- Today tab: the day's timeline with its gaps (or the whole week). Click a worklog to edit it.
- Daily tab: what you did today, to read out at the daily standup (see below).
- Review the day at the bottom (
R). Discarding doesn't ask for confirmation: an Undo shows up for a few seconds.
Daily
A checklist of what you did each day, grouped by subject, so you remember it at the daily standup. It doesn't touch
your hours: note the quick task you did with the timer running on another issue, or the two things you did at once.
- Add with
Ctrl+Alt+N from anywhere, or in the field at the top of the Daily tab: Group: what you did.
A ! at the end marks it as done. Without Group: it goes to the last group used on the same issue. Groups
autocomplete from the ones you used and from the timer issue's Jira labels.
- New notes are linked to the timer issue (click the chip to leave them without an issue). Each note can be linked
to another issue from its
⋯ menu.
- Three states: to do, in progress (
Shift+click the box) and done. Open notes carry over to the next
days on their own, marked "since 23/10".
- Click a note to edit it as text: the first line is
Group: text, the next lines are details. `code` is
highlighted. Drag to reorder or move it to another group. Deleting shows Undo.
- Daily tab in the full view (the ⤢ button in the sidebar tab): the last workday ("yesterday", skipping weekends,
days off and holidays) and today side by side, with the hours logged next to each group and a Logged without a
note list, so nothing is forgotten.
← → change the day, T goes back to today, and the search finds any note.
- History: in the same tab, Sprints shows every day of a Jira sprint (the active one first), with what you
did and the hours, plus how many notes you closed. The board is picked there once (
jiraTimer.sprintBoard; automatic
when there is only one). Without Jira Software, or without a board, it goes by week.
- When logging a worklog, the issue's notes show up as description suggestions (Daily:), and Also add to the
daily turns the description into a done note.
- Notes live in
~/.jira-timer/notes.json, on this computer only.
Full view
Five tabs at the top: Calendar, List, Review day, Daily and Settings, plus the timer pill.

- Calendar by day or week, with each day's total and goal bar, work hours highlighted (outside them is shaded),
clickable gaps to log, compact weekend, a "now" line and the timer growing live.
Navigate with ‹ › Today (or
← → T), D/S for day/week, G jumps to the next gap, zoom with − + or Ctrl + scroll.
- Log from the calendar: drag over an empty slot, click for 30 min, click a gap, or drag an issue from the side
panel (a preview shows where it will land).
- Adjust from the calendar: drag a block to change its time (even to another day) or pull its top/bottom edge.
It snaps to the grid (
jiraTimer.snapMinutes, Shift = 5 min) and to other blocks' edges; Ctrl drops
without snapping; Esc cancels; a single click opens the editor. If Jira rejects the change, the block moves back.
- List: grouped by day or by issue, with a filter, Export CSV, and edit / duplicate / delete on each row.
Next to it, the week summary per issue.
- Review the day: the whole day in one table (in Jira, to log, timer, gaps and breaks). Tick the saved periods,
pick an issue for the gaps and log everything at once; you can also stop the current timer and log it along.
- Settings: see below.

Issues on top: branches and pinned
The issue list (sidebar, full view and quick pick) shows at the top, in this order:
- Issues from your branches: the extension reads the branch of every git repository open in VS Code (one
folder, several folders or nested repositories) and links each key it finds (e.g.
feature/PROJ-123-login) to the
Jira issue. The card turns green with one tag per repository/branch. The list updates when you switch branches.
- Pinned issues: click the pin on a card (great for support tasks). They stay on top even outside the filters or
the default search, in the order you pinned them. Click again to unpin.
Logging and editing worklogs
The dialog has the same fields as Jira:
| Field |
Notes |
| Time spent |
1h 30m, 45m, 6h30, 1d... (with d/w, Jira converts using its own settings). Buttons −15m, +15m and Round |
| Time remaining |
Automatic (Jira adjusts it) or Set. Shows logged/remaining and the original estimate |
| Start date and time |
editable, both when logging and when editing |
| Work description |
plain text, with suggestions from the period's commit messages and recent descriptions |
Each pause closes a period. When you stop, the timer logs one worklog per period, at the time it happened
(e.g. 8:00–12:00 and 13:00–15:00 become two worklogs, and the calendar shows the empty break). The dialog shows the
periods as editable rows (start, end and remove), with the same description for all. Pauses shorter than 1 minute are
merged and periods shorter than 1 minute are dropped.
When you stop the timer (with jiraTimer.stopAction = dialog, the default) the dialog comes pre-filled with the
timer's time and start, and you can adjust everything before logging.
Work hours, goals and days off
In Settings → Work hours you set the days and hours (e.g. 08:00–12:00 and 13:00–17:30; the space between
them is a break and doesn't count as a gap), the same every day or per day, and a tolerance at the start and end.
The default daily goal is 6h30 (or "same as work hours"). The weekly goal is calculated from the week's
work days, minus days off, vacations and holidays (Brazilian national holidays can be added automatically), or set
to a fixed value.
Gaps, reminders, auto-pause and the calendar's focus hours all follow your work hours.
How it behaves
- On stop (
jiraTimer.stopAction): opens the dialog to review (default), logs directly, or accumulates the
periods to log later in "Review the day".
- Starting a timer while another is running logs (or accumulates) the current one and starts the new one (short
periods are dropped).
- When you switch to a branch with an issue key (e.g.
feature/PROJ-123-login), it suggests starting/switching the
timer (or switches by itself, or does nothing: jiraTimer.branchAction).
- Reminders (only during work hours): no timer running, forgotten timer (no activity in VS Code), time to
review the day before the end of the work day and, when VS Code opens, previous day below goal.
- With
jiraTimer.autoPause, the timer pauses by itself at breaks and at the end of the work day and asks whether to resume.
- The dialog suggests the description from the commit messages made during the period (
jiraTimer.commitDescriptions).
- If VS Code is closed with the timer running, it's paused at the last moment VS Code was open.
- The timer is shared between VS Code windows.
Keyboard shortcuts
| Key |
Action |
Ctrl+Alt+J |
Timer menu |
Ctrl+Alt+P |
Pause / resume (or start) |
Ctrl+Alt+S |
Stop and log |
Ctrl+Alt+T |
Switch issue |
Ctrl+Alt+N |
Add to the daily |
/ · Space · N · R |
In the panel: search, pause/resume, new worklog, review the day |
← → · T · D S · G |
In the calendar: period, today, day/week, next gap |
Ctrl+Enter |
Log in the dialog and in the review |
On macOS use Cmd instead of Ctrl. The global ones can be changed in VS Code's Keyboard Shortcuts (search for "Jira Timer").
Connect to Jira (step by step)
The connection uses your Atlassian e-mail + an API token. The token is a "special password" that only you can
create and that only works for your user: the timer logs hours in your name, with your permissions. You do this once.
What you'll need
| Info |
Where to find it |
| Jira URL |
What shows in the address bar when you open Jira in the browser. E.g. https://yourcompany.atlassian.net (pasting a link to an issue is fine, the extension keeps only the beginning) |
| E-mail |
The same e-mail you use to sign in to Jira |
| Token |
You create it in step 1 below |
Step 1: create the token (in the browser)
- Open https://id.atlassian.com/manage-profile/security/api-tokens and sign in with your Atlassian account if
asked. (The extension also opens this page for you with the Open token page button.)
- Click Create API token.
⚠️ Use the plain button. Don't use Create API token with scopes: that kind doesn't work with the extension.
- Under Name, type something like
VS Code. Under Expires on, pick the validity (max 1 year).
- Click Create.
- Click Copy. ⚠️ The token is shown only once, on this screen. If you close it without copying, just create another.
Step 2: connect in VS Code
- Click the stopwatch icon in the activity bar: the panel walks you through it. Fill in URL, e-mail and token and
click Test and connect (the steps below, with prompts at the top of VS Code, also work).
(Or
Ctrl+Shift+P → Jira Timer: Configure Jira connection.)
- Read the window and click Open token page (step 1) or I already have the token.
- Answer the 3 prompts at the top of VS Code:
- Jira URL, e.g.
https://yourcompany.atlassian.net
- Your Atlassian account e-mail
- Token: paste what you copied (Ctrl+V). It's hidden as you type, that's expected.
- The extension tests the connection before saving. If it works you'll see "Connected to Jira as Your Name".
If not, it tells you why and lets you retry without typing everything again.
The token is kept in VS Code's secure storage (SecretStorage), not in a text file.
Jira Server / Data Center
Self-hosted Jira works too (Server/Data Center 8.14 or newer). The extension detects the Jira type from the URL
(/rest/api/2/serverInfo) and, on Server/DC, asks only for the URL and a Personal Access Token: in Jira, click your
picture → Profile → Personal Access Tokens → Create token. The e-mail isn't used. If the detection gets it wrong,
set jiraTimer.deployment to cloud or server and connect again.
Common problems
| Message / symptom |
What to do |
| "Jira rejected the e-mail or token" |
Check that the e-mail is your Atlassian account's (not another service's), that the whole token was copied with no leading/trailing space, and that it isn't a token with scopes |
| "doesn't look like Jira" / "Couldn't reach" |
Check the URL (on Cloud it ends in .atlassian.net) and your internet/VPN |
| "Jira rejected the Personal Access Token" |
Server/DC: check that you copied the whole token and that it hasn't expired |
| It worked and stopped, "Jira rejected your token" |
The token expired or was deleted. Create another (step 1) and click Update token |
| I lost the token |
It can't be shown again. Create a new one and delete the old one on the same Atlassian page |
| I want to switch accounts or sign out |
Panel → Sign out, or Ctrl+Shift+P → Jira Timer: Disconnect from Jira |
Treat the token like a password: don't send it over chat/e-mail and don't commit it to a repository.
If you think it leaked, delete it on Atlassian's token page (Revoke) and create another.
Settings
Everything is in the Settings tab of the full view (gear in the sidebar or Jira Timer: Settings) and is saved
in VS Code's settings (jiraTimer.*), so it syncs with Settings Sync.
| Key |
Default |
Description |
workDays |
Mon–Fri |
Work days (0 = Sunday ... 6 = Saturday) |
workPeriods |
08:00–12:00, 13:00–17:30 |
Work hours; the space between them is a break |
sameScheduleEveryDay / workPeriodsByDay |
true / {} |
Different hours per weekday |
toleranceMinutes |
15 |
Minutes at the start/end of the work day that don't count as a gap |
dailyGoalHours / goalFromSchedule |
6.5 / false |
Daily goal (or same as work hours) |
weeklyGoalAuto / weeklyGoalHours |
true / 32.5 |
Calculated or fixed weekly goal |
daysOff / nationalHolidays |
[] / true |
Days off, vacations and holidays (national holidays are Brazil's) |
reminderMinutes |
30 |
No-timer reminder (0 disables) |
idleMinutes |
20 |
Forgotten timer: minutes without activity (0 disables) |
reviewReminder / reviewReminderMinutes |
true / 15 |
Remind to review the day before the end of the work day |
gapWarnings / gapMinMinutes |
true / 15 |
Show gaps and their minimum size |
warnIncompleteDays |
true |
Warn if the last work day was below the goal |
stopAction |
dialog |
dialog, direct or accumulate |
roundMinutes |
0 |
Round timer periods (0, 5 or 15) |
autoPause |
false |
Pause at breaks and at the end of the work day |
minSegmentMinutes |
1 |
Shorter periods are dropped |
commitDescriptions |
true |
Suggest the description from commits |
branchAction |
suggest |
suggest, auto or off when switching branches |
branchPattern |
[A-Z][A-Z0-9]+-\d+ |
Regex for the key in the branch name |
issuesJql |
my open issues |
JQL for the command palette quick pick |
projects |
[] |
Limit searches and suggestions to these projects |
calendarFocus / calendarStart / calendarEnd |
schedule |
Focus hours in the calendar |
weekend |
compact |
Weekend: normal, compact or hide |
snapMinutes |
15 |
Snap when dragging (5, 15 or 30) |
colorBy |
issue |
Block color: by issue or by project |
sprintBoard |
0 |
Board whose sprints group the daily history (0 = pick in the Daily tab) |
baseUrl / email |
|
Connection (filled in by the setup steps) |
deployment |
auto |
cloud or server (Server/Data Center), if the automatic detection gets it wrong |
The old confirmOnStop, suggestOnBranchChange and reminderStartHour/EndHour keep working until you set the new
ones (stopAction, branchAction and work hours).
Limitations
- Jira Cloud (API v3, e-mail + API token) and Server/Data Center 8.14+ (API v2, Personal Access Token).
- The token expires on the date chosen when you created it (max 1 year). When it expires, the extension tells you; just create another.
- It creates native Jira worklogs. The panel reads native worklogs, so it also shows whatever your company's timesheet
app saves as Jira worklogs.
License
MIT
| |