Agent Tiler

Agent Tiler keeps your AI agent windows in a tidy grid and colours the new ones green.

See it

New windows slot into an even grid. Fresh ones glow green, then fade.

Get it

Install

Paste this to your agent (Claude Code, Codex or whichever you use). It does the rest.

Set up Agent Tiler from https://mcissel-ai-tools.pages.dev/tiler/ : download the zip there and follow its README.

Or install by hand

Install Hammerspoon (a free Mac helper that can move windows) and tmux.
```
brew install --cask hammerspoon && brew install tmux
```

Unzip the download and step into the folder.

cd ~/Downloads && unzip agent-tiler.zip && cd agent-tiler

Copy the tiler and the iTerm helper script into Hammerspoon.

D=~/.hammerspoon/agent-tiler && mkdir -p $D && cp -R hammerspoon/agent-tiler/* bin/it2-open-window.py $D/

Copy your settings (kept if you already have some) and put the window opener on your PATH.

cp -n hammerspoon/agents-config.lua ~/.hammerspoon/ && cp bin/open-agent-window "$(brew --prefix)/bin/"

iTerm only (app = "iTerm2"): give the iTerm helper its own Python. Then turn on iTerm's Python API (Settings › General › Magic › Enable Python API).
```
python3 -m venv ~/.hammerspoon/agent-tiler/pyenv && ~/.hammerspoon/agent-tiler/pyenv/bin/pip install -q iterm2
```
Switch it on when Hammerspoon starts (run this once). Then choose Reload Config and allow Accessibility when macOS asks.
```
printf '\nrequire("agent-tiler").start(require("agents-config"))\n' >> ~/.hammerspoon/init.lua && open -a Hammerspoon
```

Use it

Tell your agent to open its work in a tiled window.
```
open-agent-window agent-demo
```
A new Terminal window joins the grid. Your cursor stays where it was.
Run a command in that window.
```
open-agent-window agent-tests "npm test"
```
The window runs your command and stays open.
Tidy everything right now.
```
hs -c 'agentTiler.tile()'
```
Every agent window snaps back into the grid.

How it works

Each agent runs in a tmux session named agent-something.
tmux puts that name in the window title.
Hammerspoon finds windows whose title matches your pattern. It ignores every other window.
It splits the screen into an even grid: one is full, two sit side by side, four make a 2 by 2.
Agent windows open in Terminal, behind your work. You type in iTerm, so a new window can't take your keyboard.

Hammerspoon: a free Mac app that automates windows
tmux: a terminal session that keeps running in the background
iTerm: a popular Mac terminal app
Terminal: the terminal app that comes with every Mac

Settings

File: ~/.hammerspoon/agents-config.lua

app: The app agent windows open in: Terminal or iTerm2. Pick the one you do not type in.
titlePattern: Which window titles count as agents (a Lua pattern).
screen: Which screen to use: builtin, primary, or part of a screen name.
tmux: Where tmux is installed.
cliPrefix: Where the hs command gets installed.
debounceSecs: How long to wait before re-tiling.
paintEverySecs: How often colours are refreshed.
fadeSecs: How long a fresh window stays green.
gap: Pixels between windows.
colors.fresh: Colour of a brand-new window.
colors.settled: Colour it fades to.
colors.base: Colour after the fade ends.
colors.closing: Colour of a window that is finishing.
startedOption: The tmux option that marks when an agent started.
closingOption: The tmux option that marks an agent as closing.
python: Which python3 runs the iTerm helper.
apiScript: Where the iTerm helper script lives.
focus.strategy: How iTerm windows open: api (no immediate activation), applescript, background, or auto. Terminal has one way.
focus.guardSecs: How long focus is guarded after a window opens, in seconds (10 covers iTerm's late activation).

Questions

Will it move my other windows?

No. Only agent windows whose title matches your pattern.

Will it steal my keyboard focus?

No. A new window can only take your keyboard when its app is already in front. Agent windows open in Terminal while you type in iTerm, and Terminal never came forward in our tests. iTerm did, 3 to 7 seconds after every new window, which is why agents no longer open there.

Why does it ask for Accessibility?

macOS only lets apps move windows with that permission. It asks once.

I type in Terminal, not iTerm. What now?

Swap them: set app = "iTerm2" in agents-config.lua, so agents open in iTerm and you keep Terminal. Expect iTerm to push itself forward now and then; the tiler hands your focus straight back. And Eric, if you use Terminal, then tell your agent to swap which one this tool uses!

How do I turn it off?

Delete the require line from ~/.hammerspoon/init.lua and reload.

Back to the toolbox