Files first

Hallway is built for the servers coding agents spin up. Its agent interface follows the author’s sibling project Local Review: files first, MCP second.

Plain files are the interface

v0 Everything Hallway knows lives in small YAML files under ~/.hallway (the data home). An agent that can read and write files can:

• register a server by writing apps/<slug>.yaml (a name and a port is enough);
• add bookmarks by editing bookmarks/<group>.yaml;
• check what’s running with hallway status --json or GET http://localhost:4255/api/state.

A file watcher turns every edit into a live update, so the dashboard changes within a second, whether the edit came from you, your editor, an agent, the CLI or the API. That works with every agent, needs no configuration, and makes a hand edit behave exactly like an agent’s.

The CLI, the HTTP API and the MCP server are all thin wrappers over one write module that validates and writes those same files atomically. None of them is a separate path, and none is the only way to do something.

The habit to change

The tooling can’t fix the real problem alone: agents will keep running npm run dev unless told otherwise, and every one of those becomes an orphan when the session ends. So Hallway gives agents:

1. v1 One command instead of npm run dev: hallway run. It hands the server to launchd, systemd or (on Windows) Task Scheduler so it outlives the session, keeps a stable port, prints the URL and exits.
2. v0 A guide and a snippet: hallway guide explains the rules, and hallway guide --snippet prints a short paragraph for your AGENTS.md or CLAUDE.md.
3. v2 An optional hook, hallway hook check-command, that catches a bare dev-server start before it runs and suggests the hallway run equivalent.

Etiquette for agents

These are in the agent guide too:

• Never change an existing app’s port. Apps hardcode their ports in scripts and configs (see Your ports stay put).
• Never delete files outside apps/ and bookmarks/. Removing an app through Hallway moves its file to backups/.
• Prefer expected: adhoc for throwaway servers, so they don’t show as down when they stop.
• Don’t touch state/, cache/ or generated/: they’re machine-written.

MCP

v2 For clients that prefer typed tools, an MCP server runs on the same port as the dashboard, at /mcp. It can describe apps and fully manage bookmarks, but by design it can’t start, stop or install anything.