Reference

Architecture & Storage

askTerminal is a local-first SwiftUI/AppKit app built around managers, engine backends, file watchers, a Unix socket approval bridge, and project-local JSON files.

High-Level Components

Component	Role
`AppDelegate`	Creates the status item, main window, terminal manager, notch manager, Quick Agent, EPIC services, and desktop-space observers.
`TerminalManager`	Owns terminal lifecycle, selected terminal state, terminal windows, command execution, and system monitoring.
`KanbanManager`	Loads sessions, todos, skills, agents, instructions, file watchers, project context, and auto-resume context.
`SessionEngineBackend`	Protocol that hides Claude/Codex storage differences from views.
`PlansManager`	Reads and writes project EPICs and drains agent result files.
`NotchManager`	Installs hooks, starts approval socket server, and owns the notch window controller.
`QuickAgentManager`	Registers `Cmd+K`, manages quick session settings, streams agent output, and installs the EPIC skill into workspaces.
`AnalyticsViewModel`	Parses transcripts and builds session, tool, risk, heatmap, and comparison rows.

Storage Layout

Path	Owner	Purpose
`~/.claude/projects`	Claude Code	Project transcript JSONL files.
`~/.claude/tasks`	Claude Code / askTerminal	Per-session todo data.
`~/.codex/state_5.sqlite`	Codex	Threads table used for Codex session listing and titles.
`~/.codex/sessions`	Codex	Codex session transcripts.
`~/.ask-terminal/projects.json`	askTerminal	Known project registry.
`~/.ask-terminal/state.json`	askTerminal	Cross-project EPIC snapshot.
`~/.ask-terminal/inbox`	Agents / askTerminal	JSON command dropbox for EPIC operations.
`<project>/.ask-terminal/epics.jsonl`	askTerminal	Project EPIC records.
`<project>/.ask-terminal/sessions`	Agents / askTerminal	Agent result files for EPIC status updates.
`<project>/.ask-terminal/skills`	User / askTerminal	Primary project skills.
`<project>/.ask-terminal/agents`	User / askTerminal	Primary project agents.

Engine Backend Contract

Each backend lists projects and sessions, saves titles, deletes sessions, mutates todos if supported, provides launch commands, and exposes a watch directory. This contract keeps SwiftUI views engine-agnostic.

protocol SessionEngineBackend {
  var engine: AIEngine { get }
  func listProjects() throws -> [String]
  func listSessions(projectPath: String?) throws -> [TodoSession]
  func saveSessionTitle(sessionId: String, projectPath: String?, title: String) throws
  func updateTodo(_ todo: TodoItem, newStatus: TodoStatus) throws
  func newSessionCommand(projectPath: String) -> String
  func resumeSessionCommand(sessionId: String, prompt: String?) -> String
}

Approval Hook Flow

HookInstaller copies bundled Python hooks into Claude and Codex hook directories.
The hook connects to the local Unix socket server.
HookSocketServer decodes hook JSON and creates permission requests.
PermissionContext stores pending requests and continuations.
ToolApprovalHandler sends approval responses back through the socket.

File Watching

The app uses file-system watchers to reload sessions, detect EPIC changes, process inbox commands, drain result files, and reflect Codex/Claude session updates without manual refresh.

<- Analytics Troubleshooting ->