guanling (關令)

A task-management MCP server that refuses.

Most task tools do what you tell them. This one has opinions and enforces them.

---

Why this exists

A real task list grew to 280 items. Sixteen were marked "in progress". Not one of them was actually being worked on.

The missing thing was not a tool — there already was a list. The missing thing was anything that forced a decision. Every operation said yes, so the list accumulated intentions and never spent them.

What makes Linear work is not its feature set. It is its refusals: a small fixed set of states you cannot extend, and limits you cannot argue with. This server copies the refusals, not the features.

The gates

Each one is a refusal, not a warning.

Gate	Behaviour
owner and next_step required	task_add is rejected without both. No owner and no next action means it is a wish, not a task.
Five states, hardcoded	triage · todo · doing · done · dropped. There is no API to add a sixth. Custom statuses are how a list starts rotting.
WIP limit on doing	Moving past the limit is rejected, and the error names what currently occupies it so you have to close something first.
External items land in triage	Anything with a source starts in triage, never straight in todo.
Closing requires a reason	done / dropped without reason is rejected. Why it closed outlives that it closed.
Rollover is visible	cycle_roll increments a rolled counter and returns anything rolled 3+ times as needing a decision. Nothing is dropped silently.

Refused calls write nothing to disk — there is a test for this.

Install

npm install -g guanling

Then add it to your MCP client config:

{
  "mcpServers": {
    "guanling": {
      "command": "npx",
      "args": ["-y", "guanling"],
      "env": {
        "GUANLING_AGENT": "me",
        "GUANLING_FILE": "/path/to/my-tasks.json",
        "GUANLING_WIP": "3"
      }
    }
  }
}

Variable	Default	Meaning
GUANLING_AGENT	unknown	Identity for this instance.
GUANLING_FILE	~/.guanling/<agent>.json	Path to the JSON store.
GUANLING_WIP	3	Maximum concurrent doing items.

⚠️ Give every instance its own GUANLING_FILE. Two processes sharing one file will overwrite each other — see Limitations.

Tools

Tool	Purpose
task_add	Open a task. Rejects without owner + next_step.
task_update	Change status/owner/next_step. Enforces the WIP limit and the close-reason rule.
task_list	List open work. stale_days surfaces tasks opened and never touched.
task_triage	Resolve inbox items: accept / decline / duplicate / snooze.
cycle_status	Days left, WIP usage, stale count, and what has rolled twice or more.
cycle_roll	Close the cycle, carry unfinished work forward with a visible counter.

Storage

One JSON file, written atomically (write to a temp file, then rename).

Deliberately not a database. The scale is hundreds of rows, and a plain file stays readable by a human, diffable in git, and backed up by cp. The complete string is built before the file is opened, so an exception mid-serialisation leaves the previous file intact.

Tests

node selftest.mjs

16 arms, weighted toward the refusals — those are the product. Includes a negative control asserting that a rejected task_add leaves nothing on disk.

The WIP gate is mutation-tested: removing it turns exactly the two arms that cover it red. A gate that cannot be observed failing has not been verified.

Limitations

Stated up front rather than discovered later.

• No concurrency lock. One process per store file. Two writers will clobber each other.
• No cross-instance visibility. Each instance sees only its own file. This is intentional for per-agent isolation, but it means separate agents cannot see each other's work and may duplicate effort.
• snooze sets snooze_until but nothing wakes it. Items do not return on their own; task_list is how you find them.
• No history or audit trail. The file holds current state only.

The name

關令尹喜 was the gatekeeper at Hangu Pass. When Laozi tried to leave through it, the gatekeeper would not let him pass until he wrote his teaching down — which is why the Tao Te Ching exists.

Same idea: you do not get through until you write it down.

Privacy Policy

What is collected: nothing. Guanling has no telemetry, no analytics, no crash reporting, and no update check.

What is stored, and where: only the tasks you create — their title, owner, next step, status, optional source and blocker, timestamps, and close reason. They are written to a single JSON file on your own machine, at the path you configure (GUANLING_FILE, or ~/.guanling/<agent>.json by default). Nothing is written anywhere else.

Third-party sharing: none by guanling itself. The server makes no network requests: no HTTP client, no sockets, no telemetry. It uses four Node builtins — node:fs, node:path, node:crypto (to mint delegation nonces), and node:child_process.

⚠️ That last one matters and is stated plainly: if you configure GUANLING_SEND_CMD, guanling executes your command and pipes a delegation payload to it on stdin. Whatever that command does with the payload — including sending it over a network — is outside guanling and is your choice. With the variable unset, delegation is refused and nothing is ever executed.

(Earlier releases of this file claimed two builtins. That stopped being true in 1.1.0 when delegation was added, and the sentence was not updated until 1.4.0.)

Data retention: entirely yours. The file persists until you delete it. Guanling never expires, prunes, or deletes data on its own — closing a task marks it done or dropped and keeps the record. To erase everything, delete the JSON file.

Your control: the store is plain JSON. You can read it, edit it, copy it, back it up, or delete it with ordinary file tools. No export feature is needed because the file is the export.

Contact: open an issue at https://github.com/fateLiang/guanling/issues.

License

MIT