Projects and machines
This is the one idea in Shio that is not already in every other terminal, so it is worth five minutes. Everything else behaves the way you expect.
a project is the thing you're doing
Most terminals give you tabs and a saved list of hosts, and leave you to remember which is which. After a week that is eleven tabs and a guess.
A project in Shio holds three things: the repos it is made of, the machines those repos live on, and the shells you opened for them. You open the work, and where it runs is a detail Shio already knows.
A project can span machines. Its web repo can sit on your Mac and its server repo on a box in a cupboard, and it is still one project.
what a repo actually is here
A repo is a folder on a specific machine. The same repo can be checked out on more than one machine, and Shio treats those as the same repo in two places rather than two unrelated entries.
Open one and the terminal starts in that folder, on that machine, with the branch and the number of uncommitted files already on screen. That glance is the point: you should know whether a repo needs you before you type anything.
machines are all your devices
Your Mac, a server, a Raspberry Pi, a VPS, and your iPhone and iPad. Everything you own appears in one list, so nothing you own is missing from the place that claims to show what you own.
Not all of them are connectable, and Shio marks the ones that are. A phone is a place work happens, not a machine you SSH into, so it appears without an option to connect to it.
where a session actually lives
On the machine, not in the app. When you open a shell for a project, Shio starts or rejoins a tmux session on that host, named after the project.
That is what makes a session survive you. Close the Mac mid-build and the build keeps running, because it was never running in the app. Open the phone and Shio rejoins the same tmux session, output and all. Quit Shio entirely and nothing stops.
It also means a machine without tmux cannot do this. Each device gets its own separate shell instead, which is the single most common surprise. The FAQ covers the fix.
what syncs, and what doesn't
Syncs, through your own iCloud: your projects, repos, machines and settings. Add a machine on the Mac and it is on the phone before you pick it up. This is CloudKit in your account, not a database of ours.
Does not sync: the sessions themselves, and your keys. Sessions stay on the machines running them, which is the whole design. Keys stay in the keychain on each device, and each device has its own.
starting one
New project, then point it at a folder on any machine you have added, or paste a GitHub link and let it clone on first open. Add more repos to the same project as you go.
There is no wrong shape. A project with one repo is fine and common. The structure exists to save you remembering, not to be filled in.
next
If a machine is not reachable yet, the setup guide gets it there in about a minute. If something is not behaving, the FAQ covers the four things that usually go wrong. The keyboard shortcuts are worth a look once the model above makes sense, because most of them are about moving between these places quickly.