First Run
Install & Setup
Prepare your AI command-line tools, add your first project, and start a session in a few minutes.
Before you begin
- A supported Mac and a copy of AskTerminal.
- Claude Code or Codex installed and signed in. You only need the engine you plan to use.
- A local project folder, or a Git repository URL that you can clone.
Open AskTerminal
Launch the app normally. AskTerminal opens its Projects window and adds a terminal icon to the macOS menu bar. Closing a window hides it; you can bring it back from the menu bar item.
macOS warning: If macOS blocks the first launch, open System Settings → Privacy & Security, find the AskTerminal notice, and choose Open Anyway only if you trust where the app came from.
Add a project
- Open the Project menu and choose Add Project….
- Browse to an existing folder, or enter a Git repository URL and choose Clone.
- Select Claude Code or Codex.
- Choose Start New Session.
AskTerminal may also discover projects from your existing Claude Code and Codex history. Select one from the Project menu to load its sessions.
Enable approval requests
- Open AskTerminal → Settings… or press
Command-,. - Select Hooks.
- Choose Install / Update for Claude Code, Codex, or both.
- Confirm that the status changes to installed.
Hooks let AskTerminal display permission and session events from the CLI. You can remove them later from the same Settings tab.
Set up Quick Agent
- Open the General tab in Settings.
- Choose the engine and workspace folder.
- Press
Command-K, enter a request, and submit it.
Quick Agent remembers a separate conversation for each engine. Use Clear Claude session or Clear Codex session when you want fresh context.
Confirm everything works
- A new terminal opens in the selected project folder.
- The chosen CLI starts without asking you to sign in again.
- The session appears in the Sessions view after refresh.
- If hooks are enabled, a test permission request appears in AskTerminal.