Liked this? The newsletter carries one note like it each month.
Subscribe
BricoWerx keeps the best parts of your projects as reusable pieces: modules, prompts, agent skills, evals. Engineers find them from the terminal. AI assistants find them over MCP. Nobody regenerates what already exists.
A version-controlled library of your organisation's proven building blocks, with the wiring and the reasoning attached, readable by humans and by AI.
Making something new from whatever is already at hand, and letting the joins show. We apply it to engineering knowledge in the AI era: the modules, prompts and evals your team already proved are the raw material. The visible join is where a piece was reused, and we think that join is the most valuable line in the codebase.
We are finishing Phase A: summaries at capture, meaning-based search and the MCP server. Leave your email and you get the first binary before anyone else, a founding badge in your Vault, and a say in what ships next.
Before anyone writes or generates, ask the Vault. The best material is the work your team has already shipped and debugged.
A reused piece keeps its name, its version and its history. Reuse is not hidden behind a copy-paste. It is recorded, queryable, and worth celebrating.
seamEach capture adds a card, a surface, a summary and a set of relations. The library gets smarter for humans and for AI with every commit.
The auth module your team perfected two projects ago still exists. It is just buried inside that project, tangled with its dependencies, and invisible to search. So the next project writes a new one. Then an AI assistant, asked the same question, writes a third one. The knowledge was never lost. It was never findable.
Prompts live in a wiki page, eval scripts rot in scratch folders, agent configs get copy-pasted between repos and slowly drift apart. Each one was hard-won. None of them are searchable as a thing in their own right.
Assistants are great at writing new code and bad at knowing what you already have. Every regeneration costs tokens, review time, and another variant to maintain.
Teams now track token spend like cloud spend, and MCP gave assistants a standard way to ask external systems for knowledge. A small, curated library of your best work is exactly what that standard was made to serve.
The knowledge was never lost. It was never findable.
the one-line version of the problem
Three verbs, one binary. Everything lives in a git folder on your machine called the Vault. No server to run, no account to create.
Point brico at a project. It suggests which modules are worth keeping. Pick one, and it is saved to the Vault as an immutable, versioned piece with a manifest, its env vars, and its wiring steps.
$ brico extract auth 92% jwt, passport, bcrypt mailer 81% smtp, templates $ brico capture auth saved auth@0.1.0 to the Vault
Search by name, tag, or plain-language meaning. Engineers use the CLI or the terminal UI. AI assistants use the exact same library over MCP, so they answer "do we have X?" from your Vault instead of guessing.
$ brico search "token auth for nest" auth@0.2.0 jwt, passport 3 projects $ brico mcp serving 4 tools to your assistant
One command copies the piece into a new project, merges env vars into your example file, and prints the manual steps that remain. You reuse verified code instead of reviewing generated code.
$ brico add auth copied 6 files, wired .env.example next: add AuthModule to AppModule imports
A package gives you code. A piece gives you code and the wiring, the env vars, the design decisions, and a few cheap summaries that let people and AI understand it without reading every file.
manifest.jsonThe contract. Dependencies, env vars, framework wiring steps, and how this piece relates to others: depends on, replaces, similar to.card.jsonThe one-liner. Name, description, tags, kind, latest version. Enough to answer "do we have something for X?" for the price of a sentence.surface.jsonThe signatures. Exported types and functions with bodies removed, extracted from the AST. Enough to write code that calls the piece correctly.summary.mdThe reasoning. Design decisions and trade-offs, generated at capture time. The part you would otherwise interrupt a senior engineer for.src/The source. Rarely needed. Most questions are answered by the three files above, at a fraction of the cost of reading code.Every piece can be read at four levels of detail. Whoever is asking, human or AI, climbs only as high as the task needs. Click a level to see exactly what gets returned.
// card.json, the whole thing { "name": "auth", "kind": "code", "description": "JWT auth with Passport and bcrypt", "tags": ["security", "jwt"], "framework": "nest", "latest": "0.2.0" }
Enough to answer existence questions across an entire Vault for the price of a sentence.
// surface.json, signatures only, no bodies export class AuthService { signIn(dto: SignInDto): Promise<Session> verify(token: string): Promise<Claims> } env JWT_SECRET, JWT_EXPIRES_IN wire add AuthModule to AppModule imports
Exported types, function signatures, env vars and wiring steps. Everything needed to call the piece correctly, and nothing else.
# summary.md, generated at capture ## Why it works this way Refresh tokens are rotated on every use and stored hashed, so a leaked token is single-use. ## Trade-offs A stateful refresh store (Redis) was accepted to gain revocation. A pure-JWT design cannot revoke.
Design decisions and trade-offs. The reasoning that usually lives only in one person's head.
// the files themselves
auth.service.ts auth.module.ts
auth.controller.ts jwt.strategy.ts
refresh-token.store.ts manifest.json
The top level is rarely needed. And the biggest saving is not on this ladder at all: not generating the code in the first place. brico add installs a verified piece for zero generation tokens and zero review of novel code.
tokens for the Vault to answer "do we have JWT auth for NestJS?"
tokens to answer the same question by scanning source files
of search vectors. Smaller than one node_modules folder.
brico mcp exposes the Vault over the Model Context Protocol. Claude, Cursor, IDE agents,
internal copilots: any MCP-capable assistant can search your pieces, read them at the right level of detail,
and recommend reuse before it writes anything new. Same engine, same index, no separate service.
search_pieces(query, kind?)Meaning and keyword search over the Vault. Returns cards.get_piece(name, level)Returns one level: card, surface, summary, or source.plan_reuse(task)Given a task, returns candidate pieces and why they fit.get_relations(name, kind?)Dependencies, dependents, replacements, similar pieces.Four tools. All of them return summaries, never raw repository scans.
The things worth keeping have grown beyond modules. A prompt with its test cases, an agent skill, a benchmark suite:
each is just a piece with a different kind. Same Vault, same commands, same MCP tools.
Files, dependencies, env vars and framework wiring steps. Captured, versioned, ready to add.
Template, input variables, target models, and the evaluation cases that prove it still works.
Instructions plus scripts, in the emerging industry format. Served over MCP, the Vault becomes a skill registry for free.
Cases, scoring criteria, harness configuration. Standalone and reusable across prompts.
URI, content hash, schema, license. Identity and provenance without the payload.
RAG and agent setups that reference other pieces by name and version.
Files in git are the source of truth.Everything that looks like a database is a projection you can delete and rebuild with brico reindex.
Each version folder holds the piece's files, its manifest, and its derived summaries. Commit it, branch it, review it, share it like any other repo.
A single database at ~/.brico/index.db, compiled into the binary. Meaning search (sqlite-vec), keyword search (FTS5), and relationship queries (plain SQL) from one file.
Postgres with pgvector for shared team Vaults. Still a projection: if it dies, it is rebuilt from the repositories.
Generating embeddings is the only step that touches a network, so it is fenced: always skippable, and
brico reindex --embed backfills later. Offline-first is a guarantee, not a footnote.
brico mcp with four toolsbrico eval harnessbrico stats token accountingbrico graph relationshipsbrico capture is the only thing a contributor does. Summaries, signatures and search vectors are derived automatically. The knowledge is attached to the code, not written about it somewhere else.brico mcp and point Claude, Cursor or your IDE agent at it. From then on, when you ask the assistant to build something, it first asks your Vault whether a piece already exists, reads a 50-token card instead of scanning your repos, and suggests brico add when there is a match.brico extract currently understands NestJS and Next.js projects and ranks reusable modules by confidence. Capture, add, search, publish and the terminal UI are shipping. MCP, prompt pieces and evals are the next two phases.Short, practical writing about reuse, token economics, and building an engineering library your AI can actually use.
One email a month. What shipped in BWX, one field note on reuse or token economics, and one piece pattern worth stealing. No noise between issues.
| Command | Status | What it does |
|---|---|---|
brico extract | working | Scans a NestJS or Next.js project and ranks reusable candidates by confidence |
brico capture | working | Snapshots a module into an immutable, semver'd piece with a manifest |
brico add | working | Resolves a version, copies files, merges env vars, prints wiring steps |
brico list / search | working | Finds any piece by name, tag, or description |
brico doctor | working | Validates engine, adapters, Vault, and project |
brico ui | working | Full-screen terminal cockpit over the Vault |
brico publish | working | Pushes the Vault or a single piece to a GitHub repo |
brico mcp | phase A | Exposes the Vault as a Model Context Protocol server |
brico eval | phase B | Runs versioned evaluation cases for prompt pieces |
brico stats | phase C | Local, opt-in token-savings accounting |
brico graph | phase C | Queries relationships: depends_on, replaces, similar_to |
The main repo is asked for once and saved to your global config. Override with
--repo, -l, or the
BRICO_PUBLISH_REPO environment variable. Pushes use your ambient git credentials.
A thin protocol layer over the same engine and index the CLI already uses.
Capture it once. Let your team and your AI assistants reuse it forever. One binary, your own git repo, nothing to sign up for.