All pages
Docs · Start here
Projects
Availability: macOS · cloud workspace. Not in the GTK app yet.
A project is a named folder shortcut. Selecting one opens a terminal whose working directory is the folder, with optional per-project shell, env, theme, and startup command. Projects are how TRMNLY groups your work: tabs are tagged with their project so the sidebar's tab list follows the one you select, but windows are deliberately not grouped — the same project can be open in any number of windows.
Projects live in the left sidebar (toggle with ⌘\). Click the +
button or drag a folder into the sidebar to add one.
What a project carries
Each project remembers:
- Folder path — the working directory the terminal opens into
- Default shell — e.g.
/bin/zsh,/opt/homebrew/bin/fish(falls back to the last shell you launched in the project if unset) - Startup command — text typed into the prompt without Enter, so you can review before running
- Env file —
KEY=VALUEfile parsed and merged into the shell env (nodirenvrequired) - Env overlay — inline key/value pairs with secret masking, layered on top of the env file
- Theme and font size — overrides for just this project
- Color and emoji — visual identity in the sidebar, also exported
as
$TRMNLY_PROJECT_COLORand$TRMNLY_PROJECT_EMOJIso your prompt can use them (every project shell also gets$TRMNLY_PROJECT_IDand$TRMNLY_PROJECT_NAME) - Run actions — named build/run commands, auto-detected from the project's kind (Node, Xcode, …) and overridable, surfaced in the command palette as "Run: …"
- Alias slug — a stable short id used for port aliases (e.g.
aw3.4337). Doesn't change when you rename the project, so agent-cached references keep working. - Per-project model overrides — pin Ollama or LM Studio (or any OpenAI-compatible endpoint) for this project without changing your default provider.
- Notes and prompts — see Notes and Prompts
Worktrees
Each project can host multiple worktrees — git checkouts on different branches, each with its own tab list and its own copy of untracked env files. The worktree selector lives at the top of the left sidebar above the tab list, and the Worktree menu carries the same actions with shortcuts. See Worktrees for the full surface, including how Claude Code is told to use them.
How projects affect the agent
When a project is active, the agent automatically:
- Loads the project's
.envinto the bash tool's environment - Scopes project-typed memory entries and notes to that project
- Tags
apply_patch/edit_filecalls against paths inside the active worktree folder (not the project's primary folder if a non-primary worktree is selected) - Resolves port aliases (
<slug>.<port>) through the project's slug
The agent lists projects with project_list and can make one with
project_create — a name and an optional folder, idempotent by name and by
folder (a folder another project already uses returns that project) — so a
task board or worktree has a project to attach to before you've opened it.
To switch projects, click one in the left sidebar's project rail. The rail
only holds as many tiles as fit, so the grid button at its end opens a
popover listing every project — overflowed and hidden ones included. That
popover has a search field, focused as it opens: type part of a project's
name or its folder path, ↑/↓ (or ⌃p/⌃n) to move, ↩ to switch to
it. Dragging to reorder is disabled while a search is active, since the
rows on screen are no longer in rail order. ⌘K (Quick Switcher) also
finds projects by name, but it opens the project in a new window rather
than switching the current one.
Project context (TRMNLY.md and friends)
When Project README / docs is enabled (Agent settings, and per
session scope), the agent prepends a cacheable Project context block
to its system prompt. It walks the project root for files like AGENT.md,
AGENTS.md, CLAUDE.md, README.md, and package.json, concatenates
them up to a ~64 KB budget, and appends a slice of recent git log if room
remains.
TRMNLY.md is a companion to CLAUDE.md that tells a Claude session
running inside TRMNLY which mcp__trmnly__* tools it has — environment
context, not project instructions. Settings → AI Agent → Add TRMNLY.md
to current project (or auto-add when opening a project) does three
things, all inside the project: writes the template if it's missing
(never overwriting — the Project notes section is yours), makes sure
CLAUDE.local.md contains the line @TRMNLY.md, and adds both names to
the repository's .git/info/exclude. Claude Code loads CLAUDE.local.md
alongside CLAUDE.md; a standalone TRMNLY.md is never read, and the
tracked CLAUDE.md is never edited, so teammates without TRMNLY see no
diff. New worktrees get both files copied from the primary checkout.
Deleting a project
Removing a project cascades to per-project stores: prompts, notes, kanban cards, pinned files, the recall index, split-layout presets, saved sessions, browser state, and worktrees (their directories are deleted). Agent transcripts and memory get a choice in the delete dialog: keep them (re-tagged as global, still reachable from the global session list) or delete them too. Tabs that were bound to the project orphan to a global state; they keep running but lose the project's env on their next shell launch.
Moving a tab between projects
Right-click a tab in the sidebar's tab list (or the window's tab bar) → Move to Project ▸ any project, or No Project to clear its tag. The tab keeps running; it simply shows under the other project's tab list.
A new window that doesn't start inside a project's folder is not tagged with the project you last had selected (before 0.1.107 it was, so a home folder window could show a project at the top of the sidebar). A tab tagged that way by an older version keeps its tag; Move to Project ▸ No Project clears it.
Quirks
- Projects are folder shortcuts, not window groups. Closing a window doesn't end the project; opening a project in two windows is fine.
- The shell field is per-project, not per-tab. Drop into a new shell
for one tab with
⌘Tand then runzshor whatever; the project's setting is unchanged. - If you delete the folder, the project entry sticks around. Either re-point it to the new location or remove it from the sidebar.
- The built-in Terminal project is permanent — it can't be deleted.
- Env files are a data surface: variables that could rewire the shell
or loader (
PATH,DYLD_*,LD_*,BASH_ENV, …) are never imported from them.