CLI & MCP server

Install

Taskessa ships as prebuilt binaries. There is nothing to compile: download the latest build for your platform, unzip it, and put taskessa and taskessa-mcp on your PATH:

• macOS / Linux: move both binaries into a directory on your PATH (for example ~/.local/bin) and make them executable with chmod +x.
• Windows: put the folder containing taskessa.exe and taskessa-mcp.exe on your PATH.

Verify:

taskessa --version

Authenticate

There is nothing to configure: taskessa connects to your Taskessa account automatically.

taskessa auth login      # prompts for your email, then a hidden password
taskessa auth status     # account, API URL, and session status
taskessa auth logout     # clear the cached session (--purge also drops the password)

auth login proves your credentials, unlocks your key locally (then drops it), stores your password in the OS keychain, caches a session token, and remembers your account so later commands need no flags. Your password is read from a no-echo prompt (never a command argument), and your key is re-derived per run and never written to disk.

Use the CLI

Content is always read from stdin, never command arguments. Decrypted output goes to stdout; counts and diagnostics go to stderr. A decrypt failure shows <undecryptable> and exits 7, never a silent gap.

# read (content decrypted locally)
taskessa task list --all --json
taskessa habit list
taskessa calendar list --start 2026-06-01 --end 2026-06-07
taskessa planning today

# write (content from stdin, never a command argument)
echo "Buy oat milk" | taskessa task add --priority High
taskessa task done <id>

Connect your own LLM (MCP)

Launch the stdio MCP server with taskessa mcp (identical to the taskessa-mcp binary). It exposes read tools (list_tasks, get_task, list_projects, list_labels, list_habits, list_habit_categories, list_calendar_blocks, get_planning_summary, get_account_plan) plus write tools for tasks, projects, labels, habits, categories, check-ins, and calendar blocks. Writes return a dry-run preview unless you pass confirm=true.

Claude Desktop

Store your password in the OS keychain once:

TASKESSA_EMAIL=you@example.com TASKESSA_PASSWORD='…' taskessa-mcp store-password

Then add this to claude_desktop_config.json (no secret appears in the config: it comes from the keychain):

{
  "mcpServers": {
    "taskessa": {
      "command": "taskessa-mcp",
      "args": [],
      "env": {
        "TASKESSA_EMAIL": "you@example.com"
      }
    }
  }
}

If Claude Desktop cannot find taskessa-mcp on its PATH, use the absolute path (the output of which taskessa-mcp). Restart Claude Desktop; the Taskessa tools then appear in the client.

Configuration

Zero-knowledge guarantees

• Content is encrypted on your device; the server stores only ciphertext plus plaintext metadata and has no code path that reads your content.
• Your encryption key is derived from your password locally and is never escrowed. A one-time recovery key restores access if you forget your password.
• Lose both your password and recovery key, and your content is unrecoverable, by design.

Full reference: use Copy for LLM above, or read /cli.md. See also the privacy policy.