Content
# Loom
> **Composition-over-Generation**: Instead of writing code from scratch, pick and assemble pre-existing components from a controlled library to create a new project - do it right the first time, minimize new code, and save AI output tokens.
> In one sentence: **They generate, Loom assembles.**
## What is Loom?
Loom is a code assembly system that helps you start a project from scratch. Give Loom an idea (e.g., "a backend with Google login, project management, and export capabilities"), and Loom:
1. Breaks down the idea into functional seams (auth / CRUD / tables / export, etc.)
2. **Retrieves** the best matching pre-existing components for each seam from a candidate library
3. Uses AI for **selection** (pick / adapt / generate), not line-by-line coding → minimal output
4. **Deterministically materializes**: assembles, injects environment, creates data tables, type checks, and bounded repairs
5. Produces a high-quality starter (create-t3-app tech stack) that can be compiled and run
Core bet: **Selection is cheaper than generation**. AI output (the most expensive part) is only used for "which one to choose," not for line-by-line writing.
Actual test (4 ideas, deepseek-chat, both arms tested to convergence or loss):
**From scratch generation: 0/4 converged to compilable code (all got stuck with errors), Loom assembly: 4/4 clean convergence**, with 1/18 output tokens used.
## Current Status (Honest Version)
Core links **M1–M5 each have real implementation + offline testing** (no external services, reproducible):
| Mechanism | Verification |
|---|---|
| Selection → materialization → repair (deterministic, client-side zero LLM) | M1 end-to-end convergence |
| Loss gate + 2×2 attribution | M2: 3 ideas × {assembly / from scratch / oracle} |
| True vector retrieval (local fastembed) | M3: recall@1 = 100% |
| Automatic ingestion expansion (tree-sitter) | M4: WRITE_OWN degradation rate 25% → 0% |
| Flywheel health loop | M5: reuse → health improvement → ranking boost |
| **Candidate pool density verification (two-arm control)** | **2 seam dense灌后 h\* = 0.058: assembly convergence vs from scratch non-convergence** |
**End-to-end real test**: Run "idea → AI selection → client assembly → 0-error starter" with deepseek.
### Test Data (Honest Version)
Complete method and data see [`docs/benchmark.md`](./docs/benchmark.md). Summary (4 ideas, deepseek-chat, both arms tested to maxRounds=8 convergence or thrash loss):
| | Assembly (pick pre-existing) | From Scratch (AI generation) |
|---|---|---|
| Convergence (repaired to 0-error) | **4/4** | **0/4** (all stopped with 2-13 errors) |
| Repair rounds | 0 | 2-5 rounds then got stuck |
| Output token total | **1401** | 25277 (wasted, didn't work) |
- **Core conclusion is not "save X%"**: Alone with deepseek from scratch, 4 ideas 0 converged to compilable code (got stuck with errors); Loom assembly 4/4 clean convergence. **From scratch can't produce compilable projects, assembly can.**
- Output token: assembly is **1/18** of from scratch - but this underestimates the gap because 25277 tokens from scratch bought 4 uncompilable half-finished products.
**Honest boundary**:
- **Single model deepseek-chat**. Swapping to stronger models (claude/gpt) from scratch arm convergence rate will improve - 0/4 is deepseek's upper limit, not entirely "from scratch" paradigm's fault. Stronger models, Loom's relative advantage smaller.
- **"Convergence" = tsc 0-error, not next build / real run**; OAuth placeholder needs self-filling, not functional completeness.
- Small sample (4 ideas / single domain / each 1 time), magnitude reference not rigorous benchmark.
- Old README's "save 91%" is maxRounds=3, from scratch not fully repaired caliber, replaced by benchmark.md.
## How to Use
### Method 1: Zero Installation, Connect to Remote Service (Recommended)
No installation needed. In Claude Code / Cursor and other MCP-supported agents, add a remote MCP server:
```jsonc
// .mcp.json (Claude Code) or corresponding configuration
{
"mcpServers": {
"loom": { "type": "http", "url": "https://loom.alhz.org/mcp" }
}
}
```
Or use command line registration (easier, less prone to errors):
```bash
claude mcp add --transport http loom https://loom.alhz.org/mcp
```
Then directly tell the agent your idea, e.g., "Use loom to build a backend with Google login, project management, tables, and forms." The agent will:
1. Call `loom_propose` → each capability seam returns 2-3 candidates + architecture trade-offs
2. You (or agent) choose one by one → `loom_plan_from_choices` assemble into a plan
3. `loom_get_files` → return complete project file list (including `app/dashboard/page.tsx` with components connected)
4. Agent writes files to local → `pnpm install` → fill `.env` with real keys → `pnpm dev`
Server only does retrieval + assembly (zero LLM, zero keys, doesn't run your code), AI "selection" only costs a few dozen tokens,
code returned by server is ready-made - this is where token saving comes from.
> Boundary: product "can compile and start" ≠ functional completeness. OAuth needs real credentials; server uses lightweight bag-of-words retrieval (speed priority),
> candidate pool covers SaaS backend / blog-like ideas (39 candidates / 10 seams / 2 domains).
### Method 2: Local Fully Automatic (Requires Environment + Keys)
See [`INSTALL.md`](./INSTALL.md). After setting up Node/pnpm/Python/uv:
```bash
LOOM_LLM_PROVIDER=deepseek LOOM_LLM_API_KEY=sk-... \
bash loom_assemble.sh ideas/<your-idea>.json <output-dir>
```
Or use [`.claude/skills/loom`](./.claude/skills/loom/SKILL.md) skill trigger in Claude Code.
## Structure
- `platform/` — Python side: selection engine (`run_select.py`), retrieval (`retrieve.py` + `embedding.py`), ingestion (`ingest.py`), flywheel (`flywheel.py`), contracts (`loom_contracts.py`), evaluation (`eval_*.py` / `verify_candidates.py`)
- `client/` — TS side: deterministic materialization (`materialize.ts`), gate (`gate.ts`), bounded repair (`repair.ts`), environment injection (`injectEnv.ts`)
- `core/` — frozen create-t3-app baseline + `loom.core.json` seam definitions
- `candidates/` — candidate library (manual curation + automatic ingestion)
- `ideas/` — idea definitions + oracle optimal plans
- `docs/` — architecture, implementation plan, complete progress (`HANDOFF.md`)
## Verification (No Gateway, Reproducible)
```bash
cd platform
uv run python eval_retrieval.py # retrieval recall
uv run python eval_writeown.py # pool growth → WRITE_OWN decrease
uv run python eval_flywheel.py # flywheel health loop
uv run python verify_candidates.py # candidate t3 gate quality gate
```
## License
MIT
