Checking CHAT files with phon-chat-check

phon-chat-check is a command installed in Phon's bin folder, inside the application's install directory. It reads CHAT (.cha) files and checks the four dependent tiers that Phon writes — %modsyl, %phosyl, %phoaln and %phoint — against the Phon tier specification published at github.com/speechmetrics/phon-chat-tiers. Each rule of the specification has a number; the command prints the number of every rule a file breaks. It reports and never repairs. The superseded tier names %xmodsyl, %xphosyl, %xphoaln and %xphoint are checked under the same rules.

The command checks the Phon tiers only. General CHAT validity — the main line, the headers, %mod and %pho — is checked by Chatter, the TalkBank validator, which Phon also bundles and runs when publishing a project.

Usage

phon-chat-check [--format text|json] [--] <file.cha|folder>...
phon-chat-check --spec-version
phon-chat-check --help

The first form checks one or more files or folders. With --format text (the default) the command prints one line per broken rule and nothing for a file that breaks no rule:

<file>:<line>: error[<rule>] <title>: <message>

For example, session.cha:42: error[3.4] Start before the previous end: %phoint start 50 is before the previous end 200. The rule number and title are those of the specification's rule index (its Appendix C), so a line can be read beside the specification. With --format json the command prints one JSON object per file holding the file name, its status (valid or invalid), the specification version, a link to that version's rule index and the list of violations; each violation carries the rule number, its title, its status (error or error, repairable), the line and the message. The second form prints the version of the specification the command implements, and the third prints this usage.

Checking a folder

A folder on the command line stands for every .cha file below it, subfolders included, checked in name order. Hidden files and folders (names starting with a dot) are skipped. Files and folders can be mixed in one run, for example to check an exported corpus:

phon-chat-check ~/Exports/MyCorpus/CHAT

When a folder is named, only the files that break a rule are listed, and the run ends with one summary line:

42 files checked, 2 invalid, 7 violations

When a file could not be read, its error goes to standard error and the summary ends with , 1 unreadable. With --format json a run that names a folder prints a single object instead of one per file: a summary object with the counts files, invalid, violations and unreadable, the specification version and link, and files, the report of each file that broke a rule or could not be read. An unreadable file's report carries its name, the status unreadable and the error.

Exit status

0 — no file breaks a rule.
1 — at least one file breaks at least one rule.
2 — a usage error, a file that could not be read, or a folder holding no .cha file. The other files and folders named on the command line are still checked.

From an MCP client

The same check is available to AI agents as the check_chat_tiers tool of Phon's MCP server. The tool takes a file parameter naming the CHAT file or a folder, absolute or relative to the directory the phon-mcp-stdio command was started in, and an optional format of text (the default) or json. The text report is one verdict line followed by the lines the command prints; the JSON report is the object the command prints. The tool needs no running Phon instance and no project, and a file that cannot be read is returned as an error. For a folder, the text report is a verdict line, the lines of the files that break a rule or cannot be read, and the summary line; the JSON report is the single object described under Checking a folder. A folder holding no .cha file is returned as an error.