---
title: "File Viewer & Script Runner"
id: "588"
type: "page"
slug: "file-script"
published_at: "2026-06-03T14:29:23+00:00"
modified_at: "2026-06-11T14:02:26+00:00"
url: "https://xedant.com/code/docs/validation/file-script"
markdown_url: "https://xedant.com/code/docs/validation/file-script.md"
excerpt: "The file viewer and script runner provide manual validation capabilities alongside automated ones. While AutoFix…"
---

# File Viewer & Script Runner

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

The file viewer and script runner provide manual validation capabilities alongside automated ones. While [AutoFix](/code/docs/autofix)
 handles automated error fixing and the [build system](/code/docs/validation/automated-build)
 runs quality gates on every file change, the file viewer lets you manually inspect code and the script runner lets you execute ad-hoc commands with real-time output — both without leaving the chat.

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

The Files dialog provides a file tree and editor accessible from the chat view. Open it to browse your project’s files, view their contents with syntax highlighting, and verify the changes the model made.

- **File tree** — Browse the project directory structure. Directories expand to show their contents
- **Syntax highlighting** — Files are displayed with code formatting appropriate for their type
- **Auto-save** — Changes are saved automatically after 2s delay

The file viewer is not a replacement for a full-featured IDE — it’s designed for quick review and quick one-line fixes. For heavier editing, use your preferred code editor and let the AI handle the rest.

The file viewer is particularly useful after the AI has finished working. Open the files it modified to verify the changes are correct, follow your project’s conventions, and don’t contain unintended modifications. This complements the [git change validation](/code/docs/validation/git-change)
 — while the git panel shows what changed at a high level, the file viewer shows the full context around each change.

The file viewer works with both repositories: **Project** (your main workspace) and **Skills** (the `.claude/skills` directory). Switch between them using the repository tabs.

## Script Execution

Shell scripts (`.sh` files) in your repository show a run button in the file editor. When executed, output streams in real-time to the Script Output dialog via SignalR. Scripts are different from [builds](/code/docs/build-deploy)
 — builds are automated by file watchers and configured in `build.yml`, while scripts are run manually and can be any executable file in your repository. The best use for scripts is in skills — you could automate builds or production deploys with small scripts, enabling you to quickly invoke and control them right in the chat by opening the corresponding skill.

### Execution Flow

1. The script path is resolved within the selected repository (project or skills)
2. The file is made executable (`chmod +x`) on Unix systems
3. A bash process is launched with `/bin/bash scriptPath` in the project root directory
4. Environment variables `PYTHONIOENCODING=utf-8` and `LANG=en_US.UTF-8` are set automatically
5. Output is captured asynchronously, buffered to prevent flooding, and streamed to the browser via SignalR every 100ms
6. When the process exits, a completion message is sent and the execution timer stops

### The Script Output Dialog

When a script executes, the Script Output dialog opens automatically with:

- **Execution timer** — Elapsed time while running, final duration on completion (updated every 100ms)
- **Status indicator** — Spinning icon while running (clickable to stop), green checkmark on success, error state on failure
- **Color-coded output** — Error lines highlighted in red, warning lines in orange, normal output in default color
- **Autoscroll** — Output auto-scrolls to the bottom as new lines arrive. Scroll up to disable; scroll back to the bottom to re-enable
- **Copy button** — Copies the full output to clipboard (enabled after completion)
- **Repository badge** — Shows whether the script ran from the project or skills repository

### Stopping Scripts

Click the spinning stop icon to kill a running script. The server kills the entire process tree (including child processes), flushes any buffered output, and sends a “Script stopped by user” message. Closing the dialog also stops the script automatically, preventing background processes from continuing if you navigate away.

## Script Sounds

Scripts play the global **complete** sound when they finish — both on success and failure. Unlike builds, scripts don’t have per-task sound configuration. To change the sound, replace the built-in `complete.mp3` by placing a custom MP3 with the same name in `.xedant/sounds/`. You can also adjust the volume in **Settings → Sound Settings** or mute all sounds with the speaker icon in the chat header. For the full reference on custom sounds, see [Sound Feedback Validation](/code/docs/validation/sound-feedback)
.

## Script Output Parsing

Script output is automatically parsed using `.xedant/output.parser`, which shares the same `[ERROR]`/`[/ERROR]` block format as the build and deploy parsers. Built-in detection patterns cover common error formats 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 stack traces, TypeError, npm ERR!
- **.NET errors** — Build errors, exceptions, fatal errors
- **HTTP/network errors** — Connection refused, ECONNREFUSED, timeouts, status codes 4xx/5xx

### Parser Format

⚠️ Don’t try to edit parser files manually — ask the AI model to do it for you. Use `.xedant/README.md` as a reference — it contains detailed information about parser file syntax, as well as extensive documentation on the structure and purpose of all other files and folders in the `.xedant/` directory.

- **Comment lines** starting with `#` are ignored
- **Single-line patterns** — A regex that must match exactly one output line
- **Multi-line patterns** — Wrapped in `{{...}}`, matches zero or more consecutive lines that follow the inner regex

```
# 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]
```

The parser works sequentially: at each output line, it tries each block’s patterns in order. When all patterns in a block match consecutively, those lines are extracted as one error and the parser advances past them. Earlier blocks take priority — once a match is found, later blocks are skipped for those lines.

Custom patterns can be added to `output.parser` for your application’s specific error format, or ask the AI model to update it. The parser is reloaded automatically on file change.

## Effective Validation Patterns

A good rule of thumb: use [builds](/code/docs/validation/automated-build)
 for repeated validations that happen several times per day or even several times per chat — compiles, linters, type checkers, and tests. Scripts are best when validation is done irregularly, or requires a lot of waiting and manual control — one-off deployments, diagnostics, interactive tools.

- **Quick manual checks after AI changes** — Run a test script or check a log file from the Files dialog without switching to a terminal. This is faster than asking the model to run the command
- **Use scripts for ad-hoc validation** — When builds aren’t configured for a specific check, create a quick script to validate what you need. Scripts run immediately without file-watcher delays
- **Combine scripts with chat** — If a script reveals an error, send the output to the chat and ask the AI to fix it. The model can read the script output and make targeted corrections
- **Verify file state manually** — After complex edits, open the modified files in the viewer to confirm the changes look right. This catches subtle issues that diffs may not reveal

For the complete scripts reference, see [Scripts](/code/docs/scripts)
. For the file system features, see [Files](/code/docs/files)
. For automated validation that runs without manual intervention, see [Automated Build Validation](/code/docs/validation/automated-build)
.

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

**[Prompt-Based Builds →](/code/docs/validation/prompt-builds)**