Guide

Noaam keeps track of the coding agents, editors, terminals and pages you already use, filed under the repository, worktree or folder they belong to. It never replaces them: a Claude Code session is still Claude Code, VS Code is still VS Code. Noaam keeps a pointer and brings the right one up. Its journal remembers what you worked on, for you and your agents to ask later.

Free for macOS 14 or later (Apple silicon). Download the latest release.

Installing

Noaam is not notarized by Apple yet, so macOS asks once:

  1. Open Noaam.dmg and drag Noaam into Applications.
  2. Open Noaam. macOS says it cannot verify the app; click Done.
  3. System Settings › Privacy & Security › Security › Open Anyway next to Noaam, and confirm.

After that it opens like any other app.

On first launch a setup panel asks where your code is, which of the repositories found there to show, which sessions belong in Noaam (under those folders, only in the chosen repositories, or everywhere), which tools you use and whether to keep a journal. The tools found on your Mac start ticked. Nothing is scanned or started until you finish.

The primitives

   
Folder A real directory that matters, nested as on disk. Its kind is Repository (main checkout of a repository you show), Worktree (one of its linked worktrees) or Directory (anything else holding items).
Item One thing you work on inside a Folder: a Claude Code or Codex session, a VS Code workspace, a shell, a page. The real thing stays where its tool keeps it; Noaam keeps a pointer.
Tool A kind of Item: Claude Code, Codex, opencode, Pi, VS Code, Neovim, Ghostty, TextEdit, your browsers. Each says what its Items point to, how they can be shown and how existing ones are found.
Presentation How an Item is shown: an embedded terminal, an embedded web view, the tool’s own app, or docked beside Noaam.
Discovery How a tool’s existing Items are found, so the sidebar is complete without importing anything.
Space A named group of related Items in a Folder, like a tab group: a session, its browser page, its editor. Shown as a list or as tiles side by side.
Settled Out of sight, never deleted.

The sidebar

The sidebar is the folders you pointed Noaam at, laid out as on disk. Each root is a row holding everything below it: your repositories and their worktrees, every folder where a session lives, and the Items inside them. Each row shows how long ago something last happened there. Right-click any folder to create a worktree there.

  • Tree or Recent. The tree shows Folders as on disk. Recent is one flat list of every Item, newest activity first, with its folder under the title: the view for following agent runs.
  • Order. Stable (folders by name, Items in the order you made them; drag Items and Spaces to rearrange) or by recent activity. The ↑↓ button at the bottom of the sidebar switches.
  • Search (⌃⌘F, or the search icon at the bottom). Filters what the sidebar shows, fzf-style: titles count most, then the folder path and Space, then status, URL, branch and a session’s first prompt. ↑↓ move through matches, Return opens one, Esc clears and closes.
  • Filter by tool. Show only some tools, for example only VS Code.
  • Jump around. ⌃⌘[ and ⌃⌘] go back and forward through every row you visited. Hold ⌃⌘ to number the Items in view, then ⌃⌘1–9 jumps to one.
  • Settle what is done (⌃⌘⇧D). A Folder goes quiet when its last Item is settled; ⌃⌘⇧H shows everything again.
  • Remove from Noaam takes an Item out of the tree. It never deletes the session, transcript, worktree, files or page it pointed at.
  • Auto-hide (⌃⌘S) gives the content the full width; touch the window’s left edge and the sidebar slides in over it.

Status

The dot on each Item says what its tool is doing:

Dot Meaning
orange with ? needs you: a permission prompt or a question
orange to read: it finished while you were looking elsewhere; looking at it clears the dot
orange ring finished, maybe unread: Noaam couldn’t tell whether you were looking
blue working (dashed: probably, by a guess; faded: an old report)
green open and idle (dashed: open, nothing reports its activity)
red crashed

Claude Code, Codex, shells and editors come set up. For any other tool, one JSON file teaches Noaam where to listen: a window title, a status file, a hook, or a script in any language. Why this status? in an Item’s menu shows which source decided, and Mark as Read clears a dot. When you quit, Noaam asks only if a terminal is busy, and says why. How status works, and how to add a tool →

Items

  • Claude Code, Codex and opencode sessions appear on their own, from each tool’s own session index, filed under the folder they ran in (for Claude Code, the folder it last moved to with /cd). Selecting one resumes it in an embedded terminal.
  • New items. ⌃⌘T (or + at the bottom of the sidebar) opens the composer: type, pick the tool and where it lives, ⌘↵. An agent starts in its own terminal with your text as its first message; a terminal takes it as its name, a browser as its address. Where browses the disk, so any directory can take an Item, and can make a new worktree or Space on the way. Clicking a folder opens it; Here at the top picks the folder itself, also one of your root folders (with a single root, Here is already at the top). ⌃⌘N, ⌃⌘⇧N and ⌃⌘⌥N make an Item of your first three tools right away.
  • Real terminals. Embedded terminals are Ghostty’s own engine: your theme, GPU rendering, native scrollback. ⌘F finds in the terminal. Drop a file or a screenshot thumbnail onto one to paste its path; Claude Code turns an image path into an attachment.
  • Terminal history survives. Terminals keep what they printed. Reopen one after the process died, Noaam quit or the Mac restarted, and the old output comes back before the tool starts again, embedded or in Ghostty. Docking and undocking keep it too. Claude Code, Codex and opencode start with it off, since resuming a session prints the conversation again; turn it on per tool with Settings › Tools › Keep terminal history.
  • VS Code opens embedded (VS Code’s own local web server) or as your desktop VS Code. The embedded one starts bare: turn on Backup and Sync Settings once from its account menu to bring your extensions and settings along.
  • Pages open embedded with a URL bar that loads addresses, searches everything else and suggests pages you visited (⌘L focuses it, ⇧⌘C copies the address, ⌘F finds), or in a specific browser. Clicking into a login field opens the macOS Passwords panel; Noaam stores nothing.
  • Docked puts the tool’s real window beside Noaam: Noaam narrows to its sidebar, the app fills the rest, and the two move together. Undock gives Noaam its width back. Needs Accessibility permission the first time.
  • Open elsewhere. ⌃⌘E hands the current pane to its own app: Ghostty, the VS Code app, your browser.
  • Move to… (right-click an Item) puts it in another folder or Space, with the composer’s place picker; it starts there from then on (a running Item keeps its directory until it restarts). On for the Claude Code, Codex, opencode, VS Code, Neovim, Terminal and browser tools; turn it on for your own in Settings › Tools.
  • Hidden items unload when quiet. Terminals and pages you aren’t looking at stop after a while, or past a number kept loaded, and come back when shown: the session resumes with its history, the page reloads. Nothing typed and unsent is ever dropped, and shells are kept. Set per tool in Settings › Tools › When hidden.

Spaces and tiles

A Space groups the Items of one task under a named row.

  • New Beside This. Looking at a session and want a browser next to it? Click + in the pane header (or right-click the row) › New Beside This › Browser. The two share a new Space, split side by side. Add to Space Only adds an Item without splitting.
  • Drag to tile. Drag an Item from the sidebar onto the right panel: near an edge, a highlight shows the half it will take; drop to split. Drag a tile by its header to another edge to move it, drag the dividers to resize. The layout is saved.
  • List or tiles. Show as List keeps the group without tiles; Show as Tiles puts its Items side by side. A tile’s × takes its Item back to its folder, still running.
  • ⌃⌘⇧G makes a named Space around the selected Item. Items move between Spaces by drag and drop or Move to…

Profiles

A profile is a whole set of folders, repositories, tools and sidebar settings with its own tree, for keeping work and personal apart. Each profile opens as a Noaam of its own, with its own window, Dock icon and ⌘-Tab entry (the icon carries its name), so several run side by side. Web views are not shared: each profile has its own cookies and sign-ins, so a work login never shows in the personal one. A new profile starts with the setup panel; a duplicate starts with the original’s settings. Manage them in Settings › Profiles or App menu › Profile.

The journal

Each profile keeps a journal: a file per day of what happened, so you and your agents can ask later what you worked on and for how long. It records:

  • which Items were shown and focused, and when
  • the app in front, and optionally its window’s title (a page or a document name; uses the Accessibility permission docking asks for)
  • whether you were typing or clicking (not the keystrokes, it’s not a keylogger)
  • screen lock, display and system sleep
  • commits and branch switches in your repositories and worktrees, also those made while Noaam was closed
  • when each agent’s turns start and end, and pages visited in web panes

For agent sessions it keeps a pointer into the files your agents already write (Claude Code’s session file, Codex’s rollout) at each turn, so a reader can look up what was said there.

The journal stays on your Mac, in the profile’s folder. Finished days are compressed. Settings › Journal turns it off, sets how long it’s kept (forever by default) and how finely input is sampled.

Asking it

The noaam command reads the journal, even with Noaam closed, and asks the running Noaam about its Items. Settings › Journal › Install links it as ~/.local/bin/noaam; it’s also on the path of Noaam’s own terminals.

noaam spans --ev item.focus --since monday --by repo --gap 300

sums the time each repository had focus this week, counting only time within five minutes of input. noaam --help lists every command, and noaam events explains every journal line.

You rarely need to type it yourself. Teach an Agent (Settings › Journal) opens a session of your coding agent that installs Noaam’s skill. From then on, ask it in plain words: “make me a timesheet of my hours this week, by project”, “what did I do yesterday?”, “write my standup”.

Voice

Talk to Noaam is a voice for one of your agent sessions. Press ⌃⌥Space, say what you want, and it goes to that session as an ordinary message; its reply is read back to you. The conversation stays in the session’s own transcript, so you can scroll it, type into it or resume it later. The voice can do whatever the session can: its tools, the accounts you connected to it (mail, calendar…), and your other items through the noaam command.

To set it up:

  1. Settings › Voice: turn on Talk to Noaam.
  2. Under Provider, paste an OpenAI API key and press Save. It’s kept in Noaam’s app files, readable only by you. The default provider, OpenAI Live (GPT-Live), costs about $0.05 a minute, billed by OpenAI. OpenAI Realtime and Gemini Live are there too.
  3. Pick the session to talk to: right-click a Claude Code or Codex item › Use as Voice Assistant, or choose it under Settings › Voice › Talk to. Otherwise it’s the item selected when you press the key. It needn’t be open; Noaam starts it in the background.
  4. Press ⌃⌥Space, wait for the pop, and talk. Press it again to stop; a quiet spell ends it too.

While it works:

  • The voice says it’s on it and keeps you posted: it hears the agent’s steps, so “how’s it going?” gets a real answer. It stops the moment you talk over it.
  • When the agent asks to run something, the voice reads you the command. Say “yes” or “no”; anything else and it asks again.
  • What you say while the agent is busy goes in right away.
  • If you were halfway through typing in the session, Noaam sets your draft aside (Claude Code’s ⌃S stash) and puts it back after.
  • Settings › Voice › Alerts: the voice tells you when another item needs you or finishes, with what it asked or said, also when no conversation is open if you like.

Answering prompts and sending to items other than the assistant need Settings › Tools › the tool › Remote control, where each command is off until you allow it. The same commands are on the command line: noaam send, answer, interrupt, start and read.

What the voice heard and said is in the journal (noaam journal --ev voice). Audio goes to the provider only while a conversation is open.

Limits: the session must run in Noaam’s own terminal, not a docked window; only one profile gets ⌃⌥Space at a time; and Gemini Live is less tested than OpenAI Live.

Settings

⌘, opens Settings. It edits the profile’s config.json, which stays readable and hand-editable.

Page What it holds
Profiles every profile, Switch, Duplicate, Rename, Delete, New profile
Overview how Noaam works, the scan interval, every source a scan uses and what it found last time, which found items to keep
Repositories where to look for repositories, and which ones show
Sidebar per folder kind its icon and when it stays visible, pinned folders, order, sidebar mode
Tools add ready-made tools from + (Claude Code, Codex, opencode, Pi, VS Code, Neovim, Terminal, TextEdit, browsers) or define your own: commands, how existing items are found, how they open, status, remote control, when hidden, keep terminal history, ask before quitting, whether items can move to another folder, icon
Terminal theme and font size of embedded terminals
Web default page zoom, search engine, URL bar history
Shortcuts every keyboard shortcut
Storage every path, what it holds and its size on disk, Check storage
Voice Talk to Noaam, the provider, its voice and API key, which item to talk to, spoken alerts
Journal keep a journal, how long, window titles, input sampling, the noaam command and Teach an Agent
Updates Automatic, Notify only or Off, and Check Now; the same for every profile

Noaam checks for updates once a day. With Automatic it downloads them in the background and installs when you quit, or right away if you click Restart in the strip above the sidebar’s bottom bar. Notify only says an update is out and waits for you to click Install. Off only checks when you pick Noaam › Check for Updates… What’s new in the strip, or Help › What’s New in Noaam, opens the changelog.

Everything Noaam knows is plain files under ~/.config/noaam, one small JSON file per Folder and Item.

Keys

Noaam’s own commands are ⌃⌘ plus a key, the same wherever the focus is. Plain ⌘ keys belong to the focused pane, so a terminal or web page keeps its own shortcuts.

Key Action
⌃⌘T New…: the composer
⌃⌘N, ⌃⌘⇧N, ⌃⌘⌥N new Item of the first, second, third tool in the selected Folder
⌃⌘⌥R rename
⌃⌘⇧D settle or unsettle
⌃⌘⇧H show or hide settled entries
⌃⌘F search the sidebar
⌃⌘⇧R scan now
⌃⌘⇧- collapse or expand all
⌃⌘⇧G new Space around the selected Item
⌃⌘⇧] / ⌃⌘⇧[ next / previous row
⌃⌘1–9 jump to an Item in view; hold ⌃⌘ to see their numbers
⌃⌘[ / ⌃⌘] back / forward through the rows you visited
⌃⌘E open the current pane in its own app
⌃⌘S sidebar always shown or auto-hide
⌃⌥Space start or stop talking to Noaam
⌘, Settings
⌘+, ⌘-, ⌘0 zoom the terminal font or the page
⌘F, ⌘G find in the terminal or page
⌘L, ⇧⌘C focus the URL bar, copy the page address
⌘R reload the page

Made by Conformal Link. Feedback, ideas and bug reports: start a discussion, or pick Help › Send Feedback… in Noaam. Help › Noaam Guide opens this page.