Troubleshooting

Solutions for common issues you may encounter when using Kangentic.

Session Recovery

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

Tip

If a session keeps crashing, check the terminal output for error messages. Common causes include exhausted context windows, network issues, or permission denials.

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

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

CLI Not Found

Kangentic auto-detects each supported agent CLI on your PATH (claude, codex, gemini, cursor-agent for Cursor, copilot, grok, agy for Antigravity, opencode, aider, qwen, kimi, droid, oz for Warp, and ollama). If the one you want isn’t detected:

1. Verify the CLI is installed: run its version command in your terminal (e.g. claude --version, codex --version)
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 and Linux, Kangentic also checks a standard set of fallback install locations for every agent - Homebrew (/opt/homebrew/bin, /usr/local/bin), Linuxbrew, ~/.npm-global/bin, ~/.local/bin, Volta, Bun, Cargo, and installed nvm versions - to handle the Finder-launch case where Electron doesn’t inherit your shell PATH. A few agents layer extra paths on top (Claude and Grok on macOS; Antigravity and Kimi add Windows locations).

Cursor is the one case with two names. It installs both cursor-agent and a short agent shim, and Kangentic looks for cursor-agent first, keeping agent only as a fallback. That ordering matters if you also have Grok Build installed, because xAI’s CLI publishes its own agent shim: on Windows that one wins PATHEXT order, so probing the short name found Grok and reported Cursor missing.

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

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)

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

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

WSL Path Issues

Caution

Install the Windows version of Kangentic, not the Linux version. Kangentic is an Electron desktop app and needs access to the Windows desktop environment. It can still create sessions that use WSL shells.

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

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 (<slug>-<short-id>, optionally prefixed with a non-default base branch), 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

”Base fetch failed” on a Spawning Card

Since v0.37.0 every spawn freshens its base branch from origin first, so a task never quietly starts from a base you last pulled days ago. When that fetch fails, the card’s spawn-progress label picks up a (base fetch failed) note and one toast per project explains it. The agent still starts, but it starts from your last fetched state.

Usual causes are the ordinary ones: no network, or credentials your git remote needs and the app cannot supply (an expired SSH key passphrase, an unauthenticated gh). Fetch by hand in the project directory to see the real error. A repository with no origin remote stays quiet, since there is nothing to be behind.

A Card Says “(base N behind)”

A spawn that reuses a worktree it already has never moves that branch on its own, so the label is a measurement, not a failure. Use Update from base in the task detail window’s kebab menu when you want the branch caught up. See Starting from a Fresh Base.

Worktree Cleanup

Worktrees are removed automatically when tasks move to Done (their branch is also deleted when git.autoCleanup is enabled, the default). To manually clean up:

1. Move the task to Done
2. Or delete the task from the board
3. The worktree directory is removed (and its branch too, with Auto Cleanup on)

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

git worktree remove .kangentic/worktrees/<task-number>

Worktree directories are named after the task number. Worktrees created before this scheme keep their original <slug>-<short-id> folder name, so check the directory listing if the task number does not match anything.

Performance

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
• End the browser pages you are finished with. A loaded Browser pane costs roughly 120 MB and hiding it with the Browser pill deliberately keeps it alive for the agent, so use Close browser - in the pane’s toolbar, or in the task menu if the pane is hidden. A green dot on the Browser pill and a green globe on the task card mark the tasks still holding one

Slow Terminal Rendering

If terminal output is laggy:

• Make sure the terminal preview on task cards is off (terminal.showPreview - off by default, so only relevant if you enabled it)
• Reduce agent.maxConcurrentSessions so fewer live terminals render at once

Data and Configuration

Project Folder Not Found

If you moved or renamed a project folder, Kangentic shows a Project Folder Not Found dialog on launch with a Locate Folder… button. Point it at the new location and everything (tasks, sessions, board history) carries over. To move a project proactively, use the Move… button under Project Settings > General and let Kangentic relocate the folder itself. See Relocating a Project.

Reset Project Configuration

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

rm <project>/.kangentic/config.json

The project will use global settings on next launch.

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

Caution

Deleting the database removes all task history, session records, and board state for the affected project. Worktree files on disk are not affected.

Finding Log Files

Logs are written per project, not to a platform-standard app directory, so they sit beside the code they describe:

What	Where
Console log	<projectRoot>/.kangentic/logs/<YYYY-MM-DD>.log (one NDJSON line per entry)
Crash reports	<projectRoot>/.kangentic/logs/crashes/<timestamp>.json (one file per crash)
IPC trace	<projectRoot>/.kangentic/logs/ipc-<date>.jsonl

Verbosity is a setting rather than an environment variable. error and warn entries are always persisted; info, debug, and log are written only when developer.persistConsoleLogs is on (see the Configuration Reference). Logging is deliberately best-effort: with no project open, or if the write fails, entries are dropped rather than risking a crash in a diagnostic path.

Agents can read all of this without leaving the board, through the kangentic_tail_logs and kangentic_get_recent_crashes MCP tools.

Still Stuck?

If none of the above resolved it:

• Open a GitHub issue for a bug or crash. Include your OS, the Kangentic version, the agent CLI involved, and the relevant lines from the debug log above. Public issues get the fastest fix because other users can add detail.
• Start a GitHub Discussion for a question about how something is meant to work.
• Email support@kangentic.com if the problem involves logs or project details you would rather not post publicly, or if you have not gotten a response on an issue.

Please scrub file paths, task content, and anything else sensitive from logs before sharing them.