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:

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.

Requirements. Node.js 18 or newer, and Claude Code, Codex, or both. Weave has no dependencies and no build step. It runs on Linux, macOS and Windows.

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:

FlagEffect
--claudeInstall for Claude Code only.
--codexInstall for Codex only.
--dir PATHInstall 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

  1. Checks that .claude/settings.json and .codex/hooks.json, if they exist, are valid JSON with a well-formed hooks object. If not, it stops before writing anything.
  2. Copies the CLI into .weave/runtime/, so hooks and skills work offline and for teammates.
  3. Installs the skills as weave-onboard, weave-evolve and weave-doctor into .claude/skills/ and .agents/skills/.
  4. Merges two hook entries into each tool's hook file. Other entries are left exactly as they are.
  5. Writes .weave/config.json and a .weave/.gitignore that excludes .weave/local/.
  6. 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

  1. Run npx github:ninodinoo/weave#171df09 init in your repository.
  2. Open your agent and run /weave-onboard (Claude Code) or $weave-onboard (Codex). Answer a handful of questions and approve the draft.
  3. In Codex, approve Weave's two hooks once with /hooks.
  4. Commit AGENTS.md, CLAUDE.md, the skills, the hook files and .weave/.
  5. Work normally for a week or two.
  6. Run /weave-evolve in Claude Code or $weave-evolve in 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:

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.

EventWhat it does
UserPromptSubmitIf 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.
SessionStartOn 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:

EvidenceBar
Standing instructionOnce is enough, if it is a lasting rule and not part of a one-off task.
CorrectionThe same theme in two or more sessions, or one that clearly cost real rework.
Failing commandIt failed in two or more sessions. If another command usually fixed it, the lesson is “use that one”.
Repeated promptThree or more sessions, and the request has steps worth writing down.
Frequent commandOnly if it is how changes get verified and the instructions do not say so.
Hot fileOnly if a pointer would save the agent from searching.
A past change marked recurringThe earlier fix did not work. Escalate it.
Doctor findingsFix 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.

VerdictConditionWhat evolve does
recurringAt 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.
holdingNo match after the change, and at least 5 sessions since.Leaves it alone.
too-earlyNo 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

ToolLocationMatched to the project by
Claude Code~/.claude/projects/<encoded path>/*.jsonlThe folder name, which is the project path with every non-alphanumeric character replaced by -.
Codex~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonlThe 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:

CommandKey
CI=1 pnpm --filter web test src/a.test.tspnpm test
npm run test:unit -- --watchnpm run test:unit
(cd app && npm run build) 2>&1 | tailnpm run build
docker compose -f dc.yml up -ddocker 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.

Hot files, repeated prompts and trend

The report

weave analyze --json prints one object:

FieldContent
summarySession count, platforms, date range, prompts, corrections, standing instructions, interrupts, the orientation figure, the window, and when the setup was last tuned.
feedbackUp to 60 recent items: kind, quote, date, platform, session, and new (since the last evolve). Items captured by the hook are marked source: "hook".
failingCommandscommand, failures, runs, sessions, errors (excerpts), usuallyFixedBy, documented.
frequentCommandscommand, sessions, runs, documented.
hotFilesfile, sessions, share (percent), documented.
repeatedPromptssessions, count, examples.
pastChangesOne entry per recorded change with watch terms: before, after, sessionsAfter, verdict.
trendOne entry per week.
setupThe 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 repoone concrete line in AGENTS.md
about one area of the codea 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 retypea skill, written once and placed in both .agents/skills/ and .claude/skills/
something that must happen every time, where a written rule has already faileda hook
a personal preferenceyour own ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, after asking
work that floods the context or needs an independent second looka 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.

WhatLimit
Lines in a root instruction filewarning above 150, error above 300
All AGENTS.md files togethererror above 32 KiB, where Codex truncates silently
Lines with IMPORTANT / MUST / NEVER-style emphasiswarning above 5 per file
Directory tree in a filewarning from 12 lines
Skill descriptionwarning under 30 characters, error over 1,024
Skill bodywarning 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

RuleLevelTriggers when
no-instructionserrorThe repo has no AGENTS.md or CLAUDE.md.
too-longwarn / errorA root instruction file is over 150 lines (warning) or 300 lines (error).
codex-truncationerrorThe AGENTS.md files total more than 32 KiB.
dead-pathwarnA path in backticks does not exist. Branch names, MIME types, package subpaths, URLs and code like console.log are not treated as paths.
dead-scripterrorThe file says npm run x (or pnpm, yarn, bun) and package.json has no script x.
vaguewarnA line is not actionable: “write clean code”, “follow best practices”, “you are an expert…”, “think step by step”.
linter-jobwarnA formatting rule (indentation, quotes, semicolons) is written in prose although the repo has a formatter or linter config.
emphasiswarnMore than 5 lines in a file shout with IMPORTANT, CRITICAL, MUST, NEVER, ALWAYS or MANDATORY.
tree-dumpwarnA file contains a directory tree of 12 lines or more.
duplicatewarnThe same line of 40 characters or more appears in two instruction files.
two-sourceswarnCLAUDE.md and AGENTS.md both exist and CLAUDE.md does not import @AGENTS.md. A symlink between them counts as one file.
no-verificationwarnpackage.json has a test, lint, typecheck, check or build script and the instructions never mention one.
secreterrorA line looks like a credential: API keys, GitHub and Slack tokens, AWS key IDs, private key headers.
skill-frontmattererrorA SKILL.md has no YAML frontmatter.
skill-descriptionwarn / errorThe description is missing or over 1,024 characters (error), or under 30 (warning).
skill-namewarnThe name does not match the folder, or is not lowercase letters, digits and hyphens.
skill-lengthwarnThe body of a SKILL.md is over 500 lines.
skill-driftwarnThe same skill differs between .claude/skills/ and .agents/skills/.
agent-frontmattererrorA 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.

CommandDoesOptions
weave initInstalls skills, hooks and runtime.--claude --codex
weave doctorLints the setup.--json --ci --strict
weave analyzePrints the evidence report.--json --days N (default 60) --all --min N (sessions a pattern must span, default 3)
weave statusWhat is installed, the score, what has accumulated.
weave uninstallRemoves skills, hooks and runtime.--purge also deletes .weave/
weave recordAppends a change to the history. Used by the skills.--kind --target --summary --evidence --watch a,b
weave mark-evolvedCloses an evolve cycle. Used by the skills.
weave hookEntry 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

PathCommit?Purpose
AGENTS.mdyesThe shared instructions. Yours; Weave only proposes.
CLAUDE.mdyes@AGENTS.md plus anything Claude-specific.
.claude/skills/weave-*/yesThe three skills for Claude Code.
.agents/skills/weave-*/yesThe same skills for Codex.
.claude/settings.jsonyesTwo hook entries, merged into what is there.
.codex/hooks.jsonyesTwo hook entries, merged into what is there.
.weave/config.jsonyesVersion, mode (project or plugin), tools.
.weave/history.jsonlyesEvery applied change with its evidence.
.weave/runtime/yesThe vendored CLI, about 80 kB.
.weave/local/state.jsonnoSession counter, last evolve, last reminder.
.weave/local/inbox.jsonlnoRules 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 CodeCodex
InstructionsCLAUDE.md, which imports @AGENTS.mdAGENTS.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 activewhen the workspace is trustedafter you approve them once in /hooks
Automatic use of Weave's skillsoff (disable-model-invocation)off (allow_implicit_invocation: false)
Size limitnone enforced; under 200 lines recommended32 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 CodeCodex
SkillsTested in live sessions, as project install and as plugin.Discovery tested against Codex CLI 0.169.
HooksTested in live sessions.Config shape taken from the Codex source; not yet run in a live session.
Transcript analysisTested 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

Limits

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.