chemx

v26.9.21-227

Published

8 minutes ago

Chemical X Protocol: Private drop-in architecture starter kit and capsule generator

0High
0Medium
0Low

Chemical X Protocol: Starter Kit

Modular architecture blueprints, production hooks, and drop-in crystalline component capsule generators for high-velocity AI coding.

Live Interactive Portal

Access the interactive book, prompt generator, and asset vault at https://chemicalx.xophz.com.

Quickstart: Scaffolding a New Project

Create a brand new molecular architecture project in seconds using your preferred package manager:

# npm (interactive or pass project directory)
npm create chemx my-molecular-app

# Automated / Agent / Headless mode (skips prompts, scaffolds Community Edition immediately)
npm create chemx my-molecular-app -- --yes

# npx
npx create-chemx my-molecular-app --yes

# pnpm / yarn / bun
pnpm create chemx my-molecular-app
yarn create chemx my-molecular-app
bun create chemx my-molecular-app

Headless & Autonomous Agent Mode

When running in unattended environments (CI/CD pipelines, Cursor Agent, Windsurf, Claude Code, Antigravity), pass --yes (or -y, --ci, --headless) to bypass interactive terminal menus and immediately scaffold the free Community Edition with recommended architectural pillars:

npx create-chemx my-molecular-app --yes

Package Architecture: Scaffolder vs Command Engine

Chemical X provides two coordinated packages:

create-chemx: Dedicated zero-dependency project scaffolder (npm create chemx). Directly provisions project templates, test suites, and architectural configurations.
chemx: The full Molecular Architecture CLI & AST Query Engine. Manages audits, verifications, AST query lookups, code patching, and multi-agent swarm task coordination.

# Install chemx CLI globally or in your project:
npm install -g chemx
# or run on-demand:
npx chemx --help

Structure

starter-kit/
├── blueprints/
│   ├── view-template.tsx       # < 20 line Table-of-Contents view blueprint
│   ├── molecule-capsule/       # Isolated crystalline molecule blueprint
│   └── composable-template.ts  # Standardized 3-to-5 return state composable
├── hooks/
│   ├── useAsyncData.ts         # 3-state async pipeline with toResult
│   ├── useSelfCleaningTimer.ts # Unmount-safe timer and RAF hook
│   └── useTwoStageDecision.ts  # Concept to Decision composition
└── cli/
    ├── index.js                # CLI router & capsule generator
    ├── verify.js               # Zero-token-burn verification engine
    ├── audit.js                # 7-Pillar static AST audit
    └── mcp/                    # Model Context Protocol stdio server

Zero-Token-Burn Verification Pipeline

Running raw, unthrottled npm test, tsc --noEmit, or build tools dumps thousands of lines of passing checkmarks, compiler noise, and bundle asset tables into an AI agent's context window. This burns tokens prematurely and degrades context quality.

Chemical X wraps tests, typechecks, and builds into silent, failure-focused verification tools available via CLI and native MCP tools:

Side-by-Side Benchmark Reports

1. Test Suite: `npm test` vs `chemx test`

Ran across the starter-kit test suite (143 test cases across 8 spec suites):

# Raw npm test: Floods context with ~13,000 tokens of passing checkmarks
✔ resolveTargetDir: returns custom directory if provided as first argument (1.64ms)
✔ search-db: indexes symbols with line ranges and finds definition (56.65ms)
✔ Verify: parseTestOutput strips passing checkmarks and extracts only failing tests (1.01ms)
... [940 MORE LINES OF PASSING CHECKMARKS & TIMINGS] ...
ℹ tests 143 | pass 143 | fail 0 | duration_ms 3002.57ms

# Chemical X: Pinpoint single-line summary
$ npx chemx test
  ✔ All tests passed (143 tests in 3500ms)

2. TypeScript Typecheck: `npm run typecheck` vs `chemx typecheck`

# Clean, banner-free terminal verification
$ npx chemx typecheck
  ✔ TypeScript typecheck clean (1820ms)

# Machine-readable output for AI agents
$ npx chemx typecheck --json
{
  "success": true,
  "exitCode": 0,
  "command": "npm run typecheck",
  "durationMs": 1820,
  "errorCount": 0,
  "errors": []
}

3. Production Build: Raw Build vs `chemx build`

$ npx chemx build
Auditing build: npx tsc --noEmit
✔ Build Succeeded (5.20s)

4. Full Pipeline: `chemx verify` Grand Total

When an AI agent runs a complete pre-commit or post-refactor verification pass:

$ npx chemx verify --dir=blueprints

  ⚡ Chemical X: Token-Conserving Project Verification

  ✔ AST Architecture:  A+ (100/100, 0 violations)
  ✔ TypeScript:        Clean (0 errors)
  ✔ Test Suite:        Passed (143/143)

  All verification checks passed with zero context burn!

CLI Command Reference & Workflow

The chemx command suite is specifically tailored for token conservation, instant feedback, and zero terminal clutter:

1. Verification & Quality

# Full verification pipeline (AST Audit + Typecheck + Tests) -> ~45 token status card
chemx verify
chemx verify --json

# Run 7-Pillar static AST audit
chemx audit
chemx audit --unroll        # Inspect individual hazard lines and explanations
chemx audit --strict        # Fail on any violation, including minor style warnings
chemx audit --json          # Machine-readable format for agent pipelines

# Silent TypeScript compilation check (suppresses passing noise, returns error lines)
chemx typecheck
chemx typecheck --json

# Silent test runner (suppresses passing tests, extracts only failing assertions & stack diffs)
chemx test
chemx test --json

# Silent build audit (categorizes diagnostics into TypeScript, Rollup, and style budgets)
chemx build
chemx build --json

2. AST Query Engine & Surgical Inspection

# Hybrid search (BM25 keyword + cosine vector similarity via Reciprocal Rank Fusion)
chemx q "useAttentionCardController" --hybrid --json

# Transitive blast radius analysis before refactoring foundational capsules
chemx q "a-button" --blast-radius --json

# Inspect component props, hooks, and types without reading entire files
chemx q "m-task-list" --inspect

# Surgical token-optimized file reader (AST outlines, stripped comments, specific symbols)
chemx read src/components/m-card.vue --symbol=useCardController
chemx read src/components/m-card.vue --outline
chemx read src/components/m-card.vue --start=10 --end=40

# Surgical file patching without full-file rewrites
chemx patch <file> --target="oldCode" --replacement="newCode"

3. Crystalline Capsule Generator

Scaffold production-ready component capsules matching strict zero-raw-DOM standards:

# Molecule capsule (component, controller, glass styling, types, spec)
chemx m-task-card

# Atom foundation (the only tier permitted raw HTML elements)
chemx a-status-pill

# Organism module (complex grouping of molecules and atoms)
chemx o-workspace-header

# Pure reactive hook / domain composable
chemx use-task-filter

4. Database-Driven Multi-Agent Swarm Coordination

Coordinate multi-agent swarms using the local SQLite store (.chemx/index.db) without multi-thousand-token markdown specification bloat:

# Auto-triage: convert AST audit hazards directly into assignable team tasks
chemx team task triage

# List tasks assigned to a specific agent
chemx team task list --agent=@agent-alpha

# Claim an open task
chemx team task claim 1 --as=@agent-alpha

# Mark task complete (automatically re-audits target file on disk to guarantee zero hazards)
chemx team task done 1 --as=@agent-alpha

# Inspect multi-agent swarm status and lock queues
chemx team status

The 7 Molecular Architecture Pillars

Chemical X enforces seven core architectural directives configured via chemx pillars:

Strict Molecular Line Budgets (< 100 Lines): Single-purpose files. Approaching 100 lines is a decomposition trigger. Eliminates context rot and cuts token ingestion costs.
Strict Component Tiers & Zero-Raw-DOM: Raw HTML elements (<button>, <input>, <div>) are strictly isolated inside foundational Atoms (a-*). Molecules, Organisms, Templates, and Views assemble atoms and never contain raw tags.
Table-of-Contents Views: Top-level page views are clean, 10–20 line declarative blueprints assembling self-contained molecules and organisms via named slots (#header, #default, #modals).
Molecular Composable Contracts: Composables return plain destructurable objects with a strict 3-to-5 property limit (State + Status + Actions). Domain types use discriminated unions (zero impossible states).
Silent Verification Pipeline: Verification tools suppress passing checkmarks and compiler banners, returning token-compact summaries (~45 tokens) to protect AI agent context windows.
AST Codebase Query Engine: In-band AST symbol graph lookups, blast radius calculations, and outline extraction eliminate blind full-file context dumps.
Database-First Swarm Coordination: Task backlogs, file locks, and agent communications live in local SQLite (.chemx/index.db) rather than monolithic markdown specifications.

Model Context Protocol (MCP) Server

Chemical X includes a high-performance, zero-dependency JSON-RPC 2.0 Stdio MCP server that connects directly to AI agent hosts (Cursor, Claude Desktop, Windsurf, Antigravity, VS Code).

Automatic 1-Step Installation

Run the interactive installer in your workspace root:

npx chemx install-mcp

This automatically registers the Chemical X server in:

.cursor/mcp.json (Cursor IDE)
.vscode/mcp.json (VS Code)
~/.gemini/config/mcp_config.json (Antigravity)
Injects chemx:mcp, chemx:verify, chemx:test, and chemx:typecheck into your package.json scripts

Manual MCP Server Configuration

To configure manually in your MCP client settings (e.g. claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "chemical-x": {
      "command": "npx",
      "args": ["-y", "chemx", "mcp"]
    }
  }
}

Available MCP Tools (14 Tools)

Living Resources & Prompts

Resources:
- chemx://directives: Mandatory Chemical X Molecular Architecture directives (AGENTS.md).
- chemx://scorecard: Live Molecular Health Index (MHI) grade, score, metrics, and active hazards.
- chemx://blueprints/molecule: Compliant molecule blueprint adhering to zero raw DOM standards.
- chemx://blueprints/view-template: Declarative 10-20 line Table-of-Contents view blueprint.
Prompts:
- chemx_remediate_hotspot: Dynamically inspects candidate file AST metrics and generates targeted decomposition instructions.
- chemx_harmonize_patterns: Generates Pre-Split Pattern Discovery instructions to extract shared capsules.

Release Versioning: Minute-Precision CalVer

This package adheres to Minute-Precision Calendar Versioning (YY.MM.DD-MMMM):

YY.MM.DD: Release date (e.g. 26.9.17 for Sept 17, 2026).
MMMM: Minute of the day (0 to 1439).

Check installed version at any time:

npx chemx --version
# create-chemx v26.9.17-606

Package Pairing & npm Registry Propagation

Package Pairing: @chemx/create-chemx and chemx publish together under synchronized minute-precision CalVer timestamps (YY.M.D-minute). For consistent behavior, install or pin the matching release versions.
npm Registry Propagation Note: Newly published releases on npm can take 2–5 minutes to propagate across all edge CDN mirrors after npm view lists them. If npm install intermittently fails with a 404 on an exact newly published version, wait a few minutes and retry.

Because autonomous coding agent models update frequently, this package is continuously integrated and deployed via automated CI whenever new agent directives, AST checks, or framework rules are tuned. Rapid version iterations reflect active, daily alignment rather than breaking SemVer shifts.

[!NOTE] Download statistics on npm reflect continuous automated test matrix verification and test runner execution across automated environments.

License

Core CLI tools and capsule generators are distributed under the MIT License.
Private production monorepos and extended starter suites are unlocked for verified GitHub Sponsors.
Explore sponsorship details at https://chemicalx.xophz.com.