Task Runner
The Task Runner MCP server gives coding agents persistent project memory, task orchestration, time reporting, and user preference/rule management.
Recall and search memory across entities, facts, notes, and projects; inspect entity details and graph health.
Create/update knowledge-graph entities and facts, link or unlink entities, correct or retire facts, and forget entities.
Save and retrieve session notes scoped to project, branch, or PR.
Create task groups from markdown or task arrays, claim the next task, complete tasks as done/failed, inspect status, and clear tasks.
Generate worklog/time reports by project, branch/task, and period, with optional detail.
Show standing rules, propose new rules for approval, and show/learn/forget learned taste preferences.
Override or inspect project context and list known projects.
Integrates with local Git repositories by deriving project keys from Git remotes, scoping task groups and notes to branches/worktrees, and saving notes for agent-made Git commits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Task Runner remember we use pnpm not npm, then start a task group for the auth refactor"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Task Runner
Memory for your coding agent. It remembers decisions, pitfalls and conventions between sessions. It also runs multi-step work as a task list.
Task Runner is one package with four parts:
an MCP server with 19 tools (works in any MCP client, over stdio or HTTP),
a Claude Code plugin that wires the server, a session briefing and a skill together,
a mod for Claude Code: a live side panel, memory toasts, task progress, reminders and a time report,
a dashboard with a graph view, a time report and a rules editor,
an optional server (a Cloudflare Worker) that holds the same data for several machines.
The data lives where the MCP server runs. With the default install that is one SQLite file on your machine, and nothing is sent anywhere. If you sign in to your own server, every machine reads and writes the server's database instead.
Install
Claude Code (recommended)
/plugin install task-runner --marketplace MrMirhan/task-runnerFrom a shell:
claude plugin install task-runner --marketplace MrMirhan/task-runnerYou need Node.js 22.13 or newer. Start a new session. The plugin adds:
Part | What it does |
MCP server | The memory, task, time and rules tools. |
Session briefing | At session start, a hook puts the most important facts of the project in the agent's context. The agent does not need to call a tool to get them. |
Skill | Tells the agent when and how to use the tools. |
Panel ( |
|
| Search memory without using a model turn. |
| Save a note. |
| Time spent by you and the agent, per project and task. |
| What was learned about how you want things; turn learning on or off for this session. |
| Show the rules in force. |
Toasts | Show what the agent remembers, links or forgets. |
Progress line | Shows task progress above the prompt while a task group is open. |
Commit notes | Saves a short note for each |
Reminder | After many edits or a commit with nothing saved, adds one line to your next prompt. |
No prompts | The plugin approves its own memory tools, so they never stop to ask. |
Each of the last five rows has a switch in the plugin settings.
Other MCP clients
Add the server to the client configuration:
{
"mcpServers": {
"task-runner": { "command": "npx", "args": ["-y", "task-runner-mcp"] }
}
}The server finds the project from its working directory. If your client starts servers in another directory, set TASK_RUNNER_PROJECT:
{
"mcpServers": {
"task-runner": {
"command": "npx",
"args": ["-y", "task-runner-mcp"],
"env": { "TASK_RUNNER_PROJECT": "my-project" }
}
}
}Other clients do not get the briefing, the panel or the slash commands. The tools and their instructions work everywhere.
Related MCP server: friday
How the agent uses it
The briefing shows the top facts for the project and for you.
The agent calls
recallfor details. Search ignores accents and matches word starts, in any language.While it works, the agent calls
rememberfor durable facts andlinkto connect them.save_memoryis for notes about the session.A wrong fact is fixed with
correct_fact. Every fact has a date.For long work, the agent calls
create_task_group, then loopsget_next_taskandcomplete_task.
Tools
Tool | Purpose |
| Search entities, facts and notes. |
| Create an entity or add facts to it. |
| Connect two entities. |
| Replace or retire one fact. |
| One entity with facts, relations and neighbors. |
| Retire an entity. |
| Session notes. |
| Counts, orphan entities and (with |
| The task loop. |
| Time by you and the agent per project and task, for a period. |
| Show your standing rules, or propose a new one. The agent cannot change rules; you approve. |
| Show, record or forget the preferences learned from what you said. They apply at once. |
| Override or inspect the project. Rarely needed. |
Entity types: preference, decision, pattern, file, concept, tool, pitfall, convention.
Relations: uses, depends_on, conflicts_with, part_of, prefers_over, decided_against, relates_to, supersedes.
Projects
The project key comes from the first match in this list:
the
TASK_RUNNER_PROJECTenvironment variable,a
.task-runner.jsonfile in the repository root:{ "project": "my-project" },a project already stored for the same folder,
the git remote, as
owner-repoin lowercase (so clones and worktrees agree),the folder name.
Commit .task-runner.json when a team wants one key for everybody.
Worktrees and copies share the project key. A linked git worktree (for example an Orca workspace) uses the key of its main checkout. A plain copy of the folder keeps the git remote, so it gets the same key. Every folder a project was seen in is remembered.
What stays separate:
Thing | How |
Session | Each agent session runs its own server process with its own folder and branch. |
Worktree or branch | Task groups belong to the branch that made them. |
Project | Entities, facts and notes are shared by every worktree of the project, so a lesson learned in one worktree is there in the next. |
You |
|
Time tracking
Task Runner reads your Claude Code session transcripts and tells you how long you worked, how long the agents worked, and on what. It needs no hook and no setup, and it works on the history you already have.
npx task-runner-mcp worklog # this week, all projects
npx task-runner-mcp worklog --today --detail # plus what you asked and what was saved
npx task-runner-mcp worklog --last-week --format md > week.md
npx task-runner-mcp worklog --month --project . --format csv # this project, for a spreadsheetAsk the agent too: "how long did I work on the checkout feature this week, and what did we do?" The worklog tool answers from the same data.
How the numbers are made:
Number | Meaning |
You | The time before each prompt you typed (reading, thinking, typing). A wait longer than 5 minutes counts as 5; longer is a break. |
Agent | The time agents worked between your prompts. A pause longer than 15 minutes counts as 15. Parallel sessions add up, so this can exceed the clock. |
Wall clock | Every minute with any activity, counted once. This is the number to compare with a calendar. |
A task is a branch. A ticket key in the branch name (feat/SHOP-1182-login gives SHOP-1182) is the task label, and the prefix tells feature from fix. Work on main or without a branch has its own rows. A session that starts in a plain folder is charged to the repository whose files it edits.
Next to the time you see what you asked first, how many prompts and file edits it took, the commit notes, the notes you saved on that branch and the task groups. The Time tab of the panel (/brain) and the dashboard show the same report.
Settings (flags, or the environment variables in brackets):
--human-cap <minutes>and--ai-cap <minutes>change the two caps above. Changing them recomputes the history.--exclude "app-*,scratch"[TASK_RUNNER_WORKLOG_EXCLUDE] hides projects.*is a wildcard. Use it for tools that run agent sessions on their own.worklog pendinglists time not yet reported. After you copy it to a time-tracking system, runworklog exported <project> <branch>so it is not reported twice.
The first run reads every transcript of the period and can take a minute for a heavy week. After that only changed files are read. The result is stored in the same database as the memory: on a signed-in machine, the server's, so the report covers every machine. Claude Code removes old transcripts after some weeks, so run a report before they go; the stored numbers stay.
Taste
Task Runner learns how you want things from what you say, and every later session follows it. There is no approval step and nothing to write by hand.
When a message carries a directive, a correction or a preference ("always…", "don't…", "bundan sonra…", "too long"), the mod checks it in the background after the turn. The check is one model call over the session's own cached context, so the agent's work is not interrupted. A message without such words costs nothing.
A preference counts from the first time you say it. Saying it again makes it firmer. A different wish on the same point replaces the old one, and taking it back drops it.
Each preference has a scope: you everywhere, the organization, or one project.
The agent is told what was learned with your next prompt, and new sessions get the list at start.
Preferences live in the same database as the memory: on a signed-in machine, on your server, so all machines share them.
/taste lists what was learned. /taste off stops learning for the current session, and /taste on starts it again. In a session that has already run, /taste on also reads what you said so far. The Taste tab of the panel lists the preferences with a button to forget each one. The taste plugin setting turns learning off by default.
From the command line: task-runner-mcp taste, and task-runner-mcp taste forget <id>. Other MCP clients get the taste tool and the list at session start, but no automatic learning.
Rules
Standing instructions for the agent, set once, injected at the start of every session. You do not write a CLAUDE.md in every repository or on every machine.
Scope | Applies to |
Everywhere | every session |
Device | one machine ("use brew", "no GUI here") |
Organization | every repository of one owner (the git remote owner, |
Project | one project |
Project on a device | one project on one machine |
The sections arrive in that order. When two disagree, the later one wins. The repository's own CLAUDE.md still loads as usual.
npx task-runner-mcp rules set "Reply in the language I write in." # everywhere
npx task-runner-mcp rules set --org "Commit messages follow Conventional Commits."
npx task-runner-mcp rules set --project "Never edit the billing module."
npx task-runner-mcp rules set --device "Use brew, not apt."
npx task-runner-mcp rules edit --project # open the document in $EDITOR
npx task-runner-mcp rules # what this folder gets, and from whereA document holds 8,000 characters at most and the sections of one session add up to 16,000. Keep rules short and imperative: they cost tokens in every session.
The agent can read the rules with the rules tool and can propose a rule when you state a lasting preference or correct it twice. A proposal waits. You approve or reject it in the panel (/brain, Rules tab), with /rules approve <id>, on the web page, or with task-runner-mcp rules approve <id>. Nothing the agent proposes is active before that, because an active rule reaches every future session.
Several devices: one server
On one machine everything lives in the local database. With several machines, run the server in server/ as a Cloudflare Worker. It holds the memory, the tasks, the time records and the rules, and it serves the dashboard. Every machine signs in once with the same key.
npm run build:dashboard # the web page the Worker serves
cd server && npm install
npx wrangler deploy # creates a new Worker named task-runner
npx wrangler secret put TASK_RUNNER_KEY # paste a long random key: openssl rand -hex 24On each machine:
npx task-runner-mcp login https://task-runner.<your-subdomain>.workers.devThe command asks for the key. To keep it out of your shell history do not pass --key; type it at the prompt, pipe it in, or set TASK_RUNNER_REMOTE_KEY. The key is saved in ~/.task-runner/remote.json (readable by you only). task-runner-mcp logout goes back to the local database. The local data is not copied to the server; move it with export before login and import after.
After login, the plugin's MCP server, the session hook, the panel and the CLI use the server. The time report reads the transcripts on each machine and uploads only the per-minute totals; the transcripts stay on the machine. The session hook waits a few seconds at most and then uses the last rules it saved, so a slow network never blocks a session. Each machine has an id and a label (the host name; change it with rules rename-device).
Open the Worker address in a browser and enter the key to see the graph, the notes, the time report and the rules, preview what a project gets on a device, review proposals and rename devices.
An MCP client can also connect to the server directly, without the local server: see server/README.md. Moving a server from before 1.0 is described there too.
Keep in mind:
The key opens your memory and edits the instructions of every agent on every machine. Make it long and random, keep it out of repositories and rotate it with
wrangler secret put.The Worker refuses a key shorter than 24 characters. Add Cloudflare rate limiting or Access in front of it if you want more.
The data is stored on Cloudflare. Do not let the agent store secrets.
loginrefuseshttp://addresses other than localhost.
Command line
npx task-runner-mcp doctor # check the installation
npx task-runner-mcp dashboard --open # graph and notes in your browser
npx task-runner-mcp export --out backup.json # all data as JSON
npx task-runner-mcp export --format markdown --out vault # one file per entity, [[wiki links]]
npx task-runner-mcp import backup.json
npx task-runner-mcp projects # list projects
npx task-runner-mcp projects merge old-key new-key --yes
npx task-runner-mcp forget "Some entity"
npx task-runner-mcp note "Free text note"The markdown export opens in Obsidian or any editor.
Data and privacy
The database is
~/.task-runner/memory.db. SetTASK_RUNNER_DBfor a file, orTASK_RUNNER_HOMEfor a folder.Without
loginthe plugin never opens a network connection. The local dashboard listens on127.0.0.1only and refuses other hosts and origins.The reminder adds a line to your next prompt that only the agent reads. Switch it off with the
nudgesetting.Do not let the agent store secrets. The skill tells it not to, but nothing filters the text.
Back up with
export. Do not put the database in a cloud-synced folder; SQLite and file sync do not mix.
Develop
npm install
npm run check # type check and tests
npm run build # bundle to dist/cli.js (committed: the plugin runs it)
npm run build:dashboard # rebuild the web UI into dist/dashboard
claude plugin validate .
claude plugin test . # mod tests
claude --plugin-dir . # try the plugin in a sessionLayout:
src/core store, schema, search, rules, REST and RPC handlers (no Node APIs)
src/mcp tool definitions, server, session scope
src/http the server as one web-standard handler: /mcp, /api/rpc, /api/*
src/node node:sqlite driver, project detection, local or remote backend
src/cli command line, session hook, local dashboard server
src/worklog transcript reader and time report
server the Cloudflare Worker
hooks the mod (register.tsx) and the SessionStart hook
skills the skill
dashboard Next.js source of the web UIMoving from the hosted version before 1.0
Before 1.0 Task Runner was only a hosted Cloudflare Worker. server/wrangler.legacy.jsonc upgrades such a Worker in place: the stored data is copied into the current schema on first use and the old keys keep working. See server/README.md.
The tool set changed:
Old | New |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| removed |
License
MIT
Available Tools
19 toolsclear_tasksClear tasksADestructive
Delete one task group, or all task groups of this project. Memory is not touched.
Inputs: task_group.
complete_taskFinish a taskA
Record the outcome of a task: done with its result, or failed with the reason. Elapsed time is measured automatically.
Inputs: result (required), task_id (required), status, task_group.
correct_factCorrect a factADestructive
Replace a wrong or outdated fact (by the id recall and what_do_i_know show), or retire it by omitting new_fact.
Inputs: fact_id (required), new_fact.
create_task_groupCreate a task groupA
Split work into ordered tasks, from markdown ('## Task 1: Title' sections) or a tasks array. Then loop get_next_task, do the task (ideally in a subagent), complete_task.
Inputs: name (required), tasks, replace, markdown, +1 more.
forgetForget an entityADestructive
Retire an entity with its facts and relations. It stops appearing in searches; the data stays in the database.
Inputs: name (required), entity_type.
get_contextGet session notesARead-only
Recent saved notes for this project (project-wide notes plus the current branch and PR). Long notes are clipped unless full is set.
Inputs: full, type, limit.
get_next_taskNext taskA
Claim the next pending task and mark it running. A task running for over 30 minutes counts as abandoned and is offered again.
Inputs: task_group.
get_task_statusTask statusARead-only
Summary counts and every task's status for a group; with task_id, that task in full including its result or error.
Inputs: task_id, task_group.
graph_statsGraph healthARead-only
Counts of entities, relations, facts and notes, orphan entities (no relations) and the top entities. With check: also old low-importance entities and notes, and file entities whose path no longer exists.
Inputs: check, max_age_days.
linkLink entitiesAIdempotent
Connect two existing entities, or with remove: true disconnect them. Types are needed only when a name matches more than one entity.
Inputs: to (required), from (required), remove, context, +3 more.
list_projectsList projectsARead-only
Projects that have memory, newest first. Rarely needed: the current project is detected.
Inputs: limit, query.
recallRecallARead-only
Search memory by keywords: graph entities with their dated facts, linked entities as related, and matching notes. Matching ignores accents, finds word starts and stems, and falls back to parts of words; it is not meaning-based, so search with the words, synonyms and both languages the facts would use. Includes global facts. Start work with this.
Inputs: query (required), limit, entity_type, all_projects.
rememberRememberA
Create or update a knowledge-graph entity and add facts to it (an existing name is extended, duplicates are skipped). One fact per item, under 1000 characters; the name stays short. Add keywords so later searches find it. Entities named in the facts are linked automatically, and facts that seem to contradict a stored one come back as possible_conflicts. Scope 'global' is for facts about the user that hold in every project.
Inputs: name (required), scope, summary, keywords, +3 more.
rulesUser rulesA
The user's standing rules for this project, organization and device, as injected at session start. action 'show' returns them. action 'propose' queues a rule the user explicitly asked to make standing; the user approves it in the panel, the web page or the CLI. Preferences you pick up from the conversation go to the taste tool instead. Never propose secrets or one-off instructions.
Inputs: action (required), mode, text, scope, +1 more.
save_memorySave a noteA
Save a session note (what was done, decided or found) for this project. Use remember for durable facts; use this for narrative.
Inputs: content (required), tags, type, scope, +1 more.
set_contextSet project contextAIdempotent
Override the auto-detected project, branch or PR for this session. Optional: the project is detected from the working directory, so call it only to correct the scope.
Inputs: pr, branch, project, project_name, +1 more.
tasteLearned preferencesA
How the user wants things, learned from what they said: style, workflow, wording, tools. They are injected at session start and apply at once, with no approval. action 'show' lists them with ids. action 'learn' records what a message taught: 'new' for a wish not seen before, 'reinforce' when they say an existing one again, 'refine' when they adjust it, 'replace' when they now want something different on the same point, 'drop' when they take it back. Write each rule as a general, short instruction (one step more general than the message, never their words as a log). scope 'global' for how they work everywhere, 'org' for this organization, 'project' for this codebase. In Claude Code the panel learns these by itself; call learn when the user asks you to remember how they want something. Never store secrets or people's private data.
Inputs: action (required), id, items.
what_do_i_knowEntity detailBRead-only
Everything about one entity: dated facts, direct relations and neighbours up to two hops away.
Inputs: name (required), entity_type.
worklogTime reportARead-only
How long the user and the agent worked, per project and task (a branch or ticket), for a period. Read from the session transcripts. Use it to answer 'how much time did I spend on X this week' or 'what did I do this week'. Agent time adds up across parallel sessions; wall time counts each minute once.
Inputs: to, from, range, detail, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
The memories cluster (save_memory / remember / correct_fact / recall / get_context / what_do_i_know) has real boundary overlap, though most descriptions explicitly cross-reference each other to steer selection. The pair 'rules' vs 'taste' is the weakest split: both are standing user preferences injected at session start, differing only in approval flow. Task tools themselves are clearly distinct.
Most names are snake_case verb_noun (create_task_group, get_next_task, complete_task, clear_tasks, correct_fact), which is readable and mostly predictable. But several are bare nouns (rules, taste, worklog, graph_stats) and one is a question phrase (what_do_i_know), so the pattern breaks down noticeably.
19 tools is at the heavy end for a server named 'Task Runner' whose actual task surface is only four tools (create_task_group, get_next_task, complete_task, get_task_status). The remainder spans memory/knowledge graph, rules, taste, and worklog, so the count feels large relative to the advertised scope.
Memory has near-full lifecycle (remember, link, recall, what_do_i_know, correct_fact, forget, graph_stats) and the task loop (create, next, complete, status, clear) is workable. Gaps remain: no way to update/reopen/delete a single task, no note edit or delete, and rules support only show/propose with no withdraw path. Agents can work around these, so it stays above mid.
Maintenance
Related MCP Connectors
Shared project memory that keeps teammates and AI agents aligned across sessions.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Project memory, documentation and controlled secret access for AI coding agents.
Shared, scoped, reviewable team memory for AI coding agents.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides durable project context for coding agents, including project maps, session history, and explicit memories, all stored locally.143 npm7MIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent cognitive memory for AI coding agents, enabling them to recall architecture decisions, coding preferences, and project facts across sessions.68MIT

nightqueueofficial
AlicenseNot gradedqualityBmaintenanceProvides persistent, scoped memory and tooling for autonomous coding agents, letting lessons, decisions, and project knowledge accumulate across queue runs.7 npm1Business Source 1.1- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to read and write persistent project-scoped and cross-project memory during sessions, using local semantic search to surface relevant decisions, preferences, error patterns, and guidelines across sessions. It also optionally exposes an autonomous task queue that draws on that same stored context.-