Actions & the exec server

Building, testing, launching — a project’s recurring commands are actions, defined in .agent/actions.json and shown in the app’s actions tab (pin favorites to the toolbar, give them shortcuts).

An action runs as argv without a shell — &&, pipes, and $(…) don’t work there. Compound commands go into a script:

{
  "name": "Build app",
  "command": "sh scripts/app-build.sh"
}

Actions can also ask for inputs before running — text, number, file, folder, choice, color — filled into {name} placeholders in the command.

Who actually executes: the exec server

A sandboxed Mac app must not spawn arbitrary processes — and shouldn’t want to. So the app executes nothing itself: it connects as an MCP client to a local exec server (default http://127.0.0.1:8765/mcp, configurable per project in .agent/settings.json). Any server that speaks the exec contract works; the app is server-agnostic. You start the server; a green bolt icon in the app means connected.

The security model sits in the middle:

Allowlist (.agent/exec-allowlist.json): commands matching an allowed pattern run; anything else is parked as a pending request you confirm in the app — once, or permanently.
The working directory is pinned to the project root, and every run has a timeout.

Output that’s worth looking at

Action output streams live, with a stop button (disconnecting kills the process) and progress from [n/m] markers. Two extras turn the stream into a workbench:

Charts — a line of JSON like {"kind":"chart", …} in the output renders as a real chart, so a profiling script can show its result instead of printing columns.
Tool-UI panels — an action of the form toolui:<kind> <paramsJSON> (for example toolui:sqlite {"path": "{file}"}) opens an interactive panel locally, no server needed.

One rule spans all these files: no secrets in the repository. Tokens live in the keychain or arrive as environment references like ${MY_TOKEN} — if a configuration seems to need a literal secret, that’s a question for the owner, not a commit.