The Terminal (and cmux)

Related guides: Personal OS · Git · Zo Computer

Preface

The terminal is the text interface to your computer. You type a command, the computer does it and prints the result. It looks intimidating and old-fashioned; it is actually the most direct, most scriptable, most agent-friendly way to operate a computer — which is exactly why every serious coding agent (Claude Code, Codex CLI) lives in one.

You do not need to become a terminal wizard. You need to be comfortable enough to: open a terminal, get into your Personal OS folder, start an agent there, and — later — reach through to your cloud computer. The agent handles the rest; you can always ask it “what does this command do?” before running anything.

By the end of this guide you should be able to:

Move around in a terminal (cd, ls, pwd) without anxiety.
Install and use cmux, our recommended terminal for agent work.
Open your Personal OS in a cmux workspace and launch Claude Code or Codex inside it.
Run several agents in parallel and know when one needs you.
(Advanced) Log into your Zo computer from your terminal and run agents there.

Basics

1. Terminal survival kit

Any terminal (macOS ships with Terminal.app) speaks the same language. Five commands cover daily life:

pwd             # "print working directory" — where am I?
ls              # list what's in this folder
cd personal-os  # move into a folder ("change directory")
cd ..           # move up one level
cd ~            # jump to your home directory

The working directory matters more than any other concept: when you launch an agent, the folder you’re standing in becomes the agent’s world. Launch from the right folder and the agent sees the right context — this is the mechanical heart of the Personal OS “nested context” idea.

Two comforts: pressing Tab autocompletes file and folder names (type cd per + Tab), and the up arrow recalls previous commands. And the standing rule: if a command looks mysterious, paste it into your agent and ask what it does before running it.

2. cmux — our favorite terminal

cmux (cmux.com, open source, by Manaflow) is a native macOS terminal designed specifically for working with AI coding agents in parallel. Why we teach it over the stock Terminal:

Workspaces in a sidebar. Each project or agent session is a vertical tab with its own panes. You can see your whole fleet at a glance — each workspace shows its folder, git branch, and latest status.
Agent-aware notifications. When an agent finishes or needs your input, its sidebar tab lights up and the waiting pane gets a blue ring. This is the killer feature: you stop babysitting one agent and start conducting several.
Session restore. Quit and relaunch, and your workspaces, panes, and agent sessions come back.
Split panes and an embedded browser. Put an agent on the left and its dev server, logs, or a browser pane on the right.
It’s a real terminal. Everything in this guide works in it unchanged — including SSH to your Zo computer.

Requirements: macOS 14 or newer. (Windows/Linux students: use your system terminal for now — every command in this guide works there too; only the cmux-specific conveniences differ.)

3. Installing cmux

Either way works:

Homebrew (the macOS package manager — if you don’t have it, ask your agent to help install it):
```
brew tap manaflow-ai/cmux && brew install --cask cmux
```
Direct download: grab the DMG from cmux.com and drag it into Applications.

Launch it once and let it install its command-line helper so cmux works as a command. It auto-updates from then on.

4. Opening your Personal OS in cmux

cmux has no “Open Folder” ceremony — a workspace is just a terminal that remembers itself:

Press ⌘N for a new workspace.
cd ~/personal-os (or wherever yours lives — Tab-complete is your friend).
That’s it. The sidebar entry now shows the folder (and git branch, once your Personal OS is a repo).

If you run several related workspaces — say, one per project inside your Personal OS — select them and press ⌘⇧G to gather them into a named group.

5. Launching your agent inside your Personal OS

With a workspace standing in the right folder, starting an agent is one word:

claude    # Claude Code (Anthropic)
codex     # Codex CLI (OpenAI)

(First time on a machine: install the CLI and log in with your subscription — claude and codex both walk you through a browser login on first run. Ask your agent-of-choice’s installer page, or just ask any agent you already have.)

Because you launched from inside your Personal OS, the agent immediately reads your AGENTS.md and knows the terrain. This combination — right folder + agent CLI + your instructions file — is the basic unit of everything else in the course.

Running agents in parallel: open a second workspace (⌘N), cd into a different project, start another agent. Work stacks up; the sidebar tells you who needs you. A sane starting pattern is one workspace per project, one agent per workspace — parallelism across different tasks, not two agents editing the same files at once (that’s a recipe for conflicts until you learn the isolation tricks).

Advanced

6. Logging into your Zo computer from your terminal

Your Zo computer is a real Linux server, which means the classic remote-access tool applies: SSH (“secure shell”) — a terminal session on a different computer, tunneled securely to yours. Type locally, execute in the cloud.

One-time setup lives on the Zo side (creating a key and exposing the SSH service) — follow the steps in the Zo guide or Zo’s docs (docs.zocomputer.com/ssh-zo). Once configured, with the shortcut entry in ~/.ssh/config, connecting from any terminal is:

ssh zo

Your prompt changes — you are now typing on your Zo computer. pwd, ls, cd, Git, everything from this guide works there identically; your workspace lives at /home/workspace. Type exit to come home.

In cmux specifically, cmux ssh zo creates a dedicated remote workspace, so your cloud computer sits in the sidebar right next to your local projects — one glance spans both machines.

7. Running Claude Code or Codex inside your Zo computer

Here’s the payoff of the whole setup. SSH in, move to your Personal OS clone, start an agent:

ssh zo
cd /home/workspace/personal-os
claude        # or: codex

You are now running a frontier agent on your always-on cloud computer, inside the same Personal OS your local agents use. Close your laptop mid-task and the work needs to survive on Zo’s side — for long-running jobs, ask the agent to run them in a way that outlives your connection (it knows how). Logging in with your subscription on a remote machine has one wrinkle (the browser is on your laptop, the CLI is on Zo) — the Zo guide covers the device-code login flow for both CLIs.

The mental model to keep: the terminal is the same everywhere. Local cmux pane, SSH session on Zo — same commands, same agents, same Personal OS. Only the location (and the uptime) changes.

Practice

Open a stock terminal and navigate: home → your Personal OS → a project inside it → back home, using only cd, ls, pwd, and Tab.
Install cmux, create a workspace in your Personal OS, and launch your agent there. Ask it: “What folder are you in, and what do you know about this place?” — confirm it found your AGENTS.md.
Run two agents in parallel on two different projects. Switch away from both; wait for a sidebar notification to pull you back.
Split a pane and run something useful beside your agent — git log --oneline, a dev server, or the embedded browser.
(Advanced) Complete the SSH setup from the Zo guide, then run the full loop: ssh zo, cd into your synced Personal OS, launch an agent, have it make a small change, commit and push — then pull it on your laptop.

Proof of understanding

Why does the folder you launch an agent from matter? What does the agent read when it starts in your Personal OS?
What problem do cmux’s sidebar notifications solve when you run more than one agent?
What is SSH, in one sentence? After ssh zo, where do your commands execute?
You’re SSH’d into Zo and start a long agent task, then your laptop dies. What determines whether the task survives?
Why is “one agent per project” the sane default for parallelism?