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=VALUE file parsed and merged into the shell env (no direnv required)
  • 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_COLOR and $TRMNLY_PROJECT_EMOJI so your prompt can use them (every project shell also gets $TRMNLY_PROJECT_ID and $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 .env into the bash tool's environment
  • Scopes project-typed memory entries and notes to that project
  • Tags apply_patch/edit_file calls 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 ⌘T and then run zsh or 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.