Setup

Getting Started

Build and launch the macOS app, connect it to local Claude Code and Codex state, and start the first project-aware agent session.

Requirements

macOS with Xcode installed.
Claude Code installed and authenticated if you want Claude sessions.
Codex CLI installed and authenticated if you want Codex sessions.
A local project directory that can be opened by terminal commands.

Build From Xcode

Open codepro2.xcodeproj.
Select the codepro2 scheme and a macOS destination.
Build with Cmd+B.
Run with Cmd+R.

The app starts as a regular Dock app and also creates a status bar item with a terminal icon. The main window is positioned near the top-right of the active screen and can be resized.

First Launch Behavior

On launch, the app creates core managers, opens the Kanban window, initializes the notch UI, installs Claude and Codex hooks if needed, starts a local hook socket server, and starts the EPIC inbox and aggregator services.

Local-only: The app primarily reads and writes files under your home directory, including ~/.claude, ~/.codex, and ~/.ask-terminal. It does not require a hosted backend for the product features documented here.

Add Or Select A Project

Open the Projects/Kanban window from launch or from the main window.
Use the project selector to choose an existing project discovered from Claude/Codex history, or add a folder manually.
When a project is selected, askTerminal registers it in ~/.ask-terminal/projects.json.
The selected project drives sessions, plans, analytics, instructions, skills, agents, and git views.

Start A Session

From the project controls, choose the engine badge: CC for Claude Code or CX for Codex. Start a new session to open a terminal in the project directory. Existing sessions can be resumed from their session card.

Configure Quick Agent

Open Settings.
Choose the Quick Agent engine.
Set the Quick Agent workspace directory.
Use Cmd+K to open the global Quick Agent input panel.

The Quick Agent keeps separate remembered session IDs for Claude and Codex. Clearing a session in Settings forces the next prompt to create a fresh session for that engine.

Enable Background Agent Continuity

The app includes a power assertion setting named KeepAgentsRunningInBackground. When enabled, askTerminal requests macOS to prevent idle sleep so long-running agent sessions can continue while the machine is unattended.

<- Product Overview Core Workflows ->