Skip to content
Kangentic

Troubleshooting

Solutions for common issues you may encounter when using Kangentic.

Session Recovery

Section titled “Session Recovery”

Agent Crashed Mid-Task

Section titled “Agent Crashed Mid-Task”

If an agent session crashes unexpectedly:

  1. The task card shows an Exited status
  2. Your work is safe — the git worktree and all file changes are preserved
  3. Drag the task back to any active column to respawn the agent with the same prompt and worktree
  4. The new agent picks up from the file state left behind

Orphaned Sessions

Section titled “Orphaned Sessions”

On rare occasions, a session may show as Orphaned — this means the PTY process exited without Kangentic detecting it cleanly. Orphaned sessions are cleaned up automatically on app restart. You can also drag the task to Done and back to an active column to force a fresh session.

App Crashed During Active Sessions

Section titled “App Crashed During Active Sessions”

Kangentic persists session state to its database. When the app restarts after a crash:

  • Sessions that were running are detected and reconnected if the PTY process is still alive
  • Sessions whose PTY process also died are marked as exited
  • Worktrees and file changes are always preserved regardless of crash state

Agent CLI Issues

Section titled “Agent CLI Issues”

CLI Not Found

Section titled “CLI Not Found”

Kangentic auto-detects each supported agent CLI (claude, codex, gemini, aider) on your PATH. If the one you want isn’t detected:

  1. Verify the CLI is installed: run claude --version / codex --version / gemini --version / aider --version in your terminal
  2. If installed but not found, set the path manually in Settings → Agent → CLI Paths — there’s one row per detected agent
  3. Alternatively, set agent.cliPaths.<agent> in your config file to the full path of the binary (e.g., agent.cliPaths.claude, agent.cliPaths.codex)

On macOS, Kangentic also checks Homebrew fallback paths for Claude Code (/opt/homebrew/bin/claude, /usr/local/bin/claude) to handle the Finder-launch case where Electron doesn’t inherit your shell PATH. Other agents rely on PATH or an explicit override.

Authentication Errors

Section titled “Authentication Errors”

If agents fail to start with authentication errors:

  1. Run the agent CLI directly in your terminal and complete its authentication flow (e.g., claude, codex, gemini, aider)
  2. Kangentic uses each CLI’s own local credentials — it doesn’t manage authentication itself for any agent

Shell Issues

Section titled “Shell Issues”

Wrong Shell Detected

Section titled “Wrong Shell Detected”

Kangentic auto-detects your shell. If it picks the wrong one:

  1. Open Settings → Terminal → Shell
  2. Set the full path to your preferred shell

See Shell Support for the detection order on each platform.

PowerShell Execution Policy (Windows)

Section titled “PowerShell Execution Policy (Windows)”

If agents fail on Windows with execution policy errors, PowerShell may be blocking script execution. Run this in an elevated PowerShell:

Terminal window
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

WSL Path Issues

Section titled “WSL Path Issues”

If WSL paths aren’t resolving correctly, ensure your project is on a Windows-accessible path. Kangentic converts between Windows and WSL paths automatically, but paths on WSL-only filesystems (like \\wsl$\) may cause issues.

Git Worktree Issues

Section titled “Git Worktree Issues”

Worktree Creation Fails

Section titled “Worktree Creation Fails”

Common causes:

  • Uncommitted changes on the base branch — commit or stash changes before creating tasks
  • Branch name conflicts — Kangentic generates unique branch names (kanban/<slug>-<id>), but if a conflicting branch exists, delete it manually
  • Locked index — another git process may hold the lock. Check for .git/index.lock and remove it if stale

Worktree Cleanup

Section titled “Worktree Cleanup”

Worktrees are cleaned up automatically when tasks move to Done (if git.autoCleanup is enabled). To manually clean up:

  1. Move the task to Done
  2. Or delete the task from the board
  3. The worktree directory and its branch are removed

If a worktree directory persists after cleanup, remove it manually:

Terminal window
git worktree remove .kangentic/worktrees/<slug>

Performance

Section titled “Performance”

High Memory Usage

Section titled “High Memory Usage”

Each concurrent agent session runs a separate PTY process. If memory is constrained:

  • Reduce agent.maxConcurrentSessions in settings (default: 8)
  • Move idle tasks to Done to suspend their sessions
  • Close projects you’re not actively using

Slow Terminal Rendering

Section titled “Slow Terminal Rendering”

If terminal output is laggy:

  • Reduce terminal.scrollbackLines (default: 5000)
  • Close the terminal preview on task cards (terminal.showPreview: false)

Data and Configuration

Section titled “Data and Configuration”

Reset Project Configuration

Section titled “Reset Project Configuration”

To reset a project’s settings to defaults, delete its local config:

Terminal window
rm <project>/.kangentic/config.json

The project will use global settings on next launch.

Database Issues

Section titled “Database Issues”

Kangentic uses SQLite for data storage. If the database becomes corrupted:

  1. Close Kangentic
  2. Delete the database file from the data directory
  3. Relaunch — a fresh database is created automatically

Finding Log Files

Section titled “Finding Log Files”

Set KANGENTIC_LOG_LEVEL=debug to enable verbose logging. Logs are written to the platform-standard log directory:

%APPDATA%/kangentic/logs/