All pages

Lesson 1.4 · Get set up · 10 min

Projects

Folder shortcuts with their own environment, theme and startup commands.

Listen

A project is a named folder shortcut. In this lesson you create one, give it its own environment and startup command, and see how tabs and the agent follow the project you select.

Time: 10 minutes · Works on: macOS app · cloud workspace

What a project is

Selecting a project opens terminals in its folder, with that project's shell, environment, theme and startup command. Tabs are tagged with their project, so the tab list in the left sidebar follows the project you select.

Projects are not window groups. The same project can be open in any number of windows, and closing a window doesn't close the project.

Create a project

  1. Show the left sidebar with ⌘\.
  2. Click the + button at the top of the project rail and choose New Project.
  3. In Folder, type a path or press Choose… to pick one.
  4. Under Display name, give it a name.
  5. If the project runs a local web server, fill in Default URL, for example http://localhost:3000. The in-app browser opens it for this project.
  6. Press Create. The project appears as a tile on the rail.

Two faster ways to do the same thing:

  • Drag a folder from Finder onto the left sidebar. It skips the sheet and creates the project straight away.
  • Choose + → From GitHub… to clone a repository and make a project from the clone.

A new project starts with no tabs. Click its tile, then press ⌘T or use the empty-state action to open one.

Give it settings

  1. Right-click the project's tile and choose Project Settings….
  2. Under Terminal, set:
    • Shell, such as /bin/zsh.
    • Startup command, such as npm run dev. TRMNLY types it at the prompt of each new terminal in the project but doesn't press Return, so you can check it before running.
    • .env / .envrc, the path to an env file. Its KEY=VALUE lines are loaded into every shell in the project. You don't need direnv.
  3. Under Appearance, set a Theme name or Font size (pt) for just this project.
  4. Under Identity, set a Color (#RRGGBB) or an icon so the tile is easy to spot.
  5. Close the sheet and open a new tab in the project to see the changes.

Tip: For safety, env files can't set variables that rewire the shell or the loader, such as PATH or DYLD_*. Those lines are skipped.

Every shell in a project also gets $TRMNLY_PROJECT_NAME and $TRMNLY_PROJECT_ID, which your prompt or scripts can read.

Switch between projects

  1. Click a tile on the rail. The tab list switches to that project's tabs.
  2. If you have more projects than fit, click the grid button at the end of the rail (More projects). Type part of a name or path, move with the arrow keys, and press Return.
  3. Press ⌘K and type a project's name. The Quick Switcher opens it in a new window rather than switching the current one.

The right-click menu

A project tile's right-click menu holds everything else:

  • Open in New Tab opens a terminal in the project.
  • Run lists build and run commands TRMNLY detected from the project's kind, such as Node or Xcode. It only appears when there are some.
  • Worktrees creates and manages git worktrees for the project. The Worktrees lesson covers them.
  • Rename…, Choose Icon… and Delete.

Deleting a project also deletes what belongs to it: prompts, notes, Kanban cards, pinned files, saved layouts and worktrees. The delete dialog asks whether to keep or delete its agent conversations and memory. The built-in Terminal project can't be deleted.

How the agent uses the project

When a project is selected, the agent works in its folder. Its shell commands get the project's env file, and project notes and project memory stay scoped to it. You'll use this in the next module.

Check yourself

  • Your project's tile is on the rail with its own color or icon.
  • A new tab in the project starts in its folder with your startup command typed at the prompt.
  • echo $TRMNLY_PROJECT_NAME prints the project's name.

Go further