Documentation

Getting Started

Installation

Homebrew (recommended):

brew tap AwalTerminal/tap
brew install --cask awal-terminal

No quarantine workarounds needed — Homebrew handles it automatically.

Manual download:

Download the latest .zip from the releases page. After extracting, right-click (or Control-click) the app, choose Open, then click Open in the dialog to bypass macOS Gatekeeper.

If that doesn't work, open Terminal and run:

xattr -cr AwalTerminal.app

Then drag the app to your /Applications folder.

First Launch

On first launch, Awal Terminal presents an LLM launcher menu where you can select your model: Claude, Gemini, Codex, or Shell (no AI). Pick a model and start your session.

Resume Sessions

The startup menu includes a Resume Session submenu for picking up where you left off. For Claude, it lists your most recent sessions per workspace with approximate turn counts and timestamps, then launches claude --resume. For Codex and Gemini, it opens their built-in session pickers (codex resume and gemini --list-sessions). Session data is loaded lazily — only when you open the submenu.

Configuration

The main config file lives at ~/.config/awal/config.toml. You can also open the Preferences window with Cmd+, for a GUI editor.

Permissions

Awal Terminal may request the following macOS permissions:

Both permissions can be managed in System Settings > Privacy & Security. Voice features are fully disabled by default and no permission prompts appear unless you opt in.

Terminal Basics

Tabs

Tabs

Custom Tab Colors & Titles

Right-click any tab to change its color from an 8-color palette or pick a custom color. You can also set a custom title for each tab via the right-click context menu.

Worktree Isolation

Each tab can optionally get its own git worktree, allowing you to work on multiple branches simultaneously without stashing or switching. Enable per-tab worktrees in your config:

[tabs]
worktree_isolation = true
worktree_branch_prefix = "awal/tab"  # default prefix for worktree branches

When creating a new tab with worktree isolation enabled, a prompt dialog lets you select the base branch for the worktree. Manage all worktrees from Shell > Manage Worktrees, which provides a status overview, cleanup actions, and orphan worktree pruning.

Tabs automatically close when their LLM session process exits.

Plan-Aware Tab Naming

When an AI agent outputs a plan header (e.g. "Here is Claude's plan:"), Awal detects the plan title from the following line and shows a banner at the bottom of the terminal offering to rename the tab. Click Rename to apply the plan title as the tab name, or dismiss the banner to keep the current title. Previously dismissed titles won't re-trigger.

Tab Groups

Organize related tabs into named, color-coded groups. Groups keep their member tabs contiguous and can be collapsed to save space.

Right-click any tab for additional group actions: add to group, remove from group, rename group, or ungroup. Drag a tab onto a group header to move it into that group. Tearing off a grouped tab moves the entire group to the new window.

Switch between a horizontal top bar and a vertical sidebar layout with the tabs.orientation config option:

[tabs]
orientation = "vertical"  # "horizontal" (default) or "vertical"

You can also toggle the orientation from Preferences > Tabs.

Show an animated activity indicator on tabs when AI is generating output with the tabs.loading_indicator config option:

[tabs]
loading_indicator = true  # false (default)

Quick Terminal

Press Ctrl+` to toggle a quake-style dropdown terminal from the top of the screen (40% height). The quick terminal is persistent across app switches — it stays available even when you focus other applications.

AI Features

Smart Output Folding

Awal Terminal automatically detects and collapses verbose regions in AI output to keep your terminal clean:

• Tool use blocks (Read, Write, Edit, Bash, Glob, Grep, Agent, etc.)
• Tool output (box-drawing character regions)
• Code blocks (fenced with language detection)
• Thinking/reasoning blocks
• Diffs (git-style)
• Cost summaries, separators, and prompts

Click column 0 to toggle any fold open or closed.

Syntax Highlighting

Code blocks in AI output are colorized with a One Dark-inspired scheme. Supported languages: Python, Rust, Swift, JavaScript/JSX, TypeScript/TSX, Go, C/C++, Java, Shell/Bash/Zsh, and Ruby.

Smart Copy

When you copy text from within a code block, Awal strips prompt decorations and fence markers automatically.

AI Side Panel

Toggle with Cmd+Shift+I. The side panel displays live session metrics:

• Token usage — input, output, and total token counts with cost estimation:
  • Claude: $3/M input, $15/M output
  • Gemini: $1.25/M input, $5/M output
  • Codex: $2.50/M input, $10/M output
• Context window — utilization bar (green <50%, yellow 50-80%, red >80%)
• Activity metrics — tool calls, code blocks, and diffs count
• Files referenced — extracted from tool labels
• Git changes tree — with status badges (M/A/D/R/?). Click a file to view its colored diff in a popover; double-click to copy its path
• Elapsed time — since session start

Remote Control

Awal Terminal automatically detects when Claude Code enables remote control mode. When detected:

• A blue REMOTE badge appears in the status bar
• Click the badge to open a QR code popover — scan it with your phone to connect to the session
• The popover also shows the session URL with a Copy URL button
• Use View → Enable Remote Control to send the /remote-control command to an active Claude session
• Remote control state automatically resets when a new session starts

Stealth Mode

Stealth mode covers all screens with a black overlay, hiding your terminal content while your session continues running safely in the background. Useful when you need to step away or share your screen without revealing terminal output.

• Activate from View → Stealth Mode (requires Prevent Sleep to be active)
• A breathing LED indicator shows the terminal is still running behind the overlay
• Press any key or click to dismiss the overlay and return to your session
• Multi-monitor aware — all screens are covered simultaneously

LLM Integration

AI Components

Awal Terminal can auto-detect your project stack (Go, Flutter, Swift, Python, etc.) and inject relevant AI components into your coding sessions. It also detects sub-stacks — frameworks like Next.js, Django, Flask, Vapor, NestJS, Remix, and more — for more targeted component injection. Components are loaded from shared Git registries and injected per model.

Component Types

Model Support

Not all component types are available for every model. The table below shows how each type is injected per model:

How It Works

1. Awal detects your project type by scanning for marker files (e.g., go.mod, pubspec.yaml, Package.swift)
2. Sub-stacks are detected for frameworks like Next.js, Django, Flask, Vapor, NestJS, Remix, and more
3. Common components are loaded for all projects
4. Stack-specific components are loaded based on detected project type and sub-stacks
5. Components are injected into the AI session: Claude via the plugin system, Gemini via --system-instruction-file, Codex via --instructions

Status Bar

When AI components are active, the status bar shows the detected stack and component count (e.g., flutter · 3 skills, 2 rules). Click it to see the full list of active components.

Default Registry

Awal ships with the awal-components registry pre-configured. It includes common coding rules, skills, and stack-specific components for Go, Flutter, Swift, Python, Rust, Node.js, Java, C#, Kotlin, PHP, Ruby, Zig, Elixir, and C++.

Registry Types

Awal supports three types of registries:

• Git — Any Git repository that follows the registry structure. Cloned and pulled automatically.
• localskills — Skills from the localskills marketplace. The CLI is auto-installed via npm if not found.
• Local — A local directory on your machine, read in-place without cloning.

Custom Registries

Add registries via AI Components > Manage Components > + Add, or in your config file:

[ai_components]
enabled = true
auto_detect = true
auto_sync = true
sync_interval = 3600
security_scan = true

# Default registry (included out of the box)
[ai_components.registry.awal-components]
url = "https://github.com/AwalTerminal/awal-ai-components-registry.git"
branch = "main"

# Add your own Git registry
[ai_components.registry.my-team]
url = "https://github.com/my-org/ai-components.git"
branch = "main"

# localskills registry (auto-installs CLI via npm)
[ai_components.registry.my-skill]
type = "localskills"
slugs = "ZpDEwZj1Yq"

# Local directory registry
[ai_components.registry.my-local]
type = "local"
path = "/path/to/local/registry"

Multiple registries are merged — components from all registries are loaded together. Use the AI Components > Manage Components menu to manage registries, browse loaded components, and configure sync settings.

Security Scanning

Awal scans registry contents for potentially dangerous patterns like shell commands, environment variable access, and network requests. Critical findings are blocked by default. Configure with security_scan = true and block_critical = true in your config.

Open the Security Rules Editor from the AI Components Manager to view all built-in detection rules, their severity levels, and pattern descriptions. Each rule has a checkbox to toggle it on or off — disabled rules are skipped during scans. You can also disable rules via the disabled_rules config key (comma-separated rule names).

Scan results are now persisted across sessions and automatically re-triggered when a registry mapping is resolved, so you always see up-to-date findings without manually re-scanning.

Per-Component Toggles

Disable individual components without removing their registry. Use the checkboxes in the AI Components Manager, or add component keys to the disabled list in your config:

[ai_components]
disabled = "my-registry/common/skill/some-skill, my-registry/node/rule/some-rule"

Import & Export

Share your registry configurations with teammates. Use AI Components > Import & Export to export your current setup or import a shared configuration bundle. Configure export behavior in your config:

[ai_components.export]
enabled = true          # Enable export functionality
formats = "json,toml"   # Supported export formats
target = "clipboard"     # Export target: "clipboard" or "file"

Hooks

Hooks are shell scripts that run automatically at specific points in an AI session. Place them in the appropriate directory under your registry's stack folder:

• Pre-session (hooks/pre-session/) — Runs when a session starts. Example: flutter pub get to ensure dependencies are up to date.
• Post-session (hooks/post-session/) — Runs when a session ends. Example: dart format . to auto-format code.
• Before-commit (hooks/before-commit/) — Runs before Bash tool calls (Claude only, via PreToolUse). Example: format staged files before they're committed.

Hooks are injected into Claude's settings automatically. For other models, pre-session and post-session hooks are executed directly by Awal Terminal.

Hook Approval Gate: Hooks from registries require explicit user approval before first execution. This prevents untrusted registries from running arbitrary scripts. Disable this with require_hook_approval = false in your [ai_components] config (default: true). All approval and revocation events are logged in an audit trail, accessible from the AI Components Manager.

AI Components Manager

Open the dedicated manager window from AI Components > Manage Components in the menu bar. The manager lets you browse all loaded components across registries, view component details, and manage sync settings. You can also trigger a manual sync with Cmd+Shift+Y.

After a sync, a notification banner shows what changed — added, removed, and updated components — so you can review exactly what was modified.

Each registry has a colored status dot indicating its state. Hover over a dot to see its meaning, or refer to the legend row below the registry table:

• ● Synced — standard structure, no warnings
• ● Mapped — custom mapping configured
• ● Needs Mapping — non-standard structure, needs mapping
• ● Error — sync failed or structure warnings
• ○ Not Cloned — registry has not been cloned yet

Stack Overrides

Force specific stacks for a project path instead of auto-detection:

[ai_components.overrides."/Users/me/my-project"]
stacks = "go,flutter"

Registry Mapping

Not all registries follow the standard directory structure that Awal expects. The Registry Mapping feature resolves non-standard repo layouts by letting you define rules that map repository paths to Awal component types (skills, rules, prompts, agents, MCP servers, hooks).

Opening the Mapping Editor

Go to AI Components > Manage Components, select a registry, then click the "Mapping…" button in the toolbar.

Editor Layout

• File tree (left) — Browse the registry's directory structure and select paths to map.
• Mapping rules table (right) — View, add, edit, and delete mapping rules. Each rule maps a glob pattern to a component type.
• Preview (bottom) — Shows which components would be resolved from the current mapping rules.

Auto-Detection

Before you need to create manual mappings, Awal tries to detect the structure automatically:

• Standard directory layout (e.g. skills/, rules/, prompts/)
• claude-plugin manifests in the repository
• In-repo .awal-mapping.json files provided by registry authors

Manual mappings are only needed when none of these methods apply.

Mapping Storage

Mappings are stored per-registry at ~/.config/awal/mappings/{registryName}.mapping.json.

Large Paste Protection

When you paste text that exceeds a configurable character threshold (default: 100,000 characters), Awal Terminal shows a confirmation dialog instead of pasting immediately. This prevents accidentally flooding your terminal or AI session with massive content.

The dialog offers four options:

• Save to File & Paste Path — Saves the clipboard content to a temporary file and pastes the file path instead.
• Paste All — Pastes the full content as-is.
• Paste Truncated — Pastes only the first N characters (default: 10,000), configurable via paste.truncate_length.
• Cancel — Aborts the paste.

Configure thresholds in config.toml:

[paste]
warning_threshold = 100000   # Show dialog above this many characters
truncate_length = 10000      # Characters to keep when truncating

Voice Input

Awal Terminal includes voice input powered by Apple's on-device speech recognition (SFSpeechRecognizer).

How It Works

Voice Commands

Screenshot to Session

Quickly capture a screen region and paste its file path into the active terminal session. This is especially useful when working with AI agents that accept image paths as input.

How to Use

• Press Cmd+Shift+S or click the camera icon in the status bar.
• The macOS screenshot selection UI appears — drag to select a region.
• The captured image’s file path is pasted into the terminal. Press Enter to confirm.
• Press Escape during selection to cancel — nothing is pasted.

Details

• Screenshots are saved as temporary PNG files and cleaned up when the app quits.
• The file path is shell-escaped, so paths with spaces or special characters work correctly.
• No trailing newline is added — you can review or edit the path before pressing Enter, matching drag-and-drop behavior.
• The camera icon appears in the status bar alongside voice controls when an AI session is active.

Mission Control

Mission Control is a dashboard window that gives you a bird's-eye view of every active AI agent running across all tabs and windows. Toggle it with Cmd+Shift+D.

Dashboard Overview

The Mission Control window displays a live-updating table of all active AI agents with the following columns:

• Tab / Window — which tab and window the agent is running in
• Model — the LLM model in use (Claude, Gemini, Codex, etc.)
• Status — real-time status indicator (thinking, tool use, idle, waiting for input)
• Tokens — input and output token counts for the session
• Cost — estimated spend for the session based on model pricing
• Elapsed — time since the agent session started
• Kill Switch — a button to immediately terminate the agent process

Aggregate Metrics

The top of the dashboard shows aggregate totals across all active agents: total tokens consumed, total estimated cost, and the number of active sessions. This makes it easy to monitor overall spend at a glance.

Per-Tab Token Tracking

Each tab independently tracks its own token usage and cost. These per-tab metrics feed into both the AI side panel and the Mission Control dashboard, so you always know exactly what each agent session is consuming.

Session Recording

Record your AI coding sessions and export them as shareable GIFs. Perfect for demos, documentation, and team reviews.

Recording

• Press Cmd+Option+Shift+R to start recording. A red dot indicator appears in the status bar.
• Press Cmd+Option+Shift+R again to stop recording.
• An export dialog appears automatically — choose where to save the GIF.
• Progress is shown in the status bar during export. The file is revealed in Finder on completion.

Export Details

• GIF — optimized animated GIF, ideal for embedding in pull requests, READMEs, and chat
• Idle compression — long idle periods are automatically compressed so you see only the action

Automatic Updates

Awal Terminal includes a built-in update checker that keeps you informed about new releases without interrupting your workflow.

How It Works

The app checks GitHub Releases for new versions automatically on launch and every 4 hours while running. When a newer version is detected, a green badge appears in the status bar to let you know an update is available.

Update Dialog

Click the green badge or use Awal Terminal > Check for Updates… from the App menu to open the update dialog. The dialog displays the release notes for the new version so you can review what has changed before updating.

Installation Methods

Awal Terminal detects how it was installed and offers the appropriate update path:

• Homebrew installations — The dialog shows an Update via Homebrew button that runs the cask upgrade for you.
• Manual installations — The dialog shows a Download Update button that takes you to the latest release download.

Manual Check

You can check for updates at any time via the Awal Terminal > Check for Updates… menu item, regardless of the automatic check schedule.

Configuration

The config file is located at ~/.config/awal/config.toml. You can also use the Preferences window (Cmd+,) which provides a GUI with structured tree and raw text editing modes.

[font]
family = "JetBrains Mono"
size = 13.0

[theme]
bg = "#1e1e1e"
fg = "#d5d5d5"
cursor = "#cccccc"
selection = "#6366f1"
accent = "#6366f1"
tab_bar_bg = "#161616"
tab_active_bg = "#232323"
status_bar_bg = "#161616"

[colors]
0 = "#1e1e1e"    # black
1 = "#f7768e"    # red
2 = "#a6e22e"    # green
3 = "#e6c07b"    # yellow
# ... 4-15 for remaining ANSI colors

[keybindings]
new_tab = "cmd+t"
command_palette = "cmd+shift+p"
# any action = "modifier+key"

[voice]
enabled = false
push_to_talk_key = "ctrl+shift+space"
vad_threshold = 0.02
language = "en"
dictation_auto_enter = false
dictation_auto_space = true

[paste]
warning_threshold = 100000
truncate_length = 10000

[tabs]
random_colors = true
# random_color_palette = "#E55353, #3498DB, #27AE60"
confirm_close = true
loading_indicator = true
worktree_isolation = false
# worktree_branch_prefix = "awal/tab"

[quit]
confirm_close = true

[system]
prevent_sleep = false

[ai_components]
enabled = true
auto_detect = true
auto_sync = true
sync_interval = 3600
security_scan = true
block_critical = true
require_hook_approval = true
remote_control = false
disabled_rules = "rule-name-1, rule-name-2"
tool_names = "Bash, Read, Write"

[recording]
max_duration = 300

[ai_components.registry.awal-components]
url = "https://github.com/AwalTerminal/awal-ai-components-registry.git"
branch = "main"

[ai_components.registry.my-skill]
type = "localskills"
slugs = "ZpDEwZj1Yq"

Theme Colors

Font Settings

Set family to any installed monospace font and size to a float value (e.g., 13.0).

Keybindings

Any action can be rebound with the format action = "modifier+key". Available actions:

• new_tab, close_tab, next_tab, prev_tab, rename_tab
• find, copy, paste, preferences, quit
• toggle_side_panel, quick_terminal, push_to_talk, sync_components
• settings, manage_components, command_palette, screenshot
• mission_control, start_recording, remote_control

Voice Settings

Enable voice input by setting enabled = true under [voice]. Voice uses push-to-talk mode with on-device speech recognition (Apple SFSpeechRecognizer). Configure the hotkey, sensitivity threshold, and language.

AI Components Settings

Add registries with [ai_components.registry.<name>] sections. Git registries use url and branch; localskills registries use type = "localskills" and slugs; local registries use type = "local" and path.

Tab Settings

Paste Settings

Quit Settings

When quit.confirm_close is enabled, Awal Terminal shows a confirmation dialog before quitting if any tabs have active sessions. This prevents accidentally losing in-progress work.

System Settings

Recording Settings

Danger Mode

Danger Mode skips all AI tool confirmation prompts, allowing the AI to execute commands, edit files, and make changes without asking for permission. When enabled, new sessions launch with unrestricted permissions (e.g., --dangerously-skip-permissions for Claude).

Visual indicators appear when Danger Mode is active: a red accent line on the tab bar, a warning banner in the side panel, and a badge in the status bar.

You can also toggle Danger Mode from the View menu. For safety, Danger Mode always resets to off when the app launches.

Keyboard Shortcuts