Chapter 1 of 15

Four Terminal Tabs and a Lot of Hope

Freddy has a notes app and three jobs for it: fix a bug in the export, add a search box, and write the tests nobody wrote. He has started all three, in three terminal tabs, and he can no longer say which one is waiting for him.

The problem

A coding agent in a terminal is a good tool for one task. The trouble starts at the second. The first agent is halfway through a refactor in the project folder, so the second one either waits or edits the same files. The third tab is the dev server. A fourth holds git status, which you run more often than you would admit, because the honest answer to “what did it just change?” is somewhere above the scrollback.

And then one of them asks a question. It does so politely, in plain text, and stops. Nothing in the other tabs tells you. The cost is not the agent's time; agents are patient. The cost is yours: every task is a thing you have to remember to go back and look at.

The hard way

People solve this in the same few ways, and each one works for a while:

  • Tab discipline. Name the tabs, keep one per task. It holds until the fifth task, and it does nothing about the agent that is waiting.
  • Several clones of the repository. One copy per task, so agents cannot collide. It does work, and it costs a folder, a branch and a dependency install every time, and you merge them by hand.
  • An editor with an agent panel. You get a window, and the agent comes with it — one agent, one way of talking to it, and the editor's idea of what a task is.

What all three have in common is that the task is not a thing the computer knows about. It is a tab, a folder or a habit.

What Workspace is

Elyra Workspace is a desktop app for working with coding agents. You add your project folders, start a thread for each task, and talk to an agent such as Claude Code. The changes it makes, Git, a terminal and your files are in the same window. Everything runs on your Mac: conversations are stored in a local database, and the agents run as the command-line tools you already have installed.

That last sentence matters, so read it twice. Workspace is not an agent. It does not ship one and it does not replace the one you use. It runs the agents you already installed — Claude Code, Codex, Elyra, Pi, and other agents that speak ACP — and puts a window around them.

Four ideas, and then you know the product

Almost everything in the next fourteen chapters hangs on four words, so here they are once, plainly:

  • Project. A folder on your disk, usually a Git repository. Freddy's is freddy-notes.
  • Thread. One task. It has its own conversation, agent session, model and settings, and it works either in the project folder itself or in its own Git worktree. “Fix the export bug” is a thread.
  • Provider. The coding agent that runs the thread, such as Claude Code. Each thread uses one provider. You can fork a thread or hand it off to another provider.
  • Turn. One message from you and the agent's work until it stops. Before every turn, Elyra saves a checkpoint of your files so you can go back. If the project has a check command, the turn is only done when it passes.

The last of those is the one to underline. A turn is the unit that Workspace protects: it snapshots before it, and can judge after it. Chapters 4 and 9 are about those two halves.

The shape of the window

The window has three parts, and you will learn to find things by which part they live in:

  • The sidebar (⌘B): projects and their threads, pinned threads, and buttons for the task board, automations, code review, a new chat and adding a project.
  • The center: the open threads as tabs. The task board, automations, the review inbox and usage statistics open here as well.
  • The tools panel (⌥⌘B): tools for the active thread — Changes, PR, Files, Browser, Context, Terminal and Side chat.

The limits, up front

  • Apple Silicon Macs only. A Mac with M1 or later, macOS 12 or later. Intel Macs are not supported.
  • You bring the agents. At least one has to be installed and signed in, or there is nothing to talk to.
  • One thread, one provider. Mixing agents happens between threads, by forking or handing off, not inside one turn.
One honest note before we start. Workspace does not make an agent smarter. It makes the agent's work visible, parallel, checkable and safe to leave. The agent is still the agent you installed, with its own strengths and its own bills, and this course says so wherever it matters.
Try it: before you install anything, write down the three tasks you would start tomorrow. In chapter 6 you will start all three, in one window, and know the state of each at a glance.

What you learned

  • Why a tab, a folder or a habit is a poor way to represent a task
  • That Workspace runs the agents you already have, and is not an agent itself
  • The four ideas everything else hangs on: project, thread, provider, turn
  • The three parts of the window: sidebar, center, tools panel
  • The limits: Apple Silicon only, and you bring the agents
Next: in Chapter 2 you install the app, launch it for the first time, and start a thread.