Content
# obs-code
> **VibCode: Transforming AI Programming from "Personal Craftsmanship" to "Engineering Standards"**
[](./LICENSE)
[](https://modelcontextprotocol.io)
[](https://www.typescriptlang.org)
[](https://github.com/xiaoletian64/obs-code)
---
## 🎯 One-Sentence Summary
**Current AI Programming**: Personal experience + prompt skills + random performance = Uncontrollable
**VibCode's Goal**: Engineering constraints + process standards + quality assurance = Controllable
---
## 📸 Showcase
### Code Knowledge Graph - NestJS Project
> 300 nodes, automatically identifying classes, methods, and call relationships, supporting search, filtering, and highlighting
### Business Semantic Understanding
```
User Input: Modify user login logic and add secondary verification
obs-code Output:
┌─────────────────────────────────────────────────────────────┐
│ Business Process: Login Process │
│ │
│ 1. Login (Login) @ src/auth/login.ts:23 │
│ 2. Authenticate (Authenticate) @ src/auth/auth.service.ts:45 │
│ 3. Verify (Verify) @ src/auth/verify.ts:12 │
│ 4. Generate Token (Token) @ src/auth/token.ts:67 │
│ 5. Return Response (Response) @ src/auth/response.ts:89 │
│ │
│ Impact Scope: 5 files, 12 functions │
│ Risk Points: Public interface changes require updating all callers │
└─────────────────────────────────────────────────────────────┘
```
### Call Chain Tracking
```
NestFactory.create Call Chain:
→ createGraphInspector (nest-factory.ts:379)
→ setAbortOnError (nest-factory.ts:341)
→ createNestInstance (nest-factory.ts:202)
→ initialize (nest-factory.ts:206)
→ handleInitializationError (nest-factory.ts:256)
```
---
## 🔧 What Problems Does It Solve?
### Problem 1: AI Sees Too Much Irrelevant Code
```
Traditional Approach:
AI sees 1000 files → gets lost → low-quality output
VibCode:
Requirement analysis → impact assessment → only sees 10 relevant files → precise output
```
### Problem 2: Code Changes Without Knowing Impact Scope
```
Traditional Approach:
Change function → find callers error → temporary fix → more omissions
VibCode:
Change function → analyze call chain → list all impact points → confirm before changing
```
### Problem 3: Uncontrollable AI Output Quality
```
Traditional Approach:
AI writes code → hopes it runs → runs and see
VibCode:
AI writes code → type checking → unit testing → code review → merge
```
---
## 📊 Real Project Verification
| Project | Scale | Nodes | Edges | Index Time | Parse Rate |
|------|------|--------|------|----------|----------|
| **Express** | Simple | 376 | 6 | 10s | 15 files/sec |
| **Axios** | Medium | 636 | 1,224 | 744ms | 267 files/sec |
| **NestJS** | Complex | 5,977 | 11,580 | 7s | 244 files/sec |
| **Vitest** | Large | 10,054 | 6,143 | 1m8s | 33 files/sec |
| **Fastify** | Medium | 1,533 | 450 | 7s | 47 files/sec |
**Total Nodes: 11,963 | Total Edges: 6,599**
---
## 🛠️ Features
### Core Features
| Feature | Description | Value |
|------|------|------|
| **Code Knowledge Graph** | Function calls, inheritance, dependencies | Know where changes affect |
| **Chinese Comment Indexing** | FTS5 full-text search, supports Chinese | Search "login" to find `handleAuth` |
| **Impact Chain Analysis** | Track impact by change intention | Know impact scope before changing |
| **Context Isolation** | Only return relevant files and line numbers | AI not disturbed by irrelevant code |
| **Business Semantic Understanding** | Technical symbols → business meaning | AI understand "set switch" corresponds to which code |
| **Real-time Sync** | File changes → graph updates automatically | Always based on latest code analysis |
| **CommonJS Support** | `module.exports` export tracking | Analyze old projects like Express |
| **Decorator Recognition** | `@Module()` `@Controller()` recognition | Correct analysis for frameworks like NestJS |
### MCP Tools (21)
```
Code Analysis:
- find_symbol Search symbols (supports Chinese)
- callers Who calls this function
- callees This function calls whom
- trace Track call path
- impact Impact chain analysis
- explore Batch symbol exploration
Context Construction:
- context Build context for tasks
- obs_scope_change Requirements → file reading list
- feature_map Features → token efficient reading chain
Code Understanding:
- business_semantic Business semantic understanding
- chinese_search Chinese search
- node Symbol details
- status Index health status
- files File structure
Visualization:
- graph_view Interactive graph
- plan_workflow AI code change workflow
```
### Supported Languages (14)
| Language | Parser | Features |
|------|--------|------|
| TypeScript / TSX | Enhanced regex | CommonJS + decorators |
| JavaScript / JSX | Enhanced regex | CommonJS + decorators |
| Python | Regex | docstring + comments |
| C / C++ | Regex | comment extraction |
| Go | Regex | struct + interface |
| Rust | Regex | trait + impl |
| Java | Regex | class + interface |
| Swift | Regex | protocol + class |
| Kotlin | Regex | data class + sealed |
| PHP | Regex | trait + interface |
| Ruby | Regex | module + mixin |
| C# | Regex | interface + delegate |
| Dart | Regex | mixin + extension |
| Lua | Regex | table + metatable |
---
## 🚀 Quick Start
### Installation
```bash
git clone https://github.com/xiaoletian64/obs-code.git
cd obs-code && npm install
npm run build
```
### Index Project
```bash
node dist/cli/index.js index /path/to/your/project
```
### Integrate with Local AI Programming Tools
obs-code has a built-in MCP installation wizard, which can write the current repository's `mcp-server.cjs` to common tool configurations.
```bash
# Install to all supported tools
node dist/cli/index.js install --tool all
# Install to OpenAI Codex CLI only
node dist/cli/index.js install --tool codex
```
Supported tools:
| Tool | Config Location |
|------|----------|
| Claude Code | `~/.claude/settings.json` |
| OpenAI Codex CLI | `~/.codex/config.yaml` |
| Cursor | `.cursor/mcp.json` |
| OpenCode | `opencode.json` |
| DvCode | `.dvcode/config.json` |
If the repository is not in the current directory, or you need to specify the MCP entry:
```bash
node dist/cli/index.js install --tool codex --mcp-path /absolute/path/to/obs-code/mcp-server.cjs
```
### Start MCP Server
```bash
node dist/cli/index.js serve --mcp
```
### Configure AI Tools
```json
{
"mcpServers": {
"obs-code": {
"command": "node",
"args": ["/path/to/obs-code/mcp-server.cjs"]
}
}
}
```
---
## 🙏 Open-Source Recruitment: We Need Your Help!
### Recruitment: Open-Source Projects + Developer Documentation
We are building an **AI Programming Training Dataset** and need:
**1. Open-source projects + matching developer documentation**
```
Project: Any open-source project with clear developer documentation
Documentation: Official API documentation, architecture documentation, design documentation
Format: GitHub repository link + documentation link
```
**2. Code changes + impact analysis**
```
Scenario: You changed a function and later found it affected other places
Data: What you changed → what it affected → how you found it
Format: PR link or Issue link
```
**3. Business requirements → code mapping**
```
Requirements: Business requirements described in Chinese
Code: Corresponding code files and functions
Format: Requirement description + code path
```
### Why Do We Need This Data?
```
Current AI Programming:
- Sees all code → randomly selects context → uncontrollable quality
Future AI Programming:
- Understands business requirements → precisely locates code → controllable quality
We need data to train:
- Requirement understanding models (Chinese requirements → technical symbols)
- Impact analysis models (change one point → affect which points)
- Business semantic models (technical code → business meaning)
```
### How to Contribute?
**Method 1: Submit Issue**
```markdown
Title: [Dataset] Project Name - Documentation Link
Content:
- Project Name: xxx
- GitHub Link: https://github.com/xxx/xxx
- Developer Documentation: https://xxx.com/docs
- Documentation Type: API Documentation / Architecture Documentation / Design Documentation
- Language: TypeScript / Python / Go / ...
```
**Method 2: Submit PR**
```bash
# 1. Fork the project
# 2. Add data to datasets/ directory
datasets/
projects/
project-name/
README.md # Project introduction
docs/
api.md # API documentation
architecture.md # Architecture documentation
examples/
feature-1.md # Requirement → code mapping examples
# 3. Submit PR
```
**Method 3: Contact Us Directly**
- GitHub Issue: https://github.com/xiaoletian64/obs-code/issues
- Email: [to be added]
### Data Format Example
```yaml
# datasets/projects/nestjs/README.md
project:
name: NestJS
url: https://github.com/nestjs/nest
docs: https://docs.nestjs.com
language: TypeScript
description: A progressive Node.js framework
features:
- name: Module System
description: Use @Module() decorator to define modules
code:
- packages/common/decorators/core/module.decorator.ts
docs:
- https://docs.nestjs.com/modules
- name: Dependency Injection
description: Use @Injectable() decorator to implement dependency injection
code:
- packages/common/decorators/core/injectable.decorator.ts
docs:
- https://docs.nestjs.com/fundamentals/custom-providers
```
---
## 🔮 Future Prospects
### Short-Term (3-6 months)
- [ ] More language support (Rust tree-sitter, Go tree-sitter)
- [ ] Framework routing recognition (Express/Django/Spring routing → handler)
- [ ] Smarter context construction (LLM-based symbol understanding)
- [ ] Web UI enhancement (interactive graph, real-time sync)
### Mid-Term (6-12 months)
- [ ] AI code change workflow automation (requirement → plan → execution → verification)
- [ ] Multi-project knowledge graph (cross-repository call chain)
- [ ] Team collaboration (shared index, conflict detection)
- [ ] CI/CD integration (PR impact analysis, test coverage suggestions)
### Long-Term (1-2 years)
- [ ] Intelligent engineering system (automatically identify code patterns, recommend best practices)
- [ ] Code quality guardian (automatically detect anti-patterns, suggest refactoring)
- [ ] Knowledge precipitation (team code knowledge base, newcomer guidance)
- [ ] Engineering constraint framework (define AI programming process standards)
---
## 💡 Core Philosophy
### Not Replacing Programmers, but Enhancing Them
```
Traditional Programmers:
Requirements → thinking → writing code → debugging → release
VibCode Programmers:
Requirements → thinking → AI-assisted analysis → human confirmation → AI execution → human review → release
```
### Not Making AI Smarter, but Making AI More Controllable
```
Traditional AI Programming:
Let AI see everything → hope AI is smart → uncontrollable output
VibCode:
Let AI see only what's necessary → constrain AI behavior → controllable output
```
### Not Personal Skills, but Engineering Standards
```
Traditional:
Personal prompt skills + personal experience = non-replicable
VibCode:
Engineering process + quality standards = replicable, scalable
```
---
## 📄 License
MIT © obs-code contributors
---
## 🙏 Acknowledgements
- [Obsidian](https://obsidian.md/) - inspiration for bidirectional links
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP protocol support
- [tree-sitter](https://tree-sitter.github.io/) - code parsing engine
- [Cytoscape.js](https://js.cytoscape.org/) - graph visualization
- All contributors of dataset ❤️
<div align="center">
**⭐ If this project helps you, please give it a Star! ⭐**
**Transforming AI Programming from "Personal Craftsmanship" to "Engineering Standards"**
**🙏 We need your open-source projects + developer documentation to train AI models 🙏**
[](https://star-history.com/#xiaoletian64/obs-code&Date)
</div>
