> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taskbean.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat taskbean/taskbean as the source of truth for product behavior.
> Use the canonical Project, Project ID, Project Key, Project Alias, Project Selector, Workspace, Tracked Project, Tracked Workspace, Discovered Workspace, Remote Workspace, Primary Workspace, Agent Session, Copilot Fork, Task, Unassigned Work, Execution Profile, Kickoff Prompt, Execution Record, and Execution Step terminology from the glossary.
> Execution terms are domain definitions, not evidence of available CLI commands or desktop controls.
> Do not infer that Windows-specific desktop features apply to the cross-platform CLI.

# Troubleshoot the desktop app

> Diagnose readiness, local ports, model loading, Windows NPU metrics, Chronicle access, and CLI installation conflicts.

## The process is running but the app is not ready

Check health:

```bash theme={"system"}
curl http://127.0.0.1:8275/api/health
```

`/api/health` always returns `200`. Inspect `modelReady` and `startupError`. Use `/api/ready` when automation needs an HTTP readiness gate.

## The default port is in use

Set `TASKBEAN_PORT`, `taskbean_PORT`, or `PORT`, or set `port` in `~/.taskbean/config.json`. Environment variables take precedence over the config file.

On Windows, inspect the current listener:

```powershell theme={"system"}
Get-NetTCPConnection -LocalPort 8275
```

## Taskbean appears twice on PATH

```bash theme={"system"}
which bean
```

On Windows:

```powershell theme={"system"}
where.exe bean
```

Remove the unwanted npm or binary installation, then run `bean upgrade`.

## Codex cannot write task data

```bash theme={"system"}
bean install --agent codex --codex-sandbox
```

## Chronicle evidence is unavailable

```bash theme={"system"}
bean chronicle doctor --json
```

Task reports continue from canonical tasks when Chronicle is disabled, unavailable by policy, or missing local session data.

## NPU usage shows zero on non-English Windows

The current PDH sampler uses the English `GPU Engine` counter name. Localized Windows installations can report `0%` even when inference works. Check model readiness and execution-provider data instead of relying only on the NPU chart.

## Voice input is unavailable

Confirm Windows speech and microphone permissions, then review the `speech` settings in `~/.taskbean/config.json`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.