---
title: "File Viewer & Script Runner"
id: "588"
type: "page"
slug: "file-script"
published_at: "2026-06-03T14:29:23+00:00"
modified_at: "2026-09-21T01:36:28+00:00"
url: "https://xedant.com/agents/agent/docs/validation/file-script"
markdown_url: "https://xedant.com/agents/agent/docs/validation/file-script.md"
excerpt: "The file viewer and script runner are the manual side of validation, added on top…"
---

# File Viewer & Script Runner

[https://xedant.com/agents/agent/docs/validation/file-script.md](https://xedant.com/agents/agent/docs/validation/file-script.md)

The file viewer and script runner are the manual side of validation, added on top of the automatic one. [AutoFix](/agents/agent/docs/autofix)
 repairs errors on its own and the [build system](/agents/agent/docs/validation/automated-build)
 checks the code on every change, while the file viewer lets you look through project files yourself and the script runner lets you run any command and watch its output live. All of it right in the interface, without leaving the chat.

![Xedant Agent file viewer dialog](https://xedant.com/wp-content/uploads/2026/06/file-viewer-dialog.png)## Built-in File Viewer

The “Project Files” dialog opens from the chat view: the project folder tree on the left, an editor on the right. It is a handy way to flip through files, read their contents, and check exactly what the model changed.

- **File tree** — the project’s folder structure; folders expand to show their contents
- **Syntax highlighting** — code is shown with color markup matched to the file type, which makes it easier to read
- **Auto-save** — changes are saved on their own 2 seconds after you stop typing

The viewer does not replace a full code editor — it is built for quick inspection and small edits. For serious work, use your usual editor and hand the rest to the AI.

The viewer is especially useful after the model finishes its work: open the changed files and confirm the edits are correct, follow your rules, and touch nothing extra. It complements [git change validation](/agents/agent/docs/validation/git-change)
: the git panel shows what changed, while the viewer shows the full context of every change.

The viewer works with the project’s single repository, which holds both the code and the [skills](/agents/agent/docs/skills)
 (the `.claude/skills` folder).

## Running Scripts

Script files (the `.sh` extension) get a run button in the editor. Press it, and the output streams live into the script output dialog. Scripts differ from [builds](/agents/agent/docs/build-deploy)
: builds start automatically on file changes and are configured in the `build.yml` file, while you launch a script by hand at any moment — it can be any executable file in your repository. The tidiest home for scripts is inside skills: that way routine builds and deployments can be launched straight from the chat by opening the right skill.

### How It Works

1. The script path is resolved inside the workspace (the project or skills tree)
2. The file is automatically given the right to run (`chmod +x` on Unix systems)
3. The script runs through `/bin/bash scriptPath` from the project root
4. The environment variables `PYTHONIOENCODING=utf-8` and `LANG=en_US.UTF-8` are set automatically, so output text reads correctly
5. Output is collected in small chunks and sent to the browser every 100 ms, so the stream never overwhelms the interface
6. When the script finishes, a completion message arrives and the execution timer stops

### The Script Output Dialog

While a script runs, the script output dialog opens on its own and shows:

- **Execution timer** — elapsed time while running, total duration when finished (refreshed every 100 ms)
- **Status indicator** — a spinning icon while the script runs (click it to stop the script), a green checkmark on success, an error mark on failure
- **Colored output** — error lines are highlighted in red, warnings in orange, plain output keeps the normal color
- **Auto-scroll** — the output scrolls to the end on its own as it arrives. Scroll up and auto-scroll switches off; return to the bottom and it switches back on
- **Copy button** — copies the whole output to the clipboard (available after the script finishes)
- **Repository badge** — shows where the script ran from: the project or your skills

### Stopping Scripts

Click the spinning stop icon to interrupt a running script. The server kills the whole process tree (nested processes included), flushes the collected output, and shows the message “Script stopped by user”. Closing the dialog stops the script too — background processes do not keep running after you leave.

## Script Sounds

When a script finishes — successfully or with an error — the shared **complete** sound plays. Unlike builds, scripts have no separate sound per task. To change it, put your own MP3 file named `complete.mp3` into the `.xedant/sounds/` folder — it replaces the built-in one. Volume is configured in **Settings → Sound**, and the speaker icon in the chat header turns all sounds off. For details, see [Sound Feedback Validation](/agents/agent/docs/validation/sound-feedback)
.

## Script Output Parsing

Script output is parsed automatically with the `.xedant/output.parser` file, which uses the same `[ERROR]`/`[/ERROR]` block format as the build and deploy parsers. The built-in templates recognize the most common errors without any configuration:

- **Shell errors** — “command not found”, “Permission denied”, “No such file or directory”, “Segmentation fault”
- **Python errors** — tracebacks, SyntaxError, ModuleNotFoundError, ImportError
- **Node.js errors** — Error with a description, TypeError, npm ERR!
- **.NET errors** — build errors, exceptions, fatal errors
- **Network errors** — “Connection refused”, ECONNREFUSED, timeouts, 4xx/5xx response codes

### Parser File Format

⚠️ Do not edit parser files by hand — ask the AI model to do it for you. The `.xedant/README.md` file serves as the reference: it describes the parser file syntax in detail, plus the purpose of every other file and folder in `.xedant/`.

- **Comment lines** starting with `#` are ignored
- **Single-line patterns** — a search mask that must match one output line exactly
- **Multi-line patterns** — wrapped in `{{...}}`, they capture the consecutive lines that match the inner pattern

```
# Python tracebacks with context
[ERROR]
Traceback \(most recent call last\):
{{^\s+.*}}
[^\s]+: [^\n]+
[/ERROR]

# npm ERR! blocks
[ERROR]
npm ERR!.*
{{npm ERR!.*}}
[/ERROR]

# Warnings
[WARNING]
warning:.*
{{^\s+.*}}
[/WARNING]
```

Parsing runs in order: for each output line, the rules are applied one after another. When all of a block’s patterns match in a row, those lines count as one error and the parser moves on. Earlier blocks take priority: once a match is found, the blocks that follow are skipped for those lines.

You can add your own patterns for your application’s error format to `output.parser` — or ask the AI model to update the file. The rules load once per page session, so your changes apply after a page refresh.

## Practical Tips

A good rule of thumb: use [builds](/agents/agent/docs/validation/automated-build)
 for repeated checks that happen many times a day (compiling, code style, types, tests). Use scripts for irregular checks, or ones that involve waiting and hands-on control: one-off deployments, diagnostics, interactive tools.

- **Quick checks after the AI’s work** — run a test script or open a log file right from the “Project Files” dialog, without switching to a terminal. It is faster than asking the model to run the command
- **Scripts for everything else** — when no build is configured for a check, create a quick script. It starts at once, with no wait for file watchers to trigger
- **Pair scripts with the chat** — if a script finds an error, send its output to the chat and ask the AI to fix it: the model reads the output and makes targeted edits
- **Check files with your own eyes** — after complex edits, open the changed files in the viewer: this exposes subtle problems that a version comparison does not show

The full scripts reference is in [Scripts](/agents/agent/docs/scripts)
. File features are in [Files](/agents/agent/docs/files)
. For automatic validation with no manual step, see [Automated Build Validation](/agents/agent/docs/validation/automated-build)
.

**[← Analytics & Observability](/agents/agent/docs/validation/analytics-observability)**

**[Automated Prompt Builds →](/agents/agent/docs/validation/prompt-builds)**