Usage
Core Workflows
The common operating loops for project work: launch sessions, resume context, manage tasks, approve tools, inspect changes, and hand EPICs to agents.
Launch A Project Session
- Select a project in the Kanban window.
- Choose Claude Code or Codex.
- Start a new terminal. The terminal opens in the selected project path and runs the engine command.
- Use the terminal window for normal CLI interaction, quick commands, and output review.
Resume Or Fork Existing Work
Session cards in the Kanban view represent known Claude and Codex sessions. Resume reopens the engine with the existing session ID. Fork starts a related session using the engine-specific fork command.
| Action | Claude | Codex |
|---|---|---|
| Resume | claude --resume <id> | codex resume <id> |
| Fork | claude --resume <id> --fork-session | codex fork <id> |
Manage Claude Todos
Claude todo files are loaded from ~/.claude/tasks/<session-id> and rendered as pending, in-progress, and completed cards. You can create, update, move, and delete todos for Claude-backed sessions. Codex sessions are visible but do not expose Claude-style todo mutation.
Review Agent Output
Session rows include title, summary, project path, branch name, files, and conversation access when transcript data is available. The conversation pane loads transcript turns and lets you inspect recent agent activity without finding the JSONL file manually.
Approve Tools
- Claude or Codex emits a hook event for a permission request.
- The installed hook connects to the local socket server.
- The app creates a
PermissionRequest. - The notch UI and permission list display the request.
- Approve, approve always for the tool, or deny.
Approval decisions are also used by analytics to count permission checkpoints and risk events where possible.
Inspect Git Changes
The Git Changes view discovers the repository root for the selected project, lists changed files, loads diffs, displays branch state, and supports operations such as checkout, commit, pull, push, and repo/worktree selection.
Use Quick Agent
Press Cmd+K to open the Quick Agent input panel. It uses the selected Quick Agent engine and workspace from Settings. Messages stream into the notch UI through IslandMessageStore, and the notch opens automatically when new content arrives.
Work With Desktop Spaces
The app includes desktop-space awareness. The main window can follow active Spaces during a switch and then re-pin itself to the new Space. The Spaces carousel also lets the UI expose and name desktop spaces when macOS data is available.