@hasna/todos weekly downloads statistics

@hasna/todos

Universal task management for AI coding agents - CLI + MCP server + interactive TUI

Install

Upgrading From 0.15.52

0.16.0 puts every surface on one credential resolver and moves three command families to the shared API. Upgrading from 0.15.52 needs no data migration, but four things change:

• Configure a credential. The ./sdk client no longer reads ~/.todos/config.json, and the unprefixed TODOS_URL / key spellings are legacy. Put the key in the macOS Keychain, in ~/.hasna/todos/config/credentials (owner-only 0400/0600), or in HASNA_TODOS_API_KEY, then confirm with todos storage status --json. With no credential the CLI exits non-zero (REMOTE_API_CONFIG_MISSING) instead of quietly serving local rows, and MCP tool calls fail closed rather than falling back to the on-box store (see the third bullet below). The retired locations — ~/.hasna/fleet-env, ~/.hasna/cloud, ~/.config/hasna, $XDG_CONFIG_HOME — are not read. • **todos plans, todos task-lists (lists, tl) and the template commands are shared-API only.** They refuse HASNA_TODOS_DB_PATH, TODOS_DB_PATH, HASNA_TODOS_LOCAL and TODOS_LOCAL before startup — any one of them set is enough to refuse the command, and the refusal names the ones that are set. todos template-library is unchanged and still credential-free. The MCP plan tools (create_plan, list_plans, get_plan, update_plan, delete_plan) and task-list tools (create_task_list, list_task_lists, get_task_list, update_task_list, delete_task_list) are shared-API only as well. • **Most MCP tools that read the on-box store need HASNA_TODOS_LOCAL=1, and every refusal is typed.** The MCP server no longer opens the on-box SQLite store implicitly, so tools that still read it directly — the template family, tags and labels, stale/blocked work, doctor, run ledger, handoffs, review queues, retrospectives, risks, knowledge records, backups, calendar, boards, focus/time reports and dispatches — fail on the default posture with the typed {"code":"API_DATABASE_FALLBACK_FORBIDDEN"} payload, whose suggestion names the opt-in; the server also logs the same code. Measured at 0.16.0 with TODOS_PROFILE=full, that is 68 of the 125 zero-required-argument tools. A further 18 return the typed REMOTE_API_CONFIG_MISSING — the 16 shared-API tools that need a credential (list_tasks, list_projects, list_agents, get_next_task, get_status, bootstrap, get_context, get_my_tasks, get_my_workload, get_health, standup, list_my_tasks, machines_register, machines_list, machines_heartbeat, machines_topology) plus list_plans and list_task_lists. Five more refuse caller input or local state with the typed INVALID_INPUT / ENCRYPTION_KEY_UNAVAILABLE / ENCRYPTED_PAYLOAD_INVALID, and five answer a readable text refusal ("Provide agent_id, id, or name."). No zero-argument tool returns an opaque UNKNOWN_ERROR on either posture — the default one measured above, or the HASNA_TODOS_LOCAL=1 opt-in these tools are served under. Run the server with HASNA_TODOS_LOCAL=1 to keep using the on-box tools; that opt-in is ignored when HASNA_TODOS_API_KEY or HASNA_TODOS_API_URL is set, because a configured environment outranks it. • The advertised command list is route-dependent. 0.15.52 listed all 166 commands to every caller because the local fallback was implicit. 0.16.0 lists only what the resolved route exposes: 76 root commands on the hosted route once a credential resolves, 75 with none configured (the extra verb, stale-lock-handoff, is advertised only when the shared-API authority is), and the full 166 only with HASNA_TODOS_LOCAL=1 set, because the on-box families fail closed on the default posture. No command was removed — todos --help, todos manual and the generated completions all honour the same rule, and every verb still resolves once its posture is configured. todos storage status also reports credential-source disagreements as a warnings array (--json) and a yellow stderr line (human mode); the entries name sources and env key names, never a value.

Everything else still runs offline with HASNA_TODOS_LOCAL=1 (when the environment configures no authority or credential of its own). The per-surface detail lives under apps/todos/docs/ (PLAN_API.md, TASK_LIST_API.md, TEMPLATE_API.md, TASK_QUERY_API.md, native-storage.md). The npm tarball ships this README, CHANGELOG.md and those five documents alongside dist/, so they are readable from an installed package; docs/cli-help.md is repo-only.

HTTP request budget

todos-serve defaults to 12,000 requests per minute per network peer, per server process. Set HASNA_TODOS_RATE_LIMIT_MAX to an integer from 1 to 1000000 to choose a different finite budget. The legacy TODOS_RATE_LIMIT_MAX variable still works; the canonical variable takes precedence when both are set. An absent or blank value uses the default. Invalid values fail startup before the database is opened or the server listens.

The fixed one-minute window covers all routes, including health checks and unauthenticated requests, except CORS OPTIONS. Exceeding the budget returns HTTP 429 with Retry-After in seconds. Authentication requirements stay the same. This setting is a request allowance, not a throughput guarantee; size a deployment using observed latency, database load, and its gateway limits.

Behind a reverse proxy, callers share the proxy's bucket unless the operator has explicitly configured trusted forwarding. Keep proxy trust off for direct traffic. Only enable TODOS_TRUST_PROXY=1 when network rules restrict access to proxies that overwrite forwarding headers; TODOS_TRUSTED_PROXIES helps resolve the forwarded chain and does not itself restrict which sockets may connect.

Credentials and Service Authority…

Description from the npm listing.