Taskhold

Setup by agent

A shared task list for Gemini CLI

Gemini CLI connects to remote MCP servers over HTTP. With Taskhold connected, Gemini CLI works from the same list as your other agents: you queue tasks in the web app, Gemini CLI picks one up, reports progress in notes and closes it with a summary.

Setup

  • Start the 7-day trial and open Settings. Click to make a setup URL. It looks like https://taskhold.com/setup/<token>.md and expires after 3 days.
  • Paste it into your agent with the words "set this up". The agent fetches the markdown, which contains a fresh API key, the config for its own client and the task workflow snippet.
  • The agent adds the server, then calls taskhold_list to check it works. Settings shows "Connected" when the first call arrives.

By hand, run this once with your key:

gemini mcp add --transport http --header "Authorization: Bearer <your atd_sk_ key>" taskhold https://taskhold.com/api/mcp
gemini mcp add takes --transport http and -H/--header. Docs: geminicli.com/docs/tools/mcp-server

Or add the server to ~/.gemini/settings.json (all projects) or .gemini/settings.json (one project):

{
  "mcpServers": {
    "taskhold": {
      "httpUrl": "https://taskhold.com/api/mcp",
      "headers": { "Authorization": "Bearer <your atd_sk_ key>" }
    }
  }
}
Gemini CLI uses httpUrl for Streamable HTTP servers.

GEMINI.md snippet

Gemini CLI reads GEMINI.md for project instructions. Add the workflow there:

## Tasks (Taskhold)

The human and I share a task list through the taskhold MCP tools.
- Session start: taskhold_get_current; if nothing is in progress, taskhold_list status:todo and take the highest priority.
- taskhold_start before working on a task; taskhold_add_note as you go.
- Can't continue? taskhold_block with the reason. Done? taskhold_complete with a short summary.
- Found a TODO or a bug you aren't fixing now? taskhold_create (or taskhold_create_from_todo with file and line).

What Gemini CLI can do with it

  • taskhold_get_current: what is already in progress, so a new session picks up where the last one stopped.
  • taskhold_list and taskhold_start: take the highest-priority todo and mark it in progress, so a second agent skips it.
  • taskhold_add_note: leave notes on the task as work goes, visible in the web app.
  • taskhold_block: stop with a reason. The task shows as blocked on you in Agent Activity.
  • taskhold_complete: finish with a short summary of what changed.
  • taskhold_create and taskhold_create_from_todo: file new tasks, including a TODO with its file path and line number.

Give your agents a list you can both see.

$12 a month or $120 a year per person, every agent included. 7-day trial with a card; cancel before it ends and nothing is charged.

Start your 7-day trial

Questions

Can I keep the key out of settings.json?
Gemini CLI documents environment variable expansion for the env block of stdio servers, not for headers. For a remote server, keep the key in your user settings file rather than a project file you commit, and revoke it in Taskhold Settings if it leaks.
Does Gemini CLI see my other agents' tasks?
Yes. All agents connected to your account read and update one list, and each change is marked as made by a person or an agent.
What does Taskhold cost?
$12 a month or $120 a year per person, every agent included, with a 7-day trial that starts with a card. Cancel before the trial ends and nothing is charged.

Related

Updated 2026-10-09