Documentation

Admiral uses a three-panel layout designed to keep everything you need visible at once - your projects, your conversations, and your code.

Admiral workspace overview

/docs/workspace-overview.png

Projects Sidebar

The left sidebar lists all your projects and their chat sessions. Each project shows its active chats, and colored dots indicate their status: green means the AI is processing, orange means it's waiting for your permission to proceed.

You can reorder projects by dragging them, collapse the sidebar for more space, and quickly switch between conversations. Archived chats are hidden from view but can be accessed from the project overview.

At the bottom of the sidebar, a footer bar provides quick access to Settings and a Help menu with links to the website, roadmap, blog, feature requests, issue tickets, and more.

Projects sidebar with status indicators and footer bar

/docs/sidebar.png

Chat Panel

The center panel is where you interact with AI. It shows the full conversation history with syntax-highlighted code blocks, tool use indicators, and thinking blocks. The input area at the bottom supports file attachments and voice dictation.

Chat panel with conversation

/docs/chat-panel.png

Inspector Panel

The right panel provides multiple views: a file browser for your project directory, a git status panel showing your current branch, staged changes, and unstaged modifications, and a History tab (clock icon) that displays version history when a skill is selected. Switch between them using the tabs at the top of the panel.

Inspector panel showing file browser and git status

/docs/inspector-panel.png

Starting a Chat

To start a new conversation, click the ellipsis button in the sidebar next to a project name, or use the keyboard shortcut. Each chat creates a dedicated Claude Code session scoped to your project directory. You can describe what you want to build, ask questions about your codebase, or request refactors - just like you would in the CLI.

Starting a new chat

/docs/new-chat.png

Running Multiple Chats

One of Admiral's most powerful features is the ability to run multiple AI conversations in parallel. Each chat operates independently with its own Claude Code subprocess. You can have one chat working on a feature while another fixes a bug - they won't interfere with each other.

Chats continue processing in the background even when you switch to a different conversation. The sidebar status dots keep you informed about what's happening across all your sessions.

Background Processing

When you switch away from an active chat, Claude keeps working. You'll see the status dot change to green while it's processing, and to orange if it needs your permission before continuing. This means you can start a long task and work on something else while waiting.

Permissions & Approvals

Admiral surfaces every action the AI wants to take for your review. File edits, terminal commands, and other operations appear as permission requests that you can approve or deny. For the active chat, these appear as a sheet within the chat panel. For background chats, they appear as floating windows so you can respond without switching context.

You can grant permissions per action ("Allow Once") or for the duration of the session ("Allow for Session"). When retrying a failed operation, Admiral supports approving multiple tools at once.

Permission request dialog

/docs/permission-request.png

Slash Commands

Admiral supports slash commands in the chat input for quick actions:

• /clear - Reset the current session
• /compact - Compact the conversation context to free up space
• /plan - Enter plan mode for structured task planning
• /pr-comments - Fetch and review pull request comments
• /security-review - Review your current diff for security issues
• /init - Initialize your project with a CLAUDE.md file

Type / in the input field to see available commands with autocomplete.

Subagents

When Claude spawns sub-tasks (subagents), they appear as collapsible cards within your conversation. Each subagent shows its status and any permission requests it needs. If multiple subagents request permissions at the same time, each gets its own floating window.

Admiral provides a complete git workflow without leaving the app. The inspector panel's git tab shows your repository state at a glance, and inline tools let you stage, commit, and push changes.

Viewing Changes

The git status panel shows staged and unstaged changes with line-level add/delete counts. Click on any file to open a side-by-side diff view showing exactly what changed.

Git diff viewer

/docs/git-diff.png

Staging & Committing

Stage individual files or all changes directly from the git panel. When you're ready to commit, Admiral can generate a commit message for you using AI - it analyzes your staged changes and drafts a conventional commit message. You can accept it as-is, edit it, or write your own.

Inline commit with AI-generated message

/docs/git-commit.png

Branch Management

The branch picker lets you switch between local and remote branches, create new branches, and view branch history. You can also fetch, pull, and push directly from the toolbar.

Branch picker with local and remote tabs

/docs/branch-picker.png

Worktrees

For tasks that need isolation, Admiral supports git worktrees. You can create a worktree for a specific chat session, giving it its own branch and working directory. This lets you run experiments without affecting your main working tree. When you're done, merge the changes back or discard the worktree entirely.

Stash Management

View and manage your git stashes from the project overview. Admiral shows your stash count and lets you apply or drop stashes without touching the terminal.

File Browser

The inspector's file browser lets you navigate your project tree, see modified files at a glance, and preview file contents. You can drag and drop files to rearrange them or drop external files into your project to copy them in.

Code Diffs

When the AI suggests file edits or writes new files, Admiral renders the changes as clean visual diffs. You can review every change line by line before approving. This applies to both Write (new file) and Edit (modify existing file) operations.

Quick Open

Press ⌘K to open the quick search. It searches across all your chat names and message transcripts, similar to Spotlight. You can filter results by chats or messages, and jump directly to a specific message with a highlight animation.

Admiral includes a set of built-in tools that extend your workspace beyond chat and code review.

Terminal Overview

The Terminal Overview is a dedicated tool that aggregates and displays all active terminal sessions across every chat and project in Admiral. It gives you a bird's-eye view of everything running in your workspace.

The overview shows:

• A summary bar with total terminal count, running terminal count, and active project count
• A scrollable list of every terminal session with its status (running or stopped), project name, associated chat, and working directory
• Action buttons on each row to navigate directly to the chat containing the terminal or stop a running process

The terminal list auto-refreshes every few seconds so you always have an up-to-date picture. You can also click the refresh button in the header to update manually.

Terminal Overview tool

/docs/terminal-overview.png

Ports

The ports tool detects active listening TCP ports on your machine and shows them per project. This is especially useful when working with local dev servers, APIs, or any service that binds to a port.

For each detected port you can:

• Open it directly in your browser with one click
• See which process is holding the port
• Kill the process if it's no longer needed

Port monitoring panel

/docs/ports.png

Skills Manager

Skills are reusable prompts and instructions that extend what Claude can do in your project. The Skills Manager lets you browse, create, edit, and organize your Claude Code skills and commands from a single interface.

You can manage two types of skills:

• Global skills (from ~/.claude/skills/) - available across all your projects
• Project skills (from .claude/skills/) - scoped to a specific project

Each skill can have a name, description, version number, argument hints, and a list of allowed tools. Skill content is written in Markdown. The toolbar provides Save, Undo, Add Page, Open in Finder, and a context menu for additional actions.

Skills manager interface

/docs/skills-manager.png

Skills Versioning

Every time you save a skill, Admiral automatically creates a version snapshot. This gives you a complete history of changes and the ability to roll back at any time.

Each version captures:

• An auto-incrementing version number
• A timestamp of when the save occurred
• A full snapshot of all files in the skill
• An optional label you can add to mark important milestones (e.g., "before refactor")

For skills backed by a directory with multiple files, all pages are snapshotted together as a single version. Restoring rolls back the entire skill directory atomically, so you never end up with a partial or inconsistent state.

You can browse the full version history in the inspector's History tab (clock icon). Each entry shows the version number, timestamp, optional label, and a Restore button. Click Restore to roll back to any previous version with one click, or edit labels to mark important milestones.

Skills version history in the inspector

/docs/skills-versioning.png

Each chat includes a native terminal panel at the bottom of the chat area. It is a full terminal emulator with ANSI escape code support, connected to your project's working directory. Run builds, tests, scripts, or any command without leaving the app.

The terminal has its own appearance settings independent from the main app theme, including a separate light/dark mode toggle. You can customize these in Settings under Terminal Settings.

Built-in terminal panel

/docs/terminal.png

Adding Projects

Add a project by clicking the "+" button at the top of the sidebar and selecting a folder. Admiral will detect the project type and scan for git repositories automatically. Each project gets its own section in the sidebar with dedicated chats, actions, and settings.

Project Overview

The project overview dashboard gives you a high-level view of your project's state. It includes:

• Summary metrics and project health
• Recent and archived chats
• Open worktrees with options to create chats or remove them
• Branch management (switch, merge, delete)
• Memory files for preserving context across sessions
• Project hygiene checks

Project overview dashboard

/docs/project-overview.png

Project Actions

You can add custom action buttons to each project for frequently used scripts or commands. These appear in the project toolbar and can be configured with custom icons for quick access.

Project Hygiene

Admiral monitors the health of your project and flags potential issues:

• Disk usage across the project
• Uncommitted changes and untracked files
• Stale branches that haven't been updated recently
• Lingering zombie processes
• Git stash count
• Outdated dependencies

Memory Files

Memory files let you preserve important context across chat sessions. These are Markdown files stored in your project that Claude can read to understand prior decisions, conventions, or project-specific knowledge. You can browse and edit them directly from the project overview using the inline Markdown editor.

Archiving Chats

When you're done with a conversation but want to keep it for reference, you can archive it. Archived chats are hidden from the sidebar but remain accessible from the project overview. You can view archived chats in a read-only standalone window, restore them to active status, or permanently delete them.

Importing Sessions

If you've been using Claude Code from the terminal, you can import those sessions into Admiral. The session import browser lets you browse your existing Claude Code sessions (stored in ~/.claude/projects/), search and filter by date or model, and import them with full message history preserved.

Admiral automatically detects sessions that have already been imported to avoid duplicates. You can select multiple sessions for batch import.

Session import browser

/docs/session-import.png

Session Resumption

Admiral can resume previous chat sessions, picking up exactly where you left off. The conversation history and context are preserved, so Claude remembers what you were working on.

Appearance

Admiral supports both light and dark mode, following your macOS system preference or set manually. Every color in dark mode has been hand-tuned for contrast and readability during long sessions. You can also adjust text scaling to your preference.

Admiral in dark mode

/docs/dark-mode.png

Keyboard Shortcuts

Admiral comes with a full set of keyboard shortcuts that you can customize from Settings > Shortcuts. There are 16 customizable shortcuts covering common actions like creating new chats, toggling panels, opening quick search, and approving permissions. Notable shortcuts include:

• ⌘L - Focus the chat input box from anywhere in the app (sidebar, inspector, or chat area)
• ⌘J - Toggle voice dictation in the chat input
• ⌘. - Stop the running agent (press once for a graceful interrupt, twice to force-stop)

The shortcut editor includes conflict detection so you won't accidentally assign the same key combination to multiple actions. You can reset all shortcuts to defaults at any time.

Keyboard shortcuts settings

/docs/keyboard-shortcuts.png

Terminal Settings

The terminal panel has its own appearance settings, independent from the main app. You can choose a separate theme for the terminal and toggle between light and dark mode independently.

Tool Visibility

You can control which tools are visible in the chat interface from the settings. This lets you hide tools you don't use frequently to keep the interface clean.

Local-First Architecture

Admiral is built with a local-first philosophy. All your project data, conversation history, and settings are stored on your Mac using SwiftData (backed by SQLite). Nothing is synced to the cloud, and Admiral never transmits your code or conversations to its own servers.

How AI Communication Works

When you chat with AI in Admiral, your messages go directly from your machine to the AI provider (e.g., Anthropic's Claude). Admiral does not act as a middleman, proxy, or relay. Your API credentials are stored securely in the macOS Keychain.

Data Access

Admiral accesses the following information on your machine to provide its features:

• Project files - to display the file browser and provide context to AI
• Git repository data - branches, diffs, stashes, and commit history
• Active network ports - to detect running dev servers
• Running processes - for terminal sessions and zombie process detection
• Microphone (optional) - for voice dictation, processed on-device via Apple Speech Recognition

Analytics

Admiral uses TelemetryDeck for anonymous, aggregated usage analytics (app launches, feature usage signals). No personally identifiable information, file paths, source code, or message content is ever collected. TelemetryDeck does not use cookies or track users across apps.

Permissions

Every action the AI wants to perform - editing files, running commands, accessing tools - requires your explicit approval. Permissions are visible, adjustable, and never assumed. You control whether to grant access per action or per session.

Admiral checks for updates automatically using the Sparkle framework. When a new version is available, you'll be prompted to update. All updates are code-signed with EdDSA for security.

You can view the full release history on the Changelog page, or read about what's new on the Blog.