Braid

Inspiration

After building my first project with Codex and GPT-5.6, I realized that both the agent and I needed a clearer way to understand and protect the codebase’s architecture. Code could pass tests while still becoming harder to maintain.

What it does

Braid is a local architecture guard for TypeScript projects. It analyzes dependencies, detects structural regressions, generates refactoring proposals, and checks agent changes against a healthy baseline. It can block a newly introduced dependency cycle, explain the problem, and verify that the repair restores the architecture.

How we built it

I built Braid as a TypeScript monorepo with separate components for analysis, planning, migrations, recovery, persistent state, and agent integrations. Braid uses deterministic static analysis instead of relying on an AI model to judge architecture. Codex helped me inspect the repository, implement features, reproduce failures, add tests, and prepare the release.

Challenges we ran into

The hardest part was supporting different coding-agent lifecycle systems while keeping one consistent architecture policy. I also had to make migration execution safe and recoverable. Another challenge was correctly analyzing TypeScript workspaces: installed workspace links initially caused unrelated modules with the same names to collapse and create false cycles.

Accomplishments that we're proud of

Braid now supports Codex, Gemini CLI, and local GitHub Copilot CLI. It provides a complete baseline → regression → block → repair → pass workflow, safe isolated migrations, durable recovery, verified installers, and more than 350 automated tests.

What we learned

AI agents are good at generating and repairing code, but they still need deterministic tools to define boundaries and verify results. Reliable agent tooling also requires reproducible installation, bounded retries, safe cleanup, and clear ownership of every change.

What's next for Braid

Next, I plan to add more architecture rules, improve proposal explanations, support more migration types, and test Braid on larger real-world repositories.

Built With

• codex
• gpt-5.6
• node.js
• typescript