Hermes Syntax Oracle

What Hermes Syntax Oracle does

The plugin hooks into transform_tool_result, the same hook used by the bundled security-guidance plugin. Every tool result gets a substring check, and work only happens on a hit. It locates the error from a traceback or from Hermes' in-process lint, recovers the source from the tool arguments, the patched file or the file named in the traceback, replays Python's tokenizer to find the unclosed, surplus or mismatched delimiter, and checks its finding against Python's own message, line and column.

It only speaks when its finding agrees with Python. It then tries the few one-character edits the finding implies and reports the first that makes the whole file compile, within limits of 160 compiles (80 for sources over 50 KiB), 1.5 seconds and 200 KiB of source. It blocks nothing and uses only the standard library. The motivating example in the README is a 27B model that blamed tool escaping, the linter and the shell for a missing brace. Setting SYNTAX_ORACLE_DISABLE=1 switches it off, and there are no other settings.

Key features

• Detects SyntaxError, IndentationError and TabError in tool results
• Tokenizer replay that finds unclosed, surplus or wrong-kind brackets
• One-character fix candidates checked with compile() on the whole file
• Stays silent unless its finding matches Python's own error message
• Bounded search with compile, time and source-size limits
• Standard library only, with an environment variable to disable it

When to use it

• Helping a small local model recover from a missing closing bracket in generated code
• Cutting repeated failed tool calls caused by unbalanced delimiters
• Diagnosing mixed tab and space indentation errors in agent-written scripts

Who it is for: Hermes Agent users running small local models that write Python and struggle to find bracket and indentation errors.

How it fits with Hermes Agent

It is a Hermes Agent plugin that uses the transform_tool_result hook, the same hook as the bundled security-guidance plugin.

How to install Hermes Syntax Oracle

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

hermes plugins install CocaKova/hermes-syntax-oracle --enable
hermes gateway restart

Requirements: Hermes Agent with plugin support; no dependencies beyond the Python standard library

FAQ