Skip to content
Back to search

ctask

MarketplaceWorks with Claude CodeGitHub

Persistent task engine for Claude Code: tasks, steps, reminders and automations across sessions and projects, with hooks that keep Claude using it

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/omarabulkhair-66--ctask/badge.svg)](/listings/omarabulkhair-66--ctask)

HTML

<a href="/listings/omarabulkhair-66--ctask"><img src="/api/listings/omarabulkhair-66--ctask/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.

**Requirements**

- [Claude Code](https://claude.com/claude-code), CLI or desktop app - Node.js 24 or newer. There are no npm dependencies. - macOS for notifications and the background checker. Linux has not been tested.

**Install the plugin**

claude plugin marketplace add omarabulkhair-66/ctask
claude plugin install ctask@ctask

Or, inside Claude Code: `/plugin marketplace add omarabulkhair-66/ctask`, then `/plugin install ctask@ctask`.

Start a new session. There is nothing else to set up: the plugin loads its hooks and skill, puts `ctask` on the session's PATH, and installs its own background checker.

**Update**

claude plugin marketplace update ctask
claude plugin update ctask@ctask

**Uninstall**

ctask daemon uninstall
claude plugin uninstall ctask@ctask

Your data stays in `~/.ctask` until you delete that folder.

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 · 13 lines
  1. {
  2. "name": "ctask",
  3. "owner": {
  4. "name": "omarabulkhair-66"
  5. },
  6. "plugins": [
  7. {
  8. "name": "ctask",
  9. "source": "./",
  10. "description": "Persistent task engine for Claude Code with enforcing hooks, a skill and an MCP server"
  11. }
  12. ]
  13. }
README.md · README · 487 lines
  1. # ctask
  2. **A task engine and memory for Claude Code.** Tasks, reminders, automations and project knowledge that survive sessions and span every project on your machine, with hooks that make Claude actually use them.
  3. Claude's built-in task list disappears when the conversation ends. With ctask, you open a new session next week and Claude already knows what is due, what it was in the middle of, what it tried that failed, and the rules of the project.
  4. ```text
  5. You: remind me tomorrow at 9 to send the invoice, and let's start the CSV importer
  6. Claude: [creates a reminder, creates a task with steps, starts the first step]
  7. ...next day, new session...
  8. Claude: Reminder: send the invoice. The importer is at step 2 of 4; the parser is done,
  9. streaming failed on Windows paths, next is wiring the tests.
  10. ```
  11. It is not a Jira or Linear replacement. It is Claude's own working memory: the step it is on, the follow-up it promised, the reminder you asked for, the job it runs every morning.
  12. ## Contents
  13. - [What you get](#what-you-get)
  14. - [Install](#install)
  15. - [Quick start](#quick-start)
  16. - [How it works](#how-it-works)
  17. - [Features](#features)
  18. - [Tasks and steps](#tasks-and-steps)
  19. - [Reminders](#reminders)
  20. - [Automations](#automations)
  21. - [Handoff notes](#handoff-notes)
  22. - [Project memory](#project-memory)
  23. - [Stats and the call log](#what-ctask-is-doing-stats-and-the-call-log)
  24. - [Evidence before done](#evidence-before-done)
  25. - [Dependencies and parallel sessions](#dependencies-and-parallel-sessions)
  26. - [Code links](#code-links)
  27. - [Playbooks](#playbooks)
  28. - [Review](#review)
  29. - [Search, paging and archive](#search-paging-and-archive)
  30. - [Command reference](#command-reference)
  31. - [Background checker](#background-checker)
  32. - [Configuration](#configuration)
  33. - [Data and privacy](#data-and-privacy)
  34. - [Troubleshooting](#troubleshooting)
  35. - [Development](#development)
  36. ## What you get
  37. | | |
  38. | --- | --- |
  39. | **Persistent tasks** | Every task keeps its project, owning session, body, instructions, status, due time and a log. |
  40. | **Works across projects** | One local database. Ask "what is open everywhere?" from any project. |
  41. | **Reminders** | A macOS notification when something is due, and Claude raises it in the chat. |
  42. | **Automations** | Recurring work that runs unattended in a headless Claude session. |
  43. | **Handoff notes** | Where a session stood is saved before its context is compacted or it ends. |
  44. | **Project memory** | Rules, preferences, decisions and gotchas that Claude edits over time and recalls when relevant. |
  45. | **Stats and call log** | See what ctask adds to your sessions, where it steps in, and what it costs. |
  46. | **Evidence before done** | A task cannot be closed without saying what was checked. |
  47. | **Dependencies** | Tasks wait for each other; parallel sessions do not collide. |
  48. | **Code links** | Which task changed a file, and why. |
  49. | **Playbooks** | Saved recipes for work that repeats. |
  50. | **Enforced, not optional** | Hooks put all of this in front of Claude at the right moments. |
  51. ## Install
  52. **Requirements**
  53. - [Claude Code](https://claude.com/claude-code), CLI or desktop app
  54. - Node.js 24 or newer. There are no npm dependencies.
  55. - macOS for notifications and the background checker. Linux has not been tested.
  56. **Install the plugin**
  57. ```bash
  58. claude plugin marketplace add omarabulkhair-66/ctask
  59. ```
  60. ```bash
  61. claude plugin install ctask@ctask
  62. ```
  63. Or, inside Claude Code: `/plugin marketplace add omarabulkhair-66/ctask`, then `/plugin install ctask@ctask`.
  64. Start a new session. There is nothing else to set up: the plugin loads its hooks and skill, puts `ctask` on the session's PATH, and installs its own background checker.
  65. **Update**
  66. ```bash
  67. claude plugin marketplace update ctask
  68. ```
  69. ```bash
  70. claude plugin update ctask@ctask
  71. ```
  72. **Uninstall**
  73. ```bash
  74. ctask daemon uninstall
  75. ```
  76. ```bash
  77. claude plugin uninstall ctask@ctask
  78. ```
  79. Your data stays in `~/.ctask` until you delete that folder.
  80. ## Quick start
  81. You mostly do not run commands. You talk to Claude, and Claude runs them.
  82. | Say this | What happens |
  83. | --- | --- |
  84. | "Add a settings page with tests" | Claude creates a task with steps before it starts, and closes each one with what it verified. |
  85. | "Remind me in 20 minutes to check the deploy" | A reminder. You get a notification, and Claude brings it up. |
  86. | "Where were we?" | Claude reads the task log and the last handoff note. |
  87. | "What's open across all my projects?" | A summary of every project with open work. |
  88. | "Remember: we never edit `generated/` by hand" | Stored as a project rule, shown to every future session. |
  89. | "Why was `login.js` changed?" | The tasks that touched that file. |
  90. | "Every morning, summarise the error log" | An automation that runs on its own. |
  91. | "Save what we just did as a playbook called release" | A reusable recipe. |
  92. | "What needs me?" | Due items, things waiting on you, blocked and stalled work. |
  93. To look at the data yourself, the same commands work in a terminal:
  94. ```bash
  95. ctask list
  96. ```
  97. ```bash
  98. ctask projects
  99. ```
  100. ```bash
  101. ctask review --all
  102. ```
  103. (For `ctask` in your own terminal, clone the repository and run `npm link` in it.)
  104. ## How it works
  105. A connector alone gives Claude tools it can forget. ctask is a plugin, and its hooks are what make it stick.
  106. | Hook | When | What it does |
  107. | --- | --- | --- |
  108. | SessionStart | A session starts, resumes, or is compacted | Shows Claude the digest: due items, work in progress, open tasks, project memory, playbooks, the last handoff, other projects, and the usage rules. |
  109. | UserPromptSubmit | Every message you send | Adds one line: the active task, anything due, or a nudge to create a task. |
  110. | Stop | Claude finishes a turn | Links the files edited this turn to the active task. Blocks the turn once if a task in progress was not updated. |
  111. | PreCompact | Context is about to be summarised | Saves a handoff note from the transcript. |
  112. | SessionEnd | The session closes | Saves a handoff note from the transcript. |
  113. Alongside the hooks:
  114. - **The CLI** (`ctask`) is the engine. Claude calls it through its shell.
  115. - **The skill** teaches Claude when to write and when to read.
  116. - **The MCP server** exposes the same engine as tools, for surfaces with no shell: `task_add`, `task_list`, `task_get`, `task_update`, `task_next`, `memory_add`, `memory_update`, `memory_recall`, `memory_list`.
  117. - **The background checker** runs once a minute for notifications, automations and housekeeping.
  118. Everything is stored in one SQLite file, `~/.ctask/ctask.db`. A project is the git root above the working directory, or the directory itself.
  119. ## Features
  120. ### Tasks and steps
  121. A task has a `title`, a `body` (what and why), `instructions` (how), a `status`, a `priority`, tags, and a log of everything that happened to it. Steps are tasks with a parent.
  122. ```bash
  123. ctask add "CSV import for orders" --body "Customers upload up to 50k rows" --instructions "Stream, do not load into memory" --start
  124. ```
  125. ```bash
  126. ctask add "Parser" --parent 12
  127. ```
  128. ```bash
  129. ctask note 12 "Decided on a streaming parser; the sync one ran out of memory at 20k rows"
  130. ```
  131. ```bash
  132. ctask show 12
  133. ```
  134. Statuses: `todo`, `in_progress`, `blocked`, `waiting` (on you), `done`, `cancelled`. Kinds: `task`, `step`, `reminder`, `automation`.
  135. ### Reminders
  136. Any task with a due time is a reminder.
  137. ```bash
  138. ctask add "Send the invoice" --next "tomorrow 9:00"
  139. ```
  140. ```bash
  141. ctask add "Check the error budget" --next "17:30" --every 1w
  142. ```
  143. When it comes due you get a macOS notification, and Claude raises it on your next message (or straight away, if the session is open and can schedule a wake-up). A repeating reminder is rescheduled when marked done instead of being closed. `ctask snooze 7 2h` moves one.
  144. Times can be `now`, `30m`, `2h`, `3d`, `17:30`, `today 17:30`, `tomorrow 9:00`, `2026-12-01 14:00`, or an ISO timestamp.
  145. ### Automations
  146. Work that runs without you.
  147. ```bash
  148. ctask add "Summarise yesterday's error log" --kind automation --every 1d --next "tomorrow 8:00" --instructions "Read storage/logs, group errors by cause, write the top five to the task as a note"
  149. ```
  150. When it is due, the background checker runs `claude -p` in the task's project with the body and instructions, records the result on the task, and reschedules it. Add `--resume` to continue the task's original session instead of starting fresh.
  151. Two things to know: the `claude` CLI must be logged in for your terminal, and headless runs use Claude Code's default permissions, so tools that need approval will be refused.
  152. ### Handoff notes
  153. Long sessions get compacted and closed sessions forget. Just before either happens, ctask reads the end of the transcript and saves:
  154. - your last three requests,
  155. - where Claude left off,
  156. - the files it edited,
  157. - its last commands.
  158. No model call is involved, so it always happens. The note is attached to the session and to any task it had in progress, and the next session start shows it: to the same session after compaction, or to a new session in the same project for up to 14 days.
  159. Claude can also write a better one itself, which takes priority:
  160. ```bash
  161. ctask handoff 12 "state: parser done / failed: streaming on Windows paths / next: wire the tests"
  162. ```
  163. ### Project memory
  164. Tasks end. Knowledge should not. Memory is a small set of statements Claude maintains about a project: rules, your preferences, decisions and their reasons, gotchas and facts.
  165. ```bash
  166. ctask remember "Never edit generated/ by hand, run make gen" --kind rule
  167. ```
  168. ```bash
  169. ctask remember "Seed a demo database with --class=DemoSeeder" --kind fact --when "demo, seed"
  170. ```
  171. What makes it more than a notes file:
  172. - **It is edited, not only appended.** `ctask memory update m3 "corrected text"` changes an entry and keeps the old version as history. `--replaces m7` supersedes an entry, and `ctask memory merge m4 m9 "..."` folds several into one. A new entry that repeats an existing one is refused and points at the one to update, so memory does not fill with near-copies.
  173. - **It is recalled when relevant, not dumped.** Only rules and preferences are shown at session start. Everything else is matched against each message you send, and the few entries that are about it are added to the conversation, once per context.
  174. - **It survives long conversations.** After the context is compacted, recall starts fresh, so what was lost comes back the next time it matters.
  175. - **Claude is prompted to keep it current.** When a message reads like a lasting instruction ("from now on…"), and every few messages with nothing saved, Claude is reminded to save or correct what the conversation has taught it.
  176. - **It is measured.** Every recall is counted. `ctask memory review` lists near-duplicates and entries nothing has recalled in 30 days; `ctask memory show m3` shows an entry's versions and how often it was used.
  177. Matching is done locally by word overlap, weighted towards rarer words, with Arabic and English normalised. It does not translate: an Arabic message will not find an English memory unless they share words or you give the entry `--when` triggers in both languages.
  178. ### What ctask is doing: stats and the call log
  179. Every hook that fires, every command Claude runs and every MCP tool call is logged locally.
  180. ```bash
  181. ctask stats
  182. ```
  183. shows the last seven days: how much context was added and what it costs in tokens, how many memories were recalled and which ones most, how many tasks were created and closed, how often ctask stepped in (a turn held until the task was updated, a "done" refused without evidence, a duplicate memory refused), and how long the hooks take. `--days 30` and `--all` widen it.
  184. ```bash
  185. ctask log --limit 40
  186. ```
  187. shows the individual calls. Filter with `--source hook|cli|mcp|tick`, `--session ID`, `--name N` or `--failed`. Entries older than 90 days are removed (`CTASK_LOG_DAYS`), and `CTASK_LOG=off` disables logging.
  188. ### Evidence before done
  189. The usual failure of an agent is saying "done" when it is not. A task or step cannot be marked done without a note saying what was run or checked:
  190. ```bash
  191. ctask done 12 --note "Ran the import test suite, 14 passing; imported the 50k sample in 9s"
  192. ```
  193. Record what done means up front, and it is printed back if Claude tries to close the task without evidence:
  194. ```bash
  195. ctask add "Fix login redirect" --accept "Login test passes and the redirect lands on /dashboard"
  196. ```
  197. Reminders and automations are exempt. `--force` overrides.
  198. ### Dependencies and parallel sessions
  199. ```bash
  200. ctask add "Deploy" --after 14,15
  201. ```
  202. A task cannot start until the tasks it waits on are closed. `ctask next` only offers work that is ready, closing a task prints what it unblocked, and cycles are rejected.
  203. A task that is in progress in a session active within the last 30 minutes cannot be started by another session, so several sessions can work on one project without stepping on each other.
  204. ### Code links
  205. At the end of every turn, the files Claude edited are attached to the task it was working on. The git branch and commit are recorded when a task is started and finished.
  206. ```bash
  207. ctask why src/auth/login.js
  208. ```
  209. That lists the tasks that touched the file, so "why is this like this?" has an answer. Add links by hand with `ctask link 12 --pr <url>`.
  210. ### Playbooks
  211. A playbook is a saved recipe for work that repeats: a task with ordered steps, instructions and acceptance criteria. Instead of explaining how you do a release every time, save it once.
  212. From a task that went well:
  213. ```bash
  214. ctask playbook save release --from 42
  215. ```
  216. Or written directly:
  217. ```bash
  218. ctask playbook save triage --title "Bug triage" --steps "Reproduce; Find the cause; Fix; Add a regression test"
  219. ```
  220. Then run it:
  221. ```bash
  222. ctask playbook run release v2.0 --start
  223. ```
  224. That creates the task "Release: v2.0" with its steps, each one waiting on the one before (`--parallel` removes the ordering). Claude is shown the playbook names at session start and uses them when the work matches.
  225. ### Review
  226. ```bash
  227. ctask review --all
  228. ```
  229. Lists what needs attention: due, waiting on you, blocked, and work in progress that nobody has touched for three days (`--stale 7` changes that). Once a day the background checker sends the same summary as a notification, and stays quiet when nothing needs you.
  230. ### Search, paging and archive
  231. - **Search** matches every word against title, body, instructions, tags and log notes, and includes closed tasks: `ctask search invoice client`. Add `--all` for every project.
  232. - **Lists are paged**, 50 at a time, and end with `showing 51–100 of 340 · next: --page 3`.
  233. - **Archive**: tasks closed more than 30 days ago are archived automatically. They disappear from lists and search but are never deleted. `--archived` brings them back, and reopening a task unarchives it.
  234. With 5,000 tasks, a list, a search and each hook take about 0.2 seconds, most of it Node starting.
  235. ## Command reference
  236. `ctask help` prints this. Add `--json` to most commands for machine-readable output.
  237. ```text
  238. Create
  239. ctask add <title> [--body T] [--instructions T] [--kind task|step|reminder|automation]
  240. [--priority 1|2|3] [--parent ID] [--tags a,b] [--next WHEN] [--every 30m|2h|1d|1w]
  241. [--accept CRITERIA] [--after ID,ID] [--start] [--resume] [--project DIR]
  242. Work
  243. ctask start|done|block|wait|cancel|reopen <id> [--note T] [--force]
  244. ctask note <id> <text>
  245. ctask handoff <id> <text>
  246. ctask update <id> [--title --body --instructions --kind --priority --tags --parent --status
  247. --accept --after --next WHEN|none --every INT|none --note T]
  248. ctask snooze <id> <WHEN>
  249. ctask rm <id>
  250. Look
  251. ctask list [--all] [--status s1,s2] [--kind K] [--due] [--mine] [--closed] [--tag T]
  252. [--parent ID] [--archived] [--limit N] [--page N]
  253. ctask search <words> [--all] [--archived]
  254. ctask show <id>
  255. ctask next [--all] what to work on now
  256. ctask due [--all] items whose time has come
  257. ctask projects open work across every project
  258. ctask review [--all] [--stale DAYS]
  259. ctask context the digest Claude sees at session start
  260. Memory
  261. ctask remember <text> [--kind rule|preference|decision|gotcha|fact] [--when "words"]
  262. [--importance 1|2|3] [--replaces mID] [--global] [--force]
  263. ctask memory [words] [--all] [--kind K]
  264. ctask memory update <mID> [new text] [--kind K] [--when W|none] [--importance N]
  265. ctask memory merge <mID> <mID> [...] <combined text>
  266. ctask memory show <mID> | review [--all]
  267. ctask recall <text>
  268. ctask forget <mID>
  269. Insight
  270. ctask stats [--days 7] [--all]
  271. ctask log [--limit 40] [--source hook|cli|mcp|tick] [--session ID] [--name N] [--failed]
  272. Code
  273. ctask link <id> [--file a,b] [--commit SHA] [--branch NAME] [--pr URL]
  274. ctask why <file> [--all]
  275. Playbooks
  276. ctask playbook save <name> --from <task id>
  277. ctask playbook save <name> --title T --steps "a; b; c" [--instructions T] [--accept T]
  278. ctask playbook run <name> [subject] [--start] [--parallel]
  279. ctask playbook list | show <name> | rm <name>
  280. Archive
  281. ctask archive [<id>] [--older 30d] [--all] [--dry-run]
  282. ctask unarchive <id>
  283. Background
  284. ctask tick [--dry-run]
  285. ctask daemon install|uninstall|status
  286. ```
  287. ## Background checker
  288. On macOS the plugin installs and maintains a launchd agent, `com.ctask.tick`, from the SessionStart hook. Once a minute it:
  289. 1. shows a notification for anything that has come due,
  290. 2. sends the daily review, once, at or after 09:00,
  291. 3. runs due automations,
  292. 4. archives tasks closed more than 30 days ago.
  293. It runs a small launcher in `~/.ctask/bin/` rather than the plugin directly, so it keeps working when the plugin is updated. Its log is `~/.ctask/tick.log`.
  294. ```bash
  295. ctask daemon status
  296. ```
  297. After `ctask daemon uninstall` the plugin leaves it off until you run `ctask daemon install`. On Linux, run `ctask tick` from cron instead.
  298. ## Configuration
  299. Set these as environment variables.
  300. | Variable | Default | Effect |
  301. | --- | --- | --- |
  302. | `CTASK_HOME` | `~/.ctask` | Data directory. |
  303. | `CTASK_DB` | `$CTASK_HOME/ctask.db` | Database file. |
  304. | `CTASK_STOP_GUARD` | on | `off` disables the end-of-turn check. |
  305. | `CTASK_DAEMON` | on | `off` stops the plugin installing the background checker. |
  306. | `CTASK_NOTIFY` | on | `off` disables macOS notifications. |
  307. | `CTASK_REVIEW_AT` | `09:00` | Time of the daily review notification. `off` disables it. |
  308. | `CTASK_ARCHIVE_AFTER` | `30d` | Age at which closed tasks are archived. `off` disables it. |
  309. | `CTASK_MEMORY_EVERY` | `8` | Messages without a memory write before Claude is reminded to save. |
  310. | `CTASK_LOG` | on | `off` disables the call log. |
  311. | `CTASK_LOG_DAYS` | `90` | How long call log entries are kept. |
  312. | `CTASK_CLAUDE_BIN` | `claude` | The executable used to run automations. |
  313. ## Data and privacy
  314. - Everything is stored locally in `~/.ctask/ctask.db`. ctask makes no network requests.
  315. - The call log records command names, their arguments (truncated) and timings, not conversation text.
  316. - Handoff notes contain short excerpts of your conversation (your last requests and Claude's last message). They stay in that same local database.
  317. - Automations call your own `claude` CLI, under your account.
  318. - Back up or move your data by copying the `~/.ctask` folder.
  319. ## Troubleshooting
  320. **Claude does not seem to know about ctask.** Hooks load when a session starts. Open a new session after installing or updating.
  321. **No notification appeared.** macOS shows them as coming from Script Editor. Allow it under System Settings → Notifications. Check `ctask daemon status` and `~/.ctask/tick.log`.
  322. **Automations fail.** Run `claude` in a terminal and log in; headless runs need it. Remember that they cannot use tools that require approval.
  323. **`node: command not found` in hook output.** The plugin looks for Node on your PATH and in common install locations. If yours is elsewhere, make sure `node` resolves in a login shell.
  324. **A task was attributed to the wrong session.** With two sessions open on the same project at once, a command that cannot see its session id falls back to the most recently active one.
  325. **The end-of-turn check is in the way.** It fires once per turn, only when a task in progress was not touched. Set `CTASK_STOP_GUARD=off` to disable it.
  326. ## Development
  327. ```bash
  328. git clone https://github.com/omarabulkhair-66/ctask.git
  329. ```
  330. ```bash
  331. npm test
  332. ```
  333. | Path | Contents |
  334. | --- | --- |
  335. | `bin/` | `ctask` entry point, and `ctask-run`, the launcher hooks use to find Node |
  336. | `src/core.js` | Tasks, statuses, dependencies, lists, search, archive |
  337. | `src/hooks.js` | The five hook handlers and the session digest |
  338. | `src/handoff.js` | Transcript summariser |
  339. | `src/memory.js` | Memory: editing, similarity, ranking, recall |
  340. | `src/log.js` | Call log and stats |
  341. | `src/links.js`, `src/playbooks.js`, `src/review.js` | One feature each |
  342. | `src/tick.js` | Background checker and launchd agent |
  343. | `src/mcp.js` | MCP server |
  344. | `hooks/hooks.json`, `skills/ctask/SKILL.md`, `.claude-plugin/` | Plugin wiring |
  345. While developing, point `CTASK_DB` at a scratch file and set `CTASK_DAEMON=off`, then load the working copy with `claude --plugin-dir .`. The code has no dependencies beyond Node's built-ins; please keep it that way.
  346. ## License
  347. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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