Docs Weave 1.0
Everything Weave does, and exactly how.
This page describes the behaviour of the code, including the thresholds it uses. Where something is a judgement made by the agent and not by the CLI, it says so.
Overview
Weave keeps the setup of AI coding agents true to how you actually work. It supports Claude Code and Codex, and it has four parts:
- Three skills that run inside your agent:
onboard,evolveanddoctor. They do the parts that need judgement. - A CLI that does the deterministic parts: mining session transcripts for evidence (
weave analyze) and linting the setup (weave doctor). - Two hooks per tool that note rules you state out loud and count sessions.
- A history file that records every applied change with its evidence, so the next run can check whether it worked.
The design rule behind all of it: judgement belongs in the skills, facts belong in the CLI. The CLI never calls a model and never touches the network. The same input always gives the same output.
Install
Into a project
This is the standard way. It covers both tools, and once committed it works for everyone on the repository.
npx github:ninodinoo/weave#171df09 init
Options:
| Flag | Effect |
|---|---|
--claude | Install for Claude Code only. |
--codex | Install for Codex only. |
--dir PATH | Install into another directory instead of the current one. |
Without a flag, Weave detects the tools: Claude Code if the project has .claude/ or CLAUDE.md, or claude is on your PATH; Codex if it has .codex/ or .agents/, or codex is on your PATH. If it finds neither, it installs for both.
What init does
- Checks that
.claude/settings.jsonand.codex/hooks.json, if they exist, are valid JSON with a well-formedhooksobject. If not, it stops before writing anything. - Copies the CLI into
.weave/runtime/, so hooks and skills work offline and for teammates. - Installs the skills as
weave-onboard,weave-evolveandweave-doctorinto.claude/skills/and.agents/skills/. - Merges two hook entries into each tool's hook file. Other entries are left exactly as they are.
- Writes
.weave/config.jsonand a.weave/.gitignorethat excludes.weave/local/. - Removes files left behind by Weave 0.x, if any.
init is idempotent: running it again produces the same files. It never creates or edits AGENTS.md or CLAUDE.md. That happens in onboarding, with your approval.
As a Claude Code plugin
For yourself, across all projects, without adding files to a repository first.
/plugin install weave --marketplace ninodinoo/weave#claude/dreamy-wright-51038x
In plugin form the skills are namespaced: /weave:onboard, /weave:evolve, /weave:doctor. The plugin brings its own hooks. A project only gets a .weave/ folder once you run onboarding there; until then the hooks do nothing in that project. If a project also has a project install, the plugin's hooks step aside so nothing is captured twice.
From the downloaded package
The package file contains the whole of Weave: 25 files, including the CLI, skills and configuration, 39.5 kB. Check it against SHA256SUMS if you like, put it in your repository folder and run:
npx --package=./weave-ai-1.0.0.tgz weave init
You can delete the .tgz afterwards.
Quick start
- Run
npx github:ninodinoo/weave#171df09 initin your repository. - Open your agent and run
/weave-onboard(Claude Code) or$weave-onboard(Codex). Answer a handful of questions and approve the draft. - In Codex, approve Weave's two hooks once with
/hooks. - Commit
AGENTS.md,CLAUDE.md, the skills, the hook files and.weave/. - Work normally for a week or two.
- Run
/weave-evolvein Claude Code or$weave-evolvein Codex. Review the proposals, apply the ones you agree with, commit.
At any time, node .weave/runtime/cli/weave.mjs status shows what is installed and what has accumulated, and … doctor lints the setup.
Onboard
The onboard skill writes down what a capable engineer would get wrong in your repository on day one, and nothing else. It works in five steps.
1. Look before asking
It runs doctor and analyze, reads any existing instruction files, and skims what is discoverable: the package manifest and scripts, CI config, linter and formatter config, the README. If you already have session history for the project, the corrections and failing commands in it count as answers you have already given.
2. Interview for what is not in the repo
One or two questions at a time, typically four to eight in total, in the language you write in. It is after six things:
- Verification. How do you know a change is good? Which command must pass, which is too slow, which is flaky?
- Traps. What looks right but is wrong here?
- Boundaries. Which files are generated or off-limits? What needs a human first?
- Decisions. Where would a sensible engineer “fix” something that is deliberate?
- Workflow. Branch, commit and PR conventions that no tool enforces.
- Personal preferences. Reply language, how terse, plan first or just start.
It does not ask you to describe the architecture or the stack. It can read those.
3. Draft
Every line has to pass one test: would the agent get this wrong without the line, and could it not find the answer in the repo? If either half is no, the line is left out. The target is under 60 lines; 150 is the ceiling. No directory trees, no architecture overviews, nothing the formatter enforces, no personas, no capital-letter emphasis.
AGENTS.md is the single source. Claude Code reads it through a CLAUDE.md containing @AGENTS.md; Codex reads it directly. Personal preferences go to your own user-level files, after asking. Area-specific detail goes into a short doc with a pointer line. No subagents, teams or generic skills are created at this stage.
4. Review
You see the full draft with its line count, or a diff if files already exist. Nothing is written until you agree. Existing files are not rewritten: what a human wrote is kept, and removals are proposed one by one.
5. Write and verify
The skill writes the files, then runs every command it documented, because an instruction file with a command that fails is worse than none. It runs doctor, fixes what it reports, records the setup in the history and resets the evidence counter.
Hooks
Weave installs two hooks per tool. They are ordinary command hooks that run the vendored CLI. They are built to be invisible: no model calls, no network, a five-second timeout, and every failure exits silently with code 0, so a Weave hook can never break a session.
| Event | What it does |
|---|---|
UserPromptSubmit | If your prompt states a lasting rule (“from now on…”, “never…”, “ab sofort…”), it appends the sentence to .weave/local/inbox.jsonl. It ignores slash commands and prompts longer than 4,000 characters. Corrections are not captured here, because judging them needs the surrounding conversation; those come from transcript analysis. |
SessionStart | On a fresh start (not on resume, clear or compact) it increments a session counter. Occasionally it shows you a one-line reminder. |
The reminder
You are reminded when 3 or more rules have been noted since the last evolve, or after 20 sessions, and then at most once every 7 days. The reminder is sent as a systemMessage, which is shown to you and costs the model no context. It reads, for example:
Weave: 3 standing instructions you gave and 12 sessions since the setup was last tuned. Run /weave-evolve to turn them into rules, skills or hooks.
Hooks act only inside a project that has .weave/config.json, found by walking up from the session's working directory. Elsewhere they do nothing and create nothing.
Evolve
The evolve skill tunes the instructions that every future session will read. The bar is high, because each added line costs attention in every session. “No change needed” is a valid result.
1. Gather
It runs weave analyze --json and weave doctor --json, reads the current instruction files and the last entries of .weave/history.jsonl, so nothing that was already tried is proposed again.
2. Decide what counts
Each kind of evidence has its own bar:
| Evidence | Bar |
|---|---|
| Standing instruction | Once is enough, if it is a lasting rule and not part of a one-off task. |
| Correction | The same theme in two or more sessions, or one that clearly cost real rework. |
| Failing command | It failed in two or more sessions. If another command usually fixed it, the lesson is “use that one”. |
| Repeated prompt | Three or more sessions, and the request has steps worth writing down. |
| Frequent command | Only if it is how changes get verified and the instructions do not say so. |
| Hot file | Only if a pointer would save the agent from searching. |
A past change marked recurring | The earlier fix did not work. Escalate it. |
| Doctor findings | Fix them. Dead paths and dead commands mislead every session. |
Anything already covered, anything the agent can find in the repo, and anything about a single task is dropped. If a quote is ambiguous, the agent asks you what you meant.
3. Route, 4. Prune
Each lesson goes to the cheapest mechanism that works (see Routing). Then the skill looks for lines to remove: ones the linter flagged, ones the agent could work out, ones about code that no longer exists, duplicates. AGENTS.md should not grow past 150 lines; if a change would push it over, a removal comes with it.
5. Propose
At most five changes, most valuable first. Each shows the exact diff or new file, the evidence (quotes with dates, or counts), and one sentence on why that mechanism. You choose which to apply.
6. Apply and record
Approved changes are made, doctor is run again, and each change is recorded with watch terms:
weave record --kind rule --target AGENTS.md \ --summary "Use pnpm, not npm" \ --evidence "npm test failed in 4 sessions" \ --watch "npm test,npm install,pnpm"
Finally weave mark-evolved closes the cycle, even if nothing changed. It resets the session counter and marks everything before it as old evidence.
Did it hold?
This is what separates a loop from a generator. Every history entry with watch terms is checked against all dated evidence in the analysis window: feedback quotes and failed commands. A piece of evidence matches when it contains any watch term, ignoring case.
| Verdict | Condition | What evolve does |
|---|---|---|
| recurring | At least one match dated after the change. | Escalates: makes the line more concrete, then moves it closer to where it applies, then turns it into a hook. |
| holding | No match after the change, and at least 5 sessions since. | Leaves it alone. |
| too-early | No match yet, fewer than 5 sessions since. | Waits. |
The report shows the counts, for example 5 before → 0 after. Watch terms are chosen by the agent when it records a change, so their quality matters: a few lowercase words that would appear in a future correction or failing command if the problem came back.
How evidence is found
weave analyze reads the session transcripts both tools already keep on your machine, for the current project only, and prints a report. By default it looks at the last 60 days. Everything below is pattern matching and counting. It produces candidates; the evolve skill and you decide what is real.
Where sessions come from
| Tool | Location | Matched to the project by |
|---|---|---|
| Claude Code | ~/.claude/projects/<encoded path>/*.jsonl | The folder name, which is the project path with every non-alphanumeric character replaced by -. |
| Codex | ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl | The working directory in the first line of each rollout. Sessions started in a subdirectory of the project count. |
CLAUDE_CONFIG_DIR and CODEX_HOME are respected. Subagent traffic and injected context are skipped, so only what you typed counts as a prompt.
Feedback: standing instructions and corrections
A standing instruction is you stating a rule that should outlive the session. Weave looks for phrases such as “from now on”, “going forward”, “remember to”, “keep in mind”, “ab sofort”, “in Zukunft”, “merk dir”, “nie wieder”. The words always, never, immer and niemals count only at the start of a sentence or addressed to “you”, and only in a message of 300 characters or less. That is the difference between “Never commit to main” and “add a test that the function never returns null”.
A correction is you pushing back on what the agent just did: a message that opens with a standalone “No,”, “Wrong.”, “Nein,”, or contains “that's wrong”, “I told you”, “why did you”, “don't use…”, “revert that”, “das stimmt nicht”, “du sollst nicht…”. An interjection must stand alone, so “No tests exist yet, please add some” is not a correction. A correction only counts if the agent has already done something in that session.
The quote kept as evidence is the sentence that carries the signal, not the whole message. Detection covers English and German.
Commands
Shell commands are reduced to a key, so that different invocations of the same thing are counted together:
| Command | Key |
|---|---|
CI=1 pnpm --filter web test src/a.test.ts | pnpm test |
npm run test:unit -- --watch | npm run test:unit |
(cd app && npm run build) 2>&1 | tail | npm run build |
docker compose -f dc.yml up -d | docker compose up |
./scripts/deploy.sh staging | ./scripts/deploy.sh |
ls, cat, git status, grep… | ignored: they say nothing about the project |
Heredocs, quoted strings, command substitutions and redirections are stripped first, so an inline script is never mistaken for a command.
- Failing commands. Reported when a command failed in 2 or more sessions, or 3 or more times. When a chain like
a && b && cfails, the failure is attributed to one command: the one the error output names, otherwise the last. - What fixed it. If, within the next three commands, a different command that does the same job succeeds (
pnpm testafternpm test), it is recorded as the usual fix. The search ends when the same command passes on retry, or when you send a new prompt. - Frequent commands. Used in 3 or more sessions. Each is marked as documented or not, by looking for the whole command in your instruction files.
npm testis not considered documented because the file sayspnpm test.
Hot files, repeated prompts and trend
- Hot files. Files the agent read in 3 or more sessions and in at least 40% of all sessions. In Codex, reads through
cat,sed -n,headand similar are recognised. - Repeated prompts. Prompts of 20 to 600 characters are compared by their meaningful words. Prompts that share at least half of them are grouped, and groups spanning 3 or more sessions are reported.
- Orientation. The average number of tool calls before the agent's first edit: a rough measure of how much searching each session starts with.
- Trend. Per ISO week: sessions, prompts, feedback, interrupts and failed commands. Useful to see whether corrections are going down.
The report
weave analyze --json prints one object:
| Field | Content |
|---|---|
summary | Session count, platforms, date range, prompts, corrections, standing instructions, interrupts, the orientation figure, the window, and when the setup was last tuned. |
feedback | Up to 60 recent items: kind, quote, date, platform, session, and new (since the last evolve). Items captured by the hook are marked source: "hook". |
failingCommands | command, failures, runs, sessions, errors (excerpts), usuallyFixedBy, documented. |
frequentCommands | command, sessions, runs, documented. |
hotFiles | file, sessions, share (percent), documented. |
repeatedPrompts | sessions, count, examples. |
pastChanges | One entry per recorded change with watch terms: before, after, sessionsAfter, verdict. |
trend | One entry per week. |
setup | The current linter score and file counts. |
Routing
Appending a rule is only one of several things a lesson can become. The evolve skill picks the cheapest mechanism that works:
| The lesson is… | It goes to… |
|---|---|
| true for every task in the repo | one concrete line in AGENTS.md |
| about one area of the code | a short doc with a pointer line in AGENTS.md. For Claude Code only, a .claude/rules/<topic>.md with paths: also works. |
| a procedure with several steps, or a prompt you retype | a skill, written once and placed in both .agents/skills/ and .claude/skills/ |
| something that must happen every time, where a written rule has already failed | a hook |
| a personal preference | your own ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, after asking |
| work that floods the context or needs an independent second look | a subagent. Rare. |
A rule that keeps being broken is escalated in a fixed order: make the line more concrete, move it closer to where it applies, turn it into a hook. Adding “IMPORTANT” is not a step on that ladder. The skill ships two reference files it reads only when needed: how to write a skill for both tools, and how to write a hook for both tools, including a tested example that blocks force pushes.
The linter
weave doctor checks everything an agent loads for the repository: AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, AGENTS.override.md, .claude/rules/, skills in .claude/skills/ and .agents/skills/, and subagents in .claude/agents/. It is deterministic and takes milliseconds.
weave doctor # human-readable report weave doctor --json # machine-readable weave doctor --ci # exit 1 if there is an error weave doctor --strict # exit 1 if there is any finding
Score. It starts at 100. Each error costs 12 points, each warning 4, and it does not go below 0.
Budgets.
| What | Limit |
|---|---|
| Lines in a root instruction file | warning above 150, error above 300 |
All AGENTS.md files together | error above 32 KiB, where Codex truncates silently |
| Lines with IMPORTANT / MUST / NEVER-style emphasis | warning above 5 per file |
| Directory tree in a file | warning from 12 lines |
| Skill description | warning under 30 characters, error over 1,024 |
| Skill body | warning above 500 lines |
The linter matches patterns and can be wrong. The doctor skill reads the lines a finding points at before changing anything, shows its fixes as a diff, and leaves a line alone when it believes the finding is a false positive.
All 19 rules
| Rule | Level | Triggers when |
|---|---|---|
no-instructions | error | The repo has no AGENTS.md or CLAUDE.md. |
too-long | warn / error | A root instruction file is over 150 lines (warning) or 300 lines (error). |
codex-truncation | error | The AGENTS.md files total more than 32 KiB. |
dead-path | warn | A path in backticks does not exist. Branch names, MIME types, package subpaths, URLs and code like console.log are not treated as paths. |
dead-script | error | The file says npm run x (or pnpm, yarn, bun) and package.json has no script x. |
vague | warn | A line is not actionable: “write clean code”, “follow best practices”, “you are an expert…”, “think step by step”. |
linter-job | warn | A formatting rule (indentation, quotes, semicolons) is written in prose although the repo has a formatter or linter config. |
emphasis | warn | More than 5 lines in a file shout with IMPORTANT, CRITICAL, MUST, NEVER, ALWAYS or MANDATORY. |
tree-dump | warn | A file contains a directory tree of 12 lines or more. |
duplicate | warn | The same line of 40 characters or more appears in two instruction files. |
two-sources | warn | CLAUDE.md and AGENTS.md both exist and CLAUDE.md does not import @AGENTS.md. A symlink between them counts as one file. |
no-verification | warn | package.json has a test, lint, typecheck, check or build script and the instructions never mention one. |
secret | error | A line looks like a credential: API keys, GitHub and Slack tokens, AWS key IDs, private key headers. |
skill-frontmatter | error | A SKILL.md has no YAML frontmatter. |
skill-description | warn / error | The description is missing or over 1,024 characters (error), or under 30 (warning). |
skill-name | warn | The name does not match the folder, or is not lowercase letters, digits and hyphens. |
skill-length | warn | The body of a SKILL.md is over 500 lines. |
skill-drift | warn | The same skill differs between .claude/skills/ and .agents/skills/. |
agent-frontmatter | error | A subagent in .claude/agents/ lacks name or description, so it is never delegated to. |
Commands
After a project install, the CLI lives at .weave/runtime/cli/weave.mjs. You can also run any command through npx github:ninodinoo/weave#171df09. Without --dir, commands act on the Weave project the current directory belongs to, so they work from a subdirectory. init is the exception: it sets up the directory it is run in.
| Command | Does | Options |
|---|---|---|
weave init | Installs skills, hooks and runtime. | --claude --codex |
weave doctor | Lints the setup. | --json --ci --strict |
weave analyze | Prints the evidence report. | --json --days N (default 60) --all --min N (sessions a pattern must span, default 3) |
weave status | What is installed, the score, what has accumulated. | |
weave uninstall | Removes skills, hooks and runtime. | --purge also deletes .weave/ |
weave record | Appends a change to the history. Used by the skills. | --kind --target --summary --evidence --watch a,b |
weave mark-evolved | Closes an evolve cycle. Used by the skills. | |
weave hook | Entry point for the hooks. Reads the event from stdin. | prompt or session-start, --platform codex |
All commands accept --dir PATH. --kind is one of rule, scoped-rule, skill, hook, subagent, prune, setup.
Exit codes. 0 success. 1 a failure, or findings under --ci / --strict. 2 a usage error, such as an unknown command or a bad option value. weave hook always exits 0.
Files
| Path | Commit? | Purpose |
|---|---|---|
AGENTS.md | yes | The shared instructions. Yours; Weave only proposes. |
CLAUDE.md | yes | @AGENTS.md plus anything Claude-specific. |
.claude/skills/weave-*/ | yes | The three skills for Claude Code. |
.agents/skills/weave-*/ | yes | The same skills for Codex. |
.claude/settings.json | yes | Two hook entries, merged into what is there. |
.codex/hooks.json | yes | Two hook entries, merged into what is there. |
.weave/config.json | yes | Version, mode (project or plugin), tools. |
.weave/history.jsonl | yes | Every applied change with its evidence. |
.weave/runtime/ | yes | The vendored CLI, about 80 kB. |
.weave/local/state.json | no | Session counter, last evolve, last reminder. |
.weave/local/inbox.jsonl | no | Rules the hook noted, as quotes of your prompts. |
A history entry
{"ts":"2026-11-17T09:12:44.103Z","kind":"rule","target":"AGENTS.md",
"summary":"Use pnpm, not npm",
"evidence":"npm test failed in 4 sessions; pnpm test worked next each time",
"watch":["npm test","npm install","pnpm"]}
The history is plain JSON Lines. You can read it, grep it, and see why any line of your setup exists.
Claude Code and Codex
Both tools read the same skill format and nearly the same hook format. The differences Weave handles for you:
| Claude Code | Codex | |
|---|---|---|
| Instructions | CLAUDE.md, which imports @AGENTS.md | AGENTS.md directly |
| Skills live in | .claude/skills/ | .agents/skills/ |
| Run a skill | /weave-evolve | $weave-evolve |
| Hooks live in | .claude/settings.json | .codex/hooks.json |
| Hooks become active | when the workspace is trusted | after you approve them once in /hooks |
| Automatic use of Weave's skills | off (disable-model-invocation) | off (allow_implicit_invocation: false) |
| Size limit | none enforced; under 200 lines recommended | 32 KiB, truncated silently |
Weave's own skills only run when you call them. That keeps them out of the model's context in normal sessions.
What has been verified
| Claude Code | Codex | |
|---|---|---|
| Skills | Tested in live sessions, as project install and as plugin. | Discovery tested against Codex CLI 0.169. |
| Hooks | Tested in live sessions. | Config shape taken from the Codex source; not yet run in a live session. |
| Transcript analysis | Tested against real transcripts. | Parser written from the Codex source and tested with fixtures. |
Teams and CI
Commit everything except .weave/local/, which is ignored automatically. Teammates then get the skills, the hooks and the runtime with a normal git pull, without installing anything. Evidence is per developer: each person's transcripts stay on their machine, and anyone can run evolve. The proposals arrive as ordinary diffs and go through your normal review.
To keep the setup from rotting between evolve runs, lint it in CI:
# .github/workflows/agents.yml
name: Agent setup
on: [pull_request]
jobs:
doctor:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 22 }
- run: node .weave/runtime/cli/weave.mjs doctor --ci
This fails a pull request that leaves a dead script reference, a credential, or an oversized file in the instructions.
Privacy
- Weave contains no network code and has no dependencies that could. There is no account, no server and no telemetry.
weave analyzereads transcripts for the current project only, from the folders the tools already write to.- Its report goes to standard output. When a skill runs it, the report becomes part of the agent session you are already in, like any file you open there.
.weave/local/contains quotes of your own prompts and is gitignored..weave/history.jsonlis meant to be committed. It contains the evidence text for changes you approved, which can include short quotes of what you typed. Read an entry before you commit it if that matters to you.- This website loads no third-party resources and sets no cookies. The linter on the home page runs entirely in your browser.
Limits
- Transcript formats are internal to both tools and can change with any release. The parsers skip what they do not understand instead of failing.
- Detection is pattern matching in English and German. It will miss some feedback and flag some ordinary requests. That is why nothing is applied without review.
- Compressed Codex rollouts (
.jsonl.zst) are skipped, because reading them would need a dependency. - Codex hooks and transcript parsing are built from the Codex source and tested with fixtures, not yet against live Codex sessions.
- The session counter is approximate when several sessions start at the same moment.
- The linter cannot judge meaning. It finds dead references and known anti-patterns, not rules that are simply wrong.
Troubleshooting
weave analyze finds no sessions
Check that you are in the project directory (or pass --dir), and that you have used the agent in this project within the window; try --all. If it stops working right after updating Claude Code or Codex, the transcript format probably changed: please open an issue.
The hooks do not seem to run
In Codex, approve them once with /hooks. In Claude Code, the workspace must be trusted. In both, node has to be on the PATH of the shell the tool uses; if it is not, the hooks skip silently. weave status shows whether the hook entries are present.
init says a settings file is not valid JSON
Weave will not merge into a file it cannot parse, because that would risk your settings. Remove comments and trailing commas from the file, or fix what a JSON validator reports, then run init again.
A linter finding is wrong
It happens; the linter matches patterns. Leave the line as it is. If the false positive is a general one, an issue with the line that triggered it is very welcome.
The skills are not listed in my agent
That is intended. They are user-invoked only, so they do not appear in the model's list of available skills. Type /weave-evolve or $weave-evolve yourself.
Uninstall
For a project install, choose one command and run it from the project root. To remove the Claude Code plugin, use /plugin uninstall weave@weave.
node .weave/runtime/cli/weave.mjs uninstall # keeps .weave/history.jsonl and config node .weave/runtime/cli/weave.mjs uninstall --purge # removes .weave/ entirely
This removes the three skills from both tools, Weave's two hook entries from each hook file, and the runtime. A normal uninstall preserves AGENTS.md, CLAUDE.md and custom skills and hooks. With --purge, custom scripts stored inside .weave/ are also deleted. A hook file that contained nothing but Weave's entries is deleted; otherwise only the two entries go.
Upgrading from 0.x
Weave 1.0 is a rewrite. Run init once; it removes what 0.x installed: the .claude/commands/weave:* files, the unused hook scripts and the generic agents. The /weave:onboarding-style commands are replaced by the three skills. Cursor, Windsurf and OpenClaw are no longer supported; Weave now does two tools properly.
Found something unclear or wrong on this page? Tell us.