# Troubleshooting

## "ctask" is not recognized

The install directory is not on your PATH, or you need to open a new terminal.

**Fix:**

1. Open a new terminal (PATH changes require a new session)
2. Run `ctask --version`
3. If still not found, verify the install location exists:

```powershell
Test-Path $env:LOCALAPPDATA\ctask\bin\ctask.exe
```

4. If the file exists but the command isn't found, check PATH:

```powershell
$env:Path -split ';' | Select-String 'ctask'
```

5. If not in PATH, re-run the install script:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1
```

## Status line not appearing in Claude Code

The status line shows ctask session context at the bottom of Claude Code's UI. If it's not showing:

**1. Check that the helper script exists:**

```powershell
ctask doctor
```

Look for the "Status line helper found" check.

**2. Check Claude Code configuration:**

`ctask doctor` also checks whether `~/.claude/settings.json` has a `statusLine` entry. If it reports a failure, it gives the exact JSON to add.

**3. Verify the config uses the right path format:**

Claude Code runs statusLine commands through bash. The path must use forward slashes:

```json
"command": "bash /c/Users/Warren/AppData/Local/ctask/bin/ctask-statusline.sh"
```

Not backslashes -- those get stripped by bash.

**4. Restart Claude Code** after changing settings.json.

## ctask doctor failures

### "Workspace root not found"

The default workspace root (`%USERPROFILE%\ai-workspaces`) doesn't exist yet.

**Fix:** Create it, or create your first workspace:

```powershell
ctask new "my first task"
```

### "Agent command not found"

The configured agent (`claude` by default) isn't installed or isn't on PATH.

**Fix:** Install the agent, or set a different one:

```powershell
$env:CTASK_AGENT = "aider"
ctask doctor
```

### "Status line helper not found"

The status-line helper scripts aren't at the expected location.

**Fix:** Re-run the install script:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1
```

### "Claude Code status line not configured"

The `~/.claude/settings.json` file is missing the `statusLine` key or it's misconfigured.

**Fix:** `ctask doctor` prints the exact JSON to add. Copy it into your settings file.

### "No workspaces found"

You haven't created any workspaces yet.

**Fix:** `ctask new "my first task"`

## "Cannot delete the active workspace"

You tried to delete a workspace that has a running session (in this terminal or another).

**Fix:** Exit the session first (close the agent or type `exit` in the shell), then retry the delete.

This protection works by checking for a `.ctask/manifest-start.json` file inside the workspace, which only exists during a live session. It also checks the `CTASK_WORKSPACE` environment variable for same-session attempts.

## Where are my files?

### Installed ctask files

```
%LOCALAPPDATA%\ctask\bin\
  ctask.exe
  ctask-statusline.sh
  ctask-statusline.ps1
```

Default: `C:\Users\<you>\AppData\Local\ctask\bin\`

### Workspace / task folders

```
%USERPROFILE%\ai-workspaces\
  <category>\
    <YYYY-MM-DD>_<slug>\
      task.yaml
      CLAUDE.md
      notes.md
      context\
      output\
      logs\
        sessions.log
```

Default: `C:\Users\<you>\ai-workspaces\`

Override with the `CTASK_ROOT` environment variable.

### Session logs

Each workspace has its own session log at:

```
<workspace>\logs\sessions.log
```

This is an append-only text file recording each session's start/end time, duration, and file changes. View it directly or use `ctask info <query>` to see the workspace contents list.

### Claude Code settings

```
%USERPROFILE%\.claude\settings.json
```

This is where the `statusLine` configuration lives.