ADR-517: The images mod ships from agent-ways as a fourth mod, installed by default, its history moved from the operator's dotfiles¶
Summary¶
- Decided: The
imagesmod, which draws pictures inline in the terminal transcript, ships from agent-ways in theagent-waysmarketplace beside attend, ways-judge and ways-theme. Its source moves toplugins/images/with its four commits, rewritten bygit filter-repofrom the dotfiles path and merged with--allow-unrelated-histories. It joinsMODSasimages@agent-ways, not critical, at Claude Code 2.1.304, andmods.images.installdefaults to true on every platform. On darwin the mod sizes pictures from a 10x20-pixel cell guess, without runningpython3, until a macOS cell-size probe is verified. Its version moves with ways', and its tests joinmake test-plugins. Its five options become ways settings undermods.images.*, and the plugin drops itsuserConfig. ways-theme frames the pictures images draws, and the contract between the two is tested in this repo with both mods' code loaded. The dotfiles stop shippingimages@dotfilesafter agent-ways ships images; until then repair reports the dotfiles copy and installs nothing beside it. - Trades away: The mod's own release cadence: a change to it waits for a ways release, and its version jumps from 0.1.0 to ways'. ways takes on its terminal matrix (kitty, Ghostty, Konsole, iTerm2, tmux, ssh) and its ImageMagick dependency as its own to support. Its options leave Claude Code's
/config, and a host that runs it without ways gets its defaults. Macs draw every picture at a guessed size, possibly too large or too small, until the macOS probe lands. Every session gains a mod that draws in the transcript unless the operator turns it off. The imported commits get new hashes and lose any signature. - One-way? No, apart from history. Withdrawing the mod is
mods.images.install: false, and moving its folder back to the dotfiles is a session's work. The four imported commits and their merge stay in main's history once merged, since main is not rewritten. - Probes: Confident (one place): images' options, its scale, captions, bare paths in replies, renderer and the SendUserFile hint, are set in ways settings beside ways-theme's, and Claude Code's
/configno longer lists them. Answered: ways settings (item 5). Not confident (Mac): on a Mac, images stays off until it has been run on one and its picture sizing checked there, andways manage mod install imagesturns it on before then. The other choice is to have it on for Macs too, drawing every picture at a guessed cell size. Answered: on, at the guessed size (item 7). - Inversion: At one end every mod lives where it was written, and the mods that depend on each other agree on a contract across repositories and test suites. At the other end agent-ways ships every mod its operator uses. This record moves a mod into agent-ways when another agent-ways mod has to recognise what it draws, and leaves other mods where they are.
Context¶
ways-theme (ADR-514) frames replies, tool rows and tool groups on the terminal surface. The images mod draws pictures under the rows that would otherwise show only a path, and lives in the operator's dotfiles, installed as images@dotfiles from a settings-declared marketplace. Framing its pictures, with their caption kept, needs ways-theme to recognise the element images draws. Held across two repositories, that contract would be tested in neither: claude plugin test runs one mod's folder, and ways-theme's tests cannot load a mod this repo does not hold.
The plumbing ADR-406 and ADR-512 built takes another mod as a table entry, a settings section and a marketplace entry: repair installs and converges it per target, ways manage mod and the settings screens' mod tab manage it, and the plugin checks hold its version and tests. The images mod measures its terminal's cell size through /proc, which exists on Linux only, and ways ships darwin builds.
Decision¶
-
A mod another shipped mod depends on ships from agent-ways. When an agent-ways mod has to recognise or wrap what another mod draws, the other mod ships from the
agent-waysmarketplace, so the contract between them lives in one repository and one test run. images is the first such mod. A mod with no such dependency stays where it was written. -
The move keeps the history. In a fresh clone of the dotfiles,
git filter-repo --path claude/mods/images/ --path-rename claude/mods/images/:plugins/images/leaves the four commits that touched the mod, each holding only the mod's files at their new paths. That branch is fetched into agent-ways and merged withgit merge --allow-unrelated-histories; the merge commit lists the dotfiles' original hashes from filter-repo's commit map. The rewrite keeps each commit's author, date and message. 83681f1's message describes the kitty tooling the dotfiles keep, and is left as written.git subtree addwould also keep the commits, with their files at the root of the mod's folder, sogit log -- plugins/imagesandgit blamewould stop at the merge; with filter-repo the files sit at their final paths in every commit. filter-repo runs only in a scratch clone and never in the operator's dotfiles checkout. -
The mod in this repo. The commits after the merge:
- add images to
plugins/.claude-plugin/marketplace.jsonwith its plugin description; - set its version to ways', add it to the ways loop in
scripts/check-plugins.shand toWAYS_MANIFESTSinscripts/release.sh, soscripts/release.sh bump waysmoves it; - add the test check-plugins.sh requires of a mod with hooks, its
register()run throughregistrationsOfand checked withpassedOverHits, and the copy of attend's passed-over list, somake test-pluginsruns its tests; -
rewrite the README's Install section for agent-ways.
-
The registry entry.
MODSgainsIMAGES: Mod { name: "images", id: "images@agent-ways", label: "images mod", min_claude_code: "2.1.304", critical: false }. The floor is the release whose engine-written declarations carry every call the mod makes (Image,Raster,$.ui.blit,onScreen), the one it was verified on. Not critical: a missing or pending images mod degrades nothing agent-ways does. The settings registry gainsmods.images, withinstalla machine-scope key read per target as ADR-512 item 1 sets for every mod. Its default is true on every platform. The mod draws on the terminal surface only and hands every other surface Claude Code's own element, as it does today. -
Its options are ways settings.
mods.images.renderer(auto,image,halfblock; defaultauto),scale(0.25 to 4; default 1),show_captions,show_paths_in_repliesandsteer_to_send_user_file(each default true) take the meanings the plugin's options have. They are set at user, target or project scope, the project winning, as ways-theme's render settings are (ADR-514 item 11), and edited in the mod tab or withways settings set. The plugin drops itsuserConfig, so Claude Code's/configoffers none of them. - The mod reads
ways settings list mods.images --json --effectiveat an interactive session's start, and again before it draws a picture when the last read is more than 5 s old. It runs no poll of its own, so a session that draws nothing callswaysonce. - Each read is bounded at 1.5 s. A missing or failing
ways, or output that does not parse, keeps the last good values, or the defaults before there are any, and writes one debug line per distinct reason (ADR-514 items 7 and 10). -
ways manage mod check imagesadds one check, ImageMagick on PATH, and a missing one is a ⚠ line naming it, by ADR-512 item 5's exit rule. -
The frame contract. While
custom:waysis selected, ways-theme frames each picture images draws, with its caption, as one framed row; outside that it leaves them as images draws them. The contract: - images marks the element it draws for a picture and its caption so ways-theme can find it without reading pixels;
- a picture is sized to the width it is drawn in, so the frame's four columns come out of the picture's width;
- the caption keeps the file's name with its link, its size in pixels and the percentage it is shown at, inside the frame.
The contract is written once, in this repo, and make test-plugins checks it with both mods' code: ways-theme's tests load images' own register() from plugins/images, or, where the test host confines a test to its mod's folder, each mod's tests hold one fixture of the contract, kept to one text by check-plugins.sh as it keeps the passed-over list. The framing itself is the ways-theme change in flight on fix/theme-frames-images.
- Darwin. The
/procprobe does not run off Linux, and a Mac's/usr/bin/python3without the Command Line Tools opens an install dialog. On darwin the mod takes 10x20-pixel cells without runningpython3, and it installs there by default as on Linux. A picture on a Mac is then sized from that guess, too large or too small by the ratio of the real cell to it, andscalecorrects it by hand. A verified macOS probe is later work that improves sizing there: it finds Claude Code's terminal without/proc, from the process's tty and its ancestors', and runs no interpreter stub that prompts. Once it has been run on a Mac in kitty or Ghostty and in iTerm2, the mod uses it in place of the guess.
Edited 2026-10-29: the operator chose "On, guessed size: images installs on Macs too, drawing at a 10x20-pixel cell guess until the probe lands". It read: "Until a macOS path is verified on a Mac, the mod takes 10x20-pixel cells on darwin without running
python3, andmods.images.installdefaults to false there. [...] Once it has been run on a Mac in kitty or Ghostty and in iTerm2, the darwin default becomes true in the same change."
- The switch from the dotfiles. In this order:
- agent-ways ships images (items 2 to 7). On a host where
images@dotfilesis installed, repair reports it as a plugin of the mod's name from another marketplace and installs nothing beside it, as attend_mod.rs does for every mod. Repair also counts as foreign animages@<other>that settings.json'senabledPluginsenables, since a plugin enabled from a settings-declared marketplace is absent fromclaude plugin listuntil a session has recorded that marketplace. The rule holds for every mod. So no host draws each picture twice. - The dotfiles change removes the mod, the
dotfilesmarketplace (images was its one plugin),claude/settings.d/70-mods.json, theclaude-modsmanifest entry and itstests/runsuite, sodotfiles deployleavesimages@dotfilesout of settings.json. Where a session recorded it,claude plugin uninstall images@dotfilesandclaude plugin marketplace remove dotfilestake it out of Claude Code. ways manage repair --commit, or the nextways manage update --commit, installsimages@agent-ways. The operator's settings hold no images options today, so nothing carries over.
The gap between steps 2 and 3 is one command, and in it pictures show as paths.
- Under the item descriptor. If the item descriptor proposed in PR #1206 is accepted, images is a
builtinmod item like the other three, with nothing particular to it.
This amends ADR-406's Decision, item 8, whose marketplace now ships four mods, images among those released with ways; and ADR-512's Decision, item 1, whose mods.<name> sections gain mods.images, with item 3's foreign-plugin case widened to a plugin enabled in settings.json.
Consequences¶
Positive¶
- ways-theme and images are changed, tested and released together, so a change to what images draws cannot break the frame unseen.
- images gets repair's install, update, floor check and per-target state, and
ways manage modand the mod tab manage it, with no code of its own for any of it. - Its options sit where the other mods' settings sit, and a change reaches an open session at its next picture.
- The mod's reasoning stays readable in this repo's log and blame.
- A plugin enabled from a settings-declared marketplace is now seen as foreign for every mod, closing a window in which repair could install a second copy.
Negative¶
- Reports from every terminal images runs in become agent-ways issues, tmux and ssh among them, and the mod's behaviour differs across them (pixels in kitty and Ghostty, half-blocks elsewhere, the PNG's bytes over ssh).
- A Linux host without ImageMagick shows a dim note at each picture until it is installed;
mod checknames it, and the installer installs nothing for it. - A Mac draws each picture from the 10x20 guess, which can be too large or too small for its cells, until the macOS probe lands, and someone has to run the mod on a Mac to get there. Most Macs lack ImageMagick, so many show the dim note at each picture until it is installed.
- The mod's version tracks ways', so a ways release bumps it with nothing changed in it, and a fix to it waits for a ways release.
- A host that runs images without agent-ways can no longer set its options; it gets the defaults.
- The frame contract adds a test that spans two mods, which check-plugins.sh has not had before.
- In the gap of item 8 step 2, until repair runs, the operator's sessions show paths where pictures were.
Neutral¶
- The dotfiles keep the shell image tooling (
72-images,ls-thumbs, the kitty aliases); only the Claude Code mod moves. - The mod's cache directory, its render log flag and its ssh handling are unchanged.
claude --plugin-dir plugins/imagesstays the way to load a working copy, as the README's Developing section already says.
Alternatives Considered¶
- Keep images in the dotfiles and have ways-theme recognise it across repositories. No move. Rejected: the contract would live in two repositories and be tested in neither, and a change in the dotfiles could break the frame with no failing test here.
- Give images a repository and marketplace of its own. It stays usable without agent-ways and keeps its own releases. Rejected: the contract with ways-theme still spans two repositories, and a second marketplace adds a second release pipeline and install path for one mod.
- Copy the files in one commit. The simplest move. Rejected: the four commits carry the reasons behind the sizing, the burst handling and the captions, and blame would point at the import.
git subtree addfrom agit subtree splitof the dotfiles path. No extra tool, and the commits keep their original trees. Rejected for item 2's reason: path-limited log and blame stop at the merge.- Off by default everywhere, as ways-theme is. ways-theme replaces the person's Claude Code theme, which is why it waits to be asked for. images replaces nothing: it draws under rows that show only a path, and does nothing off the terminal, so it is on by default.
- Off by default on darwin until the macOS probe is verified. No picture on a Mac is sized by a guess. Declined by the operator, who chose to have Macs draw at the guessed size until the probe lands.
- Keep the options in the plugin's
userConfig. The mod keeps working without ways, and Claude Code's/configedits them. Rejected: ADR-514 put every mod setting in ways settings, with no menu in Claude Code, and two homes for one mod's settings would leave the mod tab unable to show them. - Critical, as attend and ways-judge are. Rejected: agent-ways loses nothing when images is missing, and a critical flag would mark a host degraded for a missing picture renderer.