Documentation

Getting started

Temporal.ist records your working time from the work itself. You decide once which folders and web addresses belong to which project; after that, saving a file or opening a matching page records time on that project, and the web app turns it into a calendar, reports and invoices.

1. Create an account. Solo is free and has no time limit.
2. Install what fits how you work, from the download page:
   • the desktop app for Windows, macOS and Linux tracks files;
   • the browser extension for Chrome, Edge and Firefox tracks the sites you choose;
   • the terminal client does what the desktop app does on Linux servers.
3. Sign in. Each app opens your browser, where you approve the sign-in once.
4. Create a project and give it its folders (in the desktop app or the terminal client) or its web addresses (in the extension or on the project's Tracking rules tab).
5. Keep working. The first save in a watched folder starts a session.

Timers work without installing anything: start one on any project from the web app, on a computer or a phone.

How tracking works

Time is recorded as sessions: a project, a start, an end, any pauses, and optionally the task you were on. A session's worked time is its length minus its pauses.

Automatic sessions from files

The desktop app and the terminal client watch the folders you assign to each project, on each computer. Creating, changing, renaming, moving or deleting a file counts as activity; opening or reading a file does not. Editors that save by replacing the file are recognised.

• The first change starts a session on the project whose folder contains the file. Later changes keep it going.
• After 15 minutes without changes the session ends; the quiet minutes count, because you were usually still thinking about the work. Change the timeout, between 1 and 120 minutes, under Settings → Preferences, When sessions end.
• A minute before, and again ten seconds before, the desktop app tells you the session is about to end. Click the notice to keep it running.
• Folders such as .git and node_modules are ignored. Add your own exclusions to a project's folders when a build tool or a sync client writes files you did not.

Only a summary of the file changes leaves your computer: which files changed, how often and when. File contents never do.

Sleep, idle and shutdown

When your computer sleeps, the session pauses at that moment. If it wakes within 60 minutes on the same day, the same session continues and the sleep becomes a pause. Otherwise the session ends where the sleep began, and a new one starts with your next change. Set the window, between 1 minute and 12 hours, in the same place as the timeout.

Time while the computer is off is never counted. After a crash, the app closes the interrupted session at the last moment it can vouch for, never across the whole gap.

Timers you start yourself

Start a timer on any project from the web app, the desktop app, the browser extension, the terminal client or an AI assistant. A timer you started never stops because no files changed; it runs until you stop it. Pause and resume it as often as you like: paused time is not counted.

The apps never stop a session they did not start. If you start a timer in the web app, the desktop app leaves it alone, and the browser extension only ends the sessions it began itself.

Tasks

Name what you are doing ("Checkout page", "Kickoff call") while a session runs. Changing the task splits the session into parts, so reports and invoices can show time per task.

Offline

The desktop app and the terminal client save everything they record on disk before anything else, and upload it in order once there is a connection. Work done offline appears as finished sessions, never as a timer that suddenly runs on the server.

Days and long sessions

Totals belong to the day in your account's timezone. A session that runs past midnight counts towards both days, split at midnight. A session that has been open for 24 hours is closed and continued as a new, linked session, so no single entry grows without limit.

Browser extension

The extension tracks time on the websites you name for each project, and lets you start and stop timers from the toolbar.

Rules

Open a project in the extension or on its Tracking rules tab in the web app and add web addresses. A rule looks like a web address with * as a wildcard:

A rule starts with http://, https:// or *://, then an exact host name, *.example.com (the domain and all its subdomains) or *, an optional port, and a path. Without a path, every page of the host matches. Paths are case-sensitive, and the part after # is ignored. A project can have up to 100 rules of up to 2,048 characters. When a page matches rules of several projects, the project listed first in the extension gets the time.

Press Use this page to turn the address in front of you into a rule.

When it tracks

• A session starts when any open tab matches a rule, background tabs included.
• It ends when the last matching tab closes or moves to another site. Switching between tabs does not end it.
• If you stop it by hand while the tab is still open, it stays stopped until you leave the site and come back.
• After the computer slept, it ends at the last moment the extension saw the tab.

Only the project, the start and the end are sent. The addresses of your tabs and your browsing history stay in the browser. Rules are saved to your account, so the web app and your other browsers show the same ones.

Terminal client

The terminal client, temporal, brings file tracking to Linux machines without a desktop: servers, remote development boxes, a Raspberry Pi. It records into the same account as everything else.

Install

curl -fsSL https://temporal.ist/install.sh | sh

The script picks the build for your machine (64-bit x86 or ARM64), checks it against the published checksum and installs it as ~/.local/bin/temporal. Run it again to update, or use temporal update. If your shell does not find temporal afterwards, add ~/.local/bin to your PATH.

Sign in

temporal login

It shows a QR code and a short code. Scan the code with your phone, or open the address on any device, and approve. On a machine with a browser, temporal login --loopback signs in there instead. The sign-in appears under Settings → Devices and connections in the web app, where you can rename or revoke it.

Track a project

temporal projects create "Payments API"
temporal watch add "Payments API" ~/code/payments-api
temporal watch ls

temporal watch add takes a project's name or id and a folder; --ignore excludes a folder instead, and temporal watch patterns limits which files count. Folders are set per machine.

Run it in the background

temporal daemon install
loginctl enable-linger $USER

The first command installs, enables and starts a systemd user service. The second keeps it running when you log out of the machine and starts it after a reboot; you need it once per user. temporal daemon status and temporal daemon logs show what it is doing.

Everyday commands

• temporal status: what is running now and what is waiting to upload
• temporal start [project], temporal stop, temporal pause, temporal resume: timers by hand
• temporal task "Refund webhooks": name the current task
• temporal history --days 7: recent sessions
• temporal tui: a dashboard in the terminal

Like the desktop app, the terminal client keeps its work on disk until it is uploaded, and leaves sleep out. Installed versions of the old Python client move over by running temporal update; the new client takes over their settings, watched folders and sign-in.

Projects

Projects are where time goes. Create them on the Projects page, in the desktop app or with temporal projects create. Nothing creates a project for you.

• Client and rate. Link a project to a client for invoicing. A project without its own hourly rate uses its client's rate, and a client without one uses your organisation's default. A rate of zero is a real rate: that work is billed at zero.
• Colour. Your own choice for charts and the calendar; teammates choose their own.
• Tags. Labels to filter sessions, reports and invoices by.
• Tracking rules. The project's folders, per computer, and its web addresses.
• Archive. An archived project leaves your lists and no longer starts automatic sessions. Its history stays, and you can still add time to it by hand.

A project's page shows its sessions, tasks and the files changed per session, with how often and when.

Dashboard

The dashboard is where the app opens. It shows your running timers, today's sessions on a time line, this week against last week, and the split between projects. Totals and averages are your own time; the average counts only the days on which you tracked something.

The bar at the top of every page shows what is running. Start, pause and stop timers there, or press Ctrl K (⌘ K on a Mac) to start a timer on any project, jump to a page or add an entry.

Calendar and sessions

The Calendar shows your sessions by day, week or month, starting on Monday. Each block is a session in its project's colour, with its pauses shown.

• Click an empty slot to add work you did without tracking.
• Drag a block to move it, or its edge to change its start or end.
• Click a block to change its project, task, times and pauses, or to delete it.

The Sessions page lists the same sessions as a table you can filter. Select several to change their project or tags, merge them, delete them, or start an invoice from them. A session that is already on an invoice is locked until you remove it from the invoice.

Choose From first to last activity under Settings → Preferences, How a day's time is counted, and the calendar, reports and new invoices count one span per project per day, from your first activity to your last. Your sessions stay as they are: open a span to see and edit them, and switch back at any time.

On Solo you see the last 31 days. Older work is kept, and appears again when you upgrade.

Reports

Reports answers how long, on what and for whom: totals per project, client, tag and day, how they change over the period, and a timesheet. Choose a week, month, quarter, year or any range, and filter by project, client or tag. Owners and admins of a team can switch to the whole organisation and filter by person.

Temporal.ist reports how long you worked, never how you worked: there are no activity percentages or productivity scores.

On Pro and Team, export a report as CSV for a spreadsheet or as a PDF to print or send.

Invoicing

Invoicing is part of Pro and Team. In a team, the owner and admins invoice for the organisation.

1. Add your clients with their address, currency, VAT number and, if you like, an hourly rate.
2. Under Invoices, choose a client and a period. The unbilled sessions appear with their hours and amounts.
3. Create the draft. It gets its invoice number now; numbers count up per your organisation's format and are never reused, not even when a draft is cancelled.
4. Adjust lines, descriptions, rounding and VAT, then download the PDF, email it, or share a private link that your client can open without an account.
5. Mark it sent and paid. Unpaid invoices past their due date show as overdue.

Each session can be on one invoice only, so nothing is billed twice. Amounts are calculated exactly, in cents, with half-up rounding.

Teams and organisations

Everyone has an organisation; on Team it becomes shared.

• Roles. The owner pays and can do everything. Admins manage members, teams, clients and invoices. Members track their own time on the organisation's projects.
• Invitations. Admins invite people by email. Each member uses a seat; Team starts at four seats, and the owner can add more from Billing.
• Teams. Groups of people with the projects they work on.
• Team view. Owners and admins see who is tracking what right now, the team calendar, and each person's hours against their weekly target.

Members see their own time. Owners and admins see the time members track on the organisation's projects: sessions and hours, never screenshots or file contents.

Calendar sync

On Pro and Team, finished sessions can appear in Google Calendar or Microsoft 365. Connect an account under Settings → Integrations, choose a calendar for each project or for all of them, and decide whether to add your past sessions too. Changing or deleting a session updates its calendar event. Sync goes one way: events you create in your calendar do not become sessions.

AI assistants

On Pro and Team, AI assistants can work with your time through the Model Context Protocol (MCP). Add this address as a connector or MCP server in your assistant:

https://temporal.ist/mcp

The assistant opens a Temporal.ist sign-in the first time; approve it, and it can use these tools on your behalf:

• Timers: start_timer, stop_timer, pause_timer, resume_timer, get_active_timer, set_current_task
• Time entries: add_time_entry, list_time_entries, edit_time_entry, delete_time_entry
• Projects and reports: list_projects, create_project, get_time_report
• Clients and invoices: list_clients, create_client, update_client, create_invoice, list_invoices, send_invoice

The client and invoice tools stay off until you turn on Let an AI assistant handle sensitive data (customer data) under Settings → Integrations. Deleting an entry and sending an invoice always take two steps: the assistant first shows what would happen and needs your confirmation.

Each assistant you connect is listed under Settings → Devices and connections, where you can revoke it. Setup steps per assistant: Claude, ChatGPT, Codex, Gemini, Copilot, Kimi and OpenCode.

API and webhooks

On Pro and Team, create personal API keys under Settings → Integrations. A key can read only, or read and write, and its secret is shown once. Send it as a bearer token:

curl https://temporal.ist/api/v2/projects \
  -H "Authorization: Bearer tk_live_…"

Webhooks send a signed POST to your HTTPS address when a project is created, a session is created or closed, or an invoice is created or paid. The API reference describes every endpoint and how to check the signature.

Settings

• Profile: your name, email address and password, and the sign-in methods you linked (Google, Microsoft, GitHub, LinkedIn).
• Preferences: your time zone, which every day boundary and total uses; when sessions end (the idle timeout and the sleep window); how a day's time is counted; the colour theme (light, dark, or following your system); and the shortcuts on the phone tab bar.
• Tracking: the computers that track your time and the folders they watch.
• Integrations: calendar publishing, API keys, webhooks and AI assistants.
• Privacy and data: download everything you stored, or delete your account.
• Plan and billing: your plan, seats, invoices and payment details.

Devices and connections

Every app you sign in to (desktop app, terminal client, browser extension, AI assistant) is a connection under Settings → Devices and connections, with its name and when it was last seen. Rename it, or revoke it to sign that app out at once. Web sign-ins are listed there too, so you can end the ones you no longer use.

Apps stay signed in while you use them: a connection that has not been used for 30 days has to sign in again.

Privacy and your data

What the apps record: which files in your watched folders changed and when, that a tab matching your rules was open, and the sessions, pauses and tasks that come of it. What they never record: file contents, keystrokes, screenshots, other apps and windows, or pages that match none of your rules.

• Export. Under Settings → Privacy and data, download everything stored about you as one JSON file, or as spreadsheets in a ZIP file, on every plan.
• Delete your account. Also under Settings → Privacy and data. It signs out every device and connection at once. For 30 days you can sign in to undo it; after that the account and its data are deleted.

The privacy policy has the details.