Start here
Quick start
On first launch, Rotelle asks for the few preferences that shape the workspace: daily and weekly goals, rounding precision, Pomodoro, eye-rest and movement reminders, and what clicking the current menu-bar ticket should open. Every choice remains editable in Settings.
- 1Add a task
Choose a day and type a task name, Jira key or link, or text containing a key.
- 2Start tracking
Press the play button. Starting another task normally stops the first.
- 3Review the day
Edit or round the time, then upload finished Jira worklogs when you are ready.
Daily tracking
Add tasks and run timers
Each day has one smart task field. Enter a plain task title, a Jira key or link, or text containing a key, then use Add and start. Rotelle preserves ordinary task titles and resolves recognized Jira issues automatically.
The main Play button normally starts implementation; during detected call activity it defaults to discussion. Hold it for half a second to explicitly choose implementation, review, helping or discussion before the timer starts. Each Jira entry also has a compact role icon beside its badge; use the whole square button or … → My contribution to correct the role later.
Pinned Jira tickets, recent tickets, current-sprint issues assigned to you, and Quick activities appear as suggestions. Completed and closed sprint issues are hidden, and Jira statuses are shown beside issue keys. Starting the same Jira issue again on the same day resumes its existing entry instead of creating a duplicate.
In Settings → General, choose whether clicking the current ticket in the menu bar opens recent tickets, Quick activities, pinned tickets, current-sprint issues, or the full tracker panel. Right-click the menu-bar widget to change those display settings quickly. Only its dedicated play button starts or stops a timer; clicking free space opens the full panel.
Press ⌘ F or use the search button in the tracker toolbar to find work by Jira key, task title, or note. Rotelle groups the complete history of each task by day, shows its total, and opens any selected day back in the tracker.
Before your Mac sleeps, turns off its display, or locks the session, Rotelle closes active timer segments. It resumes the same tasks afterward—including parallel timers—and asks whether the unavailable interval counted as work.
While the tracker is open and no text field is active, type the numeric part of a Jira key to highlight every matching task. The query disappears automatically. Use a day’s … menu to order its tasks by newest, oldest, or title.
Smart input
What Rotelle recognizes
| You enter | Rotelle uses |
|---|---|
TEAM-42 | The Jira issue key, normalized to uppercase. |
https://company.atlassian.net/browse/TEAM-42 | TEAM-42, extracted from the link. |
please check TEAM-42 today | TEAM-42, extracted from surrounding text. |
42 | A matching issue already used on that day, if one exists. |
| A familiar task phrase | The first matching Quick activity rule. |
Issue keys follow the usual PROJECT-123 shape. A web link without a recognizable issue key is ignored rather than saved as a broken Jira key.
Reusable work
Set up Quick activities
- Open Settings → Quick activities.
- Choose an icon, add a display title, the Jira key to use, and comma-separated keywords such as
daily, standup. - Type one of those phrases in the task field, or click the Quick activity suggestion.
Matching ignores case and diacritics and works when a keyword appears inside a longer task name. Rotelle uses the first matching rule to create the activity with its saved title, Jira key, icon, and styling.
To share your setup, choose Export JSON… and send the saved file to a teammate. They can add it with Import JSON…. The export includes activity titles, Jira keys, keywords and icons, without time records or account credentials. JSON format… shows a copyable example if you prefer to prepare a file manually. Each activity requires a title, Jira key, and at least one keyword; the icon is optional. Existing Jira keys are skipped by default. Enable Replace existing activities with the same Jira key when the imported definitions should win.
Use the visible trash button beside a Quick activity to remove the rule after confirmation. Existing tracked time is not deleted.
When you edit a Quick activity and replace its Jira key with a normal ticket, Rotelle clears the Quick title and orange styling before loading the new issue. If the replacement key belongs to another Quick activity, that activity's title and styling are used instead.
Calendar
Track meetings with your confirmation
Open Settings → Calendar, press Connect Calendar, and select calendars. Rotelle reads events through macOS Calendar and never writes events back. Access is requested only after you press Connect.
The calendar button beside task shortcuts follows the displayed tracker date. Past meetings offer Add time; today's meetings offer timer start/switch or past-time entry; future days are view-only. Review the destination Jira key or local task and interval before confirming. Existing target coverage is not duplicated. Moving time can trim or split other editable sessions; uploaded Jira worklogs cannot be changed.
Eligible events last 5 minutes to 8 hours, are not all-day, cancelled or declined, and have other attendees or a recognized video-call link. Automatic suggestions help start and finish meetings, with an option to resume the previous task. Calendar selections and recurring task mappings stay local to this Mac.
In Focus & Breaks, automatic panels can pause during microphone/camera use, resuming after 60 quiet seconds. Compact icons show the active reason. Screen-sharing-only detection is currently disabled because window-activity signals caused false pauses; no screen frames are captured.
Statistics initially uses a configured sprint, or the week otherwise, and remembers the selected period, date and grouping. Calendar medals reward 1, 100 and 500 distinct meetings with at least one minute recorded each.
Atlassian
Connect Jira and upload worklogs
- Open Settings → Jira and click Connect Jira.
- Sign in to Atlassian and approve access. Rotelle adds the Jira sites available to your account.
- Track a task with a Jira issue key or link. Rotelle fetches its title and remembers the ticket for later.
- Stop the timer, review the displayed time, then use the upload button on the task. Use Upload day to send all eligible worklogs for that day.
Copied, moved, older, and previously uploaded tasks also use their assigned Rotelle day. If an upload fails, a red circle with a cross remains on the task; open it to read Jira's error and retry after fixing the problem.
Pin a recurring ticket from its … menu, copy its Jira key or link, click its badge to open it in Jira, or choose Refresh Jira details if its title changed. Discovered projects can be assigned to the correct connection—or removed when they are stale—in Jira settings.
Settings → Jira groups connection, projects and appearance separately. Issue-type icons and colors are on by default for epics, defects, spikes, stories and tasks. Choose from 12 curated hues or disable the decoration. Quick activities have an independent palette in their own settings and remain orange unless you customize it.
To remove an account, open Settings → Jira and choose Disconnect. Rotelle removes credentials that are no longer used from Keychain and safely unassigns linked projects while preserving time history and existing worklogs.
Rotelle checks every two hours for worklogs left behind on previous days. When it finds any, a Rotti panel can take you directly to the oldest affected day for review. Today is never treated as overdue.
Automation
Round and upload on a schedule
In Settings → General → Automatic Jira worklogs, enable Round & upload automatically. The same controls appear in initial setup. This is off by default. Choose every day, week, configured sprint or month and a local send time (23:00 by default); weekly schedules also let you choose a weekday.
Rotelle uses your existing rounding precision, includes overdue pending Jira entries and preserves their assigned dates. A day with a running timer waits until it stops. Local-only tasks and uploaded worklogs are untouched. Sprint mode requires a configured sprint; imported Jira sprint dates are a saved snapshot.
One assigned Mac runs the schedule and needs its own connected Jira account. If that Mac is asleep or off, missed work is processed when Rotelle runs again. This does not wake or power on the Mac. Schedule settings can sync, but the upload journal stays local.
Entries paused by sleep or screen lock wait until the inactivity review is resolved and tracking stops. Entries being uploaded cannot restart during the request. Uploaded records remain unchanged when tracking resumes; new time is recorded separately.
Persistent upload markers help reconcile interrupted requests. If Jira may have accepted a request but Rotelle cannot confirm it, it does not blindly send it again. Check Jira before resolving an uncertain upload. Errors remain visible in settings.
Automation medals count distinct work dates with at least one confirmed automatic upload: 30, 300 and 1,000 days. Multiple entries for one date count once; manual uploads do not count, and the days need not be consecutive.
Optional AI
Turn tracked work into a report
- Open Settings → AI reports and choose OpenAI, Claude, Google Gemini or Other compatible API.
- Create a key in your provider’s API console, enable API billing, enter the key and model, then save the connection. Other providers require a full Chat Completions endpoint. Test connection sends a small request using your API balance. A green checkmark confirms success; a red cross accompanies an error explanation.
- Click the blue sparkle beside a day or the weekly progress, or choose AI report in Statistics. All entry points use the same window; Back returns to Statistics.
- Select the period, choose a report type, inspect Review data, then press Generate report.
Templates include period summary, demo preparation, team update, retrospective, focus analysis and next steps. New creates a draft; Save updates a template; Save as new copies it; Delete asks for confirmation. Built-in templates are editable too. Improve with AI sends only your draft instructions and lets you accept or discard the suggestion before saving.
Demo preparation excludes known Bug/Defect issue types before creating the payload and totals. Your implemented records are selected by default; reviewed, helped and discussed records can be included explicitly. The contribution role stays in the report so collaboration is not described as implementation. Unknown issue types remain. Tracked time does not prove that a task is complete or ready for a demo; review the suggestions before using them.
Reports include selected task titles, Jira keys and issue types, worklog dates, tracked durations and running status. Notes, Jira descriptions and credentials are excluded. Keys remain in this Mac’s Keychain and are not backed up or synced. Read formatted Markdown, copy the original text or choose Share to open the macOS share menu.
Successful reports are saved automatically in AI report → Archive. Search by title or report text, reopen the formatted result, inspect its original prompt and source-data snapshot, copy Markdown or share it without another provider request. The archive is included in JSON backups and follows your data through private iCloud sync when enabled; deleting a report asks for confirmation.
Configure a sprint
In Settings → Jira → Sprint calendar, set a sprint length of 1–4 weeks and the start date of a known sprint. The same calendar applies to Statistics and reports.
Load sprints from Jira searches up to 100 assigned issues per phase and site, including completed issues, for dated active or future sprints. Select a result to use its exact dates. This is a saved snapshot: load again to refresh it. Previous/next are disabled for imported sprints; choose another in settings or return to the manual calendar.
Automation
Use Siri and Shortcuts
In the macOS Shortcuts app, add a Rotelle action: Start Task, Stop Current Timer, Stop All Timers, Get Timer Status, Start Pomodoro Break or Open Rotelle Screen. Start Task selects an existing task, Jira ticket or Quick activity. Give your shortcut a name and invoke it through Siri. Pomodoro must be enabled before starting a break.
Patterns and milestones
Read Statistics and collect achievements
Statistics remembers your period, date and grouping. On first opening it chooses a configured sprint, or the week otherwise. Select Day, Week, Sprint, Month, Year or All time; Previous, next and Current navigate the chosen calendar period. Grouping adapts: Day shows tasks only; Week adds days; longer sprints and Month add weeks; Year and All time also offer months. The summary also shows total tracked time, average active day, longest session, active days, completed Pomodoros, and eye-rest distance. Pomodoro and eye-rest counters remain explicitly labeled all time.
After at least five eligible completed sessions, Natural work rhythm estimates your typical focus length from the median of up to 30 recent sessions. Quick activities and sessions shorter than 5 minutes or longer than 4 hours are ignored. Choose Use for Pomodoro to apply that exact duration as your focus cycle.
The hourly map is built from actual timer sessions split across clock hours. The weekday map uses the same session history from Monday through Sunday. Quick activities remain part of your total time but are excluded from the task ranking so recurring background work does not hide real tasks.
New milestones reward your first AI report, 10 and 100 successful reports, sharing, demo preparation, saved prompts and accepted AI refinements. Failed or canceled actions do not count.
Contribution milestones count distinct Jira issues with at least one tracked minute: reviewed tickets at 1, 100 and 1,000; implemented defects at 1, 500 and 1,000. Repeated records for the same Jira key count once, and reviewed defects are not treated as fixes.
Movement milestones recognize the first exercise, 50 and 500 exercises, and 25 completed desk-position changes. Cumulative achievements show ×2, ×3 and higher multipliers as their targets repeat; first actions and one-time discoveries never multiply.
Open Achievements to follow progress and inspect earned Rotti medals. Secret achievements hide their artwork, name, condition, and progress until unlocked. Click an earned medal for a full-size view, then use the arrow buttons or ← and → to browse the rest of your earned collection. Icon Painter rewards assigning icons to ten Quick activities; Homer and Cipollino remember 100 skipped eye-rest and Pomodoro breaks; Edward Scissorhands and Inevitable mark 100 and 1,000 time-entry splits.
Corrections
Edit, move, copy, and round time
- Click a displayed duration to briefly reveal the actual tracked time; double-click it to edit.
- Use a task’s … menu to add or subtract 5, 10, 15, 30, or 60 minutes.
- Press + or − while the tracker is active to adjust the current task by five minutes without opening a menu.
- Choose Round, or round every stopped task with Round day. The precision comes from Settings.
- Drag a task to another visible day to move it. Hold ⌥ Option while dropping to copy it without its old sessions or worklog state.
- Choose Split time entry from a stopped task’s … menu, enter the duration to move, and choose its destination date. The original and new entries keep the same combined displayed and raw session totals.
- Use the day menu to export one day as JSON or import it into another day.
Adjusted totals do not erase the original start and stop sessions, so you can reveal the actual tracked value later.
Review and recovery
Use the Productivity Library
Open Library from the tracker toolbar to work with your complete local history without crowding the daily workspace.
Search saved tasks, open their day, edit details, and inspect or correct individual timer sessions.
Audit a day or week for missing titles, Jira context, running timers, and other unfinished work before closing the period.
Choose a date range, compare totals, and export the result as CSV for further analysis.
Restore deleted tasks for 30 days, or permanently remove them when you are certain they are no longer needed.
Diagnostics shows the local database and snapshot locations and verifies that Rotelle can read its data store.
Keyboard
Keyboard shortcuts
These shortcuts work while Rotelle is active. The plus and minus shortcuts are ignored while you are editing text, preserve the original timer sessions, and never reduce a task below zero. Rotelle does not intercept keys in other applications.
Healthy pacing
Pomodoro, eye-rest, and movement reminders
Open Settings → Focus & breaks to configure Pomodoro, eye-rest and movement reminders. Movement is enabled by default every 60 minutes, with intervals from 30 minutes to 3 hours. Its schedule advances only while work is tracked and resets after a pause of five minutes or more.
The focus countdown advances only while a work timer is running. Break time keeps counting even if the task timer is paused.
The interval pauses with your work timer. Each uninterrupted completed break adds 20 feet to your distance statistic; closing or skipping it early does not count.
Choose from 15 illustrated exercises with instructions and targets. Strength and floor exercises are optional; every activity links to its official guidance source.
If you use a height-adjustable desk, Rotelle can combine every first, second or third scheduled movement reminder with a prompt to switch between sitting and standing. The saved position changes only after Done; Skip retries the switch next time, and Another keeps the desk suggestion while changing the exercise. A manual movement break does not alter the automatic desk schedule. A circular Rotti illustration and an up/down arrow show the desk action over the hero image; exercise instructions stay in the card below.
Breaks appear as centered in-app panels, including over full-screen spaces. Use the status cards to start any enabled activity immediately. Press Esc to close the current panel. Idle detection defaults to 10 minutes and uses one of five rotating scenes when a running timer has been left unattended.
At the start of each weekday, Rotelle can show an illustrated Rotti scene with a rotating practical tip. Disable these openings at any time in Settings → General.
Rotelle can also show an end-of-day review after you reach the daily goal and stop working for the selected interval, or at a fixed time. The review compares actual and rounded time, summarizes tasks, breaks, completed eye rests, and overtime, lets you adjust each worklog, then uploads eligible Jira entries and closes the day. You can snooze it whenever the day is not actually over.
Between your Macs
Optional private iCloud sync
Open Settings → General → iCloud and turn on sync to keep Rotelle data aligned across Macs signed into the same Apple Account. Rotelle remains fully usable offline and stores synced records in your private iCloud database.
The current week and profile travel as small compressed records, while older history stays in a separate archive. Concurrent sessions and changes to different tasks merge independently; permanent deletions leave tombstones so an offline Mac cannot restore stale work.
Help shape Rotelle
Send feedback or a feature request
Open Settings → Feedback, choose Feedback or Feature request, write your message, and press Send. Rotelle sends it directly to Plane & Ladybird without opening an email app or requiring an email account.
Only the message you write, its category, and your Rotelle and macOS versions are included. Task names, Jira content, tracked time, and contact details are not attached automatically.
Your data
Backup, restore, and privacy
Rotelle stores its time data locally by default. Use Settings → General to export a JSON backup containing entries, sessions, settings, ticket history, pinned tickets, achievements, and Jira connection metadata.
Passwords and OAuth secrets are stored in macOS Keychain and are not included in backup files. Importing a full backup replaces the current Rotelle data; running sessions are safely closed at import time.