<br><br>

<p align="center">
  <img src="assets/lockup-light.svg#gh-light-mode-only" alt="Clockify Agent Plugin" height="64">
  <img src="assets/lockup-dark.svg#gh-dark-mode-only" alt="Clockify Agent Plugin" height="64">
</p>

<br>

<p align="center">
  <img src="https://img.shields.io/badge/status-stable-C9A227?style=flat-square&labelColor=2A2A2A" alt="Stable">
  <img src="https://img.shields.io/badge/version-1.0.0-C9A227?style=flat-square&labelColor=2A2A2A" alt="1.0.0">
  <img src="https://img.shields.io/badge/stack-TypeScript%20%2F%20MCP-C9A227?style=flat-square&labelColor=2A2A2A" alt="TypeScript / MCP">
  <img src="https://img.shields.io/badge/license-MIT-C9A227?style=flat-square&labelColor=2A2A2A" alt="MIT">
</p>

<br>

---

Unofficial agent plugin for [Clockify](https://clockify.me): [MCP](https://modelcontextprotocol.io) tools plus Agent Skills — start/stop timers, enter time, and summarize sessions in Cursor and other MCP hosts.

**Not affiliated with, endorsed by, or sponsored by Clockify or Cake.com.** Third-party connector only.

---

<br>

## Features

| Feature                                 | Description                                                                                   | Documentation                                                |
|-----------------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| Easy Installation | Single user-scoped MCP server utilizing a single Clockify API key                           | [Config](docs/config.md)                                     |
| Granular Repo Integration | Initialize and configure on a per-repo basis      | [Config](docs/config.md)                                     |
| Easy Uninstallation  | Skills and scripts rollback changes with guards to prevent overreach or harm | [Use](docs/use.md) |
| Good Hygiene                     | Plugin artifacts are gitignored by default                                                | [Config: git hygiene](docs/config.md#git-hygiene)            |
| Three Time Entry Methods                | Running timer, explicit start/stop times, automated using workflow triggers               | [schema](docs/schema/config.yml.md)                          |
| IDE Layouts                          | Supports: single-window, multi-window, multi-root code workspace | [Config: which repo](docs/config.md#which-repo-config_root)  |
| Customize Time Entry                     | Configure nearest/up/down rounding, start/stop, increment, minimums, include seconds    | [schema: rounding](docs/schema/config.yml.md#rounding)       |
| Overlap guards                          | Handle overlapping time entries based on config                                 | [schema: overlap](docs/schema/config.yml.md#overlap)         |
| Init then Automate                      | `/clockify-init` pins workspace; `/clockify-automate` enables forge + Cursor Plan/Debug     | [Config: Init vs Automate](docs/config.md#init-vs-automate)  |
| Description templates                   | Tokenized strings (`{issue_number}`, `{label}`, …) or agent prompt                    | [schema: placeholders](docs/schema/config.yml.md#description-placeholders) |
| Timer Runaway Prevention  | Ask when a running timer exceeds a ceiling so Clockify is ready for automation            | [schema: runaway](docs/schema/config.yml.md#runaway)         |

---

<br>

## How it works

Two modes. Both use the same Clockify project for a given repo config (when automate has ensured one). Clockify still allows only **one running timer**. Product ladder: [Config: Init vs Automate](docs/config.md#init-vs-automate).

| Mode | How time gets in | Skills |
|------|------------------|--------|
| **Manual** | You (or the agent, when you ask) start/stop a timer or log a completed range | `/clockify-start-timer`, `clockify-stop-timer`, `/clockify-enter-time` |
| **Automated** | Agent follows Cursor rules from `entry.automated` (forge issue/PR triggers + optional Plan/Debug) | `/clockify-automate` on; `/clockify-automate-disable` pause (keep settings); `/clockify-unautomate` full rollback |

---

<br>

## Getting started

### Prerequisites

| Need | Why |
|------|-----|
| Node 18+ (npm / npx) | Install script and the MCP `npx` command |
| Cursor (or AI Agent/IDE) | Run skills and MCP |
| Clockify API key | MCP sevrver connection to Clockify |

If Cursor cannot find `node` / `npx`, see [troubleshoot](docs/troubleshoot.md#node-not-found). MCP process logs: [logging](docs/logging.md).

#### Additional Prerequisites

- [Develop Prerequisites](docs/develop.md#prerequisites)
- [Publish Prerequisites](docs/publish.md#prerequisites)

<br>

### Install the plugin (once per machine)

1. Create a Clockify API key (Preferences → Advanced → Manage API Keys).
2. Run **`npx -y -p @dustinestes/clockify-agent-plugin@latest clockify-install-cursor`** — installs skills + global MCP ([docs/install-cursor.md](docs/install-cursor.md)). Optional: Directory MCP button (MCP only; [caveats](docs/install-cursor.md#cursordirectory-optional)).
3. Reload Cursor; confirm **Customize → MCP** shows **clockify-agent-plugin** enabled.
4. Optional: [pre-allow Clockify MCP tools](docs/use.md#pre-enable-clockify-tools) so agents do not stall on an Allow / Always allow prompt mid-run.

Credentials, allowlists, and non-Cursor hosts: [docs/use.md](docs/use.md).

### Add Clockify to a repo (each repo)

1. In that repo, run `/clockify-init` — choose a Clockify workspace. Writes v3 `.clockify/config.yml` (prompt descriptions, timer starts without requiring a task; automation off). After this you can enter time with skills (start/stop timer, enter-time, summarize).
2. Optional: run `/clockify-automate` for forge (GitHub) + Cursor Plan/Debug + runaway, project/task ensure, Cursor rules, and runaway hooks when enabled.

To undo a repo without uninstalling the plugin: [docs/use.md](docs/use.md#remove-clockify-from-a-repo).

---

<br>

## Skills

You talk to the agent in plain language (or run a `/skill`). The agent calls MCP tools; you do not.

> Setup skills (`init`, `uninit`, `automate`, `automate-disable`, `automate-enable`, `unautomate`) are slash-only so they do not fire by accident.

| Group | Skill | Purpose | Example |
|-------|-------|---------|---------|
| Repo | [`clockify-init`](skills/clockify-init/SKILL.md) | Pin workspace; write v3 base config + ignore defaults (no project ensure) | `/clockify-init` |
| Repo | [`clockify-uninit`](skills/clockify-uninit/SKILL.md) | Full local teardown (keep plugin unless asked) | `/clockify-uninit` |
| Mode | [`clockify-automate`](skills/clockify-automate/SKILL.md) | Agent mode on: forge + Cursor Plan/Debug + runaway, ensure, rules, hooks when runaway enabled | `/clockify-automate` |
| Mode | [`clockify-automate-disable`](skills/clockify-automate-disable/SKILL.md) | Pause automate: remove rule/hooks; keep forge/triggers/modes (`enabled: false`) | `/clockify-automate-disable` |
| Mode | [`clockify-automate-enable`](skills/clockify-automate-enable/SKILL.md) | Resume after disable: flip flags on, rewrite rule/hooks from preserved settings | `/clockify-automate-enable` |
| Mode | [`clockify-unautomate`](skills/clockify-unautomate/SKILL.md) | Agent mode off: remove rule/hooks; reset `entry.automated` to example defaults | `/clockify-unautomate` |
| Timer | [`clockify-start-timer`](skills/clockify-start-timer/SKILL.md) | Start a running timer (`entry_method: timer`) | `/clockify-start-timer` or “start a timer on this issue” |
| Timer | [`clockify-stop-timer`](skills/clockify-stop-timer/SKILL.md) | Stop the running timer | `/clockify-stop-timer` or “stop my Clockify timer” |
| Timer | [`clockify-status`](skills/clockify-status/SKILL.md) | Read-only running timer (or none) | `/clockify-status` or “is a timer running?” |
| Time | [`clockify-enter-time`](skills/clockify-enter-time/SKILL.md) | Completed range, no rounding (`entry_method: manual`) | `/clockify-enter-time` or “log 2–3pm on this issue” |
| Review | [`clockify-summarize`](skills/clockify-summarize/SKILL.md) | Today / range totals | `/clockify-summarize` or “how much time today?” |

---

<br>

## Developing

Working on this repo: [docs/develop.md](docs/develop.md). Shipping a release or Directory listing: [docs/publish.md](docs/publish.md). How to contribute: [CONTRIBUTING.md](CONTRIBUTING.md).

---

<br>

<strong>Clockify Agent Plugin</strong>
<div align="right">

[MIT License](LICENSE)

</div>
<br clear="both">