Weave 1.0The self-tuning setup for Claude Code and CodexMIT · zero dependencies

Weave

Stop telling your agent the same thing twice.

Weave reads your real sessions, finds what you keep correcting, and turns it into reviewed changes to your instructions, skills and hooks. Then it checks whether they worked.

  • 0dependencies
  • 0network calls
  • 0tokens added to your sessions
  • 65tests on Linux and Windows
  • 19linter rules
00In one picture

Evidence in. Reviewed diffs out.

The examples on the left show patterns Weave can find in your sessions. On the right is what it becomes. Nothing crosses without your approval.

What your sessions say

  • Correction“No, use pnpm here.”4 sessions
  • Standing instruction“From now on, named exports only.”said once, meant forever
  • Repeated prompt“Write the release notes for the merged PRs.”retyped in 5 sessions
  • Rule broken anywayForce push, despite the rule.2 before → 3 after
  • Stale linesrc/legacy/api.ts no longer exists.misleads every session

What your setup becomes

AGENTS.md4 lines
# Shop API - Run the tests before you commit. - Money is integer cents, never floats. - The legacy API lives in src/legacy/api.ts. - Use pnpm, not npm. The lockfile is pnpm-lock.yaml. - Named exports only; no default exports.
skill · release-notes hook · no-force-push
Every thread is a diff you approved. Nothing is applied silently.
01The problem

Instruction files fail in two ways. Both are measured.

You wrote AGENTS.md once. Since then the codebase moved, you corrected the agent dozens of times, and none of it made it back into the file. Or you let a tool generate it, and now it is four hundred lines the agent skims.

They rot. In a study of 155 AGENTS.md files, about half were never changed after the day they were created. arXiv 2510.21413
They bloat. Auto-generated context files lowered agent success and raised cost by more than a fifth. Short, human-written ones helped. arXiv 2602.11988
Short wins. Anthropic's guidance is to stay under 200 lines and write down only what the agent cannot find by itself (Claude Code docs). Weave aims for 60, and its linter warns at 150.

AGENTS.md, generated once412 lines

  • directory tree the agent can list itself
  • “write clean code”, “you are an expert”
  • IMPORTANT, NEVER, MUST
  • paths and commands that no longer exist

The same repo, kept by Weave14 lines

# Shop API

## Commands
- Verify with `pnpm test` and `pnpm lint`.
- The e2e suite takes 20 minutes. Run it before a release only.

## Rules
- Use pnpm, not npm. The lockfile is pnpm-lock.yaml.
- Money is integer cents, never floats.
- `src/gen/` is generated. Change the schema, not the output.
- Named exports only.

## Ask first
- Migrations, dependency upgrades, anything in `infra/`.

Each line is something the agent got wrong once and could not have found in the repo.

02How it works

A loop, not a generator.

Four steps. The first takes ten minutes, the second takes none, and the last two are what nobody does by hand.

/weave-onboard

WeaveI've read your manifest, CI config and README, so I won't ask about the stack. How do you know a change is good here?

Youpnpm test has to pass. The e2e suite is too slow, we only run it before a release.

WeaveWhat does every new teammate get wrong once?

YouThey edit the generated client in src/gen. It gets overwritten.

WeaveIs there anything I should always ask before doing?

YouMigrations. Always.

✓ AGENTS.md drafted, 14 lines. Every command in it was run and works.

The sessions and numbers in these panels are illustrative. The output format is the real one.

03The right mechanism

Not every lesson is a line in AGENTS.md.

Most tools that learn from you can only append rules. Weave routes each lesson to the cheapest mechanism that works, and each kind of evidence has to clear its own bar first. Pick one.

goes to


        

04Try it now

Paste your AGENTS.md. See what it costs you.

weave doctor is a deterministic linter for everything an agent loads. This is a subset of it running in your browser. Nothing you paste leaves this page.

AGENTS.md
weave doctor
100

Setup health

Nine of the 19 rules run here. The others need your file system: dead paths, drift between the Claude Code and Codex copies of a skill, missing frontmatter. See all rules.

Nine of the 19 rules run here. The others need your file system: dead paths, drift between the Claude Code and Codex copies of a skill, missing frontmatter. See all rules.

05Restraint

What Weave deliberately does not do.

Most of what makes agent setups worse is added with good intentions. These are decisions, not gaps.

  • No context injection.

    Tools that add memory to every session cost thousands of tokens per session for recall that is rarely used. Weave adds nothing to a session. Its hooks talk to you, not to the model.

  • No personas or pipelines.

    Planner, architect, reviewer chains multiply token use and do not make a single task better. Weave suggests a subagent only when evidence calls for one.

  • No generic skill packs.

    A skill appears when you have retyped the same request in several sessions, and it contains the steps specific to your repo. Not before.

  • No silent changes.

    Every change is a diff you approved, logged in .weave/history.jsonl with the evidence that justified it. You can read why any line exists.

  • No telemetry.

    Transcripts are read on your machine by a script with no dependencies and no network code. There is no account, no server and nothing to opt out of.

  • No lock-in.

    The output is plain files in the formats both tools already read. Remove Weave and your AGENTS.md, skills and hooks keep working.

06In your repo

Plain files. All of them readable.

Commit them and the whole team gets the same setup, including people who never ran npx. Select a file to see what it is for.

07Honest status

What is tested, and what is not yet.

A tool that edits how your agent works should tell you exactly how far it has been proven.

Claude CodeCodex
Skillstested live in real sessions, as project install and as plugindiscovery tested against Codex CLI 0.169
Hookstested live in real sessionsfrom source config shape taken from the Codex source, not yet run live
Transcript analysisreal transcriptsfixtures parser written from the Codex source
PlatformsCI runs the suite on Linux and Windows with Node 18 and 22
ReviewAn independent adversarial review reproduced 29 defects before release. All are fixed, each with a regression test.

Transcript formats can change

They are internal to both tools. The parsers skip what they do not understand. If weave analyze finds no sessions after an update, this is the likely cause.

Detection finds candidates

Feedback detection is pattern matching in English and German. It proposes; the agent and you decide what is real.

One known gap

Compressed Codex rollouts (.jsonl.zst) are skipped, because reading them would need a dependency.

08Get it

Installed in one command.

You need Node 18 or newer and Claude Code, Codex, or both. Weave has no dependencies of its own.

For Claude Code and Codex. Works for the whole team once committed.

  1. Run this in your repository:

    It adds three skills, two hooks per tool and a copy of the CLI in .weave/runtime/. Use --claude or --codex to pick one tool.

  2. Start the interview in your agent:

    In Codex, approve Weave's two hooks once with /hooks.

  3. Commit the result, work as usual, and run /weave-evolve in Claude Code or $weave-evolve in Codex after a week or so.

To remove Weave from a project, run node .weave/runtime/cli/weave.mjs uninstall in its root. This removes the bundled skills, hook entries and CLI. Your instructions and custom skills stay. More on uninstalling.

09Questions

Before you trust it with your setup.

Does Weave send my code or transcripts anywhere?

No. Weave is a local script with no dependencies and no network code. It reads Claude Code transcripts under ~/.claude/projects/ and Codex rollouts under ~/.codex/sessions/ for the current project only, and prints a report. That report goes to the agent session you are already in, the same way any file you open does.

Does it cost tokens?

The hooks cost none: they make no model calls and add nothing to the model's context. /weave-evolve is an ordinary session you start yourself, typically every week or two, and costs what a short conversation costs.

How is this different from /init or the built-in memory?

/init writes a first file from the code. Built-in memory lets the agent keep its own notes on your machine. Weave does the part neither covers: it maintains the shared, committed setup from evidence, routes lessons to rules, skills or hooks, prunes under a size budget, and checks afterwards whether a change worked. It complements both.

Will it rewrite my existing AGENTS.md or CLAUDE.md?

No. With existing files, onboarding keeps what you wrote, proposes removals for lines that no longer hold, and shows everything as a diff. weave init itself never touches your instruction files; it only adds skills, hooks and the .weave/ folder.

What happens to my settings.json when I install?

Weave merges two hook entries into what is already there and leaves everything else alone. If the file cannot be parsed, init stops before writing anything and tells you. Uninstalling removes exactly those two entries again.

Do I need both Claude Code and Codex?

No. Either one works. If you use both, they read the same AGENTS.md and the same skills, and weave doctor warns you when the two copies drift apart.

Which languages does the feedback detection understand?

English and German. It looks for phrases like “from now on”, “no, use…”, “ab sofort” or “das stimmt nicht”. It produces candidates only. A quote becomes a rule when the agent and you agree that it is one.

Can I use the linter in CI?

Yes. weave doctor --ci exits with code 1 on errors, --strict on any finding, and --json prints machine-readable output. It is deterministic and takes milliseconds.

Does it work on Windows?

The test suite runs on Windows and Linux with Node 18 and 22 on every commit.

What does it cost?

Nothing. Weave is MIT licensed and has no paid tier, account or server.

Make the next correction the last one.

Download 1.0.0Read the docsGitHub