{"_id":"clickup-flow","_rev":"5-a03f5d5abb2a77cb00e19e1f63e87017","name":"clickup-flow","dist-tags":{"latest":"1.3.3"},"versions":{"0.0.0-stage":{"name":"clickup-flow","version":"0.0.0-stage","_id":"clickup-flow@0.0.0-stage","stub":true,"maintainers":[{"name":"twahanur","email":"twahanur.rahman@gmail.com"}],"dist":{"shasum":"c3322fc5434c85c59a68b367864e0ad7c51f7b76","tarball":"https://registry.npmjs.org/clickup-flow/-/clickup-flow-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-+GDzN8bBTzc3Pm+lDM4Y6cmPFA7NtvfIhLg6IEr/W4Wt3fWxi9k7Q2w1ZYvtNo5A/8yUsxoeJlCrKNY21ySDKw==","signatures":[{"sig":"MEQCIGe3uyJ9zp1gDCC+Ofi+Eu/T04PZHGm1hMO235UgShjDAiBsda3GT3aJGpX0CwfsN3ikGaD5qPUbCYxQ/pziM0YZLg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":334},"_npmUser":{"name":"twahanur","email":"twahanur.rahman@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"1.3.0":{"name":"clickup-flow","version":"1.3.0","keywords":["clickup","cli","git-hooks","task-tracking","claude-code","clickup-cli","productivity","mcp","mcp-server","ai-agent","cursor"],"author":{"name":"Twahanur Rahman"},"license":"MIT","_id":"clickup-flow@1.3.0","maintainers":[{"name":"twahanur","email":"twahanur.rahman@gmail.com"}],"homepage":"https://github.com/twahanur/cu-clickup#readme","bugs":{"url":"https://github.com/twahanur/cu-clickup/issues"},"bin":{"cu":"bin/cu.js","clickup-flow":"bin/cu.js"},"dist":{"shasum":"f5f1587e6b7a9c4106b39377bfbff43a6d3c63c9","tarball":"https://registry.npmjs.org/clickup-flow/-/clickup-flow-1.3.0.tgz","fileCount":7,"integrity":"sha512-JycYIXvEObsjzU5aTH4OFejNG9l44v+N0CQIzVfhPfgGgZoleZ0gfrtKCo/+EF91hUWaMScHFF8Eqw0OaV7J1g==","signatures":[{"sig":"MEUCIGmDUo0AjdMDliOSml65Btpj1S8JCZ/hlVWELn/yYSxIAiEAxYmTlSuRQ5WZKbCwHJb940qDxiMAdl0hWTK9xgRS82o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQC49X32uo6p6wlYu3GuuO9XnJRguhciUQpN1QIZ8IRtHQIhALPH0o+J7GyZjkG+VBkaVpjk0i/pckMLH+MQnCDwUnw7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":116106},"type":"module","engines":{"node":">=18.17"},"gitHead":"3f24fc4f9e25de53ce2492df3407d02f30396936","scripts":{"test":"node scripts/test.js","build:skill":"node scripts/build-skill.js"},"_npmUser":{"name":"twahanur","email":"twahanur.rahman@gmail.com"},"cuInstall":"clickup-flow","repository":{"url":"git+https://github.com/twahanur/cu-clickup.git","type":"git"},"_npmVersion":"10.9.8","description":"Keep ClickUp in sync from your terminal, git and AI agents (Claude Code, Cursor, MCP): plan the day, start/finish tasks, log every commit, see who works on what.","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/clickup-flow_1.3.0_1793877190798_0.4162585159867793","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"clickup-flow","version":"1.3.1","keywords":["clickup","cli","git-hooks","task-tracking","claude-code","clickup-cli","productivity","mcp","mcp-server","ai-agent","cursor"],"author":{"name":"Twahanur Rahman"},"license":"MIT","_id":"clickup-flow@1.3.1","maintainers":[{"name":"twahanur","email":"twahanur.rahman@gmail.com"}],"homepage":"https://github.com/twahanur/cu-clickup#readme","bugs":{"url":"https://github.com/twahanur/cu-clickup/issues"},"bin":{"cu":"bin/cu.js","clickup-flow":"bin/cu.js"},"dist":{"shasum":"bc298ee7b984a7bc4a6786cc767cc91c3ee747bd","tarball":"https://registry.npmjs.org/clickup-flow/-/clickup-flow-1.3.1.tgz","fileCount":7,"integrity":"sha512-GI2paUBHUfYtOr09Sz0A2EJY59mbQEmYkgNo9DjoytlgIiKOrSSSBrdlUaCvIJWG6HjL7jhzZQsybpPzX9gVPg==","signatures":[{"sig":"MEQCIDGmoDw2/+SAgTDDipTzdg3ecFmcKPrO/rfZcpGKlRU2AiA3kfiUleFJEkqJxUAsule3CHy1B0ZvPKEwgqWboAmnRw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQC1KG7BDbIDi1Poe/jRx1meS/vwdNGRcOur2deOPK9V4QIhAOKEOjpdKSvaProFfg6pXEO9if742xDSRqgWmkIsRhgB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":116188},"type":"module","engines":{"node":">=18.17"},"gitHead":"d0f497e1a937002e47e6873f94a389599ead6c47","scripts":{"test":"node scripts/test.js","build:skill":"node scripts/build-skill.js"},"_npmUser":{"name":"twahanur","email":"twahanur.rahman@gmail.com"},"cuInstall":"clickup-flow","repository":{"url":"git+https://github.com/twahanur/cu-clickup.git","type":"git"},"_npmVersion":"10.9.8","description":"Keep ClickUp in sync from your terminal, git and AI agents (Claude Code, Cursor, MCP): plan the day, start/finish tasks, log every commit, see who works on what.","directories":{},"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/clickup-flow_1.3.1_1793877682436_0.5385146771213992","host":"s3://npm-registry-packages-npm-production"}},"1.3.2":{"name":"clickup-flow","version":"1.3.2","keywords":["clickup","cli","git-hooks","task-tracking","claude-code","clickup-cli","productivity","mcp","mcp-server","ai-agent","cursor"],"author":{"name":"Twahanur Rahman"},"license":"MIT","_id":"clickup-flow@1.3.2","maintainers":[{"name":"twahanur","email":"twahanur.rahman@gmail.com"}],"homepage":"https://github.com/twahanur/cu-clickup#readme","bugs":{"url":"https://github.com/twahanur/cu-clickup/issues"},"bin":{"cu":"bin/cu.js","clickup-flow":"bin/cu.js"},"dist":{"shasum":"deeeab9a27cca6a58909dff6187d724e925935ed","tarball":"https://registry.npmjs.org/clickup-flow/-/clickup-flow-1.3.2.tgz","fileCount":7,"integrity":"sha512-XMFm17yl/jpyZPJLdnZ3dsFEjRY1JSAau2gCEwL5GnmFZpgvxXT8r35V+a1hfnJMbwxzvcs1VXHVlIxhuOqM2g==","signatures":[{"sig":"MEUCIQCSTYuiYEul8A0Qv3uBk5/KqBFyucHZwujt3vR3VYnSMgIgKni20nOrrHxxiQkpEPW52Op4l2BmJdeRA4J2+RncfqE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQDvmPuom2oI7MTQCxg2CAPSM4bkpnmcEw+0vpxsBjgzJAIhALEuQBJxkMp4Mp4j2Sd8fbrnLTb1DXMfofgDuBe1pQ2G","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/clickup-flow@1.3.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":116790},"type":"module","engines":{"node":">=18.17"},"gitHead":"1a1516833efdc6d72d224186d8632c13e8ca9639","scripts":{"test":"node scripts/test.js","build:skill":"node scripts/build-skill.js"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"a3603a3f-4021-4e31-95f1-d4f95e55f554"}},"cuInstall":"clickup-flow","repository":{"url":"git+https://github.com/twahanur/cu-clickup.git","type":"git"},"_npmVersion":"11.21.2","description":"Keep ClickUp in sync from your terminal, git and AI agents (Claude Code, Cursor, MCP): plan the day, start/finish tasks, log every commit, see who works on what.","directories":{},"_nodeVersion":"24.22.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/clickup-flow_1.3.2_1793941493440_0.39674405592505646","host":"s3://npm-registry-packages-npm-production"}},"1.3.3":{"_id":"clickup-flow@1.3.3","bin":{"cu":"bin/cu.js","clickup-flow":"bin/cu.js"},"bugs":{"url":"https://github.com/twahanur/cu-clickup/issues"},"dist":{"shasum":"747916fce38f70d0c5c2f08d9ad3fa0380882934","tarball":"https://registry.npmjs.org/clickup-flow/-/clickup-flow-1.3.3.tgz","fileCount":7,"integrity":"sha512-/3rikWx2+9soEPRknhbmLPYA1OR495jwXaCy/wMZAcX1F4j6+wFM5JdYbkDOuXi/sJpHeKJH+i7KLzB0ykhroQ==","signatures":[{"sig":"MEQCIAz5AScu2m4xwI3uG4HWUUg88kOv1BOZPyj+M2lqZ1fWAiAwU/VhzDFo21JljgiaDWHzNv+jimdEMv0Anq6nllYP3w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGjgmZykz7bpTGIWy0gEW/1OEld0aAIRdSrmhiIyF2d+AiEA9WBWKVZyAqOqxoPpzC1b8TabD7apiwIZo4cVsYfDijY="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/clickup-flow@1.3.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":117246},"name":"clickup-flow","type":"module","author":{"name":"Twahanur Rahman"},"engines":{"node":">=18.17"},"gitHead":"72a16f3186bec5d923da43ce9c4c5e278a377202","license":"MIT","scripts":{"test":"node scripts/test.js","build:skill":"node scripts/build-skill.js"},"version":"1.3.3","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"a3603a3f-4021-4e31-95f1-d4f95e55f554"}},"homepage":"https://github.com/twahanur/cu-clickup#readme","keywords":["clickup","cli","git-hooks","task-tracking","claude-code","clickup-cli","productivity","mcp","mcp-server","ai-agent","cursor"],"cuInstall":"clickup-flow","repository":{"url":"git+https://github.com/twahanur/cu-clickup.git","type":"git"},"_npmVersion":"11.21.2","description":"Keep ClickUp in sync from your terminal, git and AI agents (Claude Code, Cursor, MCP): plan the day, start/finish tasks, log every commit, see who works on what.","directories":{},"maintainers":[{"name":"twahanur","email":"twahanur.rahman@gmail.com"}],"_nodeVersion":"24.22.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/clickup-flow_1.3.3_1793973098311_0.3408137033167479"}}},"time":{"created":"2026-11-05T11:11:53.622Z","modified":"2026-11-06T13:51:38.870Z","0.0.0-stage":"2026-11-05T11:11:53.622Z","1.3.0":"2026-11-05T11:13:10.890Z","1.3.1":"2026-11-05T11:21:22.525Z","1.3.2":"2026-11-06T05:04:53.537Z","1.3.3":"2026-11-06T13:51:38.419Z"},"bugs":{"url":"https://github.com/twahanur/cu-clickup/issues"},"author":{"name":"Twahanur Rahman"},"license":"MIT","homepage":"https://github.com/twahanur/cu-clickup#readme","keywords":["clickup","cli","git-hooks","task-tracking","claude-code","clickup-cli","productivity","mcp","mcp-server","ai-agent","cursor"],"repository":{"url":"git+https://github.com/twahanur/cu-clickup.git","type":"git"},"description":"Keep ClickUp in sync from your terminal, git and AI agents (Claude Code, Cursor, MCP): plan the day, start/finish tasks, log every commit, see who works on what.","maintainers":[{"name":"twahanur","email":"twahanur.rahman@gmail.com"}],"readme":"<div align=\"center\">\n\n# clickup-flow\n\n**ClickUp from your terminal and git.** Install with `npx clickup-flow`, then use the `cu` command.\n\nPlan the day, start and finish tasks, and log every commit on the task you are working on,\nwithout leaving the terminal and without defining tasks in advance.\n\n[![npm](https://img.shields.io/npm/v/clickup-flow.svg)](https://www.npmjs.com/package/clickup-flow)\n[![Tests](https://github.com/twahanur/cu-clickup/actions/workflows/test.yml/badge.svg)](https://github.com/twahanur/cu-clickup/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen.svg)](https://nodejs.org)\n[![Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](package.json)\n\n</div>\n\n---\n\n## Why\n\nTask boards drift out of date because updating them is a separate chore. `cu` makes the update a side effect of\nthe work you already do:\n\n- **You commit, ClickUp knows.** A git hook posts each commit to the task you are working on.\n- **Nothing to set up in advance.** `cu start \"fix login redirect\"` finds the task or creates it.\n- **The board shows who does what.** Every developer gets a personal list in the space, and `cu team` prints\n  who is working on what right now.\n- **Your AI does it for you.** Claude Code, Cursor, Codex, Copilot, Windsurf or any MCP client can drive `cu`: tell\n  it what you will work on today and it keeps ClickUp in sync while it codes.\n\n## Features\n\n- Daily flow in four commands: `today`, `start`, `finish`, `block`\n- `cu start` with no arguments opens a picker of your open tasks\n- Due dates and priorities in plain words: `--due fri --priority high`\n- ClickUp time tracking that starts and stops with your tasks\n- Automatic commit logging through git hooks that never block a commit\n- A `CU-<id>` line added to each commit message, so ClickUp's own GitHub integration links the commit too\n- Hand a task over to a teammate with a note: `cu handoff sara \"API done, UI left\"`\n- A daily report built from what you did, printed or posted to Slack or ClickUp\n- An optional GitHub Action that moves tasks to done when their pull request is merged\n- One ClickUp space per repo, so several projects can run side by side\n- Status names matched to each space (`to do`, `complete`, and so on)\n- Offline queue: commit logs made without a network are sent later\n- A single catch-all task per day for commits made without a current task, so tiny tasks do not pile up\n- Works with AI agents: rules for every agent, a Claude Code plugin, and an MCP server\n- Token in a file or in the system keychain (macOS Keychain, Linux Secret Service)\n- Nothing is written to your repository's tracked files unless you ask for the GitHub Action\n- Zero runtime dependencies. Needs Node 18.17 or later and git.\n\n## Get started\n\nOpen a terminal in your project and run **one command**:\n\n```bash\nnpx clickup-flow\n```\n\nA short guided setup follows. It takes about a minute:\n\n```\n👋 cu setup for my-app\n\nStep 1 of 2 · ClickUp token\n  Open that page in your browser now? [Y/n]           ← opens ClickUp → Settings → Apps\n  Paste the token (starts with pk_, it will not be shown):\n  Keep the token in your system keychain (safer than a file)? [Y/n]\n  ✔ signed in as Jane Doe\n\nStep 2 of 2 · Which ClickUp space is my-app tracked in?\n   1) Marketing\n   2) Product\n  Type a number: 2\n  ✔ space: Product\n  ✔ your list: 👤 Jane Doe (your new tasks go here)\n  ✔ git hooks on in my-app\n\nInstall the `cu` command permanently? [Y/n]\n\n🎉 All set: commits in my-app are now logged in ClickUp.\n```\n\nThe keychain question only appears when a system keychain is available. That's it. For your next project, open it\nand run `cu setup` (or just `cu`). The token is remembered, so only the space question is asked.\n\n<details>\n<summary>Other ways to install</summary>\n\n```bash\nnpm i -g clickup-flow                    # install the `cu` command first\ncd path/to/your-repo && cu setup   # then link each repo\n```\n\nLatest code from GitHub: `npm i -g github:twahanur/cu-clickup`.\n\nWithout a terminal prompt (scripts, CI): `cu setup --token pk_... --space \"Product\"`.\n\n</details>\n\n**Something not working?** Run `cu doctor`. It checks Node, git, your token, the repo link and the hooks, and\nprints the fix for anything that is wrong.\n\n**What setup changes:** your token goes to the system keychain or to `~/.config/clickup/token` (readable only by\nyou), the repo gets local git settings and hooks, and a git-ignored `CLAUDE.local.md` is written for Claude Code.\nNothing is committed.\n\n**Tab completion.** Add one line to your shell's startup file yourself:\n\n```bash\neval \"$(cu completion bash)\"     # ~/.bashrc\neval \"$(cu completion zsh)\"      # ~/.zshrc\ncu completion fish | source      # ~/.config/fish/config.fish\n```\n\n### Your first day\n\n```bash\ncu today \"Login page\" \"Password reset email\" --due fri   # plan the day: two tasks in todo\ncu start \"Login page\"                           # in progress, now the current task, timer running\ngit commit -m \"feat(auth): login form\"          # logged on \"Login page\", message gets CU-<id>\ncu comment \"Form done, validation left\"         # progress note\ncu finish \"Login page with validation\"          # summary, then in review, timer stopped\ncu report --slack                               # what you did today, posted to Slack\n```\n\n## Commands\n\n### Daily flow\n\n| Command | Effect in ClickUp |\n|---|---|\n| `cu today \"<title>\" [\"<title>\" ...] [--list L] [--due D] [--priority P]` | Creates each title as a task in **todo** |\n| `cu start [<ref \\| \"new title\">] [--list L] [--parent REF] [--due D] [--priority P]` | Moves to **in progress**, makes it the current task and starts the timer. Creates it if nothing matches. With no argument, opens a picker |\n| `cu comment [<ref>] \"<text>\"` | Comments on the current task, or on `<ref>` |\n| `cu pause` | Stops the timer. The status and the current task stay as they are. `cu start .` resumes |\n| `cu finish [\"<summary>\"]` | Comments the summary, moves to **in review**, stops the timer, clears the current task |\n| `cu block \"<reason>\"` | Moves the current task to **blocked** with a comment and stops the timer |\n| `cu handoff <person> [\"<note>\"] [--task REF]` | Assigns the current task (or `REF`) to a teammate, removes you, and comments the note. Stops the timer if it was your current task |\n| `cu report [--date YYYY-MM-DD] [--slack] [--clickup]` | Prints your daily report. `--slack` posts it to your Slack webhook, `--clickup` on the day's catch-all task |\n\n**Picking a task.** `cu start` with no arguments lists your open tasks, in progress first, then todo, blocked and\nin review. Type to filter, move with the arrow keys, press Enter to start one or Esc to cancel. The last entry,\n\"＋ a new task…\", asks for a title and creates it.\n\n**Due dates and priorities.** `--due` accepts `today`, `tomorrow`, a weekday (`mon` to `sun`, the next one to\ncome), `+3d`, `+1w` or `YYYY-MM-DD`. `--priority` accepts `urgent`, `high`, `normal` or `low`. Both work on\n`cu today`, `cu add` and on `cu start` when it creates a new task.\n\n**Handing over.** `<person>` is part of a teammate's ClickUp name, or the part of their email before the `@`. If\nseveral people match, `cu` lists them.\n\n**Daily report.** `cu` keeps a short local diary of what you started, finished, blocked, handed over, planned and\ncommitted. `cu report` builds the day's report from it, without asking ClickUp. The diary stays on your machine\nfor 14 days and is only sent when you pass `--slack` or `--clickup`. Set the Slack webhook once with\n`cu config slack_webhook https://hooks.slack.com/services/...`.\n\n### Overview\n\n| Command | Shows |\n|---|---|\n| `cu team` | Everyone's tasks that are in progress, blocked or in review in this space |\n| `cu mine [--all]` | Your open tasks in this space. The current task is marked `▶` |\n| `cu current` | The current task |\n| `cu show <ref>` | One task: status, assignees, list, link |\n| `cu where` | Which workspace and space this folder is linked to |\n| `cu lists` / `cu statuses` | Lists and statuses of the space |\n\n### Other\n\n| Command | Effect |\n|---|---|\n| `cu setup` (or just `cu`) | Guided setup: token, space, hooks. Rerun to switch space. Flags: `--space <name>`, `--token pk_...` |\n| `cu doctor` | Checks everything and prints the fix for each problem |\n| `cu config [<name> [<value>]]` | Shows all settings, one setting, or changes one. See [Configuration](#configuration) |\n| `cu add \"<title>\" [--list L] [--parent REF] [--desc D] [--due D] [--priority P]` | Creates one task in **todo**, or a subtask with `--parent` |\n| `cu status <ref> <status>` | Sets any status of the space |\n| `cu pr [<ref>] <url>` | Fills a PR link field if the list has one, then moves to **in review** |\n| `cu bug \"<title>\" [\"<details>\"]` | Creates a bug in the space's bug list, or in your own list |\n| `cu tasks [file]` | Writes all your tasks in the space as a Markdown checklist |\n| `cu github-action [--force]` | Writes a GitHub workflow that moves tasks to done when their pull request is merged |\n| `cu completion bash \\| zsh \\| fish` | Prints a tab completion script for your shell |\n| `cu agents` | Connects your AI tools (Cursor MCP, Claude Code plugin) and prints MCP config for others |\n| `cu mcp` | Runs the MCP server. AI tools start this themselves |\n| `cu version` | Prints the version |\n\n### Task references\n\nA `<ref>` can be:\n\n- a ClickUp task id: `86ex1abcd`\n- the same id with a prefix: `CU-86ex1abcd`\n- `.` for the current task\n- any part of the name of one of your open tasks: `\"login page\"`. If several tasks match, `cu` lists them.\n\n### Merged pull requests\n\n`cu github-action` writes `.github/workflows/clickup-flow-merged.yml`. When a pull request is merged, the workflow finds\nevery `CU-<id>` in its title, body, branch name and commits, moves those tasks to **done** and comments the PR\nlink on each. Commits made with `cu` already carry their `CU-<id>`.\n\nThis file is for the whole team, so unlike everything else `cu` writes, it is meant to be committed. After you\npush it, once per repository:\n\n```bash\ngh secret set CLICKUP_API_TOKEN                     # a ClickUp token that may edit the tasks\ngh variable set CLICKUP_DONE_STATUS --body \"qa\"     # optional: another status than \"done\"\n```\n\nWithout the secret, the workflow skips itself. `cu github-action` asks before replacing an existing file; pass\n`--force` to replace it without asking.\n\n## How it works\n\n```\ncu start \"Login page\"   ─────►  task \"Login page\" → in progress, saved as current, timer started\ngit commit              ─────►  prepare-commit-msg hook ─► adds CU-<id> of the current task to the message\n                        ─────►  post-commit hook ─► comment on the current task\n                                 │\n                                 ├─ message contains CU-<id>  → that task instead\n                                 ├─ no current task          → today's catch-all task\n                                 └─ offline                  → queued, sent later\ncu finish \"summary\"     ─────►  comment + in review, timer stopped, current cleared\n```\n\n**Statuses.** `cu` reads the statuses of each space and maps `todo`, `in progress`, `in review`, `blocked` and\n`done` to the space's own names. A space with `to do / in progress / complete` works without configuration. If a\nspace has no matching status, for example no `blocked`, the status is left alone and only the comment is added.\n\n**Current task.** There is one current task per space, shared by every repo linked to that space on your machine.\n\n**Commit messages.** While you have a current task, each commit message gets a last line `CU-<id>` with that\ntask's id. ClickUp's own GitHub integration uses the same line to link the commit to the task, and\n`cu github-action` uses it on merge. The line is not added when the message already names a task, for merge and\nsquash commits, for `git commit --amend`, or when there is no current task. Turn it off with\n`cu config commit_tag off`.\n\n**Commits without a task.** These go to one catch-all task per day, named `🗒 <Name>: Other work <date>`, so a\nforgotten `cu start` does not create a new task for every commit. With `cu config lang bn` the name is\n`🗒 <Name>: অন্যান্য কাজ <date>`.\n\n**Amend and rebase.** An amended, rebased or cherry-picked commit is not logged again: the original was logged\nalready.\n\n**Time tracking.** `cu start` starts the ClickUp timer on the task, after stopping any timer that was running.\n`cu finish`, `cu block` and `cu handoff` stop it, and `cu pause` stops it without changing anything else. A timer\nerror is printed as one line and never fails the command. Turn it off with `cu config timer off`.\n\n**Branches.** Creating a branch whose name contains `CU-<id>`, for example\n`git checkout -b feat/CU-86ex1abcd-login`, starts that task. Checking out a colleague's existing branch changes\nnothing.\n\n**Offline.** If ClickUp cannot be reached, the commit still succeeds and its log is saved to\n`~/.config/clickup/queue.json`. The next commit or `cu` command sends it, with the time it was saved.\n\n**Rate limit.** ClickUp allows about 100 requests a minute per token. When it says to slow down, `cu` waits and\nretries on its own (up to 30 seconds, with a one-line notice). Inside a git hook it waits at most a few seconds;\nafter that the commit log is queued like an offline one, so git is never held up.\n\n**Hooks never block git.** Any error inside a hook is printed as one line and the commit or checkout goes through.\n\n**Updates.** Once a day, in a terminal, `cu` checks whether a newer clickup-flow is published on npm and prints one line\nif so. The check takes at most 1.5 seconds, never runs in hooks or CI, and can be turned off with\n`cu config update_check off`.\n\n## Use it with AI agents\n\nMost of us code with an AI now, so `cu` is built to be driven by one. Tell your agent what you will work on today\nand it plans the tasks, starts the right one before writing code, posts progress, and finishes it with a summary.\nYou never type a `cu` command unless you want to.\n\nThere are three ways an agent learns about `cu`. `cu setup` sets up the first one for you and offers the others.\n\n**1. Rules in the repo (every agent).** `cu setup` writes the same short instructions for each agent, all kept out\nof git:\n\n| Agent | File |\n|---|---|\n| Claude Code | `CLAUDE.local.md` |\n| Cursor | `.cursor/rules/clickup-flow.mdc` |\n| Codex, GitHub Copilot, Windsurf and other `AGENTS.md` readers | `AGENTS.md` (skipped if your repo already tracks one) |\n\n**2. Claude Code plugin.** It adds a `clickup` skill, the MCP tools below, and a session hook that tells Claude which\ntask is current when a session starts. Run this once inside Claude Code:\n\n```\n/plugin install clickup-flow --marketplace twahanur/cu-clickup\n```\n\nOn older Claude Code versions: `/plugin marketplace add twahanur/cu-clickup`, then `/plugin install clickup-flow@clickup-flow`.\n\n**3. MCP server (Cursor, Claude Desktop, Windsurf, VS Code and any MCP client).** Your agent calls ClickUp tools\ndirectly instead of typing commands. `cu agents` adds it to Cursor for you and prints the config for other clients:\n\n```json\n{ \"mcpServers\": { \"clickup-flow\": { \"command\": \"npx\", \"args\": [\"-y\", \"clickup-flow\", \"mcp\"] } } }\n```\n\n| Tool | Does |\n|---|---|\n| `clickup_plan_day` | Creates today's tasks in todo, with optional due date and priority |\n| `clickup_start_task` | Finds or creates a task, moves it to in progress, makes it current, starts the timer |\n| `clickup_comment` | Posts a progress note |\n| `clickup_pause_timer` | Stops the timer, keeps the status and the current task |\n| `clickup_finish_task` | Posts a summary, moves to in review |\n| `clickup_block_task` | Moves to blocked with the reason |\n| `clickup_handoff` | Reassigns a task to a teammate with a note |\n| `clickup_pr` | Links a pull request, moves to in review |\n| `clickup_set_status` | Sets any status |\n| `clickup_add_task` / `clickup_report_bug` | Creates a task, subtask or bug. Tasks take an optional due date and priority |\n| `clickup_daily_report` | Returns the day's report |\n| `clickup_my_tasks` / `clickup_team` / `clickup_show_task` / `clickup_where` | Reads: your tasks, who does what, one task, setup |\n\nEach tool takes an optional `repo_path` for agents that work across several projects.\n\n**What agents do on their own.** They change only your own tasks, tell you in one line what they changed, never mark\na task done until you confirm it is merged and tested, and ask you to run `npx clickup-flow` if a repo is not set up yet.\nThe token never reaches the agent: the tools run locally with the token on your machine.\n\n## Configuration\n\nSettings are changed with `cu config`. `cu config` alone lists them with their current values, `cu config <name>`\nprints one, and `cu config <name> <value>` changes it.\n\n| Setting | Values | Default | Effect |\n|---|---|---|---|\n| `lang` | `en`, `bn` | `en` | Language of the names and reports `cu` writes: the catch-all task and `cu report` |\n| `timer` | `on`, `off` | `on` | Start and stop ClickUp time tracking with `cu start`, `pause`, `finish`, `block`, `handoff` |\n| `commit_tag` | `on`, `off` | `on` | Add `CU-<id>` of the current task to commit messages |\n| `update_check` | `on`, `off` | `on` | Say once a day when a newer clickup-flow is published |\n| `slack_webhook` | a `https://hooks.slack.com/services/...` URL, or `off` | not set | Where `cu report --slack` posts |\n| `token_store` | `file`, `keychain` | `file` | Where the token is kept. Changing it moves the token |\n\nEverything lives in `~/.config/clickup/`:\n\n| File | Contents |\n|---|---|\n| `token` | Your ClickUp API token (mode `600`). Absent when the token is in the keychain |\n| `config.json` | Default space, your personal list per space, and your settings |\n| `state.json` | Current task and today's catch-all task per space, the local diary for `cu report` (14 days), the last update check |\n| `queue.json` | Commit logs waiting to be sent |\n| `hooks/` | The git hook scripts used by linked repos |\n\nEach linked repository gets only local git settings (`clickup.space`, `clickup.workspace`, `clickup.spacename`,\n`core.hooksPath`) and the git-ignored agent rule files listed above.\n\n| Environment variable | Purpose |\n|---|---|\n| `CLICKUP_API_TOKEN` | Use this token instead of the saved one |\n| `CU_CONFIG_DIR` | Use another folder instead of `~/.config/clickup` |\n\n## Security and privacy\n\n- **Your token stays on your machine.** It is kept either in the system keychain (macOS Keychain, or the Linux\n  Secret Service through `secret-tool`) or in `~/.config/clickup/token`. Setup offers the keychain when one is\n  available, and `cu config token_store keychain` or `cu config token_store file` moves the token later. The\n  config folder is `700` and every file in it is `600`, so other users on the computer cannot read your token,\n  tasks or commit messages.\n- **The token is never on a command line.** When it goes into or out of the keychain, it is passed to `security`\n  or `secret-tool` through standard input, so it does not show up in the process list.\n- **The token is only sent to `api.clickup.com`.** No other server ever receives it. The test-only\n  `CU_API_BASE` override is refused unless it points to `localhost`, so a hostile environment variable cannot\n  redirect the token. The token is never passed on to other programs that `cu` starts, such as `npm` or the browser.\n  The Slack webhook receives only the report text, and only when you pass `--slack`.\n- **The prompt hides the token.** `cu setup --token pk_...` also works, but the value then stays in your shell\n  history. Prefer the prompt.\n- **Nothing is committed.** Repos get local git settings and a `CLAUDE.local.md` listed in `.git/info/exclude`. If a\n  repo ships `CLAUDE.local.md` as a symlink, `cu` refuses to write through it. The only exception is the workflow\n  that `cu github-action` writes when you ask for it. It reads the token from a repository secret, never from your\n  machine.\n- **Hooks are plain, quoted shell scripts** in `~/.config/clickup/hooks/`. You can read them. They never block a\n  commit.\n- **Only your own work is touched.** Tasks are created for you and assigned to you. Name matching only searches\n  your own tasks. Another person's task changes only when you pass its id yourself.\n- **Quiet comments.** Commit logs are posted with `notify_all: false`, so they do not notify the whole team.\n- **No dependencies and no install scripts.** The package is a single readable file, [`lib/cu.js`](lib/cu.js).\n\nFound a security problem? See [SECURITY.md](SECURITY.md).\n\n## Troubleshooting\n\n| Problem | Fix |\n|---|---|\n| Not sure what is wrong | `cu doctor` |\n| `cu: command not found` | `npm i -g clickup-flow`, and make sure `$(npm prefix -g)/bin` is on your `PATH` |\n| `... is not linked to a ClickUp space yet` | Answer **Y** when `cu` offers to set it up, or run `cu setup` |\n| `ClickUp did not accept that token` | Copy a fresh token and run `cu setup` again |\n| Commits are not logged | Run `cu setup` in the repo, then check `git config core.hooksPath` |\n| `could not read the ClickUp token from the system keychain (locked?)` | Unlock the keychain. Commit logs made meanwhile are queued and sent by the next `cu` command. To stop using it: `cu config token_store file` |\n| `(timer not started: ...)` | Time tracking may be off in your ClickUp workspace. Run `cu config timer off` |\n| `ClickUp rate limit: waiting ...` | Normal under heavy use. `cu` retries by itself |\n| `This space has no \"blocked\" status` | Expected for spaces without that status. See `cu statuses` |\n| Tab completion does not work | Add the `cu completion` line for your shell to its startup file, then open a new terminal |\n\n## Uninstall\n\n```bash\ncu config token_store file   # first, if the token is in the keychain (or delete the \"clickup-flow\" keychain item)\n\n# in each linked repo\ngit config --unset core.hooksPath   # turns off all cu hooks, including prepare-commit-msg\ngit config --unset clickup.space\ngit config --unset clickup.workspace\ngit config --unset clickup.spacename\nrm -f CLAUDE.local.md .cursor/rules/clickup-flow.mdc   # or remove only the \"clickup-flow\" section\n# AGENTS.md: remove the section between <!-- clickup-flow:start --> and <!-- clickup-flow:end -->\n# .github/workflows/clickup-flow-merged.yml: delete it if you added it with cu github-action\n\nnpm uninstall -g clickup-flow\nrm -rf ~/.config/clickup\n# Cursor: remove \"clickup-flow\" from ~/.cursor/mcp.json · Claude Code: /plugin uninstall clickup-flow\n```\n\nIf `cu` is already gone, delete the keychain item yourself: `security delete-generic-password -s clickup-flow -a clickup`\non macOS, or `secret-tool clear service clickup-flow account clickup` on Linux.\n\n## Development\n\n```bash\ngit clone https://github.com/twahanur/cu-clickup.git\ncd cu-clickup\nnpm test          # unit tests, no network\nnpm link          # use your working copy as the global `cu`\n```\n\nThe tests also run on GitHub Actions for every push to `main` and every pull request (the Tests badge above).\n\nThe code is a single module, [`lib/cu.js`](lib/cu.js), with no dependencies.\nIssues and pull requests are welcome.\n\n## License\n\n[MIT](LICENSE) © Twahanur Rahman\n","readmeFilename":"README.md"}