Your AI agent is grepping blind.
Every time Claude Code or Cursor opens a repo, it starts
from zero — reading README fragments, scanning the file
tree, guessing what your features are and how they connect.
A
.remedy
file at the root hands it the manifest: features declared,
flows mapped, embeddings baked in. Your folder stops being
a pile of files and starts behaving like a catalogued
instrument.
remedy:
id: hello-world
name: Hello World
domain: examples
kind: feature
intent: >
The smallest possible Remedy. One feature, one step, no integrations. Exists
so `remedy fmt`, `remedy lint`, and `remedy build` have a trivially correct
target for their round-trip tests.
owners:
- petitgen-ltd
tags:
- example
- smoke-test
entities:
- greeting
files:
spec:
ext: .md
path: SPEC.md
required: true
features:
- id: say-hello
intent: Emit the string "hello world" to stdout.
triggers:
- user.invokes: run
steps:
- emit: hello world
outputs:
- stdout
version: 0.1.0
runtime: sovereign
version: 0.1.0
The smallest complete Remedy. One feature, one step, no integrations — the same bytes your agent reads.
Claude Code reads your .remedy
through MCP and arrives oriented. Features, flows, triggers,
outputs — all declared. It navigates with context instead of
exploring the file tree for the hundredth time.
READMEs rot. Architecture diagrams fall behind reality within weeks. The manifest is lint-verified, schema-validated, and diff-aware. When the folder changes and the spec doesn't, the build fails loud.
The CLI, the editor, the desktop app, the MCP server for Claude Code — they all read the same file and agree on what the folder is. Any new surface that speaks the spec joins automatically. Stop re-implementing project context.
One YAML file, four concerns: who the folder is, what it can do, what it's made of, what it runs against.
remedy.id,
remedy.name,
remedy.domain.
Stable, globally unique, reference-able from anywhere.
Ordered lists of what the folder can do, each with triggers, preconditions, steps, outputs, errors, tags. Verifiable. Embeddable. Diff-able.
Every intent, tag, and natural-language step argument
runs through a local embedding model at build time.
Sovereign by default — Ollama
nomic-embed-text.
remedy fmt / lint / build / diff
— canonicalise, validate, compile, compare. Same
operations exposed to Claude Code via MCP.
Committed to the repository, canonicalised, lint-clean, built against local Ollama. Drop-in targets for the toolchain's round-trip tests and the shape every new Remedy starts from.
The smallest possible Remedy. One feature, one step, no integrations. Exists so `remedy fmt`, `remedy lint`, and `remedy build` have a trivially correct target for their round-trip tests.
Pull the past week's Toggl time entries, group them by client, draft invoices in Xero, let the operator review and confirm per-invoice before submission. The canonical weekly Friday workflow.
Install once, prove the loop, then drop a
.remedy
in your own repo.
# Clone, install, build the toolchain.
git clone [email protected]:petitgen-ltd/remedy.git
cd remedy
pnpm install
pnpm -r build
# Round-trip an example.
node packages/remedy-cli/dist/bin/remedy.js lint examples/hello-world
node packages/remedy-cli/dist/bin/remedy.js fmt examples/hello-world
node packages/remedy-cli/dist/bin/remedy.js build examples/hello-world
# You should see:
built examples/hello-world/.remedy.compiled.json
(5 embeddings, 0 cached, 5 fresh, model=nomic-embed-text)
Requires Node 20+, pnpm 9, and a local Ollama instance for
embedding (ollama pull nomic-embed-text). Set
REMEDY_EMBED_MODEL=openai:text-embedding-3-small to
fall back to OpenAI.