# Learn tuios

URL: https://tuios.dev/learn

> A hands-on tour that runs the real tuios in the browser, with a pretend shell. Each track is a list of steps: press the keys, and the page checks what tuios did.

## The basics

Windows, typing, the leader key and help. From zero. For: New here. About 4 minutes.

- **Open a window**: `n`. You start in window mode. Keys move windows.
- **Start typing in it**: `i`. i flips to typing mode. Watch the badge.
- **Say hi to the shell**: `fastfetch enter`. Your keys go to the program now.
- **Split with the leader key**: `ctrl+b |`. ctrl+b, let go, then a key. It works in any mode.
- **Back to window mode**: `ctrl+b esc`. ctrl+b, then esc. The badge flips back.
- **Hop between windows**: `tab`. The bright border follows you.
- **Close one**: `x`. No prompt, no fuss.
- **Every key, one page**: `? esc`. Forgot a key? It is in here.
- **Or just search for it**: `ctrl+p zoom enter`. The command palette runs anything by name.

## Coming from tmux

Turn on the tmux keys. Your fingers already know the rest. For: tmux users. About 5 minutes.

- **Pick the tmux keys**: `U ↓ enter`. U opens the keybind presets. tmux is the second row.
- **Split right**: `ctrl+b %`. Same as tmux. Each split makes a new pane.
- **Split down**: `ctrl+b "`. Same as tmux.
- **Move between panes**: `ctrl+b ←`. Same arrows as tmux. One ctrl+b covers a few arrows in a row.
- **Jump by number**: `ctrl+b q 2`. ctrl+b q shows a number on each pane. Type one to go there.
- **Zoom in, then out**: `ctrl+b z ctrl+b z`. Same as tmux.
- **A new workspace**: `ctrl+b c`. tuios calls a tmux window a workspace. Each workspace has its own panes.
- **Back to the last one**: `ctrl+b p`. ctrl+b p goes to the previous workspace, as in tmux.
- **Copy mode, vim keys built in**: `ctrl+b [ / tuios enter q`. tmux used emacs keys unless you set mode-keys vi.
- **Meet window mode**: `i ctrl+b esc`. New: a mode with no prefix. Single keys move panes. i types into the pane, ctrl+b esc comes back.
- **Detach, same as ever**: `ctrl+b d`. ctrl+b d detaches, like tmux. A daemon keeps every pane running. tuios ls lists sessions, and ctrl+b s switches between them. Put preset = "tmux" under [keybindings] to keep these keys.

## Coming from zellij

Turn on the zellij keys, then use them: panes, tabs, floats, search. For: zellij users. About 5 minutes.

- **Pick the zellij keys**: `U ↓ ↓ ↓ enter`. U opens the keybind presets. zellij is the fourth row.
- **Locked, like zellij**: `i top enter`. i starts typing. Every key now goes to the program, except ctrl+g.
- **Split right**: `ctrl+g p r`. ctrl+g opens the menu. p is the pane menu, r splits right.
- **Split down**: `ctrl+g p d`. Same menu, d for down.
- **Move between panes**: `ctrl+g p k esc`. h, j, k and l move. The menu stays open for more moves. Esc closes it.
- **Fullscreen, then back**: `ctrl+g p f ctrl+g p f`. f in the pane menu, as in zellij.
- **Float a pane**: `ctrl+g p e`. e in the pane menu. Drag its title bar with the mouse to move it.
- **A new tab**: `ctrl+g t n`. A zellij tab is a tuios workspace. t is the tab menu, n makes one.
- **Scroll and search**: `ctrl+g s / tuios enter q`. s is scroll mode, here copy mode. / searches, q leaves.
- **Sessions and detach**: `ctrl+g d`. ctrl+g d detaches, as in zellij, and a daemon keeps it all running. ctrl+g o is the session manager. Put preset = "zellij" under [keybindings] to keep these keys.

## Layouts

Tiles, a master and a stack, a scrolling strip, and floats. For: Tidy minds. About 5 minutes.

- **Choose where it lands**: `alt+j n`. alt and h, j, k or l picks the side. Then n.
- **Rotate the split**: `R`. Side by side becomes stacked, and back.
- **Swap two windows**: `H`. shift+h, shift+j, shift+k and shift+l push the window that way.
- **Master and stack**: `ctrl+p master-stack enter`. One big window on the left, the rest stacked on the right.
- **Grow the master**: `>`. > grows it, < shrinks it.
- **The scrolling strip**: `ctrl+p scrolling enter`. Columns on an endless strip. New ones slide in, nothing shrinks.
- **Widen a column**: `>`. The strip scrolls to keep it in view.
- **Zoom in, then out**: `z z`
- **Let them float, then snap**: `t h`. t turns tiling off. h and l snap to a half. Floating windows can overlap, and the snapped one sits on top.

## Workspaces

Nine desktops in one terminal, and a side rail that shows it all. For: Many projects. About 4 minutes.

- **Visit workspace 2**: `ctrl+b w 2`. Your two windows wait on workspace 1.
- **Make it yours**: `n`. Each workspace has its own windows and layout.
- **Jump straight back**: `alt+1`. alt and a number skips the prefix.
- **Send a window, stay here**: `ctrl+alt+2`. ctrl+alt and a number sends the window away. You stay put.
- **Send a window and follow**: `ctrl+b w #`. In the workspace menu, shift and a number moves the window, and you go with it.
- **Open the rail**: `ctrl+b b`. Sessions, windows, agents and files, at a glance.
- **Walk the rail**: `s j j enter`. s steps in. j and k move, enter jumps there.
- **See every workspace**: `ctrl+b W enter`. Go to opens on the workspaces of this session.
- **Every session, every machine**: `ctrl+b S`. On your machine the rail lists every session, and sessions on your other machines too. ctrl+b S switches between them.

## Power moves

Palette, launcher, copy mode and the scrollback browser. For: Keyboard fans. About 5 minutes.

- **Show your keys**: `ctrl+b D k`. Every key you press now pops up bottom right.
- **Menus inside menus**: `ctrl+b t esc`. After ctrl+b the panel lists every next key. t opens the window menu.
- **Run anything by name**: `ctrl+p split vertical enter`. No key to remember. Just type.
- **Launch a program**: `ctrl+b a rain enter`. ctrl+b a opens the launcher. alt+space does too.
- **Copy mode with vim keys**: `ctrl+b [ / WebAssembly enter`. hjkl, w, b, gg and G all work. / searches.
- **Select and yank**: `v e y q`. v selects, e stretches it a word, y copies. q leaves.
- **Browse old commands**: `ctrl+b s esc`. Every command and its output, newest first.

## Pane tricks

A scratch pane, a pane in the corner, numbers, hints and the spotlight. For: Busy screens. About 4 minutes.

- **Open a scratch pane**: `ctrl+b g`. A pane that floats over the rest, for a quick job.
- **Hide it, keep it**: `ctrl+b g`. The same keys hide it. It keeps running for next time.
- **Pin a pane**: `ctrl+b esc p`. p in window mode pins the pane you are on, the rain.
- **Watch it from another pane**: `tab`. The pinned pane shows in a small corner window.
- **Unpin it**: `p`. p again puts it away.
- **Jump by number**: `ctrl+b Q 1`. Every pane gets a big number. Type one to go there.
- **Copy what you see**: `ctrl+b 2 ctrl+b F a`. Hints put a letter on each hash, path and link. Type it to copy.
- **Light up one pane**: `ctrl+b B esc`. The spotlight dims the rest of the screen. Good for a demo.

## Agents

Run coding agents side by side and never miss a question. For: Agent herders. About 4 minutes.

- **Open the rail**: `ctrl+b b`. Every agent shows up here, with what it is doing.
- **Start an agent**: `claude enter`. A pretend Claude Code. It never leaves this tab.
- **Go do something else**: `ctrl+b w 2`. It will ask you something soon. You will know.
- **Jump to the question**: `ctrl+b j`. The rail turns orange and the dock rings. ctrl+b j takes you there.
- **Say yes**: `y`. y approves. The mark turns green when it is done.
- **Agents that talk**: `ctrl+b M`. On a real machine agents find each other with tuios list-agents and mail each other. ctrl+b M opens the mail between them.
- **Every agent in one view**: `ctrl+b i`. ctrl+b i opens the agents view. The next track, The agents view, shows what it does.

## The agents view

Answer, reply to and start agents from one view. For: Agent herders. About 5 minutes.

- **Go do something else**: `ctrl+b w 2`. Three agents work in the other panes. They keep working while you are away.
- **Open the agents view**: `ctrl+b i`. Every agent on every workspace, grouped by what it needs from you.
- **Read the edit first**: `]`. claude wants to edit style.css. ] goes to the next tab: the changes of its turn.
- **Allow the edit**: `a enter`. Press a to ask to allow it once, then enter to send it. shift+a asks to always allow it. r asks to reject it, and shift+r to give a reason. Any key but enter drops the ask.
- **Peek at the question**: `g space`. g goes to the top row: gemini asks which colours to use. Space reads its question.
- **Pick an answer**: `2 enter`. The number of an option asks to answer with it. Enter sends it, and tuios presses it in gemini's pane.
- **Reply to a finished agent**: `g r add a test for an empty name enter`. codex is done and waits at the top. r writes to it, and enter sends.
- **Start three attempts**: `n add a footer shift+tab shift+tab shift+tab + + enter`. An attempt is one agent that tries the task. Several attempts of one task make a fan. n opens the New agent sheet, + adds an attempt.
- **Compare, then open one**: `G c enter`. shift+g goes to the last row, an attempt. c shows the attempts of the fan side by side. Enter opens the one under the cursor.

## Automation

Tapes that drive tuios, a JSON protocol, and hooks. For: Scripters. About 4 minutes.

- **Read a tape**: `cat demo.tape enter`. A tape is a script of keys and commands.
- **Press play**: `tuios tape play demo.tape enter`. Hands off. tuios types it all.
- **Find more tapes**: `tuios tape list enter`
- **Play the party tape**: `tuios tape play party.tape enter`. Three programs, a zoom and a trip to workspace 2.
- **Drive it with JSON**: `tuios list-verbs`. The daemon speaks JSON lines on its socket. Open windows, type, read panes and wait for output from any script. tuios list-verbs lists it all.
- **Run a command on events**: `tuios list-hooks`. Hooks run your shell commands when a window opens, focus moves, or an agent finishes. Put them in [hooks] in your config.

## Surfaces and diagrams

Forms, dashboards, diagrams and charts, drawn by tuios. For: Tool builders. About 5 minutes.

- **Read the markup**: `cat deploy.tml enter`. TML is the markup tuios draws forms and dashboards from. A file is a tree of parts with a JSON state.
- **Draw it as text**: `tuios tml render deploy.tml enter`. tuios tml render shows the file the way a pane draws it.
- **Open the form**: `tuios tml show deploy.tml --wait enter`. A surface is a TML file that tuios shows live, in a popup or a pane. With --wait, the command waits for your answer.
- **Move to the form**: `ctrl+b 2`. The keyboard focus stays on your shell. ctrl+b 2 moves the focus to the form. A click works too.
- **Deploy to production**: `↓ enter tab enter`. down and enter pick production. tab goes to Deploy. enter sends the answer to the shell.
- **Draw the deploy flow**: `tuios mermaid flow.mmd enter`. tuios mermaid draws a Mermaid diagram as text that fits the pane.
- **Chart the sales**: `tplot sales.csv --kind bar enter`. tplot reads CSV and draws it in your theme's colours.
- **Open a dashboard pane**: `tuios tml show status.tml --pane enter`. A table, a chart and a diagram in one surface. --pane tiles it beside your shell.
- **Float the dashboard**: `ctrl+b → ctrl+b t f`. ctrl+b right moves to it. ctrl+b t f floats it. Press ctrl+b t f again to put it back in the tiles.

## Files and review

Walk a project in the rail, open a file, and review its change. For: Code reviewers. About 5 minutes.

- **Go to the project**: `cd projects/hello enter`. A small Go project. It has a change in it.
- **Open the rail**: `ctrl+b b`. The files section lists the folder of this pane.
- **Give the rail the keys**: `ctrl+b e`. ctrl+b e moves the keyboard into the rail. The same keys bring it back.
- **Walk to greet.go**: `j j j j j j`. j moves down and k moves up. The lit row is the cursor.
- **Open the file**: `enter`. Here enter opens it in a viewer. On your machine, enter copies the path and shift+enter opens your editor.
- **Review the change**: `ctrl+b v`. ctrl+b v shows what changed in the repository of this pane.
- **Jump to the next hunk**: `]`. A hunk is one block of changed lines. ] goes to the next hunk, [ to the one before. } and { go by file.
- **Leave a note**: `c Add a test enter`. c writes a note on the line under the cursor. enter saves it.
- **Send your notes**: `S`. On your machine, S sends the notes to the agent in this pane. esc closes the review.

## Ship a change

Make a worktree, change a file, review it, and open a pull request. For: Shippers. About 5 minutes.

- **Make a worktree**: `ctrl+b U`. A worktree is a second checkout of the project on its own branch.
- **Name the branch**: `shout enter`. tuios makes the branch and the folder, and opens a pane in it.
- **List the worktrees**: `git worktree list enter`. The new pane is in the worktree. The prompt shows its branch.
- **Change a file**: `echo "Ship it." >> README.md enter`. An agent does this part on a real machine. Here you add a line.
- **Review the change**: `ctrl+b v q`. ctrl+b v shows the change against main. q closes it.
- **See the ship steps**: `tuios ship enter`. tuios ship lists the steps from this worktree to a merged change.
- **Commit the change**: `tuios ship commit -m Docs enter`. tuios ship commit commits every change on the branch.
- **Open a pull request**: `tuios ship pr enter`. tuios ship pr pushes the branch and opens a pull request. In the demo, nothing leaves the tab.

## Your keys, your way

Presets for tmux, screen and zellij, actions by name, every key. For: Keyboard owners. About 4 minutes.

- **Open the keybind presets**: `U`. Each preset gives you the keys of another multiplexer.
- **Try the screen keys**: `↓ ↓ enter`. The panel says which keys your programs lose. Screen's leader is ctrl+a.
- **Split the screen way**: `ctrl+a S`. ctrl+a, then shift+s, as in screen.
- **Hop with tab**: `ctrl+a tab`. ctrl+a, then tab moves to the next region.
- **Back to the tuios keys**: `ctrl+p preset enter ↑ ↑ enter`. Every preset is a row in the palette too.
- **Run any action by name**: `ctrl+p #zoom enter`. In the palette, # searches every action and shows its keys.
- **Every key in one list**: `ctrl+b k esc`. Search it with /. Esc closes it.

## Look and feel

Themes, a theme editor, glyphs, borders, titles and a screen saver. For: Ricers. About 5 minutes.

- **Try on a theme**: `ctrl+p theme enter nord enter`. Type to filter, arrows to browse. Watch top change colour.
- **Open the theme editor**: `ctrl+p theme enter ctrl+f nord ctrl+e`. ctrl+f shows only the dark themes. ctrl+e edits the theme under the cursor.
- **Change the accent colour**: `enter → → ↑ ↑ enter`. Enter opens the colour picker. The arrows move the colour. Enter keeps it.
- **Drop the change**: `esc esc`. On your machine, ctrl+s saves it as your own theme. Here, esc twice drops it.
- **Pick heavy glyphs**: `ctrl+b , / glyph enter heavy enter`. ctrl+b , opens the settings. / searches them. Glyphs are the shapes of frames and marks.
- **Draw borders with them**: `esc / border style ←`. Set Border style to glyphs and the frames turn heavy.
- **Change the title style**: `esc / title style →`. A title is a pill, a tab or plain text on the border.
- **Mark the rail's current row**: `esc / current row → esc esc`. The rail is open on the right. Current row sets how it marks where you are.
- **Start the screen saver**: `S esc`. It kicks in by itself when you step away. Give it a few seconds, then any key wakes it.
- **Keep it forever**: `i cat .config/tuios/config.toml enter`. Your picks, saved in one file.
- **Share your theme**: `tuios theme share nord enter`. One line holds the whole theme. Paste it in a chat.

## Sessions and machines

Sessions that outlive the terminal, other machines, and your phone. For: Power users. About 5 minutes.

- **Sessions outlive the terminal**: `ctrl+b d`. A session holds your workspaces and panes. The daemon keeps it running after you close the terminal. ctrl+b d detaches, and tuios attach work brings it back.
- **List your sessions**: `tuios ls enter`. The demo prints what a real machine shows. There, ctrl+b S switches between them.
- **Find sessions in the rail**: `ctrl+b b`. The demo has one session, local. On your machine, every session is here.
- **Go to anything**: `ctrl+b G api enter`. One list of agents, sessions, workspaces and panes. Type to filter.
- **Move a window elsewhere**: `tuios move-window`. tuios move-window sends a window to another session. The program in it keeps running, with its scrollback.
- **Leave a note for later**: `ctrl+b I`. A return note says what comes next. Press ctrl+b, then shift+i, to write one for the session. The dock shows it when you come back.
- **Restart the daemon**: `tuios restart-server`. A new tuios needs a new daemon. --dry-run shows what stops and what comes back. Each session comes back with its layout and pane history.
- **Your other machines**: `tuios hosts`. tuios hosts add links another machine over ssh. Its sessions and agents show in your rail, and a pane can run there.
- **Your phone and the browser**: `tuios-web`. tuios-web shows your sessions in a browser, on a phone too. Web Push tells your phone when an agent needs you.
- **Hand out work as cards**: `tuios task add`. A task card is one piece of work in a session. An agent takes the oldest open card with tuios task claim --next. The card moves from todo to done.
