ctask/docs/troubleshooting.md

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:

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

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

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

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

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:

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:

"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:

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:

$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 -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.