Save Your Whole Terminal Workspace as a Project in Polter

You have the same three tabs open every day: a dev server, tail -f on a log, and a pane for git and vim. Then you restart. You cd three times, retype three commands, and whatever error you were reading is gone.

Polter is a terminal for macOS and Windows built on Ghostty's rendering. Its main feature is projects: workspaces you save and load back later. This post follows the video chapter by chapter.

A quick note on the base: Polter uses Ghostty's rendering, VT parsing, and fonts (MIT). It is not an official Ghostty project and is not affiliated with it.

1. Set up a normal workday

The demo project is called shop-web. It has three tabs:

• Tab 1, split in two with ⌘D. Left: python3 -m http.server 8123. Right: tail -f logs/app.log.
• Tab 2: git log --oneline -20, then a quick edit in vim README.md.
• Tab 3: a few loose commands such as ls -la and du -sh *.

2. Save it as a project

Right-click a tab and choose Save as Project… (it is also in the Project menu). The dialog lists the window's tabs. Only the current one is ticked, so tick all three, type a name (shop-web), and confirm.

You only do this once. Polter writes layout changes back to the project on its own. If you drag a split divider, the new ratio is saved without another click.

3. Quit, reopen, load

Press ⌘Q. If a process is still running, Polter asks first; click Terminate. Reopen the app and you get a single empty window. Choose Project → Load Project… and pick shop-web.

You get your three tabs back, along with the split ratio, every pane in its own directory, and the old output. A dim divider line separates the last session from the new one:

── Above this line: history restored from the previous session ──

Below it sits a fresh prompt.

4. What does not come back

This part matters more than the demo.

• Processes. The server in the left pane is not running. The pane shows the old output and a new shell. Your command history did come along: press Up, then Enter, and the server is back.
• Full-screen programs. The tab where you used vim shows what was printed before vim opened, not vim.
• Kitty graphics come back as blank space.

If you need processes to survive, that is tmux's job. tmux keeps processes alive when you close a window, though its server also dies on reboot. You can run tmux inside Polter.

5. Crashes and power cuts

Scrollback is written to disk while panes run: every 5 seconds by default, new lines only. In the worst case, you lose about 5 seconds of output. Each pane keeps 10 MB of scrollback by default, which is about 120,000 lines of plain text. When it fills, the oldest lines go first.

The two settings are project-scrollback-autosave-interval and project-scrollback-limit-bytes.

6. The Settings window and your config file

Press ⌘, to open Settings. Changing the font size updates the terminal immediately, with no save button.

The window edits your plain-text config. On macOS the file is at ~/Library/Application Support/com.lugia.polter/config.polter. If a setting is already in the file, such as font-size = 20, Polter replaces that line in place. If it is not there, Polter appends it at the end in a block marked as written by the Settings window. A backup (config.polter.polter-bak) is made before the first write after each launch.

You can still edit the file by hand. Save it, press ⇧⌘, to reload the config, and the Settings window shows the new value. The window does not watch the file, so it will not update without that reload.

7. The MCP interface

The last chapter is for tinkerers. Polter ships an MCP interface: other programs can list your terminals, read a screen, and type for you. The config line is:

{"command": "polter", "args": ["+mcp"]}

In the video I use the generic MCP Inspector to call terminal_list, terminal_read and terminal_send. It has guards. If you typed in a pane in the last ten seconds, terminal_send is refused with UserPresent. If there is half a command on the line, it is refused with DraftInLine. Setting poltergeist-mcp = false turns the interface off. I have only exercised it through the Inspector.

8. Windows and download

The same project model runs on Windows; the video shows a short clip. Packages are on the releases page for macOS 13+ and Windows 10+. There is no Linux installer yet, so on Linux you build from source.

Download: https://github.com/Lugia123/polter/releases/latest
Source (MIT): https://github.com/Lugia123/polter

If you try it, save a project, quit, reopen, and look for the divider line. I would like to hear what you would want saved that is not.