HCS in practice: the complete guide, with use cases

In short

• HCS is an open format and a free tool that makes an AI context file verifiable: every claim cites its source with a hash, and hcs check reports what changed. If you are new to it, start with the project page and the launch article.
• You can try it without installing anything in HCS live: edit the code of an example project and watch the claims turn red.
• Three ways to create an HCS file: by hand, without AI and for free; with a free or local AI; with a paid AI for large projects.
• Checking it never needs AI: check, seal, render, audit and impact run on your machine, with no network.
• Six detailed use cases: coding agent, team, agency, shop with an AI assistant, non-technical documents, hand-off between conversations.
• HCS is still experimental (version 0.3) and does not suit everything: I also say when not to use it.

Getting started with the online tool

The fastest way to understand HCS is to watch it react. I put HCS live online: the real engine of the published version runs in your browser. Nothing is sent anywhere and no AI is used.

The "Demo" tab

In English, it loads the official example project of the HCS repository: a small shop written in TypeScript, Python and Markdown, with a context file of 41 claims and 12 test questions, each tied to its source. The French and Arabic versions of the page use "Boutique Atlas", a fictitious Moroccan shop with delivery fees in dirhams and the same three scenarios.

On the left, the code, which you can edit. On the right, each claim with its status, recomputed at every keystroke. Three scenarios run in one click:

1. 💰 Change a price. The base shipping fee goes from 500 to 700 cents in the code. The four claims that cite those lines become stale. The others stay up to date.
2. 🧹 Reformat the code. Spaces and indentation of shippingFee change, not its logic. Everything stays up to date: HCS hashes a symbol without its whitespace.
3. ↪️ Move a function. applyCode moves to a new file, src/discounts.ts. The six claims that cite it become moved: HCS found the same function, with the same hash, in another file. They remain valid.

Below the list, the budget control (250 to 4,000 tokens) shows the exact text an AI would receive, in the compact profile. Stale claims never appear in it.

The "Check my project" tab

If you already have an .hcs file, choose your project folder: the tool reads the files in your browser and shows the same report as hcs check. The node_modules and .git folders are skipped, and the limit is 5,000 files and 20 MB.

The statuses, as HCS defines them

A claim takes the worst status of its anchors, in the order ok < moved < review < unsealed < stale < missing. A claim tagged suspect is text that looks like an instruction addressed to an AI ("ignore previous instructions"): HCS does not send it to the model.

Creating an HCS file: three ways

First, install the tool (it needs Node.js 18.17 or newer):

npm install -g @oufrid/hcs-cli
hcs --version

1. By hand, without AI and for free

This is the method I recommend to start with, and for everything no AI would guess: business rules, prohibitions, commitments to customers.

Take a small loyalty programme: a file src/fidelite.ts that computes points, and a rulebook docs/reglement.md. (I kept my French file names; the example below is in French, as in my real test.)

hcs init -o fidelite.hcs --title "Programme de fidélité"

The command creates an empty file with instructions in comments. I write two claims, each tied to its sources:

HCS/0.2
@title Programme de fidélité
@root .

[claims]
## Points
#f1[manual] Chaque dirham dépensé rapporte 1 point, arrondi à l'entier inférieur.
  > src/fidelite.ts::pointsGagnes
  > docs/reglement.md::"Gagner des points"
#f2[manual] À partir de 500 points, le client reçoit un bon d'achat de 50 DH.
  > docs/reglement.md::"Utiliser ses points"
  > src/fidelite.ts:4

(f1: each dirham spent earns 1 point, rounded down. f2: from 500 points, the customer gets a 50 MAD voucher.)

Three anchor forms exist:

• path::Name: a function, a class, a constant (here pointsGagnes);
• path::"Heading": a Markdown section, addressed by its heading, in quotes if it contains spaces;
• path:10-20: a line range (here line 4, where the 500-point threshold is defined).

The [manual] tag says a human wrote the claim: automatic updates will never delete it. Then seal and check:

$ hcs seal fidelite.hcs
fidelite.hcs: 4 sealed, 0 relocated, 0 re-hashed
$ hcs check fidelite.hcs
fidelite.hcs: 2 claims, 0 probes
  claims: 2 ok
OK: every claim still matches its sources.

Every anchor now carries its hash, for example > src/fidelite.ts::pointsGagnes #59e39d976b0c.

Now the shop changes its rule: the voucher is granted from 400 points. I edit the rulebook and the code, but forget the context file. HCS notices:

$ hcs check fidelite.hcs
fidelite.hcs: 2 claims, 0 probes
  claims: 1 ok, 1 stale
  STALE    f2     docs/reglement.md::"Utiliser ses points"  symbol changed (lines 7-9)
  STALE    f2     src/fidelite.ts:4  anchored text changed
FAIL: 1 item(s) no longer match their sources. Review them, then fix or `hcs seal --rehash --ids ...`, or recompile with --update.

The command exits with code 1, which is enough to stop a continuous integration run. Above all, the text sent to the AI no longer contains the false claim:

$ hcs render fidelite.hcs
<hcs-context title="Programme de fidélité">
[Points]
f1: Chaque dirham dépensé rapporte 1 point, arrondi à l'entier inférieur. (src/fidelite.ts::pointsGagnes; docs/reglement.md::"Gagner des points")
</hcs-context>

To get it back anyway, you must ask with --keep-stale, and it is then marked (unverified). I fix the claim's text (500 becomes 400), then tell HCS I re-read it:

$ hcs seal fidelite.hcs --rehash --ids f2
fidelite.hcs: 0 sealed, 0 relocated, 2 re-hashed
$ hcs check fidelite.hcs
  claims: 2 ok
OK: every claim still matches its sources.

--rehash is a human statement: "I re-read it, it still holds". HCS never does it on its own.

These outputs are the ones I got running the commands with version 0.3.0. The same steps work in Arabic, with Arabic Markdown headings as anchors: I tested it, and the change is detected the same way.

2. With a free or local AI

For an existing project of dozens of files, writing every claim by hand would take long. hcs compile reads your files and asks a model to propose claims and test questions, then discards every one whose quote is not found word for word in the source. It is a mechanical guard against made-up summaries.

export GEMINI_API_KEY=...        # or GROQ_API_KEY
hcs models gemini                # the model ids your key can use
hcs compile --model gemini:<model> --rpm 8 -o project.hcs

--rpm 8 spaces requests to stay within free-tier limits. If the quota runs out midway, nothing is lost: run again later with --update, and only the missing chunks are processed.

To keep everything on your machine, use a local model through Ollama (prefix ollama:). Two warnings, from the project's documentation:

• Some free tiers may use your prompts to improve their products. Only send code you are allowed to share.
• Small local models (7B parameters, on CPU) gave weak results: they abstain too often.

I did not run compile for this guide: it needs a model. The above comes from the official documentation.

3. With a paid AI, for large projects

It works the same way, with a more capable model (openai:, anthropic:, mistral:…). Every command that uses an AI ends with the number of requests and tokens used. To estimate the cost in advance, use my API cost calculator.

Keeping it true day to day

A context file is only worth something if it stays right. Here is the routine I use.

Check on every change. hcs check exits with code 0 when everything is up to date, 1 when something no longer matches, and 2 on a syntax error. On GitHub, the official action does it on every push, with no AI and no secret:

- uses: actions/checkout@v4
- uses: Oufrid/HCS@main
  with:
    file: project.hcs
    strict: "false"      # "true" also fails on unsealed anchors and suspect claims

Warn before merging. The impact mode posts on each pull request a comment listing the claims whose cited code changed:

on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  impact:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Oufrid/HCS@main
        with:
          file: project.hcs
          mode: impact

Locally, hcs impact project.hcs --base origin/main gives the same information. On my loyalty example, after replacing rounding down with normal rounding:

$ hcs impact fidelite.hcs --base HEAD
fidelite.hcs: 1 item(s) cite code changed since HEAD (1 file(s) changed)
  f1     [stale] Chaque dirham dépensé rapporte 1 point, arrondi à l'entier inférieur.
         src/fidelite.ts::pointsGagnes: changed lines 8

Follow moves. After a reorganisation, hcs seal project.hcs updates the anchors of moved claims, without re-reading anything else.

Accept a reviewed change. hcs seal project.hcs --rehash --ids f2 for one claim, after re-reading and fixing it.

Update a compiled file. hcs compile --model … --update re-reads only the changed files and keeps everything still verified, including your manual claims.

Connect your AI agent. hcs serve turns the file into an MCP server: the agent first reads the verified claims, then opens the exact source when it needs a detail. With Claude Code, in the project folder:

claude mcp add hcs -- hcs serve project.hcs

For Cursor or another client, the configuration looks like this (absolute paths recommended):

{
  "mcpServers": {
    "hcs": {
      "command": "hcs",
      "args": ["serve", "/absolute/path/to/project/project.hcs", "--root", "/absolute/path/to/project"]
    }
  }
}

Only Claude Code has been tested so far. For MCP in general, read my guide Connecting AI to your tools.

Six detailed use cases

1. The developer working with an AI agent

The situation. You use Claude Code, Cursor or another agent, with a CLAUDE.md or AGENTS.md describing the project. Three months later, half of it is wrong, and the agent applies it confidently.

What goes in the HCS file. The important rules, written by hand and tied to the code that applies them ("amounts are stored in cents", "no admin route without authentication"), plus, for a large project, a compiled file for the rest.

The commands. Start by auditing your current file, without AI:

$ hcs audit AGENTS.md
AGENTS.md: ~92 tokens, 4 file references, 2 broken, 0 unresolved names
  BROKEN line 5: src/bons.ts
  BROKEN line 6: tests/fidelite.test.ts

Here, two files cited by the AGENTS.md no longer exist. Then connect hcs serve to your agent. To know which one conveys more, hcs compare AGENTS.md project.hcs --model M compares both on the same test questions, but that comparison uses an AI.

What you gain. An agent that no longer works from outdated information, and reads the exact source when in doubt. To write the instructions file itself, my agent instructions generator helps.

The limit. HCS only checks what is tied to a source. A general instruction with no anchor ("be concise") remains your job.

2. The development team

The situation. Several people change the code. Nobody thinks of updating the documentation, and the gap grows.

What goes in the HCS file. Architecture, conventions and business rules, with anchors to the code that applies them.

The commands. The GitHub action in check mode on the main branch, and in impact mode on pull requests (see the two YAML blocks above).

What you gain. Code review shows in black and white which claims a change touches. The author fixes the claim, or confirms it holds with --rehash.

The limit. Pull requests from forks get a read-only token: the comment cannot be posted there. And the --deps option, which flags claims whose used code changed, mostly gives false alarms: on the project's history, only 1 alert in 18 pointed at a claim that had really become wrong.

3. The agency or freelancer

The situation. You deliver a website or app to a client, with documentation. Six months later, another provider takes over and does not know what is still true.

What goes in the HCS file. How the project works, its rules and its commitments ("orders ship only after confirmation"), tied to the delivered code.

The commands. Deliver the .hcs file with the code, and the GitHub action if the client has a repository. To go further, a fidelity certificate can be signed: hcs keygen creates a key pair, hcs score … --write --sign signs the certificate, and hcs badge draws a README badge. These three steps need a fidelity measurement, so an AI.

What you gain. Documentation anyone can check, in one command, still matches the code. A real selling point.

The limit. The client needs someone able to run the check, or a continuous integration that does it.

4. The online shop with an AI assistant

The situation. Your shop uses an AI assistant to answer customers, on the website or on WhatsApp. Its answers rely on your terms: shipping prices, return windows, discount codes. The day a term changes and the assistant's knowledge is not updated, it announces a wrong price or deadline, and you pay for it when the parcel is refused.

What goes in the HCS file. One claim per term, tied to the page or file that is authoritative: the "Shipping" section of your terms of sale, the code constant that computes the fees. This is exactly what the "Boutique Atlas" example in HCS live does (in the French and Arabic versions).

The commands. hcs check daily or on every change, and hcs render --budget N to produce the text given to the assistant.

What you gain. A mechanical guarantee: if a term changes, check fails, and the stale claim disappears from the text given to the assistant. I verified it above: after the threshold change, render only contained the claim that was still true. The assistant can no longer announce the old rule as if nothing happened.

The limit. HCS does not write the new answer for you: it flags the gap and withdraws the doubtful information. And your terms must exist in a text file (Markdown, code), not only in an image or a PDF. For AI in e-commerce more broadly, read my guide on AI for your online store.

5. Non-technical documents

The situation. Internal rules, a quality procedure, research notes: long texts, often summarised for an AI or a newcomer, and that evolve.

What goes in the HCS file. The key points, each tied to the section that states it, with a heading anchor: docs/procedure.md::"Leave approval". Arabic headings work as anchors too.

The commands. The same: init, seal, check, render.

What you gain. The day a section changes, the matching summary is flagged, instead of staying silently wrong.

The limit. The anchor follows the whole section: the smallest edit in it, even a comma, marks it stale. That is intended (better to re-read for nothing than to miss a change), but worth knowing.

6. Hand-off between two conversations

The situation. A long conversation with an AI led to decisions. You want to continue in a new conversation, or with another model, without copying everything or losing anything.

The commands. hcs snapshot conversation.json --model M -o session.hcs turns the conversation (ChatGPT export, message array, or a plain .md or .txt file) into claims, each tied to the message it came from. Then hcs render session.hcs --decoder produces the text to paste into the new conversation.

What you gain. Decisions, constraints and next steps, each traceable to the original message.

The limit. snapshot uses an AI, and quality depends on the model. I did not run it for this guide.

When not to use it, and the limits

• A small project: if the code fits in a few files, giving it directly to the AI is simpler, and sometimes shorter than its context file.
• Measurements made on English projects: the published gains (46.7% correct answers against 27.8% for a naive summary) come from English repositories. French and Arabic work is verified, not yet measured.
• An experimental tool: the format is stable (SPEC 1.0), but the tool is at version 0.3.
• Injection detection is imperfect: on attacks never seen during tuning, it caught about half. It is an extra layer, not a guarantee.
• Dependency alerts (--deps) mostly give false alarms.
• HCS does not make a bad summary good: it tells you whether it is still true and measures what it conveys. The quality of the claims remains your job, or that of the model that compiles them.

FAQ

Do I need an API key to use HCS?

Not for the essentials. Writing claims by hand, sealing, checking, producing the context, auditing an AGENTS.md and listing a change's impact work without AI and without network. Only automatic creation (compile), measurement (score, curve, compare) and snapshot need one, and they accept free tiers and local models.

Does HCS work with French or Arabic text?

Yes. The format is UTF-8, and the hash is computed on the text, whatever the language. I tested claims in French and Arabic, with Arabic Markdown headings as anchors: a single changed value is detected. The published fidelity measurements were made on English projects.

Is my code sent anywhere?

Not by check, seal, render, stats, impact, audit without --probes, nor by the MCP server. Commands that use an AI send text to the provider you choose. The online tool HCS live runs entirely in your browser.

What do I do when a claim goes stale?

Re-read it. If it became wrong, fix its text. If it still holds (the change does not affect it), confirm with hcs seal file.hcs --rehash --ids <id>. If the file was compiled, compile --update can regenerate it.

Where do I start on a real project?

With five to ten claims written by hand, on the rules that would be costly if the AI forgot them, then hcs seal and the GitHub action. You will quickly see whether the habit suits you, before compiling the rest.

Need help setting up HCS in your team, or making an AI assistant reliable? That is the core of my AI & automation service.