Workaddict

A private, free and simple time tracker for small teams, as an alternative to Clockify.

• No server, no cost. The app is a static website hosted on GitHub Pages.
• Your data stays in your own repository. Every entry, project and tag is stored as a JSON file in a private GitHub repository (the "data repo") that you control. The app reads and writes it straight from your browser through the GitHub API.
• Features: a live timer that syncs across devices, manual entries (including overnight ones), projects and tags, statistics with charts, and exports to PDF, Excel (.xlsx), OpenDocument (.ods) and CSV from one Export menu, plus a full JSON backup. Optional AI integration (beta): your own AI assistant (Claude Code and other MCP clients) can set up projects and log your day for you. Team roles (worker, editor, team leader), a live "Team now" view for editors and team leaders, and entries you can edit by clicking a field. Built-in help pages, a guided tour and an Expert mode for fewer hints. English and German UI (switchable on the login page), light and dark themes with a one-click toggle, works on mobile.
• Full history. Each change is a git commit with a readable message (entry: add 2h "Fix login" (alice)), so the data repo doubles as an audit log that you can revert.

Try it without an account at workaddict.me by clicking "Try the demo" on the start page. Demo data stays in memory and is never saved.

---

How it works

Browser (this app, GitHub Pages)  ──GitHub REST API──►  private data repo
                                                         ├─ tracker.json          schema version
                                                         ├─ workspace.json        projects & tags
                                                         ├─ roles.json            member roles (optional)
                                                         ├─ entries/<login>/<YYYY-MM>.json
                                                         └─ timers/<login>.json   running timer

• Each member writes only their own entry and timer files, so members don't overwrite each other. workspace.json is shared, and its writes retry automatically on conflicts.
• Timestamps are stored in UTC and shown in the team time zone (timeZone in workspace.json, set by team leaders under Settings → Time zone). Without one, each browser's zone is used. Privacy browsers often report UTC, so set a team time zone to keep everyone's times aligned.
• Team members are the collaborators of the data repo. Everyone sees everyone's entries. Who may change what depends on their role.
• roles.json stores the role of each member (optional; created when an owner assigns the first role).
• On the first login the app creates tracker.json and workspace.json in an empty data repo.

---

Setup

Quick start: let the app guide you

Open the app (for example workaddict.me) and click Set up a team. The wizard first asks who the setup is for:

• Just me: no organization needed. A fine-grained token reaches a private repository in your own account, so it is three steps: create the repo, create the token, sign in. If other people join later, move the repository into a free organization and run the wizard again as a team — a repository in a personal account cannot be shared with fine-grained tokens.
• A team: enter your organization name once; every step then opens the right GitHub page: organization, private data repo, base permission, token approval, invitations (optionally as ready-made gh commands) and your own token. At the end you get an invite link and a message for your team. Later you find both under Settings → Invite members.
• Member: open the invite link from your team owner. It walks you through accepting the invitation, checking your access, creating the token and signing in, in the right order.
• Sign-in fails? The app looks up what's wrong, lists the most likely causes with links, and gives you a ready-made message for the owner.

The sections below describe the same setup by hand and are the reference for special cases.

You need two repositories:

Repository	Visibility	Contents
App repo (this one)	public (required for free GitHub Pages)	source code only, no data, no secrets
Data repo	private	your team's time data

The order matters. The team owner first sets up the organization, the data repo, and everyone's access (step 1). Only then does each member create their token (step 2). A token created before its owner had access to the data repo will not work, even after access is granted later. See Troubleshooting sign-in.

1. Create the organization and the data repo (team owner, once)

The team owner does this once for the whole team. We recommend a free GitHub organization. The data repo lives inside it.

Why an organization? Fine-grained tokens (the safe kind) only work for repositories owned by your own account or by an organization you belong to. If the data repo belongs to someone else's personal account, the other members have to use classic tokens, which can access all of their repositories.

1.1 Create the organization

1. Sign in to GitHub and open https://github.com/organizations/plan.
2. Choose the Free plan and click Create a free organization.
3. Organization name: choose a short name, e.g. my-team. This name is the owner part of the data repo name later on (my-team/time-data).
4. Contact email: your email address.
5. This organization belongs to: My personal account.
6. Solve the verification, accept the terms, and click Next.
7. You can skip the "Add organization members" screen for now by clicking Skip this step. You invite members in step 1.3.

You are now the owner of the organization.

1.2 Create the private data repo

1. Open https://github.com/organizations/my-team/repositories/new (replace my-team with your organization name). Alternatively: open the organization page → Repositories tab → New repository.
2. Owner: make sure your organization is selected, not your personal account.
3. Repository name: e.g. time-data.
4. Visibility: Private. This is important, since the repo holds all your team's time data.
5. Leave Add a README, .gitignore, and license unchecked. The repo can be empty; the app initializes it on the first sign-in.
6. Click Create repository.

The full name of the data repo is now my-team/time-data. Write it down; every member needs it to sign in.

1.3 Invite your team members to the organization

1. Open the organization page → People tab → Invite member (or go to https://github.com/orgs/my-team/people).
2. Enter the member's GitHub username or email address and click Invite.
3. Choose the role Member (not Owner, unless they should be able to manage the organization) and click Send invitation.
4. Repeat for every team member.

Every member must accept the invitation. They get an email, or they can open https://github.com/orgs/my-team/invitation while signed in and click Join my-team. An invitation that has not been accepted gives no access at all.

1.4 Give the members write access to the data repo

Being a member of the organization is not enough. By default, organization members only get Read access to the organization's repos, or none at all, and the app needs Write.

1. Open the data repo → Settings → Collaborators and teams (under Access in the left sidebar).
2. Click Add people, search for the member, select them, choose the role Write, and click Add … to this repository.
3. Repeat for every member.

Simpler: open the organization → Settings → Member privileges → Base permissions and choose Write. Then every member can write to the data repo, and you can skip adding people one by one. This applies to all repos of the organization, so use an organization that holds only the time data.

Tip for larger teams: create a team (organization → Teams → New team, e.g. trackers), add all members to it, and then add the team to the data repo with the role Write via Add teams. New members then only have to be added to the team.

Members who should be able to assign roles in the app need the role Admin instead of Write (see Assign roles).

1.5 Check the token policy of the organization

1. Open the organization page → Settings → in the left sidebar under Third-party Access → Personal access tokens → Settings (or https://github.com/organizations/my-team/settings/personal-access-tokens).
2. On the Fine-grained tokens tab:
   • Allow access via fine-grained personal access tokens must be selected. Otherwise nobody can use a fine-grained token for the data repo.
   • Require administrator approval is the default for new organizations. Every member's token then stays pending, and their sign-in fails until an owner approves it (step 2.3). Your own token as an owner is approved automatically, so you won't notice the problem yourself. For a small team you trust, select Do not require administrator approval; tokens then work immediately.
3. Click Save.

Checklist before members create their tokens:

• The organization exists and the data repo is private and owned by the organization.
• Every member has accepted the organization invitation.
• Every member has Write (or Admin) on the data repo.
• Fine-grained tokens are allowed in the organization.

Test: each member opens https://github.com/my-team/time-data in the browser while signed in to GitHub. If they see the (possibly empty) repo, their access is correct. If they see a 404 page, their access is not set up yet. Fix that first, before they create a token.

Alternative without an organization: a private repo in your personal account works too. You can use a fine-grained token yourself, but your collaborators must use classic tokens (see Fallback: classic token). Add them under the repo's Settings → Collaborators → Add people; they have to accept the invitation.

2. Create a personal access token (every member)

Every team member creates their own token on their own GitHub account. Never share one token between people: the app uses the token to find out who you are, and all your entries are saved under that account.

⚠️ Create the token only after you have accepted the organization invitation and can open the data repo in your browser (see the test above). A token created earlier cannot be fixed afterwards. If you already have one, delete it and create a new one.

2.1 Create a fine-grained token (recommended)

1. Sign in to GitHub with your own account and open https://github.com/settings/personal-access-tokens/new. The How do I get a token? help on the app's sign-in page links the same form with the token name filled in. GitHub may first ask you to confirm it's you (password or GitHub Mobile). Alternatively: click your profile picture (top right) → Settings → Developer settings (at the bottom of the left sidebar) → Personal access tokens → Fine-grained tokens → Generate new token.
   • Only the name and description can be prefilled by a link. As of September 2026 GitHub ignores the resource owner, expiration and permission parameters, so the form always opens on your personal account with a 30-day expiry and no permissions. Steps 4, 5, 6 and 7 below are the ones you have to set by hand every time.
2. Token name: something recognizable, e.g. Workaddict.
3. Description (optional): e.g. Time tracking.
4. Resource owner: open the dropdown and select the organization that owns the data repo (e.g. my-team), not your own username.
   • This setting cannot be changed later. If you pick the wrong owner, delete the token and create a new one.
   • If the organization is missing from the dropdown, you have not accepted the invitation yet (step 1.3), or the organization does not allow fine-grained tokens (step 1.5).
5. Expiration: choose how long the token stays valid, e.g. 90 days or a custom date. When it expires, the app asks you to sign in again with a new token. No expiration is possible but less safe.
6. Repository access: select Only select repositories, open the Select repositories dropdown, and pick the data repo (e.g. my-team/time-data).
   • If the repo is missing from the list, you don't have access to it yet (step 1.4), or you selected the wrong resource owner.
7. Permissions: under Repository permissions, find Contents and set it to Read and write. (In newer versions of the form: click Add permissions → Repositories, tick Contents, then set the access level next to it to .)

2.2 If you need approval

If the organization requires approval (the default, see step 1.5), your token shows up as pending and every request to the data repo fails with "Your token cannot see the repository" until an organization owner approves it. Tell your team owner that you created a token; the sign-in page has a Copy message for the owner button with the right link.

2.3 Approve tokens (team owner)

1. Open the organization page → Settings → Third-party Access → Personal access tokens → Pending requests (or https://github.com/organizations/my-team/settings/personal-access-token-requests).
2. Click the member's request, check that it only asks for the data repo with Contents: Read and write, and click Approve.

You only see this page if you are an owner of the organization. If the list is empty, either no token is waiting or approval is turned off.

2.4 Fallback: classic token

Use a classic token only if the data repo is owned by another person's personal account, or as a quick temporary workaround.

1. Open https://github.com/settings/tokens/new (Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)).
2. Note: e.g. Workaddict. Expiration: as you like.
3. Tick the repo scope (the whole group). Leave everything else unticked.
4. Click Generate token and copy the token (it starts with ghp_).

⚠️ A classic repo token grants read and write access to all repositories you can access, not just the data repo. Prefer a fine-grained token in an organization. Organizations can also block classic tokens (step 1.5, Personal access tokens (classic) tab).

3. Deploy the app to GitHub Pages

1. Push this repository to GitHub, as a public repo.
2. Go to Settings → Pages → Build and deployment → Source: select GitHub Actions.
3. Push to main. The workflow in .github/workflows/deploy.yml runs npm ci → npm test → npm run build and deploys dist/. If tests fail, nothing is deployed and the previous version stays live. After a successful deploy it tags the commit and publishes a GitHub release when the version changed (see Versions and releases).
4. The app is available at https://<user-or-org>.github.io/<app-repo>/.

Pull requests to main are checked by .github/workflows/ci.yml (audit, lint, tests, build) before they can be merged.

The build uses a relative base path and hash routing (#/stats), so it works under any repo name and page reloads never 404.

Deploying your own copy? index.html (canonical and og: URLs), the static search pages (clockify-alternative/, import-from-clockify/ and their German versions under de/: canonical, hreflang and og: URLs), public/robots.txt and public/sitemap.xml point to https://workaddict.me. Change them to your own URL, or search engines will treat your copy as a duplicate of the official site. Links between the pages and the app are relative and work on any path.

The import guides quote the app's labels (checked by src/app/seoPages.test.ts). Update them, and retake their screenshots, when the Clockify import wizard changes.

4. Sign in

1. Open the Pages URL.
2. Token: paste your token.
3. Repository: enter the data repo as owner/name, exactly as it appears in the browser's address bar when you open the repo, e.g. my-team/time-data. The owner is the organization name, not your username.
4. Keep "Save as a workspace on this device" ticked to save the token, encrypted with a passphrase you choose, or untick it to sign in for this tab only (on shared computers). The first time you save a workspace, the app asks for the passphrase and whether to ask for it on every visit or stay unlocked on this device. The passphrase cannot be recovered; if you forget it, you reset the workspaces and enter your tokens again.
5. Click Sign in. The first sign-in initializes the empty data repo.

Several workspaces. Each data repository is a workspace; its name defaults to owner/name and can be changed under Settings → Workspaces → Rename. Open the avatar menu → + Add workspace to add another one: when you already have a token for the same owner (or a classic token), the app offers to reuse it, otherwise you paste a new token (a fine-grained token covers only one organization or account). Switch workspaces with one click in the avatar menu; a dot marks workspaces where your timer is running. Each browser tab can show a different workspace. Settings → Workspaces has the unlock mode, Change passphrase, Export workspaces and Import workspaces (to move your workspaces to another device as an encrypted file), and Forget all workspaces on this device.

If sign-in fails, see Troubleshooting sign-in.

5. Assign roles

Every member has one of three roles:

Permission	Worker	Editor	Team leader
Track time, run own timer, edit and delete own entries	✓	✓	✓
See all entries and statistics, export	✓	✓	✓
Add, edit, and delete other members' entries		✓	✓
See who is tracking right now ("Team now" on the tracker page)		✓	✓
Stop or discard other members' running timers		✓	✓
Create, rename, recolor, archive, and delete projects and tags		✓	✓
Import from Clockify			✓

• Owners are everyone with admin permission on the data repo. For a personal repo that is the account owner; in an organization it is the repo or organization admins. Owners are always team leaders, and only owners assign roles (under Settings → Team & roles), including making other members team leaders.
• Members without an assigned role are workers. Upgrading from an earlier version: after the update, everyone except the owners is a worker until an owner assigns roles. The app shows owners a reminder until the first role is assigned.
• Team now. Editors and team leaders see, above their entries, what every other member is tracking right now (description, project, tags, elapsed time), each member's total for today, and when idle members were last active. A timer that has run for more than 10 hours, or since before today, is flagged. They can stop such a timer at a chosen end time or discard it. The member gets a notice, the entry records who stopped it, and the commit message names both. There is no opt-out. Workers don't see the block, but the running timers in timers/ can be read by anyone with access to the data repo.
• Missing entries. Editors and team leaders can add an entry for another member: in the manual form, pick the member under For. The entry belongs to that member, shows "added by" with your login, and the commit message names both.
• Issue links. Every entry and the running timer can link to one GitHub issue or pull request. Type owner/repo#42, paste the issue URL, paste the link of a card on your GitHub Projects board, or just type #42. For #42, an editor or team leader links the project's board or repository once (Projects & Tags → Link GitHub board or repository). With a board, paste one card link the first time; after that the number is enough for that card's repository. With several linked repositories, #42 goes to the default one (the first; Make default changes it) and api#42 to the one named api. The entry list links to the issue, and the exports have an "Issue" column (a hyperlink in Excel and OpenDocument). The app never loads issues from GitHub, so your token still needs access to the data repo only, and a link to a private repository works only for people who can see that repository.
• Roles are enforced by the app, not by GitHub. See Security notes.

6. Optional: import your Clockify history

Switching from Clockify? A team leader opens Settings → Data → Import from Clockify. The wizard imports projects (name, color, archived), tags, and all completed time entries of the users you select, in a single commit.

• Replaces existing data. If the data repo already has entries, projects, or tags, the wizard shows how many and asks for confirmation; the import then replaces all of them (running timers are kept). There is no merging. The old data stays in the data repo's git history and can be restored by reverting the import commit.
• API key. Create one in Clockify under Profile settings → API. To import the whole team, it must be the key of a Clockify workspace admin; other keys can only read their own entries. The key is kept in memory only, sent only to Clockify, and never saved. Delete it in Clockify after the import.
• User mapping. Map each Clockify user to a GitHub login of the team, keep them as a former member (read-only pseudo-login clockify.<name>, so yearly totals stay correct), or skip them.
• Changing the mapping later. Mapped a Clockify user to the wrong member, or a former member joined the team? A team leader opens Settings → Data → Reassign entries and moves all entries of one member (including clockify.* former members) to another, in one commit. Tick "Only entries that started before a date" and pick the import day so that entries the member tracked in Workaddict afterwards stay with them.
• Free plan limits. Clockify Free allows only 30 API requests per hour. The import uses large pages (about 5 requests plus 1–2 per user), shows a request counter, and if the limit is hit it pauses and lets you continue later without re-fetching what was already loaded. Keep the tab open until the import is done.
• Not imported: clients, tasks, billable flags, rates, custom fields, and running timers. The preview shows how many entries are affected and lists hours per member and project so you can compare them with Clockify's summary report.

---

7. Optional (beta): connect your AI assistant

Beta. The AI integration is new: the tools and the plugin may still change, and the activity heuristic only sees time in which Claude Code was working. Check the suggested entries before you confirm them.

Every member can let their own AI assistant work with Workaddict through the Workaddict MCP server (workaddict-mcp, runs on your computer via npx). Workaddict itself has no server and holds no AI key: whoever uses Claude Code, Claude Desktop, Cursor or another MCP client connects it with their own token, everyone else keeps using the app as before. Settings → AI assistants → Connect AI shows the commands below with your data repo filled in.

1. Create a separate fine-grained token for the assistant, like the app token: only the data repo, Contents: read and write, Metadata: read. A separate token can be revoked without signing you out of the app.
2. Set two environment variables and open a new terminal:
   • Windows: setx WORKADDICT_REPO "owner/repo" and setx WORKADDICT_TOKEN "github_pat_…"
   • macOS / Linux: add export WORKADDICT_REPO="owner/repo" and export WORKADDICT_TOKEN="github_pat_…" to your shell profile
3. Claude Code: install the plugin, then use /workaddict:log-today and /workaddict:new-project:

   /plugin install workaddict --marketplace Workaddict/workaddict
   

   Without the plugin, add only the server: claude mcp add workaddict --scope user -e WORKADDICT_REPO=owner/repo -e WORKADDICT_TOKEN=github_pat_… -- npx -y [email protected] (on native Windows -- cmd /c npx -y …).
4. Other MCP clients (Claude Desktop, Cursor, …) take this in their MCP configuration:

   {
     "mcpServers": {
       "workaddict": {
         "command": "npx",
         "args": ["-y", "[email protected]"],
         "env": { "WORKADDICT_REPO": "owner/repo", "WORKADDICT_TOKEN": "github_pat_…" }
       }
     }
   }
   

What it does:

• Log your day. /workaddict:log-today reads your Claude Code session transcripts (~/.claude/projects) on your computer only, turns them into activity blocks (a pause of 15 minutes starts a new block), matches each block to a project through its linked repositories and to an issue through the branch name (fix/42-login → #42), and shows you a table of suggested entries. Time you already tracked is left out. Nothing is saved until you confirm, and only the description the assistant writes is stored, never the transcript.
• Set up projects. /workaddict:new-project turns a description ("new client Huber, shop is github.com/acme/huber-shop, we do support and development") into projects, linked repositories and tags, after you confirm. Needs the editor or team leader role.
• Same rules as the app. The server uses the app's storage code, so roles, validation and conflict handling are identical. It can read and add data, but has no tools to delete or archive anything, change roles or the team time zone. Entries that overlap time you already tracked are refused unless you explicitly allow it.
• Visible in the history. Every commit it makes ends with (via claude-code) (the client's name). Team leaders can also turn on Settings → AI assistants → Mark AI entries (off by default); new AI entries then show "via Claude Code" in the entry list.

Help, guided tour and Expert mode

The app explains itself; nothing of this is tracked or sent anywhere.

• Tips. Hover, focus or long-press an icon button to see what it does. Words with a dotted underline (data repository, workspace, passphrase, …) explain themselves in one sentence, with a Learn more link.
• Help pages at #/help, signed in or not, in English and German: token & data repository, workspaces & passphrase, roles, projects & tags, Team now, issue links & project boards, connecting an AI assistant, export & backup, Clockify import, time zone, keyboard shortcuts and a glossary. Complex features have a ? button next to their heading that opens their topic. Each page ends with "Was this helpful?"; 👎 offers a prefilled question in GitHub Discussions, which you open yourself. The old #/token-help address redirects to #/help/token.
• Help overlay. Press ? (outside text fields) or choose Help in the avatar menu to search the topics and glossary and see the keyboard shortcuts.
• Guided tour. After the first sign-in on a device, a welcome dialog offers a short tour that points out the timer, the entry list, projects & tags, statistics & export, the workspace chip and the avatar menu. Editors and team leaders also see Team now and the member filter, team leaders also Team & roles. The tour only shows where things are; it never changes data. Members who already have entries older than a week see no dialog, only a one-time notice. On the start page, Demo with tour opens the demo with the tour.
• First steps. A card on the Tracker ticks itself off as you track your first time, create a project and a tag, and (owners) invite your team. Hide it any time.
• "New" dots mark features added since your first visit and disappear once you open them.
• Expert mode. Settings → Help & guide → Expert mode hides the underlined terms, the first steps card, the "New" dots and the welcome dialog, and shortens the empty-page explanations. Tips on icon buttons, ? buttons, help pages and the overlay stay. The same section has Restart tour, Show tips again and a link to the help pages. These settings are stored per device.

Troubleshooting sign-in

The login page first checks the token and then the data repo. The error message tells you which step failed.

Message on the login page	Cause	Fix
Enter the repository as owner/name	The repo field has the wrong format.	Enter my-team/time-data, with no https://github.com/ in front.
GitHub rejected this token	Token incomplete, expired, or deleted.	Copy it again without spaces, or create a new one (step 2).
There is no GitHub account or organization named …	The owner part of the repo name is misspelled.	Copy owner/name from the address bar of the repo on GitHub.
Your token cannot see the repository …	The token is valid but can't see an organization's repo. GitHub answers with 404.	The app lists the causes in order, starting with a token that waits for approval. See the checklist below.
… which belongs to the personal account of …	The repo is in another person's account. Fine-grained tokens can't reach it.	Move the repo into an organization, or use a classic token (step 2.4).
… in your own account	Wrong repo name, or the token doesn't include this repo.	Check the name and the token's Repository access.
You can read the repository …, but not write to it	Contents is only Read-only, or the member only has Read on the repo.	Set Contents to Read and write (step 2.1, item 7) and give the member Write (step 1.4).
GitHub rate limit reached	Too many requests.	Wait until the time shown. See the note below.

Checklist for "Your token cannot see the repository" (404):

1. Is the token still waiting for approval? Organizations require approval by default. An organization owner checks Pending requests (step 2.3). The owner's own token never needs approval, which is why sign-in can work for the owner but not for members.
2. Was the token created before the member had access? If the token was created before the member accepted the organization invitation or before they had Write on the data repo, it stays unable to reach the repo, and editing it later doesn't help. Delete the token and create a new one (step 2.1).
3. Can the member open the repo in the browser? They open https://github.com/my-team/time-data while signed in. If they see a 404 page, the problem is their access, not the token. Go back to steps 1.3 and 1.4.
4. Is the resource owner correct? Open the token under Settings → Developer settings → Fine-grained tokens. Resource owner must be the organization. If it's the member's own account, create a new token.
5. Is the data repo selected? On the same page, Repository access must list the data repo.
6. Is the repo name correct? Compare it character by character with the address bar (hyphens vs. underscores, organization name vs. username).

Test without the app: run this in a terminal with the member's token:

curl -H "Authorization: Bearer <TOKEN>" https://api.github.com/repos/my-team/time-data

If this returns JSON with "full_name": "my-team/time-data" and "push": true, the token is fine. If it returns "message": "Not Found", the problem is on GitHub's side (checklist above).

Rate limit when testing in the browser: don't test by opening https://api.github.com/... links directly in the browser. Those requests are sent without a token, so GitHub only allows 60 per hour per IP address, shared by everyone in the same office network. They also always return 404 for a private repo. Some browsers auto-translate the message into something confusing (such as "installment payment" for "rate limit"). Use the curl command above instead. With a token, the limit is 5,000 requests per hour per token.

---

Security notes

Read this before you use the app with real data. To report a vulnerability, see SECURITY.md.

• Roles are not a security boundary. Anyone with write access to the data repo can read and change all data through the GitHub API or the GitHub website, including other members' entries, projects, and roles.json itself. The app checks roles before every change it makes, but it cannot stop direct edits to the repository. Only add people you trust. Every change is a commit that names the acting user (for example entry: delete "Standup" for bob (carol), role: set bob to editor (alice)), so you can find and revert unwanted changes in the git history.
• Your tokens are stored in your browser. Saved workspaces live in an encrypted vault in localStorage (AES-GCM with a key derived from your passphrase by PBKDF2-SHA256, 600,000 iterations); no token or repository name is stored in plaintext, and nothing is sent anywhere. Without "Save as a workspace", the token stays in sessionStorage and is cleared when the tab closes. While the app is unlocked, the tokens are in memory, so any script that ran on the page could read them; the vault protects them at rest and in export files, not against such script. To limit the risk:
  • use a fine-grained token limited to the data repo, with an expiration date (the app warns when you sign in with a classic token);
  • choose a long passphrase (a few words); anyone with your browser profile or an export file can try to guess it;
  • on shared computers, sign in without saving. Repository data is then cached in memory only and nothing stays on disk after the tab closes. "Stay unlocked on this device" keeps cached data and the key on disk, so use it only on your own device;
  • Lock (avatar menu) when you step away; Settings → Workspaces → Forget all workspaces on this device removes every token and all cached data;
  • if you used "Remember me" in an earlier version, accept Protect with a passphrase so the plaintext token is deleted;
  • if a token leaks, revoke it on GitHub right away.
• AI assistant token. The MCP server (optional, see setup step 7) reads its token from an environment variable or the AI client's configuration file, where it is stored in plain text. Give the assistant its own fine-grained token limited to the data repo, and revoke it on GitHub when you stop using it. The server cannot delete data, and every commit it makes names the assistant.
• Content Security Policy. The production build ships a strict CSP: scripts only from the app's own origin, and network requests only to https://api.github.com and, for the one-time Clockify import, https://*.clockify.me. Trusted Types are enforced and inline styles are not allowed. Nothing is sent anywhere else: no analytics, no third-party scripts at runtime.

---

Development

Requirements: Node.js 20.19+ or 22.12+.

npm install
npm run dev        # dev server at http://localhost:5173 (use "Try the demo" to skip login)
npm test           # unit tests (Vitest)
npm run lint       # ESLint
npm run build      # type-check + production build into dist/
npm run preview    # serve the production build (with CSP) locally

Project layout

src/
  app/           shell, routing, frame guard, static search pages, project links
  components/    shared UI building blocks
  domain/        types, time/duration helpers, month keys (pure, unit-tested)
  storage/       StorageAdapter interface, memory adapter, GitHub adapter
  features/      auth, tracker, workgroups, stats, export, import, data, settings,
                 onboarding, profiles, help (help pages, tour, "New" dots)
  i18n/          English and German texts
  styles/        design tokens, light/dark themes
mcp/             Workaddict MCP server (npm package workaddict-mcp)
plugin/          Claude Code plugin with the /workaddict:* skills
scripts/         build and release helpers

All data access goes through the StorageAdapter interface (src/storage/types.ts). UI code never calls GitHub directly. That makes it possible to swap the backend later (e.g. for Supabase), and the JSON backup format serves as the migration path. The MCP server reuses the same storage and domain code, so src/storage and src/domain must not use browser APIs.

Versions and releases

The app's version is set automatically from the commit messages, which follow Conventional Commits. On every deploy, scripts/next-version.mjs looks at the commits since the last v* tag:

Commits since the last release	Next version (from 1.1.0)
at least one feat:	1.2.0
only fix: or perf: (plus others)	1.1.1
feat!:, fix!: … or a BREAKING CHANGE: footer	2.0.0
only chore:, docs:, ci:, test:, refactor: …	no new version

The build shows that version under Settings → About, and after a successful deploy the workflow creates the tag and a GitHub release with generated notes. Nothing is committed back to main; version in package.json is only used for local builds. When you add a feature to NEW_FEATURES (src/features/help/newFeatures.tsx) for a "New" dot, use the next minor version.

The MCP server and the plugin have their own versions and are published by hand (.github/workflows/publish-mcp.yml).

License

Workaddict is free and open-source software, © 2026 Benedikt Lehner, licensed under the GNU Affero General Public License v3.0 with two additional terms in NOTICE.

In short:

• You may use, study, change and share the code, for free, also for your own team or company.
• If you publish a changed version, or run one as a website for others, you must share its source code under the same license.
• Keep the credit visible: the footer and Settings > About must keep showing "Made by Benedikt Lehner" and a link to this project.
• Mark changed versions as your own (for example "based on Workaddict by Benedikt Lehner"). Don't present them as the original.

This summary is for convenience; the LICENSE and NOTICE files are what counts.

Built something with Workaddict? Please open an issue and tell me about it. That's a request, not a condition, but I'd love to see it. Suggestions and pull requests are welcome too.