Skip to content
Back to search

clockout

MarketplaceWorks with Claude CodeGitHub

clockout: timesheets drafted from your real work

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/devprjl--clockout/badge.svg)](/listings/devprjl--clockout)

HTML

<a href="/listings/devprjl--clockout"><img src="/api/listings/devprjl--clockout/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

You need [Claude Code](https://claude.com/claude-code) and [uv](https://docs.astral.sh/uv/). uv runs clockout's Python scripts and fetches their dependencies automatically, so there's nothing else to set up.

brew install uv            # or: curl -LsSf https://astral.sh/uv/install.sh | sh

Then, in Claude Code:

/plugin install clockout --marketplace devprjl/clockout

On older Claude Code versions, use two steps instead: `/plugin marketplace add devprjl/clockout`, then `/plugin install clockout@clockout`.

Run it as **`/clockout:clockout`** (plugin skills are namespaced), or just say "fill my timesheet". Start with `/clockout:clockout setup`.

Updating

New versions arrive when the plugin's version is bumped. Update with `/plugin marketplace update clockout`, then `/plugin update clockout@clockout`, or turn on auto-update for the marketplace under `/plugin` → Marketplaces. Your settings in `~/.config/clockout/` are never touched by installs, updates or uninstalls.

Without the plugin (manual)

git clone https://github.com/devprjl/clockout.git ~/code/github/clockout
ln -s ~/code/github/clockout/skills/clockout ~/.claude/skills/clockout   # then run it as /clockout

uv is still used to run the scripts. Don't install it both ways, because you'd get two clockout skills.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "clockout",
  3. "owner": { "name": "devprjl", "url": "https://github.com/devprjl" },
  4. "description": "clockout: timesheets drafted from your real work",
  5. "plugins": [
  6. {
  7. "name": "clockout",
  8. "source": "./",
  9. "description": "Draft your timesheet from GitLab/git activity and meetings; export to clipboard, Google Sheets or OpenProject."
  10. }
  11. ]
  12. }
README.md · README · 246 lines
  1. # clockout
  2. **Run it when you clock out.** `clockout` is a [Claude Code](https://claude.com/claude-code) skill. It looks at what you actually did (commits, merge requests, issue activity and the meetings you told it about) and drafts your timesheet **in each project's own format**. You review it, and it goes to the clipboard, ready to paste, or straight into a Google Sheet.
  3. ```
  4. /clockout → today, for whichever projects you worked on
  5. /clockout yesterday
  6. /clockout 2026-11-04..2026-11-20
  7. ```
  8. | Person | Date | Task Description | Hours Spent | Remarks |
  9. |---|---|---|---|---|
  10. | Alex | Nov 19 | - Login errors now show proper toast messages<br>- Added review summary filter and translations<br>- Added confirmation dialog for deleting users and tags | 6.5 | |
  11. ---
  12. ## ⚠️ Disclaimer: read this
  13. - **It drafts; you decide.** clockout builds a starting point from your GitLab activity, local commits and the meetings you describe. It isn't a record of the time you worked.
  14. - **It can't see everything.** Team discussions, pairing, reviews done outside GitLab, research, support, debugging that never became a commit, and work in tools or repos you didn't configure are all invisible to it. Add them yourself.
  15. - **Hours are assumed.** Each task line comes from real activity, but the time is an *estimate* of the effort behind it: planning, prompting, thinking, testing, design curation. A light day stays light, and it won't pad a day to 8 hours.
  16. - **Log your true hours.** You are responsible for what you submit. Correct the estimates, add what's missing, remove what's wrong, and keep your timesheet honest and transparent for your team.
  17. ---
  18. ## How it works
  19. ```
  20. ~/.config/clockout/
  21. ├─ config.yaml you: name, timezone, workdays, hours, sources
  22. ├─ secrets.env tokens
  23. └─ projects/*.yaml per project: match rules, layout, destinations, meetings
  24. GitLab API ─┐ ┌─ project A ─ layout A ─► clipboard
  25. git log ────┼─► collect ─► routed to ──────┤
  26. meetings ───┘ (real work) projects └─ project B ─ layout B ─► Google Sheet
  27. │
  28. Claude drafts short bullets + estimated hours ─► you approve/edit ─► export
  29. ```
  30. - **Personal settings** (`config.yaml`) apply everywhere: your name, timezone, workdays, working hours, how many focused hours a day is realistic, and your GitLab instances.
  31. - **Projects** (`projects/<slug>.yaml`) are set up once each. A project file holds:
  32. - which repos belong to it (by remote, GitLab path or folder),
  33. - the exact columns of that team's timesheet,
  34. - where the rows go,
  35. - its meetings,
  36. - anything that differs from your defaults (a different name spelling, workdays, style).
  37. - On every run, the day's activity is **routed to the right project automatically**. If a day spans two projects, you get two drafts, each in its own layout and sent to its own destination. Activity from repos you haven't set up is flagged so you can assign it, set it up or ignore it. It's never silently dropped.
  38. ---
  39. ## Install
  40. You need [Claude Code](https://claude.com/claude-code) and [uv](https://docs.astral.sh/uv/). uv runs clockout's Python scripts and fetches their dependencies automatically, so there's nothing else to set up.
  41. ```bash
  42. brew install uv # or: curl -LsSf https://astral.sh/uv/install.sh | sh
  43. ```
  44. Then, in Claude Code:
  45. ```
  46. /plugin install clockout --marketplace devprjl/clockout
  47. ```
  48. On older Claude Code versions, use two steps instead: `/plugin marketplace add devprjl/clockout`, then `/plugin install clockout@clockout`.
  49. Run it as **`/clockout:clockout`** (plugin skills are namespaced), or just say "fill my timesheet". Start with `/clockout:clockout setup`.
  50. ### Updating
  51. New versions arrive when the plugin's version is bumped. Update with `/plugin marketplace update clockout`, then `/plugin update clockout@clockout`, or turn on auto-update for the marketplace under `/plugin` → Marketplaces. Your settings in `~/.config/clockout/` are never touched by installs, updates or uninstalls.
  52. ### Without the plugin (manual)
  53. ```bash
  54. git clone https://github.com/devprjl/clockout.git ~/code/github/clockout
  55. ln -s ~/code/github/clockout/skills/clockout ~/.claude/skills/clockout # then run it as /clockout
  56. ```
  57. uv is still used to run the scripts. Don't install it both ways, because you'd get two clockout skills.
  58. ## Set up (once)
  59. Open Claude Code in a project repo and run:
  60. ```
  61. /clockout setup
  62. ```
  63. 1. **You** (first time only). Claude asks for your name (as written in timesheets), timezone, workdays and working hours. It also asks for your GitLab URL and pre-fills your commit emails from git.
  64. - Create a GitLab **personal access token with only the `read_api` scope**: avatar → *Edit profile* → *Access tokens*.
  65. - Paste it into `~/.config/clockout/secrets.env` yourself, not into the chat.
  66. 2. **This project**:
  67. - Claude proposes match rules from the repo's remote.
  68. - **Paste your timesheet's header row, or share a screenshot of the sheet.** Claude maps each column (date format, hours format, one row per day or one per task, constant columns, columns it should ask you about) and shows a couple of your real recent rows in that layout to confirm.
  69. - Choose a destination: clipboard (works with any sheet), or write directly into a Google Sheet (below).
  70. - Optionally describe your meetings: "DSM on alternate days from Oct 27, about 20 minutes".
  71. Run `/clockout setup` in any other project repo to add it. If the timesheet's columns change, say *"our timesheet columns changed"* and paste the new header.
  72. Everything is plain YAML in `~/.config/clockout/`, and you can edit it by hand. See [`skills/clockout/examples/`](skills/clockout/examples/) for fully commented files. Check your setup with:
  73. ```bash
  74. uv run --script <path to clockout>/skills/clockout/scripts/config.py validate # or ask Claude: "validate my clockout config"
  75. ```
  76. ## Daily use
  77. | You type | What happens |
  78. |---|---|
  79. | `/clockout` | Today. Asks once about anything it can't see (discussions, reviews), previews, then exports |
  80. | `/clockout yesterday` / `/clockout 2026-11-18` | A specific day |
  81. | `/clockout 2026-11-04..2026-11-20` | Catch up on a range (one preview for everything) |
  82. | `/clockout just print` | Show tab-separated rows instead of exporting |
  83. | "DSM is weekly from today, 1 hour" | Updates that project's meetings; past days keep the old schedule |
  84. | "No DSM today" / "had a 1h discussion with design" | Records it for that day |
  85. **Which days get rows:** non-workdays and holidays get nothing unless you worked. A workday with only meetings gets just the meetings. A workday with nothing gets a date-only row in your main project, so the gap is visible.
  86. **Pushing a draft:** `/clockout` always stops at a preview of exactly what each destination will get. Reply "send it" (or ask for edits: "make #42 2h", "drop the last row", "append, don't replace") and Claude runs the export. The draft is saved in `.cache/entries-<date>.json`, so you can also push it yourself with `scripts/export.py --entries .cache/entries-<date>.json`.
  87. **Pasting:** click the first empty cell of the first column and press **⌘V** / **Ctrl+V**. Each entry becomes one row, and multi-line task lists stay in one cell.
  88. ## Layouts
  89. Each column in a project's `layout.columns` has a `header` (exact text from the sheet) and a `value`:
  90. | value | fills in |
  91. |---|---|
  92. | `person`, `date`, `task`, `hours`, `remarks` | the usual fields |
  93. | `project` | the code project (e.g. `group/repo`) |
  94. | `ticket` | first issue/MR ref of the entry, e.g. `#21`, `!58` |
  95. | `work_package` | the work package the entry is logged on (from `OP#123` / `Ref: <name>`); empty = the destination's default bucket |
  96. | `refs` | links to the MRs and issues behind the entry (`format: lines` or `comma`) |
  97. | `const:<text>` | the same text on every row |
  98. | `ask` | Claude asks you (optional `default`, `choices`) |
  99. | `blank` | left empty |
  100. Formats:
  101. - **Dates:** `MMM d` → Nov 4, `D MMM` → 4 Nov, `DD/MM/YYYY`, `YYYY-MM-DD`, `dddd` for the weekday.
  102. - **Hours:** `number` → 6.5, `h:mm` → 6:30, `~number` → ~6.5, `minutes` → 390.
  103. - **Granularity:** `per_day` puts the day's tasks as bullets in one cell. `per_task` gives each task its own row and hours.
  104. ## Destinations
  105. | type | what | config |
  106. |---|---|---|
  107. | `clipboard` | copies rows as a table, pastes cleanly into Google Sheets/Excel | `with_header: true` to include headers |
  108. | `tsv` | prints tab-separated rows | |
  109. | `gsheet_webapp` | appends to **your own** Google Sheet through a small Apps Script; no Google Cloud, sheet stays private | `url_env`, `token_env`, `tab` |
  110. | `gsheet_api` | appends via the Sheets API | `sheet_id`, `tab` |
  111. | `openproject` | logs **time entries** in OpenProject (API v3), one per entry | `url_env`, `token_env`, `project`, `activity`, `work_package` |
  112. Both Google Sheet destinations:
  113. - check that the sheet's header row still matches the layout, and stop if it doesn't;
  114. - only ever **append** below existing data;
  115. - refuse to write if you already have rows on those dates. `--replace-date` replaces only **your** rows for those dates.
  116. ### Google Sheet via Apps Script (`gsheet_webapp`)
  117. 1. Generate a token with `python3 -c "import secrets;print(secrets.token_urlsafe(32))"` and add it to `secrets.env`, e.g. `MY_SHEET_TOKEN=...`.
  118. 2. In the sheet, open **Extensions → Apps Script**. Paste [`skills/clockout/apps-script/Code.gs`](skills/clockout/apps-script/Code.gs), set `TOKEN` to the same value, and save.
  119. 3. Click **Deploy → New deployment → Web app**. Set *Execute as* to **Me** and *Who has access* to **Anyone**, then authorise it. Add the URL to `secrets.env`, e.g. `MY_SHEET_URL=...`.
  120. 4. In the project file, add `- {type: gsheet_webapp, url_env: MY_SHEET_URL, token_env: MY_SHEET_TOKEN, tab: Timesheet}`. Set the sheet's sharing back to **Restricted**.
  121. ### Google Sheet via Sheets API (`gsheet_api`)
  122. Enable the Sheets API in a Google Cloud project, then either:
  123. - save a service-account key as `~/.config/clockout/google/service-account.json` and share the sheet with its email, or
  124. - save an OAuth Desktop client as `~/.config/clockout/google/credentials.json` and run `scripts/auth.py sheets`.
  125. ### OpenProject (`openproject`)
  126. 1. In OpenProject: avatar → **My account** → **Access tokens** → **API** → **+ API token**. Put it in `secrets.env` as `OPENPROJECT_TOKEN`, and the instance URL as `OPENPROJECT_URL`. These are set **once** for all your projects through `destination_defaults` in `config.yaml`:
  127. ```yaml
  128. destination_defaults:
  129. openproject: {url_env: OPENPROJECT_URL, token_env: OPENPROJECT_TOKEN}
  130. ```
  131. A project on a different server or account just sets its own `url_env`/`token_env` on its destination; those win.
  132. 2. In the project file, add the destination (see [`skills/clockout/examples/projects/openproject.yaml`](skills/clockout/examples/projects/openproject.yaml)): the project identifier, a default activity (Development, Testing…) and the work package. Use a fixed id, `from_refs` (below), or `ask` to have Claude ask per entry. If your team picks the activity per entry, add a layout column `{header: Activity, value: ask, default: Development, choices: [...]}`; each entry's answer overrides the default. On **OpenProject 17+, time must be logged on a work package**.
  133. 3. Lookups that work without admin rights (or just ask Claude, e.g. "which work packages are open in tiny-ledger?"):
  134. ```bash
  135. S=<path to clockout>/skills/clockout/scripts
  136. uv run --script $S/op.py work-packages --project <slug> --query search # find a work package id
  137. uv run --script $S/op.py activities --project <slug> # allowed activities
  138. uv run --script $S/op.py logged --project <slug> --date 2026-11-16..2026-11-20 # what you already logged
  139. uv run --script $S/op.py delete --project <slug> --id 8,9 # delete your own entries (e.g. duplicates)
  140. ```
  141. 4. `--preview` lists exactly what will be sent (date, duration, work package, activity, comment). `--dry-run` checks the server (project, permissions, entries you already logged) without writing. Re-running a day with entries already logged is blocked until you choose: `--append` adds next to them (deletes nothing, skips identical entries; handy for a second run later in the day), or `--replace-date` deletes and re-logs only **your own entries that clockout created** for those dates. Every entry clockout logs ends with `[clockout]` in its comment; time you logged by hand is never deleted, only reported. Teammates' entries are never touched. Hours are checked before anything is sent (> 0, ≤ 24 per day), comments are trimmed to OpenProject's 1000-character limit, and a failure part-way reports exactly what was written so a re-run with `--append` can finish the rest.
  142. #### Link commits to work packages
  143. References are found in commit messages, merge request titles/descriptions and branch names, and a commit inherits the references of the merge request it belongs to (so `Ref:` in the MR description is enough, even after squash or branch deletion):
  144. | You write | Linked to |
  145. |---|---|
  146. | `OP#42`, `op#42`, `OP #42`, `[OP#42]`, `Fixes OP#42`, `Refs OP#42` | work package 42 |
  147. | `Ref: Export ledger as CSV` | the work package with that name (asks if several match or none) |
  148. | branch `fix/OP-42-…` or OpenProject's **Git actions** branch `bug/42-…` | work package 42 |
  149. | GitLab's own branch `12-some-title`, `#12`, `!3` | nothing (those are GitLab numbers) |
  150. OpenProject's Git-actions "create branch" command makes an **empty** commit; clockout uses it for the link but doesn't count it as work.
  151. Mention the work package in a commit message, merge request title/description, or branch name, and clockout logs that work's time on it:
  152. ```
  153. Apply member discount once
  154. Ref: OP#42 ← by id (also works anywhere in the text, or as branch fix/OP-42-…)
  155. Ref: Export ledger as CSV ← by name (matched against the project's work packages)
  156. ```
  157. Set the destination to `work_package: from_refs` with `default_work_package: <id>` (a bucket such as *General development* for work without a reference) and the layout's `granularity: per_work_package`. Each day then becomes one time entry per work package. `OP#42` is also the syntax OpenProject's built-in **GitLab integration** uses: with its webhook configured, the MR and commits show up on the work package's GitLab tab. Override the patterns per project with `work_refs: {id_patterns: [...], name_patterns: [...]}`.
  158. Your user needs the **Log own time** permission in the project (the default *Member* role has it). Admin rights aren't needed.
  159. > **What about OpenProject's MCP server?** OpenProject 17 ships one, but it's an Enterprise feature and has no time-entry tools (work packages, projects, users, etc. only), so it can't log time. clockout writes time through the REST API instead, with preview, duplicate guard and replace. If your instance has the MCP enabled, Claude can still use it for lookups.
  160. ## Sources
  161. - **GitLab** (one or more instances): pushes, MRs opened/merged/approved, issues, comments and commit messages. You need a `read_api` token.
  162. - **Local git** (`git log`): every repo in your projects' `match.paths`, plus `sources.git.repos`.
  163. - **Meetings**: whatever you describe, stored per project.
  164. - **Google Calendar** (optional, `sources.calendar.enabled`): only useful if your calendar exposes event titles. Run `scripts/auth.py calendar`.
  165. ## Without Claude
  166. ```bash
  167. S=<path to clockout>/skills/clockout/scripts
  168. uv run --script $S/collect.py --date yesterday # activity routed per project (JSON)
  169. uv run --script $S/config.py detect # which project is this folder?
  170. uv run --script $S/export.py --entries entries.json --preview # exactly what each destination gets
  171. uv run --script $S/export.py --entries entries.json --dry-run # check against destinations, write nothing
  172. uv run --script $S/export.py --entries entries.json # each project → its destinations
  173. ```
  174. ## Adding a destination
  175. Destinations live in `skills/clockout/scripts/sinks/`. Each one is a module with `DESCRIPTION`, `REQUIRED` (config keys) and `export(entries, dest, layout, opts) -> str`; `check(dest)` is optional. Add the module and list it in `scripts/sinks/__init__.py`. Entries carry `project`, `refs` and `fields` as well as the layout columns. Tools that file time against projects or work items can use those fields, and drafting and layouts stay the same.
  176. ## Layout
  177. ```
  178. .claude-plugin/ plugin.json (name, version) + marketplace.json (this repo is its own marketplace)
  179. skills/clockout/
  180. SKILL.md what Claude follows (/clockout:clockout)
  181. scripts/config.py personal + project config, project detection, validation
  182. scripts/collect.py activity → routed per project (GitLab, git log, meetings, Calendar)
  183. scripts/layout.py entries → a project's columns and formats
  184. scripts/export.py entries → each project's destinations
  185. scripts/sinks/ clipboard, tsv, gsheet_webapp, gsheet_api, openproject
  186. scripts/op.py OpenProject lookups (work packages, activities, logged time)
  187. scripts/auth.py Google OAuth (gsheet_api / Calendar only)
  188. apps-script/Code.gs sheet-side writer for gsheet_webapp
  189. examples/ config.yaml, secrets.env, projects/*.yaml
  190. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.