DEV Community

Cover image for Built a Framework for AI Coding Assistants in Multi-Repo Projects (and You Can Use It)
@kiwibreaksme
@kiwibreaksme

Posted on

Built a Framework for AI Coding Assistants in Multi-Repo Projects (and You Can Use It)

#webdev #programming #opensource #ai

🤖 The Problem: AI Assistants Lose Context in Multi-Repo Projects

If you've been using AI coding assistants like Claude Code or Cursor, you've probably experienced this:

"Can you update the user authentication flow?"

AI starts modifying code...

"Wait, stop! You need to update the backend API first, then the mobile client, and the frontend uses a different pattern!"

Sound familiar? 😅

Here's why this happens:

  • 🔄 Lost context - Every new chat session means re-explaining your architecture
  • 🧩 Fragmented knowledge - AI only sees one repository at a time
  • ⚠️ Dangerous assumptions - AI guesses at critical business logic instead of asking

After dealing with this for months on a project with 3+ repositories, I decided to solve it.

Today, I'm open-sourcing the solution: https://github.com/bitjaru/codesyncer

💡 The Core Insight

AI assistants work exponentially better when they have:

  1. ✅ Structured documentation instead of just raw code
  2. ✅ Explicit decision records instead of inferring intent
  3. ✅ Safety guardrails for critical operations

Think of it like the difference between:

  • ❌ Throwing a junior dev into a codebase with zero onboarding
  • ✅ Giving them architecture docs, decision logs, and a senior dev to check risky changes

CodeSyncer does exactly this for AI.

🚀 How CodeSyncer Works

Step 1: Auto-Generate AI-Readable Documentation

npm install -g codesyncer
cd your-project
codesyncer init

CodeSyncer scans your repository and generates:

| Document | Purpose |
|------------------------|--------------------------------------------------------|
| 📐 Architecture Guide | System overview, service boundaries, data flow |
| 📋 Decision Log | Why you chose X over Y, technical trade-offs |
| 🔌 API Conventions | Endpoint patterns, auth flow, error handling |
| 🔒 Security Guidelines | Critical paths, validation rules, sensitive operations |

The magic? These docs are structured specifically for AI consumption, not just humans.

Step 2: Record Decisions in Code

Use structured comment tags to make your decisions permanent:

// @codesyncer-rule: Always validate user input before database queries
// Reason: We had a SQL injection incident in 2023

export async function createUser(input: UserInput) {
// @codesyncer-decision: Using bcrypt for password hashing (not argon2)
// Reason: Team familiarity + sufficient security for our threat model

const validated = validateUserInput(input);
const hashedPassword = await bcrypt.hash(validated.password, 10);

return db.users.create({
  email: validated.email,
  password: hashedPassword
});
Enter fullscreen mode Exit fullscreen mode

}

When AI works on this code, it reads these tags and respects your decisions. No more:

"I've refactored your auth to use plain MD5 hashing for better performance! 🎉"

😱

Step 3: Auto-Pause for Safety

Configure keywords that should always require human review:

{
"criticalKeywords": [
"payment",
"stripe",
"delete",
"DROP TABLE",
"admin",
"auth",
"password"
]
}

When AI tries to modify code containing these keywords, CodeSyncer:

  1. ⏸️ Pauses the AI
  2. 🔍 Highlights the risky operation
  3. 👤 Asks you to review and confirm

// AI wants to make this change:

  • await stripe.charges.create({ amount: 1000 })
  • await stripe.charges.create({ amount: total * 100 })

⚠️ CODESYNCER PAUSE: This code involves "payment" and "stripe"
❓ Review this change before proceeding? (y/n)

📊 Real-World Impact

After using CodeSyncer internally for 3 months:

| Metric | Improvement |
|----------------------------------|-------------|
| Repeated explanations to AI | -80% |
| Risky AI assumptions | -95% |
| Time to onboard AI to new repos | -70% |
| Incidents from AI-generated code | 0 (was 3) |

🎯 Real Usage Example

Before CodeSyncer:

You: "Add a new endpoint to get user orders"
AI: creates endpoint
You: "Wait, did you add authentication?"
AI: "Let me add that..."
You: "Also we need to filter by user ID"
AI: "Updating..."
You: "And we need to join with the products table"
AI: "One moment..."
You: "Ugh, and don't forget rate limiting"

After CodeSyncer:

You: "Add a new endpoint to get user orders"
AI: reads ARCHITECTURE.md and DECISIONS.md
AI: creates endpoint with:
✅ JWT authentication (per SECURITY.md)
✅ User ID filtering (per API_CONVENTIONS.md)
✅ Product joins (per ARCHITECTURE.md)
✅ Rate limiting (per DECISIONS.md entry #47)
You: "Perfect! 🎉"

🛠️ Quick Start Guide

Installation

npm install -g codesyncer

Initialize Your Project

cd /path/to/your/backend
codesyncer init

This will:

  1. 🔍 Scan your project structure
  2. 🎯 Detect your tech stack (React, Node.js, Django, etc.)
  3. 📝 Generate initial documentation
  4. ⚙️ Create a .codesyncer/ directory with configuration

Tell Your AI Assistant

"Hi Claude, please read all the files in .codesyncer/ to understand this project"

That's it! Now your AI has full context. 🚀

🗺️ Multi-Repo Setup

For projects with multiple repositories:

# Backend
cd ~/projects/my-app-backend
codesyncer init

# Frontend

cd ~/projects/my-app-frontend
codesyncer init --link ../my-app-backend

# Mobile
cd ~/projects/my-app-mobile
codesyncer init --link ../my-app-backend --link ../my-app-frontend

Now AI understands the entire system architecture across all repos! 🎯

🔧 Advanced Features

Custom Rules

// .codesyncer/rules.ts
export const customRules = [
{
pattern: /fetch(.*)/,
message: "Use our custom apiClient wrapper instead of raw fetch",
severity: "error"
},
{
pattern: /console.log/,
message: "Use our logger instead of console.log in production code",
severity: "warning"
}
];

Update Mode

As your project evolves, keep docs synchronized:

# Soft update: Add new info without removing old content
codesyncer update

# Hard update: Full regeneration based on current codebase
codesyncer update --hard

Language Support

codesyncer init --lang ko # Korean
codesyncer init --lang en # English (default)

🎯 Current Status & Roadmap

✅ Available Now

  • Full Claude Code support
  • Auto tech-stack detection (React, Next.js, Node.js, Python, Go, etc.)
  • Multi-language documentation (English, Korean)
  • Critical keyword detection
  • Comment tag system
  • Multi-repo linking

🚧 Coming Soon

  • Cursor integration
  • GitHub Copilot support
  • Continue.dev support
  • Team collaboration features (shared decision logs)
  • VS Code extension
  • Custom AI prompt templates

🤝 Contributing & Feedback

This is an early version and I'm actively looking for:

  • 🐛 Bug reports
  • 💡 Feature suggestions
  • 🔧 Code contributions
  • 📖 Documentation improvements
  • 🌍 Translation help

📦 Try It Out

npm install -g codesyncer

GitHub: https://github.com/bitjaru/codesyncer
npm: https://www.npmjs.com/package/codesyncer

💬 Discussion

Questions for the community:

  1. What's your biggest pain point with AI coding assistants?
  2. What features would make CodeSyncer more useful for you?
  3. What other AI tools should we prioritize supporting?

Drop a comment below or https://github.com/bitjaru/codesyncer/issues!

🙏 Final Thoughts

AI coding assistants are incredibly powerful, but they need the right context and guardrails to be truly effective in complex, multi-repository projects.

CodeSyncer is my attempt to solve this problem. It's been working great for my team, and I hope it helps yours too!

If you found this useful:

  • ⭐ Star the repo on GitHub
  • 🔄 Share with your team
  • 💬 Comment with your thoughts

Happy coding! 🚀

Building in public. Follow my journey on https://github.com/bitjaru

Top comments (0)