ziptask

MCP task tracker for AI agents — pure state layer (statuses, deps, leases, versioning) over SQLite.

Install

One-liner — downloads a compiled binary, writes default config, prints client setup:

# latest release
curl -LsS https://raw.githubusercontent.com/zumik3-del/ziptask/main/scripts/install.sh | sh

# pin a version (set the variable on the sh side of the pipe)
curl -LsS https://raw.githubusercontent.com/zumik3-del/ziptask/main/scripts/install.sh | ZIPTASK_VERSION=v0.1.3 sh

Default install dir: ~/.ziptask/. Override with ZIPTASK_HOME=/some/path (also on the sh side of the pipe). On systemd systems the installer provisions a background service on port 3005 (override with --port), using sudo to write the unit and start the service; if root access is unavailable it skips the service and prints the manual start command. Skip it explicitly with --no-service. update.sh and uninstall.sh are installed into ~/.ziptask/scripts/.

Prebuilt release binaries target Linux x86_64 only. On other platforms (macOS, arm64 Linux) build from source with bun run build:bin.

Service mode

When systemd is detected and running, install.sh creates /etc/systemd/system/ziptask.service (Type=simple, Restart=on-failure, port 3005) and starts it. The unit runs as the user that invoked the installer — even under sudo, SUDO_USER is honoured, so the binary, DB and service stay under that user's home rather than root's. Manage it with:

sudo systemctl start ziptask
sudo systemctl stop ziptask
sudo systemctl enable ziptask     # auto-start on boot
journalctl -u ziptask -f         # live logs

Remove with bash ~/.ziptask/scripts/uninstall.sh (use --keep-data to preserve the DB and settings).

MCP client config (stdio)

// Claude Desktop / Cursor / opencode — see your client's MCP config (key "mcpServers" in most)
{
  "mcpServers": {
    "ziptask": {
      "command": "/home/you/.ziptask/bin/ziptask",
      "args": ["--stdio", "--settings", "/home/you/.ziptask/settings.json"]
    }
  }
}

Pass --settings so the DB path and options come from settings.json regardless of the client's working directory — otherwise the DB defaults to ./data/ziptask.db under the client's cwd. Clients do not expand ~ in command/args; substitute the absolute path (the installer prints a ready-to-paste block).

MCP client config (remote HTTP)

When the service is running on the same host, point the client at the HTTP endpoint instead:

{
  "mcp": {
    "ziptask": { "type": "remote", "url": "http://127.0.0.1:3005/mcp" }
  }
}

The endpoint has no authentication, so keep it bound to 127.0.0.1 (ZIPTASK_HOST/settings.json). Use a reverse proxy with auth if it must be reachable from other hosts.

Related MCP server: tasqr-mcp

Quick start (from source)

Requires Bun ≥ 1.4.

bun install
bun run start          # HTTP server on an ephemeral port (MCP endpoint + /health + experimental /api/task/:id)
bun run start:stdio    # run over stdio

Build a binary

bun run build:bin        # produces dist/ziptask
dist/ziptask --version   # prints ziptask and the package.json version
dist/ziptask --stdio     # runs as stdio MCP server

Architecture

Layered by carrier, no framework beyond the MCP SDK:

The public task API is MCP, exposed at POST/GET/DELETE /mcp, alongside GET /health and one experimental REST-style read endpoint, GET /api/task/:id, kept as an integration endpoint for the subagentix client. No endpoint authenticates. See HTTP endpoints.

Development

bun test               # unit tests (per-test temp DBs)
bunx tsc --noEmit      # type check
bunx biome check src/  # lint
bun run src/smoke.ts   # MCP end-to-end over HTTP (ephemeral port + temp DB)
bun run changelog      # rebuild CHANGELOG.md from git tags (maintainers; clean tree required, then commits and pushes it)

Documentation

• Configuration — settings.json, environment variables, the upgrade path, and backups.

• HTTP endpoints — /mcp, /health, and the experimental GET /api/task/:id integration endpoint.

• MCP tools — tool reference, task statuses, and lease-reap semantics.

• Epic → sub-task workflow — declaring epics, attaching sub-tasks, roll-up and closure.

• Subagent setup — install and configure the example orchestrator + subagent agents.

License

MIT

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.