# Install the Taskhold CLI (optional)

> Most agents need nothing installed. One command adds the Taskhold terminal board and the Claude Code status line. How updates, pins and uninstall work.

Source: https://taskhold.com/install
Last updated: 2026-10-26

Most agents need nothing installed. Taskhold's MCP server is remote: Claude Code, Cursor, Codex, Windsurf and most other clients connect to https://taskhold.com/api/mcp over HTTPS, and the setup URL in Settings gives your agent the exact config.

The CLI on this page is optional. It adds a live board in your terminal, the task in progress in the Claude Code status line, and a stdio server for clients that can't reach a remote one. It comes from taskhold.com, not the npm registry.

## Install the CLI

```bash
curl -fsSL https://taskhold.com/install.sh | sh
```

Read the installer first if you like: https://taskhold.com/install.sh (about 80 lines of sh).

- Needs Node.js 18 or later, or Bun. No sudo: everything goes in ~/.taskhold.
- Downloads the latest build from taskhold.com and checks its sha256 against /dl/latest.json before installing anything.
- Links taskhold-mcp into ~/.local/bin when that folder is on your PATH. Otherwise it prints the PATH line to add, and the full path ~/.taskhold/bin/taskhold-mcp works everywhere.

Then save your API key (Settings, API keys):

```bash
taskhold-mcp login
```

Paste the atd_sk_ key when asked. It is checked against the API and stored in ~/.taskhold/config.json, readable only by you. TASKHOLD_API_KEY in the environment wins over the saved key.

## Watch your agents from the terminal

```bash
taskhold-mcp watch
```

The live board in a terminal: tasks in progress with a bar split by step, what each agent says it is doing, blocked tasks with their question, and recent activity. It redraws as events arrive over the events stream and reconnects on its own. Ctrl-C quits.

## Show the task in the Claude Code status line

```bash
taskhold-mcp statusline --install
```

This adds a statusLine entry to ~/.claude/settings.json and keeps a backup next to it. If you already have a status line, it leaves yours alone and tells you; add --force to replace it. New Claude Code sessions show the line:

```text
▶ Deploy v2.4 to staging ███░░░░░░░ 33% 1/3 · Run migrations
```

To mix Taskhold into a status line you already like, use the [status line recipe](/docs/claude-code-status-line) or the [status line generator](/tools/claude-code-statusline) instead.

## Use the stdio server

For MCP clients that only run local servers. npx downloads the latest build from taskhold.com each time the client starts the server:

```json
{
  "mcpServers": {
    "taskhold": {
      "command": "npx",
      "args": [
        "-y",
        "https://taskhold.com/dl/taskhold-mcp-latest.tgz"
      ],
      "env": {
        "TASKHOLD_API_KEY": "atd_sk_..."
      }
    }
  }
}
```

With Bun: bunx -p https://taskhold.com/dl/taskhold-mcp-latest.tgz taskhold-mcp

If you installed the CLI, the installed copy is a faster stdio server: set command to its full path (for example /Users/you/.taskhold/bin/taskhold-mcp), no args. It reads the saved key.

## Updates and version pins

- taskhold-mcp update installs the latest version. taskhold-mcp update 1.3.0 installs that version and pins it.
- The CLI checks for a new version at most once a day and prints one line when there is one. The line goes to stderr, so an MCP client never sees it. Turn it off with TASKHOLD_NO_UPDATE_CHECK=1; pinned installs don't check.
- npx configs that use taskhold-mcp-latest.tgz get each new version on the next start. To pin one, put the version in the file name: taskhold-mcp-1.3.0.tgz.
- To pin at install time: curl -fsSL https://taskhold.com/install.sh | sh -s -- --version 1.3.0

## Current version and checksums

| File | Size | sha256 |
| --- | --- | --- |
| taskhold-mcp-1.3.1.mjs | 915 KB | e145a102e4c3c04b625488f08628a3d590e4e27e5c80b865fa09992290dc25ef |
| taskhold-mcp-1.3.1.tgz | 194 KB | c2335aad84d16ac1ad220dff3f4e4819e264ac4cade2be7f35188fdfbf914940 |

taskhold-mcp 1.3.1, released 2026-10-26. Every release with its checksums: https://taskhold.com/dl/releases.json. A released file never changes; a new build gets a new version number.

Check a download yourself:

```bash
curl -fsSL https://taskhold.com/dl/taskhold-mcp-1.3.1.mjs | shasum -a 256
```

## Uninstall

```bash
taskhold-mcp uninstall
```

Removes ~/.taskhold, the ~/.local/bin link and the Claude Code status line if the installer set it. By hand: rm -rf ~/.taskhold. Stdio entries in an MCP client config are yours to delete. The remote server has nothing to uninstall; revoke its key in Settings.

## Related

- [Quickstart: watch your agent's first plan in 5 minutes](https://taskhold.com/docs/quickstart.md)
- [Show the current task in the Claude Code status line](https://taskhold.com/docs/claude-code-status-line.md)
- [Troubleshooting Taskhold: errors, missing tools, no progress](https://taskhold.com/docs/troubleshooting.md)