# Taskessa CLI & MCP server

> The Taskessa CLI (`taskessa`) and its bundled MCP server (`taskessa-mcp`) are a single, zero-knowledge tool that runs on your own device. They log into your Taskessa account, derive your encryption key locally, and decrypt your tasks, habits, and calendar **on your machine**, so the Taskessa operator and the hosted API only ever see ciphertext and plaintext metadata (dates, priorities, status, IDs). "Bring your own LLM" means you connect a model you choose (for example, Claude Desktop) to the local MCP server; that model is the only party besides you that ever sees your plaintext.

This page covers installation, authentication, the CLI commands, and how to connect your own LLM over MCP. The CLI is in alpha and the current release artifacts are listed in the public manifest.

## What it is

- **One tool, two front-ends.** The same zero-knowledge core ships as `taskessa` (a one-shot CLI) and `taskessa-mcp` (a stdio MCP server). `taskessa mcp` launches the same server as the standalone binary.
- **Zero-knowledge.** Content (task titles and notes, project/label/habit/category names, calendar titles, attachment names) is end-to-end encrypted with XChaCha20-Poly1305 under a key derived from your password via Argon2id. Only ciphertext plus plaintext metadata ever leave your device.
- **No server-side AI.** There is no server-mediated assistant. AI runs through the model you connect to the local MCP server.

## Agent plugin artifacts

If you use Codex or Claude Code, Taskessa also publishes small plugin artifacts:

- Codex plugin zip: `https://taskessa.com/codex/taskessa-cli-codex-plugin.zip`
- Codex metadata: `https://taskessa.com/codex/taskessa-cli-codex-plugin.json`
- Claude plugin zip: `https://taskessa.com/claude/taskessa-cli-claude-plugin.zip`
- Claude metadata: `https://taskessa.com/claude/taskessa-cli-claude-plugin.json`

The Codex zip contains a top-level `taskessa-cli/` plugin folder with `.codex-plugin/plugin.json` and `skills/taskessa-cli/SKILL.md`. The Claude zip uses the same top-level folder and skill path, with `.claude-plugin/plugin.json` as its manifest. Both skills teach the install/auth/MCP flow and the zero-knowledge guardrails for Taskessa. They contain instructions only: no secrets, account tokens, passwords, recovery keys, or Taskessa binaries.

## Install

Taskessa ships as prebuilt binaries. There is nothing to compile. The release manifest at `https://dl.taskessa.com/latest/manifest.json` records the current version, target, archive filename, and SHA256 checksum. Download the build for your platform from **https://dl.taskessa.com**, unzip it, and put `taskessa` and `taskessa-mcp` on your PATH:

- macOS (Apple Silicon): `https://dl.taskessa.com/latest/taskessa-aarch64-apple-darwin.tar.gz`
- Linux (x86-64): `https://dl.taskessa.com/latest/taskessa-x86_64-unknown-linux-gnu.tar.gz`
- Windows (x86-64): `https://dl.taskessa.com/latest/taskessa-x86_64-pc-windows-msvc.zip`

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

```sh
taskessa --version
```

## Authenticate

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

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

`auth login` proves your credentials, unlocks your data-encryption 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.

**Security.** Your password is read from an interactive no-echo prompt (or from piped stdin / the `TASKESSA_PASSWORD` variable for scripts), never a command-line argument, so it never lands in your shell history or process list. Your data-encryption key is re-derived per run and is **never written to disk**; only the session token is cached.

## Use the CLI

Content (titles, notes, names) is always read from **stdin**, never command-line arguments. Decrypted output goes to stdout; counts and diagnostics go to stderr. Add `--json` for machine-readable output or `--quiet` for counts only.

Read:

```sh
taskessa task list                 # open tasks (titles decrypted locally)
taskessa task list --all --json    # include completed; machine-readable
taskessa task get <id>
taskessa project list
taskessa label list
taskessa habit list
taskessa calendar list --start 2026-06-01 --end 2026-06-07
taskessa planning today
taskessa account plan
```

Write (content from stdin; non-destructive writes apply immediately, destructive ones confirm on a TTY or need `--yes`; `--dry-run` previews without applying):

```sh
echo "Buy oat milk" | taskessa task add --priority High
printf "New title\nNew details" | taskessa task set <id>
taskessa task done <id>
taskessa task rm <id> --yes
echo "Groceries" | taskessa project add
echo "Standup" | taskessa calendar add --start 2026-06-02T09:00:00Z --end 2026-06-02T09:15:00Z
```

Portability and backup (local-only; ciphertext in and out unless you pass `--plaintext`):

```sh
taskessa export --out backup.json                # ciphertext (useless without your key) by default
taskessa export --plaintext --out readable.json  # decrypts locally, guard the file
taskessa import readable.json
taskessa maint backup --out dr.json
taskessa maint reseal                            # local integrity scan
```

A decrypt failure (tamper or wrong key) is shown as `<undecryptable>` and exits with code 7, never a silent gap.

## Connect your own LLM (MCP)

Launch the stdio MCP server:

```sh
taskessa mcp        # identical to running 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`) and write tools for creating, updating, completing, reopening, and deleting tasks, projects, labels, habits, categories, check-ins, and calendar blocks. All content is decrypted locally before it reaches the model and sealed locally before any write leaves your device. Write tools return a dry-run preview unless you pass `confirm=true`.

### Claude Desktop

Store your password in the OS keychain once:

```sh
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):

```json
{
  "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 instead (the output of `which taskessa-mcp`, e.g. `~/.local/bin/taskessa-mcp`). Restart Claude Desktop; the Taskessa tools then appear in the client. Because the server runs on your device with your key, the model sees your decrypted tasks while the Taskessa operator never does.

## Run as an agent (optional)

By default `taskessa` and `taskessa-mcp` run with your account key (full access). You can instead run as one of your **agents**: a separate, revocable identity you own, with its own keypair (generated and kept on your device, never escrowed) and API token. An agent can be **scoped** (it sees only the projects you grant it: least privilege) or **full access** (it reads and writes your whole account). For an automated or always-on LLM, a scoped agent is the safest way to connect: grant it only what it needs, and revoke it anytime.

```sh
echo "Agent perso" | taskessa agent add      # creates the agent (keypair generated locally)
taskessa agent token issue <agent-id>        # issues its token (stored in your keychain)
taskessa --agent <agent-id> task list        # run a command as the agent
TASKESSA_AGENT_PROFILE=<agent-id> taskessa-mcp   # or run the MCP server as the agent
```

Grant a project (or toggle full access) from the web app under **Gérer les agents**. The keys are sealed on your device; the server only ever stores ciphertext, and a revoked agent or token fails closed.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `TASKESSA_EMAIL` | — | Account email. The CLI also prompts for it and remembers it after `auth login`. |
| `TASKESSA_PASSWORD` | — | Password fallback for scripts and automation; prefer the keychain or the interactive prompt. |
| `TASKESSA_AGENT_PROFILE` | — | Run as one of your agents (its id) instead of with your account key: the CLI/MCP authenticate with that agent's local token + key. Same as the CLI `--agent` flag. |

## 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.
- If you lose both your password and your recovery key, your content is unrecoverable, by design.

## Links

- Web app: https://app.taskessa.com
- Privacy policy: https://taskessa.com/privacy