Documentation

Hangar after installing

Everything you need for everyday work with Hangar: from your first agent to the files where Hangar keeps your settings.

First steps

  1. Install. Download Hangar-Setup.exe and run it. Hangar installs for your user only, without administrator rights.
  2. Start an agent. Pick a project folder under New session, choose Private or Team and click an agent. Hangar lists every agent it finds on your machine, with its version; under Team only those that can run as team sessions.
  3. Bring in your team (optional). Click "Sign in" at the bottom of the sidebar, confirm the code in your browser, then connect the project. Teammates who join the same project see each other in the Team window.
  4. Profile picture (optional). Your profile picture from your Hangar account shows in the sidebar. You upload it on this website under Account › Settings.

Download Hangar Supported agents

If Windows shows a SmartScreen warning while installing, choose "More info" and then "Run anyway". The installer is not yet signed with a code signing certificate. Updates inside Hangar are always signed and verified.

Requirements: Windows 10 version 1809 or later, or Windows 11 (x64). You install the agents yourself, with your own accounts. Git is needed for team sessions (worktrees), change tracking, commits and shared notes.

Keyboard shortcuts

Hangar only intercepts combinations that shells and agents do not need. The counterparts without Shift stay with the program in the terminal: Ctrl+B, Ctrl+F or Ctrl+P still reach your shell or agent.

Anywhere in Hangar
KeysAction
Ctrl+Shift+PQuick access: find sessions, programs, files, recent commits, settings and every menu command
Ctrl+Shift+SSearch the output of all sessions
Ctrl+Shift+MShow all sessions as live tiles
Ctrl+Shift+HShow the home view; the sessions keep running
Ctrl+Shift+TNew session with the most recently used program
Ctrl+Shift+WClose session
Ctrl+TabNext session
Ctrl+Shift+TabPrevious session
Ctrl+Shift+AGo to the next session waiting for you
Ctrl+Shift+NQuick note
Ctrl+Shift+DShow or hide the changes in the session's folder
Ctrl+Shift+FSearch the terminal history
Ctrl+Shift+BCollapse or expand the sidebar
Ctrl+,Open settings
Ctrl++Larger text
Ctrl+-Smaller text
Ctrl+0Reset text size
In the terminal
KeysAction
Ctrl+CCopy the selection; without a selection the key goes to the program (interrupt)
Ctrl+Shift+CCopy the selection and keep it selected
Ctrl+VPaste; with an image on the clipboard, Hangar pastes the path of the saved image file
Shift+EnterNew line in an agent's prompt, without sending it
Ctrl+Shift+SpaceHold to dictate; speech is recognized on your own computer
In the history search
KeysAction
EnterNext match
Shift+EnterPrevious match
EscClose the search
Notes, sidebar and sending to several sessions
KeysAction
F6 / Shift+F6With the notes open, move the focus between terminal, notes list and editor
F2Rename note
Alt+↑ / Alt+↓Move the focused session up or down in the sidebar
Ctrl+EnterSend a message to several sessions

Profiles in profiles.toml

Your own terminals and agents live in profiles.toml in the configuration folder, on Windows %APPDATA%\com.feoren.hangar\profiles.toml. If the file is missing, Hangar creates it on start from an annotated template, with PowerShell 7, Windows PowerShell and Command Prompt.

The quickest way to open the file is in Settings under Terminals & agents › Open profile file.

Agents from the catalog need no profile, Hangar knows them on its own. To start one of them differently, create a profile with the same id: it replaces the catalog entry's name, icon, command, arguments and position; project page and install command stay from the catalog.

Fields of a profile
FieldMeaning
idRequired. Unique, without spaces. Hangar rejects two IDs that differ only in upper and lower case.
nameRequired. Display name in the sidebar.
commandRequired. Program name from the PATH or a full path. No shell syntax: Hangar starts the program directly.
argsArguments as a list, for example ["--model", "opus"].
cwdFixed working folder. Without this field the program starts in the folder you pick.
iconOne or two characters for the icon in the sidebar.
[profile.env]Environment variables as a table of their own. Do not put secrets here.
secret_envNames of variables whose values Hangar keeps in Windows Credential Manager, for example ["GITHUB_TOKEN"].
resume_argsArguments to resume the last conversation. They replace args instead of being appended.
version_argsArguments for the version query, default ["--version"]; [] means: never start the program to read its version.
latest, packages, self_update, update_hintWhere new versions are published and how Hangar updates the program with one click. The annotated template in the file explains every field.

Example

The first profile starts Claude Code from the catalog with a different model. The second is a PowerShell of your own with a fixed working folder, one plain and one secret variable.

[[profile]]
id = "claude"
name = "Claude Code (Opus)"
command = "claude"
args = ["--model", "opus"]
icon = "C"

[[profile]]
id = "pwsh-shop"
name = "PowerShell (Shop)"
command = "pwsh"
args = ["-NoLogo"]
cwd = 'C:\src\shop'
icon = "SH"
secret_env = ["GITHUB_TOKEN"]

[profile.env]
DOTNET_CLI_TELEMETRY_OPTOUT = "1"

Secret variables

The values from secret_env never appear in the file. You enter them in Settings, where you edit the profile. Hangar keeps them in Windows Credential Manager under the service hangar and only puts them into a session's environment when it starts. A variable must not appear in both [profile.env] and secret_env.

After you save, Hangar reloads the file as soon as you return to its window, or you choose "Reload profiles". Hangar shows an error with line and column; running sessions stay as they are.

Notifications for waiting agents

The sidebar shows at a glance which agent is working, which one is done and which one waits for you. Everything else is in Settings under Attention.

  • Highlight waiting sessions: a session pulses gently when an agent is done or waiting for you while you are looking elsewhere. You choose after how many seconds of quiet the hint appears.
  • Colors and pulse: Working, Done, Asks you and Pause each get their own color, pulse strength and pulse duration, with a preview.
  • Sound: a soft two-tone chime when a session is waiting that you cannot see right now. If a program ends with an error, it sounds lower. The volume is adjustable.
  • Desktop notification: only while Hangar is in the background. Click it to open the session.
  • Flash the taskbar: only while Hangar is not in the foreground. The flashing stops as soon as you switch to its window.
  • Count on the taskbar: a small icon on the taskbar button shows how many sessions are waiting, from 1 to 9 and 9+ above that.
  • Push to your phone: through ntfy or Pushover when a session waits for you. With ntfy, pick a topic that is hard to guess, because anyone who knows it can read along.
  • Quiet hours: during the hours you choose there is no sound, no notification, no push to your phone and no flashing taskbar. Colors and the count of waiting sessions stay.
  • Keep running in the notification area: when you close the window, your sessions keep running, and the icon in the notification area shows how many are waiting. To quit Hangar, right-click the icon.

Ctrl+Shift+A takes you straight to the next waiting session.

Team sessions and worktrees

Under New session you choose Private or Team. A private session runs right in your folder, just for you. A team session gets its own Git worktree and is visible to your team, so several agents can change the same project at once without pulling files out from under each other.

For each team session Hangar creates a branch hangar/… from the current state. When an agent wants to edit a file another session is working on, Hangar holds it and asks you; answer "always" or "never" for a file or folder and Hangar remembers it per project. Claude Code, Codex CLI, OpenCode and Pi run as team sessions.

Worktrees live in the app data folder under %LOCALAPPDATA%\com.feoren.hangar\worktrees\, not next to your repository. That keeps repositories and synced folders clean.

When an agent starts in a fresh worktree, it first checks for new commits upstream and asks before pulling them. You can switch this off in the settings under Terminals & agents.

When a team session ends, Hangar removes its worktree again unless it still holds changes or ignored files such as build output, or another session still works in it. If the branch has commits that are not merged yet, it stays. Hangar never forces anything.

Git must be installed and the folder must be inside a Git repository. Hangar does not run Git on network shares, and the check before edits does not apply inside WSL.

Notes

Notes belong to the project of a session or to the General area. They are real Markdown files you can open in Explorer as well.

  • Ctrl+Shift+N starts a quick note from anywhere.
  • Send selected terminal text straight into a note, or a note to a session. There it is pasted without Enter, so you can check it first.
  • Deleted notes go to "Recently deleted", where you can restore them.
  • At the top of the notes panel you switch between Private and Shared, so your own notes stay apart from the team's.

Shared, encrypted notes

When you turn on shared notes for a project, Hangar encrypts them and keeps them in the repository's .hangar\notes\ folder. They travel with your commits. Anyone with the repository and the code can read them. Decrypted text is never written to disk, and Hangar never commits on its own.

When you turn them on, Hangar shows a notes recovery code once. Keep it safe: without it, the notes are gone for good if this computer loses its key. With the code you open them on another clone as well.

One instruction file for all agents

HANGAR.md lives in the configuration folder next to profiles.toml and works like AGENTS.md or CLAUDE.md, only without a file in your repository. Hangar hands its content to every agent that accepts extra instructions: Claude Code, Codex CLI and Aider. It is on by default; the template is empty and sends nothing until you write into it.

You open the file in the settings under Terminals & agents › Open HANGAR.md. There you also switch "Use HANGAR.md for every agent" on or off. Do not put secrets in it: the text appears in the agents' command line.

Storage locations

Hangar keeps its settings in your user profile, on Windows in %APPDATA% and %LOCALAPPDATA%. Only shared notes live in the project.

Storage locations
LocationContent
%APPDATA%\com.feoren.hangar\profiles.tomlYour profiles
%APPDATA%\com.feoren.hangar\HANGAR.mdYour instructions for all agents
%APPDATA%\com.feoren.hangar\account.jsonThe chosen server and the servers you are signed in to; no tokens
%LOCALAPPDATA%\com.feoren.hangar\workspace.json, scrollback\Open sessions and their history, so Hangar restores them after a restart
%LOCALAPPDATA%\com.feoren.hangar\notes\Private notes as .md files, per project folder and under general; deleted ones in .trash
%LOCALAPPDATA%\com.feoren.hangar\worktrees\Worktrees of your sessions
%LOCALAPPDATA%\com.feoren.hangar\pastes\Pasted screenshots; Hangar deletes them after a week
%LOCALAPPDATA%\HangarThe program itself
.hangar\notes\Shared notes, encrypted, in the repository
Windows Credential ManagerSecret profile variables, your sign-in and the keys for the team and shared notes

Your own team server

For teams, Hangar connects to the official service at https://hangar.feoren.com/api/v1 by default. Without signing in, everything except the Team window works.

If your team runs its own Hangar server, enter its address in Settings under Account › Server address (self-hosting) and click Apply. Left empty, the official service applies again.

The address is the server's API base, for example https://team.example.com/api/v1. It must start with https://; Hangar allows plain http only for localhost, 127.0.0.1 and [::1]. User name, password, query and fragment are not allowed. Hangar stores the address in account.json; sign-ins for other servers stay stored on the device.

Such a server has to speak the same interface as the official service: sign-in through the OAuth device flow, account and projects, plus tickets for the relay that carries the team data over WebSocket. The protocol's data types and its encryption are open in the app repository, in the crates hangar-team-protocol and hangar-team-crypto under the MIT license.

Everything shared with the team is encrypted on your device. The server stores and forwards it but cannot read it. New devices join only after someone compares a safety number and confirms it.

Where things stand: Ready-made server software for self-hosting has not been published yet. The app can already use an address of your own, but there is no installation guide here yet.

Planning Hangar for a company and need a server of your own? Write to us and we will look at your case.

Contact for teams