{ "markdown": "

\n \"Braid\n

\n\n

Braid

\n\n

\n Keep architecture healthy while Codex writes code.
\n Analyze structure, generate reviewable proposals, guard coding sessions, and execute approved migrations in isolation.\n

\n\n

\n \"CI\n \"Latest\n \"MIT\n \"Node.js\n

\n\n

\n Install\n ·\n Quick start\n ·\n Growth Mode\n ·\n Demo\n ·\n Documentation\n

\n\nBraid is a local architecture guard and migration planner for growing TypeScript codebases.\n\nIt analyzes dependency structure without executing application source, turns architectural findings into deterministic and reviewable proposals, and helps prevent supported architecture regressions from being left behind during supported coding-agent sessions.\n\nWhen an approved migration is executed, Braid works inside isolated, owned Git resources. It validates the resulting diff, compares the architecture, and produces a local candidate commit for review. It never automatically merges or pushes changes.\n\n## What Braid does\n\n| Capability | Result |\n| ----------- | --------------------------------------------------------------------- |\n| **Analyze** | Build a deterministic snapshot of the current architecture |\n| **Propose** | Generate evidence-backed `break-cycle` and `extract-module` proposals |\n| **Guard** | Detect supported regressions introduced during an agent session |\n| **Migrate** | Execute explicitly approved extraction proposals in isolation |\n| **Recover** | Resume or safely clean up interrupted Braid-owned executions |\n\nBraid is designed around explicit approval, deterministic evidence, bounded automation, and reviewable outputs.\n\n## Installation\n\nInstall the latest stable release:\n\nThe current release is v0.6.0. Its native-agent workflow is:\n\n1. Install the Braid CLI once.\n2. Choose Codex, Gemini CLI, or local GitHub Copilot CLI and install its native\n Braid plugin or extension.\n3. Run `$braid:setup` in Codex or `/braid:setup` in Gemini/Copilot.\n4. Run `braid init` in the TypeScript project if it is not initialized.\n5. Review `.braid/architecture.yaml` and explicitly enable Growth Mode.\n6. Use the coding agent normally; native lifecycle hooks run Braid\n automatically.\n\nNative adapters do not download Braid, initialize a project, enable Growth\nMode, or grant host trust. The local Codex, Gemini, and Copilot package smokes\nhave passed. Remote owner/repository installation works only after the plugin\ncontent exists on the repository's default branch; release validation tests\nthose paths after merge. See the\n[native agent plugin guide](docs/native-agent-plugins.md) for exact verified\nlocal commands, host limitations, uninstall, and troubleshooting. Claude Code\nsupport is deferred and is not included in the current release. Completed\ncompatibility research is preserved for a future implementation cycle in the\n[compatibility report](docs/agent-compatibility.md).\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ting10688/Braid/main/install.sh | sh\n```\n\nThen open a new shell and verify the installation:\n\n```bash\nbraid --version\nbraid --help\n```\n\n### Requirements\n\n- Node.js 22 or newer\n- Git 2.39 or newer\n- macOS arm64, macOS x86_64, or Linux x86_64\n\nThe installer:\n\n- installs without `sudo`;\n- verifies release checksums;\n- does not require pnpm or a repository clone;\n- keeps versioned installations;\n- supports safe upgrades and explicit downgrades;\n- manages only paths recorded as Braid-owned.\n\nTo inspect the installer before running it:\n\n```bash\ncurl -fsSL \\\n https://raw.githubusercontent.com/ting10688/Braid/main/install.sh \\\n -o install-braid.sh\n\nless install-braid.sh\nsh install-braid.sh\n```\n\nSee the [installation guide](docs/installation.md) for custom directories, version pinning, PATH behavior, upgrades, downgrades, checksum verification, manual archive use, Windows instructions, and uninstalling.\n\n## Quick start\n\nRun Braid inside an existing TypeScript project:\n\n```bash\ncd path/to/your-project\n\nbraid init\nbraid analyze\nbraid propose\n```\n\nThis creates project-local configuration and state under `.braid/`.\n\n```text\n.braid/\n├── architecture.yaml\n├── state/\n│ ├── project.json\n│ ├── snapshots/\n│ └── proposals/\n└── executions/\n```\n\nThe basic workflow is:\n\n1. `braid init` creates the project configuration.\n2. `braid analyze` records a deterministic architecture snapshot.\n3. `braid propose` analyzes the latest state and creates reviewable proposals.\n\nThese commands do not rewrite application source code.\n\nFor an analysis without saving a snapshot:\n\n```bash\nbraid analyze --no-save\n```\n\nFor proposals without saving snapshots or proposal files:\n\n```bash\nbraid propose --no-save\n```\n\nFor machine-readable output:\n\n```bash\nbraid analyze --json\nbraid propose --json\n```\n\n## Typical workflow\n\n### 1. Analyze the project\n\n```bash\nbraid analyze\n```\n\nBraid scans configured TypeScript and TSX files, resolves supported relative and tsconfig-aliased imports, classifies modules, detects cycles, calculates architecture metrics, and saves a validated snapshot.\n\nExample output:\n\n```text\nBraid analysis\n\nProject: /path/to/project\nSource files: 42\nModules: 8\nInternal imports: 91\nExternal imports: 24\nCross-module imports: 17\nCircular dependencies: 1 [warning]\nOversized files: 2 [warning]\n\nSnapshot: S-...\nSaved: .braid/state/snapshots/S-....json\n```\n\n### 2. Generate proposals\n\n```bash\nbraid propose\n```\n\nLimit or filter the results when needed:\n\n```bash\nbraid propose --limit 1\nbraid propose --type extract-module\nbraid propose --type break-cycle\n```\n\nBraid currently generates:\n\n- `break-cycle` proposals for deterministic dependency-cycle root causes;\n- `extract-module` proposals for statically identified responsibility clusters.\n\nProposal generation is advisory. It does not edit source, tests, manifests, or TypeScript configuration.\n\n### 3. Inspect migration readiness\n\nChoose a proposal ID from the output:\n\n```bash\nbraid migrate plan \n```\n\nThe plan reports one of:\n\n- `ready`\n- `ready-with-warnings`\n- `not-ready`\n\nReadiness analysis includes required companion symbols, retained dependencies, external dependencies, unresolved references, predicted import direction, and cycle risks.\n\nA `not-ready` proposal is rejected before Braid creates a worktree, staging repository, branch, executor process, or candidate commit.\n\nFor an advisory repair suggestion:\n\n```bash\nbraid migrate suggest \n```\n\nSuggestions may identify a minimal addition to `approvedCompanionSymbols`, but they never modify or approve the original proposal.\n\n### 4. Execute an approved migration\n\nMigration execution is disabled by default. It must be explicitly enabled in `.braid/architecture.yaml`, including trusted validation commands.\n\nOnly supported low-risk, easy-reversibility `extract-module` proposals are currently executable.\n\n```bash\nbraid migrate run --approve \n```\n\nThe exact proposal ID must be repeated through `--approve`.\n\nA successful run:\n\n1. verifies readiness;\n2. creates Braid-owned isolated Git resources;\n3. runs the bounded Codex executor in a disposable staging repository;\n4. inspects the resulting diff independently;\n5. runs configured validation;\n6. compares the resulting architecture;\n7. creates one local candidate commit.\n\nBraid never merges or pushes the candidate.\n\nSee the [migration guide](docs/migrations.md) for configuration, approval, validation, execution records, retained patches, and cleanup.\n\n## Growth Mode\n\nGrowth Mode brings Braid into ordinary Codex, Gemini CLI, and local GitHub\nCopilot CLI coding sessions.\n\nIt captures a baseline when a session starts, evaluates architecture after relevant source changes, returns concise findings to the same session, and performs a bounded final check before the agent finishes.\n\nInstall the selected native plugin or extension, initialize the project, and\nexplicitly enable `growthMode` in `.braid/architecture.yaml`. See the\n[native agent plugin guide](docs/native-agent-plugins.md) for exact Codex,\nGemini, and Copilot installation commands and host-specific trust or restart\nrequirements.\n\nThe existing repository-local Codex adapter remains available as a manual\nfallback:\n\n```bash\nbraid growth install codex --dry-run\nbraid growth install codex --confirm\n```\n\nDo not install both Codex adapters. If both are detected, keep the native\nplugin by running:\n\n```bash\nbraid growth uninstall codex\n```\n\nOpen Codex in the repository and review the exact hook definitions with:\n\n```text\n/hooks\n```\n\nUseful Growth Mode commands:\n\n```bash\nbraid growth context\nbraid growth check --session \nbraid growth final --session \nbraid growth status --session \nbraid growth reset --session --confirm \n```\n\nTo remove only Braid-owned Codex hook handlers:\n\n```bash\nbraid growth uninstall codex\n```\n\nGrowth Mode:\n\n- compares the current working tree with the session baseline;\n- reports newly introduced supported regressions;\n- separates pre-existing findings from session changes;\n- uses bounded final-stop behavior;\n- caches unchanged states;\n- does not edit source;\n- does not invoke migration execution;\n- does not create commits, branches, or worktrees.\n\nThe v0.6.0 production host scope is Codex, Gemini CLI, and local GitHub Copilot\nCLI. Copilot cloud-agent support is not claimed. Claude Code production support\nis deferred.\n\nSee the [Growth Mode guide](docs/growth-mode.md) for lifecycle behavior, hook ownership, finite blocking, caching, configuration, and limitations.\n\n## Safety model\n\nBraid separates analysis, approval, execution, and integration.\n\n### Analysis and proposals\n\n`analyze`, `propose`, and proposal-repair suggestions never modify application source.\n\n### Explicit execution approval\n\nMigration execution requires:\n\n- migration support enabled in project configuration;\n- a supported proposal type;\n- acceptable risk and reversibility;\n- passing readiness checks;\n- the exact proposal ID repeated through `--approve`;\n- configured validation commands.\n\n### Isolated execution\n\nThe main checkout is not used as the executor workspace.\n\nBraid uses:\n\n- an owned external Git worktree;\n- a disposable remote-free staging repository;\n- a bounded Codex process;\n- independent patch and scope inspection;\n- validation and architecture gates;\n- a local candidate branch and commit.\n\n### No automatic integration\n\nBraid does not automatically:\n\n- merge;\n- push;\n- open a pull request;\n- rewrite the main checkout;\n- execute `break-cycle` proposals;\n- roll back existing architectural drift.\n\n### Trusted local boundary\n\nBraid validates ownership, paths, diffs, refs, configured commands, and supported process behavior, but it is not an operating-system security sandbox.\n\nValidation commands and their transitively executed scripts are trusted local code.\n\n## Core capabilities\n\n### Static architecture analysis\n\nBraid currently analyzes configured TypeScript and TSX files.\n\nIt supports:\n\n- static `import` declarations;\n- static `export ... from` declarations;\n- relative imports;\n- supported tsconfig aliases;\n- module classification;\n- public entrypoint detection;\n- cross-module dependency analysis;\n- strongly connected dependency components;\n- file and module size metrics;\n- deterministic JSON snapshots.\n\nApplication source is parsed but not executed.\n\n### Deterministic proposals\n\nBraid produces evidence-backed proposals with:\n\n- stable identities;\n- risk and reversibility classifications;\n- expected architecture impact;\n- source evidence;\n- one ranked primary cycle action;\n- typed alternatives where applicable;\n- deterministic ordering.\n\n### Execution readiness\n\nBefore launching an executor, Braid evaluates symbol dependency closure and predicts whether an extraction can be performed without introducing prohibited reverse dependencies or cycles.\n\nIncomplete proposals fail before execution resources are created.\n\n### Advisory proposal repair\n\nFor supported `not-ready` extraction proposals, Braid can suggest the smallest bounded addition to `approvedCompanionSymbols`.\n\nSuggestions are:\n\n- additive only;\n- deterministic;\n- advisory;\n- never automatically persisted;\n- never treated as approval.\n\n### Durable recovery\n\nBraid records immutable, integrity-checked migration checkpoints.\n\nAfter interruption, a fresh process can classify an execution as:\n\n- `resumable`\n- `cleanup-required`\n- `already-complete`\n- `unsafe-to-resume`\n- `manual-inspection-required`\n\nInspect recovery state:\n\n```bash\nbraid migrate recover\nbraid migrate recover \n```\n\nResume verified work:\n\n```bash\nbraid migrate resume --confirm \n```\n\nClean up only verified Braid-owned resources:\n\n```bash\nbraid migrate cleanup --confirm \n```\n\nDurable recovery does not guess ambiguous executor state and does not relaunch completed executor work.\n\nSee the [durable recovery protocol](docs/durable-migration-recovery.md).\n\n## CLI reference\n\n| Command | Purpose |\n| ------------------------------ | -------------------------------------------------------- |\n| `braid init` | Create project-local configuration and state |\n| `braid analyze` | Create a deterministic architecture snapshot |\n| `braid propose` | Generate deterministic migration proposals |\n| `braid migrate plan` | Evaluate migration readiness without creating a worktree |\n| `braid migrate suggest` | Generate an advisory repair suggestion |\n| `braid migrate run` | Execute an explicitly approved migration in isolation |\n| `braid migrate list` | List migration execution records |\n| `braid migrate status` | Show one execution status |\n| `braid migrate inspect` | Show the portable plan and execution record |\n| `braid migrate diff` | Show a retained candidate patch |\n| `braid migrate recover` | Inspect durable recovery state |\n| `braid migrate resume` | Resume a verified interrupted execution |\n| `braid migrate cleanup` | Remove verified Braid-owned recovery resources |\n| `braid migrate discard` | Remove an execution-owned worktree and branch |\n| `braid growth context` | Initialize or show session architecture guidance |\n| `braid growth check` | Evaluate changes relative to a session baseline |\n| `braid growth final` | Apply the bounded final-session policy |\n| `braid growth status` | Show session and adapter status |\n| `braid growth reset` | Reset Braid-owned state for one session |\n| `braid growth install codex` | Install the repository-local Codex adapter |\n| `braid growth uninstall codex` | Remove only Braid-owned Codex handlers |\n\nRun the built-in help for complete options:\n\n```bash\nbraid --help\nbraid migrate --help\nbraid growth --help\n```\n\n
\nAdvanced command examples\n\n### Initialization\n\n```bash\nbraid init\nbraid init path/to/project\nbraid init --force\n```\n\n### Analysis\n\n```bash\nbraid analyze\nbraid analyze --json\nbraid analyze --no-save\n```\n\n### Proposals\n\n```bash\nbraid propose\nbraid propose --json\nbraid propose --no-save\nbraid propose --limit 1\nbraid propose --type extract-module\nbraid propose --type break-cycle\nbraid propose --snapshot \n```\n\n### Migration lifecycle\n\n```bash\nbraid migrate plan \nbraid migrate suggest \nbraid migrate run --approve \n\nbraid migrate list\nbraid migrate status \nbraid migrate inspect \nbraid migrate diff \n\nbraid migrate recover \nbraid migrate resume --confirm \nbraid migrate cleanup --confirm \nbraid migrate discard --confirm \n```\n\n### Growth Mode\n\n```bash\nbraid growth install codex --dry-run\nbraid growth install codex --confirm\n\nbraid growth context\nbraid growth check --session \nbraid growth final --session \nbraid growth status --session \nbraid growth reset --session --confirm \n\nbraid growth uninstall codex\n```\n\n
\n\n## Demo\n\nA deterministic Growth Mode demo is included in every stable standalone distribution.\n\nDownload and extract the `braid-v-demo-node22` archive from GitHub Releases, then run:\n\n```bash\n./braid-demo\n```\n\nThe demo:\n\n1. creates a disposable healthy TypeScript repository;\n2. captures a Growth Mode baseline;\n3. verifies an initial pass;\n4. introduces a labeled dependency cycle;\n5. runs the real bundled Growth Mode implementation;\n6. reports a block;\n7. applies a labeled repair;\n8. reports a final pass;\n9. verifies that Braid made no source or Git mutation;\n10. cleans up automatically.\n\nThe deterministic path requires no OpenAI account, Codex login, pnpm installation, source build, or network connection after extraction.\n\nCross-platform entrypoint:\n\n```bash\nnode ./demo/run-demo.mjs\n```\n\nSee the [demo guide](demo/growth-mode-live-guard/README.md) for expected output, retained temporary state with `--keep`, and the optional live-Codex walkthrough.\n\n## Other installation methods\n\n### Prebuilt CLI archive\n\nThe stable release archive contains the standalone CLI:\n\n```bash\n./bin/braid --version\n./bin/braid --help\n```\n\nOn Windows:\n\n```bat\nbin\\braid.cmd --help\n```\n\nCross-platform Node entrypoint:\n\n```bash\nnode ./bin/braid.mjs --help\n```\n\nThe standalone CLI does not require pnpm, `node_modules`, workspace packages, or a source checkout.\n\n### Development from source\n\nUse the package-manager version pinned by the repository:\n\n```bash\ngit clone https://github.com/ting10688/Braid.git\ncd Braid\n\ncorepack enable\npnpm install --frozen-lockfile\npnpm build\npnpm braid --help\n```\n\nAn optional contributor-only global link can be created after building:\n\n```bash\npnpm --filter @braid/cli link --global\n```\n\nSource development is separate from the supported standalone end-user installation channel.\n\n## Documentation\n\n- [Installation](docs/installation.md)\n- [Architecture](docs/architecture.md)\n- [Proposal behavior](docs/proposals.md)\n- [Safe migration execution](docs/migrations.md)\n- [Durable migration recovery](docs/durable-migration-recovery.md)\n- [Growth Mode](docs/growth-mode.md)\n- [Benchmark methodology](docs/benchmarking.md)\n- [Metric definitions](docs/metrics.md)\n- [Roadmap](docs/roadmap.md)\n\n## Current scope and limitations\n\n- Only TypeScript and TSX source is currently supported.\n- Import analysis models static imports and static re-exports, not dynamic runtime resolution.\n- Module classification is based on paths, package entrypoints, and static statement shape.\n- Symbol clustering uses identifiers and static references rather than semantic runtime behavior.\n- Metrics provide evidence, not a universal architecture quality score.\n- Extraction impact remains partly estimated because all downstream caller rewrites are not simulated during proposal generation.\n- Migration execution supports only eligible `extract-module` proposals.\n- `break-cycle` proposals are advisory and cannot currently be executed.\n- Repair suggestions support only additive `approvedCompanionSymbols` changes.\n- Validation dependencies must already be available in the isolated worktree.\n- Candidate branches and commits remain local review artifacts.\n- Durable recovery is local and single-host.\n- Growth Mode detects supported static regressions relative to a session baseline.\n- Growth Mode does not prove that code is correct or secure.\n- Braid is not an adversarial security boundary.\n\nThe project deliberately refuses unsupported or ambiguous operations instead of guessing.\n\n## Development\n\nCommon contributor commands:\n\n```bash\npnpm build\npnpm typecheck\npnpm lint\npnpm test\npnpm format\npnpm braid --help\n```\n\nUseful example and benchmark commands:\n\n```bash\npnpm analyze:example\npnpm propose:example\n\npnpm benchmark:smoke\npnpm benchmark:regression\npnpm benchmark:real:regression\npnpm benchmark:migration:regression\npnpm benchmark:readiness\npnpm benchmark:repair-suggestions\npnpm benchmark:growth-mode\npnpm benchmark:recovery\n```\n\nBraid Bench freezes protocol, suite, expectation, fixture, configuration, repetition, and timeout inputs before comparing executables. It records immutable manifests and separates correctness, stability, and cost evidence.\n\nSee the [benchmark methodology](docs/benchmarking.md).\n\n## Repository guide\n\n| Path | Responsibility |\n| ----------------------- | -------------------------------------------------------------------------------- |\n| `apps/cli` | CLI commands and human/JSON presentation |\n| `packages/core` | Domain schemas and validated architecture configuration |\n| `packages/analyzer` | TypeScript scanning, dependency graphs, classification, and metrics |\n| `packages/planner` | Deterministic candidate generation, identity, classification, and ranking |\n| `packages/migrator` | Readiness, isolated execution, validation, candidate commits, and recovery |\n| `packages/guard` | Session baselines, architecture comparison, bounded feedback, and agent adapters |\n| `packages/store` | Atomic snapshots, proposals, execution records, and recovery journals |\n| `packages/benchmark` | Isolated fixtures, comparisons, baselines, and regression reports |\n| `packages/shared` | Shared errors and project-local path constants |\n| `benchmarks` | Versioned synthetic and pinned real-world benchmark suites |\n| `examples/bloated-saas` | Deterministic integration fixture and example application |\n\n## Status\n\nBraid v0.6.0 adds native Growth Mode integrations for Codex, Gemini CLI, and local GitHub Copilot CLI\nwhile preserving the manual Codex fallback and verified standalone distribution. Claude Code\nproduction support is deferred. Authenticated package-level live-agent smoke has not been performed.\nRecovery journals use schema version `1.0.0`; Growth reports and their adapter protocol remain at\n`1.0.0`, while snapshot, proposal, execution-plan, and execution-record schemas remain version 1.\n\n## License\n\nBraid is available under the [MIT License](LICENSE).\n\n## Built with Codex and GPT-5.6-Sol during OpenAI Build Week\n\nBraid began as an early architecture-analysis project. After building my first\nproject with Codex and GPT-5.6-Sol, I realized that both the agent and I needed\na clearer way to understand and protect a growing codebase's architecture.\n\nDuring OpenAI Build Week, Braid was extended into a release-ready architecture\nguard, migration system, and coding-agent integration platform.\n\n### How Codex was used\n\nCodex handled repository-level engineering work, including:\n\n- repository analysis and implementation;\n- test generation and regression coverage;\n- failure reproduction and debugging;\n- agent compatibility research;\n- workflow and release auditing;\n- installer, distribution, and release qualification.\n\nCodex was also used to test Braid on real TypeScript projects, including\nidentifying and repairing a dependency cycle in a four-workspace project.\n\n### How GPT-5.6-Sol was used\n\nGPT-5.6-Sol supported the higher-level reasoning and supervision work,\nincluding:\n\n- defining the product direction and scope;\n- designing the architecture and safety boundaries;\n- decomposing large tasks into precise Codex instructions;\n- reviewing implementation and validation results;\n- identifying missing edge cases and test requirements;\n- planning the demo, documentation, and release strategy.\n\nCodex focused on repository execution, while GPT-5.6-Sol helped direct,\nevaluate, and refine that work.\n\n### What was added during Build Week\n\n- Native Growth Mode integrations for Codex, Gemini CLI, and GitHub Copilot CLI\n- Host-neutral lifecycle adapter runtime\n- Bounded block, retry, repair, and pass behavior\n- Linked-worktree and duplicate-adapter handling\n- Durable migration recovery and interrupted-process cleanup\n- Workspace-aware module identity and import resolution\n- Public installer, release artifacts, checksums, and standalone demo\n- Multi-platform CI, installer validation, and release gates\n\n### Human responsibility\n\nI retained responsibility for product decisions, architecture, safety\nboundaries, validation requirements, compatibility claims, and release\napproval.\n\nThe repository history, merged pull requests, automated tests, and public\nrelease artifacts document the work completed during the submission period.\n", "bytes": 26117, "sha": "e0a79a72e3e3421bf0ce3d95a7da8157e633634a4fa9b4e79f0251002570b44b", "repo_slug": "ting10688/braid", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_ting10688_braid_a9270098/readme" }