Format what the agent writes

After writing a file, the agent reads it back: it receives the file as it stands on disk after formatting, along with the errors the environment reports for that file. This page describes what it finds out, and what you declare so that formatting happens in the terminal.

What happens after each write

In this order:

1. The file is formatted. In the IDE, your editor handles it, with the formatting you set up for save. In the terminal there is no editor: the command you declare below does the work.
2. The file’s errors are read back: those of this file, and of no other.
3. The agent receives the file’s real state: the diff it is shown is that of the file as it stands on disk, and if formatting changed it, the agent is told.

Without the third point, the agent moves on to an edit based on the text it believes it wrote, fails to find the line it is looking for, and returns an error.

Declare a formatter for the terminal

In your workstation’s settings file, ~/.lemniscate/workstation.yaml:

formatter:
  - command: prettier --write $FILE
    extensions: [".ts", ".tsx", ".js", ".json", ".md"]
  - command: black $FILE
    extensions: [".py"]

• $FILE is replaced by the file to format. Without this marker, the file is appended to the end of the command.
• Extensions are read with their leading dot. The first declaration that claims an extension wins.
• Without a declaration, nothing happens: the product ships no formatter and installs none.
• The declaration names the command. What the command is allowed to do is decided by the project policy, described below.

The formatting command and the project policy

A formatter is a command run after each write. It goes through the project’s command policy, like any other command: it runs without approval when the administrator has placed it among the free commands, where formatting sits alongside compilation, tests and analysis (security white paper V3, section 5.1). By default, no command is free. When the policy does not let the command through, formatting does not happen and the agent receives the reason; see When formatting does not happen.

The declaration in the repository file

A .lemniscate/project.yaml file that carries this declaration is ignored on this point, and the product names the setting it discarded. Content read from the repository does not decide what runs (security white paper V3, section 5.2).

The formatter’s configuration files

The formatter reads its own settings from the repository: configuration file, manifest that pins its version, hook that runs it when a commit is recorded. These files are run or read later by parties other than the session: continuous integration, your colleagues’ workstations. They fall under the classes of files with dedicated controls that the project policy defines. The agent is forbidden from modifying them by default, or must obtain an approval distinct from the ordinary approval of a diff and flagged as such (security white paper V3, section 5.3).

What the agent finds out from errors

In VS Code, the errors are the ones your development environment knows about: the ones you see underlined in your code. The agent receives only those of the file it just wrote; a real project contains hundreds of others, which are none of its concern.

A file without errors produces no lines. Silence means “nothing to report”.

In JetBrains, no errors are read back: the host answers about the file selected on screen rather than the file asked for, and the product would rather say nothing than report another file’s errors.

In the terminal, there are no errors. The terminal has no way of knowing them, and it does not claim there are none.

When formatting does not happen

Your write stands. Formatting is a service layered on top; if it fails, it undoes nothing, and the agent receives the reason:

What you read	What to do
the command cannot be found	install the formatter, or fix its name in your settings
the command stopped at its limit	it is too slow for automatic formatting; restrict it to fewer extensions
the command returned a non-zero exit code	the first line of its output is carried into the message; fix the command or the file
the policy does not let the command through	the rule is named in the message; it is up to your administrator to decide
no execution environment could be opened	the terminal runs this command in its sandbox, like all the others; the message says what is missing on the workstation

Terminal formatting runs in the session sandbox, without network access, like any command the agent runs. The formatter must therefore already be installed there; see Prepare the session container.