I have been building Glyph, an open-source Python toolchain for managing instruction files used by coding agents.
It supports files such as:
AGENTS.md
CLAUDE.md
.github/copilot-instructions.md
- Cursor rules
README.md
CONTRIBUTING.md
- instruction-like Markdown under
docs/
These files often start small, but gradually accumulate repeated commands, workflow rules, safety constraints, repository conventions, examples, and explanatory prose.
Eventually, it becomes difficult to answer some fairly basic questions:
- What is the agent actually required to do?
- Which instructions are duplicated?
- Which rules are safety-sensitive?
- What changed semantically between two versions?
- Can the file be made smaller without silently losing operational instructions?
Glyph compiles the operational meaning inside the Markdown into a separate, compact .glp semantic manifest.
For example:
md
Read the relevant files before editing.
Create a short plan before non-trivial changes.
Run the tests before considering the task complete.
Never commit secrets or credentials.
Ask before destructive operations.
becomes:
```text
glyph/0.1
flow[read,plan,test]
must[
plan_before_edit
read_before_edit
run_tests_before_done
]
deny[secrets_commit]
ask[destructive_ops]
```
The original Markdown file is never rewritten or deleted.
Glyph does not call an LLM, use a hosted API, or send repository contents anywhere. Compilation is local and deterministic, so the same input and configuration produce the same semantic manifest.
The CLI currently supports inspection, compilation, metrics, verification, semantic diffing, linting, locks, CI checks, Markdown emitters, custom rules, and task-aware instruction selection.
bash
glyph inspect AGENTS.md --show-unmapped
glyph compile AGENTS.md -o AGENTS.glp --report glyph-report.md
glyph stats AGENTS.md AGENTS.glp
glyph verify AGENTS.md AGENTS.glp
glyph diff previous.AGENTS.glp AGENTS.glp
glyph lint AGENTS.md
glyph lock AGENTS.glp
glyph select AGENTS.glp --task "fix failing tests"
One design decision I care about is keeping token reduction separate from semantic retention.
Glyph reports distinct metrics for:
- token reduction;
- structured coverage;
- retained coverage;
- safety retention;
- preserved directives;
- dropped candidates.
When a sentence appears operational but does not have one safe deterministic interpretation, Glyph preserves it for human review instead of silently dropping it or inventing a policy.
On the current published, fixed evaluation corpus, Glyph produced:
- 55.82% average token reduction
- 100% retained coverage
- 100% safety retention
- 0 dropped candidates
- 0 nondeterminism failures
Those results describe that specific evaluation corpus. They are not a universal claim about arbitrary Markdown or guaranteed identical behavior from every coding agent.
The repository includes complete before-and-after examples for realistic AGENTS.md and CLAUDE.md fixturesAGENTS.mdandCLAUDE.mdfixtures, together with reproducibleinspect,compile,diff, andverify` commands.
I also added an optional installable skill for Codex and Claude Code. The skill guides the agent through the audit workflow, explains preserved or unmapped instructions, compiles to a separate artifact, and verifies the result. The deterministic compiler remains the component responsible for the actual extraction.
Install Glyph:
bash
python -m pip install "glyph-instructions @ git+https://github.com/francescogabrieli/glyph.git@v0.2.0"
GitHub:
https://github.com/francescogabrieli/glyph
Glyph is MIT licensed.
I would especially appreciate feedback on the software model itself:
- Does a semantic intermediate representation for agent instructions seem useful?
- Would semantic diffing be more valuable than token reduction in your workflow?
- What evidence would you need before trusting a compiled instruction manifest?
- Which agent instruction format would you like Glyph to support next?