Troubleshooting

Build Fails In Xcode

• Confirm all Swift files are included in the codepro2 target.
• Clean build folder with Cmd+Shift+K and rebuild.
• Verify Swift language version and macOS deployment target are compatible with SwiftUI and AppKit APIs used by the project.
• If resource hook scripts are missing, verify codepro2/Resources/askTerminal-hook.py and askTerminal-codex-hook.py are copied into the app bundle.

Projects Do Not Appear

• Use Add Project to register a folder manually.
• Check ~/.claude/projects for Claude history and ~/.codex/state_5.sqlite for Codex state.
• Confirm the path exists and is readable.
• Inspect ~/.ask-terminal/projects.json after selecting a project.

Claude Todos Are Missing

• Claude task management depends on ~/.claude/tasks/<session-id>.
• Sessions without conversation data may be skipped.
• Codex sessions intentionally show no Claude-style todos.
• Use the Kanban refresh action after external file edits.

Codex Sessions Are Missing

• Verify ~/.codex/state_5.sqlite exists.
• Close or wait for Codex if the SQLite database is locked; the backend retries and can fall back to an immutable snapshot.
• Confirm the session working directory matches the selected project path after path normalization.

Approval Requests Do Not Appear

• Confirm the notch UI was initialized and the hook listener is online.
• Check that hooks were installed under ~/.claude/hooks and ~/.codex/hooks.
• Verify Claude settings or Codex hook config references the askTerminal hook command.
• Restart the app to recreate the socket server.

Quick Agent Does Not Open

• Check whether another app owns Cmd+K.
• Open Settings and confirm the Quick Agent workspace exists.
• Clear the remembered Claude or Codex session if the backend session is stale.

EPIC Inbox Command Is Ignored

• Write complete JSON to a temp file, then atomically move it into ~/.ask-terminal/inbox.
• Use a known project name from ~/.ask-terminal/projects.json or an absolute path.
• Wait roughly one second, then inspect ~/.ask-terminal/state.json.
• Malformed files may be retried during the grace period and renamed to *.bad if still invalid.

Message Bus Command Runs In The Wrong Place

Each subscriber executes the command in its own terminal context. Check the terminal title, current path, and channel subscriptions before publishing broad commands.

Analytics Looks Empty

• Select a project with matching transcript working directories.
• Confirm transcripts exist in the engine-specific directories.
• Check that sessions contain parseable timestamps and usage records; analytics can still show partial results without all fields.