First steps
- Install. Download
Hangar-Setup.exeand run it. Hangar installs for your user only, without administrator rights. - 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.
- 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.
- 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.
| Keys | Action |
|---|---|
| Ctrl+Shift+P | Quick access: find sessions, programs, files, recent commits, settings and every menu command |
| Ctrl+Shift+S | Search the output of all sessions |
| Ctrl+Shift+M | Show all sessions as live tiles |
| Ctrl+Shift+H | Show the home view; the sessions keep running |
| Ctrl+Shift+T | New session with the most recently used program |
| Ctrl+Shift+W | Close session |
| Ctrl+Tab | Next session |
| Ctrl+Shift+Tab | Previous session |
| Ctrl+Shift+A | Go to the next session waiting for you |
| Ctrl+Shift+N | Quick note |
| Ctrl+Shift+D | Show or hide the changes in the session's folder |
| Ctrl+Shift+F | Search the terminal history |
| Ctrl+Shift+B | Collapse or expand the sidebar |
| Ctrl+, | Open settings |
| Ctrl++ | Larger text |
| Ctrl+- | Smaller text |
| Ctrl+0 | Reset text size |
| Keys | Action |
|---|---|
| Ctrl+C | Copy the selection; without a selection the key goes to the program (interrupt) |
| Ctrl+Shift+C | Copy the selection and keep it selected |
| Ctrl+V | Paste; with an image on the clipboard, Hangar pastes the path of the saved image file |
| Shift+Enter | New line in an agent's prompt, without sending it |
| Ctrl+Shift+Space | Hold to dictate; speech is recognized on your own computer |
| Keys | Action |
|---|---|
| Enter | Next match |
| Shift+Enter | Previous match |
| Esc | Close the search |
| Keys | Action |
|---|---|
| F6 / Shift+F6 | With the notes open, move the focus between terminal, notes list and editor |
| F2 | Rename note |
| Alt+↑ / Alt+↓ | Move the focused session up or down in the sidebar |
| Ctrl+Enter | Send 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.
| Field | Meaning |
|---|---|
id | Required. Unique, without spaces. Hangar rejects two IDs that differ only in upper and lower case. |
name | Required. Display name in the sidebar. |
command | Required. Program name from the PATH or a full path. No shell syntax: Hangar starts the program directly. |
args | Arguments as a list, for example ["--model", "opus"]. |
cwd | Fixed working folder. Without this field the program starts in the folder you pick. |
icon | One 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_env | Names of variables whose values Hangar keeps in Windows Credential Manager, for example ["GITHUB_TOKEN"]. |
resume_args | Arguments to resume the last conversation. They replace args instead of being appended. |
version_args | Arguments for the version query, default ["--version"]; [] means: never start the program to read its version. |
latest, packages, self_update, update_hint | Where 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.
| Location | Content |
|---|---|
%APPDATA%\com.feoren.hangar\profiles.toml | Your profiles |
%APPDATA%\com.feoren.hangar\HANGAR.md | Your instructions for all agents |
%APPDATA%\com.feoren.hangar\account.json | The 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%\Hangar | The program itself |
.hangar\notes\ | Shared notes, encrypted, in the repository |
| Windows Credential Manager | Secret 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.