@backendkit-labs/curator-codex-agent 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/AGENT.md +187 -0
  2. package/README.md +475 -0
  3. package/dist/analyzer.d.ts +44 -0
  4. package/dist/analyzer.d.ts.map +1 -0
  5. package/dist/analyzer.js +381 -0
  6. package/dist/analyzer.js.map +1 -0
  7. package/dist/api/config.d.ts +57 -0
  8. package/dist/api/config.d.ts.map +1 -0
  9. package/dist/api/config.js +183 -0
  10. package/dist/api/config.js.map +1 -0
  11. package/dist/api/http-server.d.ts +24 -0
  12. package/dist/api/http-server.d.ts.map +1 -0
  13. package/dist/api/http-server.js +108 -0
  14. package/dist/api/http-server.js.map +1 -0
  15. package/dist/api/routes.d.ts +8 -0
  16. package/dist/api/routes.d.ts.map +1 -0
  17. package/dist/api/routes.js +382 -0
  18. package/dist/api/routes.js.map +1 -0
  19. package/dist/api/security.d.ts +107 -0
  20. package/dist/api/security.d.ts.map +1 -0
  21. package/dist/api/security.js +200 -0
  22. package/dist/api/security.js.map +1 -0
  23. package/dist/checksum.d.ts +56 -0
  24. package/dist/checksum.d.ts.map +1 -0
  25. package/dist/checksum.js +186 -0
  26. package/dist/checksum.js.map +1 -0
  27. package/dist/documentation-curator.d.ts +18 -0
  28. package/dist/documentation-curator.d.ts.map +1 -0
  29. package/dist/documentation-curator.js +231 -0
  30. package/dist/documentation-curator.js.map +1 -0
  31. package/dist/http-server-main.d.ts +28 -0
  32. package/dist/http-server-main.d.ts.map +1 -0
  33. package/dist/http-server-main.js +69 -0
  34. package/dist/http-server-main.js.map +1 -0
  35. package/dist/index.d.ts +16 -0
  36. package/dist/index.d.ts.map +1 -0
  37. package/dist/index.js +23 -0
  38. package/dist/index.js.map +1 -0
  39. package/dist/knowledge/engine.d.ts +90 -0
  40. package/dist/knowledge/engine.d.ts.map +1 -0
  41. package/dist/knowledge/engine.js +181 -0
  42. package/dist/knowledge/engine.js.map +1 -0
  43. package/dist/knowledge/rag-provider.d.ts +87 -0
  44. package/dist/knowledge/rag-provider.d.ts.map +1 -0
  45. package/dist/knowledge/rag-provider.js +189 -0
  46. package/dist/knowledge/rag-provider.js.map +1 -0
  47. package/dist/knowledge/synthesis.d.ts +27 -0
  48. package/dist/knowledge/synthesis.d.ts.map +1 -0
  49. package/dist/knowledge/synthesis.js +142 -0
  50. package/dist/knowledge/synthesis.js.map +1 -0
  51. package/dist/providers/anthropic-adapter.d.ts +14 -0
  52. package/dist/providers/anthropic-adapter.d.ts.map +1 -0
  53. package/dist/providers/anthropic-adapter.js +29 -0
  54. package/dist/providers/anthropic-adapter.js.map +1 -0
  55. package/dist/providers/index.d.ts +14 -0
  56. package/dist/providers/index.d.ts.map +1 -0
  57. package/dist/providers/index.js +29 -0
  58. package/dist/providers/index.js.map +1 -0
  59. package/dist/providers/openai-adapter.d.ts +16 -0
  60. package/dist/providers/openai-adapter.d.ts.map +1 -0
  61. package/dist/providers/openai-adapter.js +37 -0
  62. package/dist/providers/openai-adapter.js.map +1 -0
  63. package/dist/providers/types.d.ts +4 -0
  64. package/dist/providers/types.d.ts.map +1 -0
  65. package/dist/providers/types.js +3 -0
  66. package/dist/providers/types.js.map +1 -0
  67. package/dist/server.d.ts +33 -0
  68. package/dist/server.d.ts.map +1 -0
  69. package/dist/server.js +640 -0
  70. package/dist/server.js.map +1 -0
  71. package/dist/types.d.ts +41 -0
  72. package/dist/types.d.ts.map +1 -0
  73. package/dist/types.js +4 -0
  74. package/dist/types.js.map +1 -0
  75. package/dist/watcher.d.ts +26 -0
  76. package/dist/watcher.d.ts.map +1 -0
  77. package/dist/watcher.js +168 -0
  78. package/dist/watcher.js.map +1 -0
  79. package/package.json +58 -0
package/AGENT.md ADDED
@@ -0,0 +1,187 @@
1
+ # curator-codex-agent
2
+
3
+ **Unified Code + Documentation Curator**. Recursively analyzes both source code files AND documentation (.md, .txt), discovers associated files, and extracts structured knowledge into enterprise vaults using LLM reasoning.
4
+
5
+ ## Quick Start
6
+
7
+ ```bash
8
+ # Analyze entire project (code + docs)
9
+ CURATOR_INPUT_PATH=/project \
10
+ CURATOR_OUTPUT_PATH=/vault \
11
+ CURATOR_API_KEY=sk-... \
12
+ npm run watch-code
13
+ ```
14
+
15
+ ## Core Capabilities
16
+
17
+ 1. **Unified Processing** — Analyzes both code (.ts, .js, .py, etc) AND docs (.md, .txt) in single pass
18
+ 2. **Multi-language Code Analysis** — TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, Kotlin, Swift
19
+ 3. **Documentation Analysis** — Extracts policies, procedures, decisions, lessons from .md/.txt
20
+ 4. **Smart Documentation Discovery** — Finds and combines associated .md files, README.md, project context
21
+ 5. **Automatic Type Detection** — Routes files to appropriate analyzer (CodeAnalyzer or DocumentationCurator)
22
+ 6. **Reasoning-based Extraction** — Uses deepseek-reasoner for deep understanding
23
+ 7. **Change Detection** — Manifest-based tracking; only reanalyzes changed files
24
+ 8. **Vault Integration** — Outputs semantic markdown notes with metadata
25
+ 9. **MCP Server** — Runs as stdio or HTTP MCP server
26
+
27
+ ## Key Features
28
+
29
+ - ✅ Recursive directory scanning
30
+ - ✅ Public API extraction (types, functions, classes, interfaces)
31
+ - ✅ Pattern & architecture detection
32
+ - ✅ Dependency mapping
33
+ - ✅ Documentation association (code.ts + code.md → combined analysis)
34
+ - ✅ Change tracking via SHA256 manifest
35
+ - ✅ Efficient reprocessing (skip unchanged files)
36
+ - ✅ Multi-provider support (DeepSeek, OpenAI, Anthropic, Ollama)
37
+
38
+ ## Environment Variables
39
+
40
+ **Required:**
41
+ - `CURATOR_API_KEY` — LLM API key
42
+ - `CURATOR_OUTPUT_PATH` — Vault output directory
43
+
44
+ **Optional:**
45
+ - `CURATOR_INPUT_PATH` — Code directory to analyze once (default: watch mode)
46
+ - `CURATOR_PROVIDER` — LLM provider (default: deepseek)
47
+ - `CURATOR_MODEL` — Model ID (default: deepseek-reasoner)
48
+ - `CURATOR_PORT` — HTTP port for MCP (default: stdio transport)
49
+
50
+ See `.env.example` for all options.
51
+
52
+ ## Architecture
53
+
54
+ ```
55
+ CodeAnalyzer
56
+ ├── findAssociatedDocs() — Discovers code.md, README.md, etc
57
+ ├── analyzeFile() — Analyzes single file + combined docs
58
+ ├── callLLM() — Sends to reasoning model
59
+ └── writeNote() — Outputs to vault
60
+
61
+ Manifest System
62
+ ├── calculateFileHash() — SHA256 tracking
63
+ ├── loadManifest() — Read .codex-manifest.json
64
+ ├── hasFileChanged() — Detect changes
65
+ └── saveManifest() — Update tracking
66
+ ```
67
+
68
+ ## Vault Output
69
+
70
+ Generates markdown files with frontmatter per analyzed module:
71
+
72
+ ```markdown
73
+ ---
74
+ title: "AuthService: JWT-based Authentication"
75
+ area: general
76
+ tipo: componente
77
+ language: typescript
78
+ resumen: "NestJS service for JWT-based authentication..."
79
+ source_ref: "src/services/auth.service.ts"
80
+ sources_combined: ["src/services/auth.service.ts", "src/services/auth.service.md"]
81
+ depends_on: ["@nestjs/jwt", "@backendkit-labs/result"]
82
+ exports: ["AuthService", "login", "validateToken"]
83
+ ---
84
+
85
+ ## Overview
86
+ ...
87
+ ```
88
+
89
+ ## Usage Modes
90
+
91
+ 1. **Direct Analysis** (single run):
92
+ ```bash
93
+ CURATOR_INPUT_PATH=/project npm run watch-code
94
+ # Analyzes once, exits
95
+ ```
96
+
97
+ 2. **Watch Mode** (continuous):
98
+ ```bash
99
+ npm start
100
+ # Polls vault/incoming/ every 30s
101
+ ```
102
+
103
+ 3. **MCP Server**:
104
+ ```bash
105
+ CURATOR_PORT=3101 npm start
106
+ # HTTP MCP server
107
+ ```
108
+
109
+ ## Performance
110
+
111
+ - 3-8 seconds per file (reasoning model)
112
+ - Skipped files: < 100ms
113
+ - 500 files, 1st run: ~40-60 min
114
+ - 500 files, 2nd run (1% changed): ~2-3 min
115
+
116
+ ## Integration
117
+
118
+ ### Claude Desktop
119
+ Add to `claude_desktop_config.json`:
120
+ ```json
121
+ {
122
+ "mcpServers": {
123
+ "codex": {
124
+ "command": "npx",
125
+ "args": ["-y", "@backendkit-labs/curator-codex-agent"],
126
+ "env": {"CURATOR_API_KEY": "sk-...", "CURATOR_OUTPUT_PATH": "/vault"}
127
+ }
128
+ }
129
+ }
130
+ ```
131
+
132
+ ### bk-agent
133
+ Register as MCP skill in bk-agent manifest.
134
+
135
+ ### knowledge-agent
136
+ Query vault generated by curator-codex for RAG-powered code questions.
137
+
138
+ ## Architecture
139
+
140
+ ```
141
+ CodeAnalyzer
142
+ ├── analyzeFile() — Dispatcher
143
+ ├── analyzeCode() — Route to CodeAnalyzer
144
+ ├── analyzeDocumentation() — Route to DocumentationCurator
145
+ ├── isDocFile() — File type detection
146
+ └── findAssociatedDocs() — Discover code.md, README.md
147
+
148
+ DocumentationCurator (embedded)
149
+ ├── curateFile()
150
+ ├── curateText()
151
+ └── callLLM() — Extract policies, procedures
152
+
153
+ Manifest System
154
+ ├── findAllFiles() — Find code + docs (recursive)
155
+ ├── isCodeFile() — Detect .ts, .js, .py, etc
156
+ ├── isDocFile() — Detect .md, .txt
157
+ └── Change tracking — .codex-manifest.json
158
+ ```
159
+
160
+ ## Comparison
161
+
162
+ | Feature | curator-agent | curator-codex-agent |
163
+ |---------|---|---|
164
+ | **Input** | .md, .txt docs only | Code + Docs (.ts, .js, .py, .md, .txt) |
165
+ | **Code Analysis** | ❌ No | ✅ Yes (extract APIs, components) |
166
+ | **Doc Analysis** | ✅ Yes | ✅ Yes (extract policies, procedures) |
167
+ | **File Detection** | Manual separation | Automatic file routing |
168
+ | **Associated Docs** | N/A | ✅ Finds code.md, README.md |
169
+ | **Use Case** | Docs-only projects | Projects with code + docs |
170
+ | **Workflow** | Sequential | Unified (one pass) |
171
+
172
+ ## When to Use Each
173
+
174
+ | Scenario | Use |
175
+ |----------|-----|
176
+ | I have code + docs (mixed project) | **curator-codex-agent** ← unified |
177
+ | I ONLY have documentation files | curator-agent |
178
+ | I ONLY have code (no docs) | curator-codex-agent |
179
+ | I want code analysis only | curator-codex-agent (will skip .md) |
180
+ | I want docs analysis only | curator-agent |
181
+
182
+ ## See Also
183
+
184
+ - **curator-agent** — Specialized documentation curator (if you prefer separate concerns)
185
+ - **bk-agent** — Multi-agent framework
186
+ - **knowledge-agent** — RAG retrieval on curated vaults
187
+ - **curator-codex-agent** ← **You are here** (unified code + doc curator)
package/README.md ADDED
@@ -0,0 +1,475 @@
1
+ # curator-codex-agent
2
+
3
+ **Codex Curator** — Unified source code and documentation analysis with intelligent knowledge extraction into enterprise vaults using LLM reasoning.
4
+
5
+ ## Overview
6
+
7
+ `curator-codex-agent` is a **unified curator** that analyzes both source code and documentation:
8
+
9
+ ### 🔵 Code Analysis
10
+ Analyzes source code files (TypeScript, JavaScript, Python, Go, Rust, Java, etc.) and extracts:
11
+ - **Public APIs** — functions, classes, interfaces, type definitions
12
+ - **Modules & Components** — what each file/directory does
13
+ - **Patterns & Architecture** — design patterns, integration points
14
+ - **Dependencies** — external libraries and internal module relationships
15
+ - **Usage Examples** — extracted from comments and associated documentation
16
+
17
+ ### 📄 Documentation Analysis
18
+ Processes documentation files (.md, .txt) and extracts:
19
+ - **Policies** — company rules, procedures, governance
20
+ - **Decisions** — architectural decisions, standards
21
+ - **Procedures** — how-to guides, workflows
22
+ - **Lessons** — learned experiences, best practices
23
+ - **External Standards** — compliance requirements, ISO standards
24
+
25
+ ### Key Features
26
+
27
+ ✅ **Unified Processing** — Handles both source code AND documentation in single pass
28
+ ✅ **Multi-language Code** — TypeScript, JavaScript, Python, Go, Rust, Java, C/C++, Kotlin, Swift
29
+ ✅ **Smart Documentation Discovery** — automatically finds and combines associated .md files, README.md, and project context
30
+ ✅ **Reasoning-based Analysis** — uses deepseek-reasoner for deep understanding of both code and docs
31
+ ✅ **Change Detection** — SHA256 manifest tracking, intelligent reprocessing of only changed files
32
+ ✅ **Recursive Scanning** — processes entire directory hierarchies, smart ignoring of node_modules, dist, venv, etc.
33
+ ✅ **MCP Server** — works as stdio or HTTP server for integration with Claude, bk-agent, other tools
34
+ ✅ **Vault Integration** — outputs semantic notes into shared vaults for knowledge sharing
35
+ ✅ **Automatic Type Detection** — detects file type and routes to appropriate analyzer
36
+
37
+ ## Installation
38
+
39
+ ```bash
40
+ npm install @backendkit-labs/curator-codex-agent
41
+ ```
42
+
43
+ Or clone and build:
44
+
45
+ ```bash
46
+ cd packages/curator-codex-agent
47
+ npm install
48
+ npm run build
49
+ ```
50
+
51
+ ## Usage
52
+
53
+ ### Mode 1: Direct Code Analysis (Single Run)
54
+
55
+ Analyze a project's code once and generate knowledge vault:
56
+
57
+ ```bash
58
+ CURATOR_INPUT_PATH=/path/to/my-project \
59
+ CURATOR_OUTPUT_PATH=/path/to/vault \
60
+ CURATOR_API_KEY=sk-... \
61
+ npm run watch-code
62
+ ```
63
+
64
+ This will:
65
+ 1. Recursively scan `/path/to/my-project` for all code files
66
+ 2. For each file, search for associated documentation:
67
+ - `filename.md` (same directory)
68
+ - `README.md` (same directory)
69
+ - `docs/filename.md` (in docs/ folder)
70
+ - Root `/README.md` (project context)
71
+ 3. Analyze code + docs together with reasoning model
72
+ 4. Extract structured knowledge and write to vault
73
+ 5. Create `.codex-manifest.json` to track analyzed files
74
+ 6. Exit
75
+
76
+ **Second run with same inputs** (after modifying some files):
77
+ - Manifest detects unchanged files → skips
78
+ - Manifest detects changed files → reanalyzes only those
79
+ - Efficiency: if 500 files and only 3 changed, processes only the 3
80
+
81
+ ### Mode 2: Watch Incoming (Autonomous)
82
+
83
+ Monitor `vault/incoming/` directory for new code files:
84
+
85
+ ```bash
86
+ CURATOR_OUTPUT_PATH=/path/to/vault \
87
+ CURATOR_API_KEY=sk-... \
88
+ npm start
89
+ ```
90
+
91
+ Polls every 30 seconds (or `CURATOR_POLL_MS`), processes new code files automatically.
92
+
93
+ ### Mode 3: MCP Server
94
+
95
+ Run as HTTP MCP server for Claude Desktop or remote clients:
96
+
97
+ ```bash
98
+ CURATOR_OUTPUT_PATH=/path/to/vault \
99
+ CURATOR_API_KEY=sk-... \
100
+ CURATOR_PORT=3101 \
101
+ npm start
102
+ ```
103
+
104
+ Then use via MCP client:
105
+
106
+ ```typescript
107
+ // Analyze a single file
108
+ POST http://localhost:3101/mcp
109
+ {
110
+ "tool": "analyze_file",
111
+ "params": {
112
+ "file_path": "/absolute/path/to/file.ts",
113
+ "relative_path": "src/services/auth.ts"
114
+ }
115
+ }
116
+
117
+ // Analyze entire directory
118
+ POST http://localhost:3101/mcp
119
+ {
120
+ "tool": "analyze_directory",
121
+ "params": {
122
+ "directory_path": "/absolute/path/to/project"
123
+ }
124
+ }
125
+ ```
126
+
127
+ ## Configuration
128
+
129
+ ### Environment Variables
130
+
131
+ **Required:**
132
+ - `CURATOR_API_KEY` — Your API key (DeepSeek, OpenAI, Anthropic, etc.)
133
+ - `CURATOR_OUTPUT_PATH` — Absolute path to vault root
134
+
135
+ **Optional:**
136
+ - `CURATOR_INPUT_PATH` — Code directory to analyze once (if not set, uses watch mode)
137
+ - `CURATOR_PROVIDER` — `deepseek`, `openai`, `anthropic`, `ollama` (default: `deepseek`)
138
+ - `CURATOR_MODEL` — Model ID (defaults to reasoning models for each provider)
139
+ - `CURATOR_BASE_URL` — Custom LLM endpoint
140
+ - `CURATOR_PORT` — HTTP port (if set, runs HTTP MCP; if not, uses stdio)
141
+ - `CURATOR_POLL_MS` — Polling interval in milliseconds (default: 30000)
142
+
143
+ ### Example `.env.local`
144
+
145
+ ```env
146
+ CURATOR_API_KEY=sk-...
147
+ CURATOR_OUTPUT_PATH=/Users/john/Vaults/code-knowledge
148
+ CURATOR_INPUT_PATH=/Users/john/Projects/my-framework
149
+ CURATOR_PROVIDER=deepseek
150
+ CURATOR_MODEL=deepseek-reasoner
151
+ ```
152
+
153
+ ## Vault Output
154
+
155
+ For each analyzed file, generates markdown notes with frontmatter:
156
+
157
+ **File:** `vault/general/2026-06-13-authservice-jwt-based-authentication.md`
158
+
159
+ ```markdown
160
+ ---
161
+ title: "AuthService: JWT-based Authentication"
162
+ area: general
163
+ tipo: componente
164
+ language: typescript
165
+ resumen: "NestJS service implementing JWT-based authentication..."
166
+ author: "agent/codex"
167
+ date: 2026-06-13
168
+ source_ref: "src/services/auth.service.ts"
169
+ sources_combined: ["src/services/auth.service.ts", "src/services/auth.service.md", "README.md"]
170
+ tags: ["code/typescript", "modulo/authentication", "tipo/service", "patron/jwt"]
171
+ version: 1.0
172
+ depends_on: ["@nestjs/jwt", "@backendkit-labs/result"]
173
+ exports: ["AuthService", "login", "validateToken"]
174
+ files: ["src/services/auth.service.ts"]
175
+ ---
176
+
177
+ ## Overview
178
+ JWT-based authentication service for NestJS applications.
179
+
180
+ ## Public API
181
+
182
+ ### login(username, password)
183
+ ...
184
+
185
+ ### validateToken(token)
186
+ ...
187
+
188
+ ## Dependencies
189
+ ...
190
+ ```
191
+
192
+ ### Frontmatter Fields
193
+
194
+ | Field | Meaning |
195
+ |-------|---------|
196
+ | `title` | Human-readable name of the analyzed module/component |
197
+ | `area` | Category: general, backend, frontend, devops, infraestructura |
198
+ | `tipo` | Type: componente, api, patron, utilidad, arquitectura, integracion |
199
+ | `language` | Programming language detected |
200
+ | `resumen` | 1-2 sentences with searchable terms (function names, types) |
201
+ | `source_ref` | Original file analyzed |
202
+ | `sources_combined` | Array of files combined (code + associated docs) |
203
+ | `tags` | Searchable tags (e.g., code/typescript, modulo/auth) |
204
+ | `depends_on` | External dependencies or modules |
205
+ | `exports` | Public APIs this file exports |
206
+ | `files` | List of files analyzed for this note |
207
+
208
+ ## How It Works
209
+
210
+ ### 1. Discovery
211
+
212
+ ```
213
+ Scans INPUT_PATH recursively
214
+ ↓
215
+ Finds ALL files:
216
+ Code: .ts, .tsx, .js, .jsx, .py, .go, .rs, .java, .c, .cpp, .kt, .swift
217
+ Docs: .md, .txt
218
+ ↓
219
+ For each code file:
220
+ - Look for filename.md (same dir)
221
+ - Look for README.md (same dir)
222
+ - Look for docs/filename.md
223
+ - Look for root README.md
224
+ ```
225
+
226
+ ### 2. File Type Detection & Routing
227
+
228
+ ```
229
+ Per file, determine type:
230
+
231
+ IF .md or .txt → Route to DocumentationCurator
232
+ ↓
233
+ Analyzes as: policy, decision, procedure, lesson, standard
234
+
235
+ IF .ts, .js, .py, etc → Route to CodeAnalyzer
236
+ ↓
237
+ 1. Read code (truncate if > 20KB)
238
+ 2. Read associated docs (if found)
239
+ 3. Send to reasoning model
240
+ 4. Extract: APIs, components, patterns, architecture
241
+ ```
242
+
243
+ ### 3. Analysis
244
+
245
+ **Code Analysis (CodeAnalyzer):**
246
+ ```
247
+ 1. Read code file
248
+ 2. Find & read associated .md file (if exists)
249
+ 3. Find & read README.md for context
250
+ 4. Send ALL THREE to reasoning model
251
+ 5. LLM extracts: APIs, types, patterns, dependencies
252
+ 6. Returns structured JSON
253
+ ```
254
+
255
+ **Documentation Analysis (DocumentationCurator):**
256
+ ```
257
+ 1. Read .md or .txt file
258
+ 2. Send to LLM
259
+ 3. LLM extracts: policies, decisions, procedures, lessons
260
+ 4. Returns structured JSON
261
+ ```
262
+
263
+ ### 4. Deduplication
264
+
265
+ ```
266
+ Check if output file already exists in vault
267
+ If yes → skip (avoid duplicate notes)
268
+ If no → write new markdown file
269
+ ```
270
+
271
+ ### 5. Manifest Tracking
272
+
273
+ ```
274
+ On first run:
275
+ Creates .codex-manifest.json
276
+ Stores hash of EVERY file (code + docs) + analysis status
277
+
278
+ On subsequent runs:
279
+ Loads manifest
280
+ Checks hash of each file
281
+ If unchanged → skip analysis
282
+ If changed → reanalyze
283
+ If new → analyze
284
+ ```
285
+
286
+ ## Example: Analyze a Framework with Code + Documentation
287
+
288
+ ```bash
289
+ # Setup
290
+ export CURATOR_INPUT_PATH=/Users/john/Projects/my-framework
291
+ export CURATOR_OUTPUT_PATH=/Users/john/Vaults/framework-knowledge
292
+ export CURATOR_API_KEY=sk-...
293
+
294
+ # Project structure:
295
+ # my-framework/
296
+ # ├── src/
297
+ # │ ├── auth.service.ts
298
+ # │ ├── auth.service.md ← associated doc
299
+ # │ └── payment.ts
300
+ # ├── docs/
301
+ # │ ├── architecture.md
302
+ # │ ├── setup-guide.md
303
+ # │ └── contributing.md
304
+ # └── README.md
305
+
306
+ # First run: analyze EVERYTHING (code + docs)
307
+ npm run watch-code
308
+ # Output:
309
+ # - 100 code files analyzed (extracted APIs, components)
310
+ # - 10 doc files analyzed (extracted procedures, decisions)
311
+ # - .codex-manifest.json created
312
+
313
+ # Developer modifies 3 code files + 1 doc
314
+ # Second run: only those 4 files reanalyzed
315
+ npm run watch-code
316
+ # Output: 4 files analyzed, 106 skipped (96% efficiency!)
317
+ ```
318
+
319
+ ## MCP Integration
320
+
321
+ ### Claude Desktop
322
+
323
+ Add to `claude_desktop_config.json`:
324
+
325
+ ```json
326
+ {
327
+ "mcpServers": {
328
+ "codex": {
329
+ "command": "npx",
330
+ "args": ["-y", "@backendkit-labs/curator-codex-agent"],
331
+ "env": {
332
+ "CURATOR_API_KEY": "sk-...",
333
+ "CURATOR_OUTPUT_PATH": "/Users/john/Vaults/code-knowledge"
334
+ }
335
+ }
336
+ }
337
+ }
338
+ ```
339
+
340
+ Then use in Claude:
341
+
342
+ > I have a folder at `/path/to/my-project`. Can you analyze it and extract knowledge about the architecture and APIs?
343
+
344
+ ### bk-agent
345
+
346
+ Add to skills or MCP registry:
347
+
348
+ ```yaml
349
+ - name: curator-codex
350
+ command: npx @backendkit-labs/curator-codex-agent
351
+ env:
352
+ CURATOR_API_KEY: ${CURATOR_API_KEY}
353
+ CURATOR_OUTPUT_PATH: /shared-vault
354
+ ```
355
+
356
+ ## Scripts
357
+
358
+ ```bash
359
+ npm run build # Compile TypeScript → dist/
360
+ npm run dev # Run analyzer in dev mode (tsx)
361
+ npm start # Run MCP server (stdio or HTTP)
362
+ npm run watch-code # Analyze code with progress bar
363
+ npm run typecheck # Type checking only
364
+ ```
365
+
366
+ ## Supported Languages
367
+
368
+ | Language | Extensions | Example |
369
+ |----------|-----------|---------|
370
+ | TypeScript | .ts, .tsx | class, interface, type |
371
+ | JavaScript | .js, .jsx | function, class, export |
372
+ | Python | .py | def, class, async def |
373
+ | Go | .go | func, type, interface |
374
+ | Rust | .rs | fn, struct, trait, impl |
375
+ | Java | .java | class, interface, method |
376
+ | C | .c | struct, typedef, void |
377
+ | C++ | .cpp | class, namespace, template |
378
+ | Kotlin | .kt | class, fun, data class |
379
+ | Swift | .swift | class, struct, protocol |
380
+
381
+ ## Unified Architecture
382
+
383
+ ### curator-agent (Documentation Only)
384
+ - Specializes in .md and .txt files only
385
+ - Extracts: policies, procedures, decisions, standards
386
+ - Use when: processing documentation separately
387
+
388
+ ### curator-codex-agent (Unified: Code + Documentation)
389
+ - Processes BOTH code files AND .md/.txt files in single pass
390
+ - Code Analysis: extracts APIs, components, patterns, architecture
391
+ - Documentation Analysis: extracts policies, procedures, decisions, standards
392
+ - Automatic File Detection: routes .ts to CodeAnalyzer, .md to DocumentationCurator
393
+ - Associated Doc Discovery: finds code.md, README.md, combines with code analysis
394
+ - Use when: analyzing projects with mixed code + documentation
395
+
396
+ ### Single vs. Dual Curator Workflows
397
+
398
+ **Option A: Unified Workflow (Recommended for Projects)**
399
+ ```
400
+ Project/
401
+ ├── src/ ← Code (.ts, .js, .py)
402
+ ├── docs/ ← Docs (.md, .txt)
403
+ └── README.md
404
+
405
+ curator-codex-agent INPUT=/project OUTPUT=/vault
406
+ ↓
407
+ Processes EVERYTHING in one pass
408
+ ↓
409
+ vault/
410
+ ├── general/
411
+ │ ├── authservice-api.md (from src/auth.ts + auth.md)
412
+ │ ├── architecture-overview.md (from docs/architecture.md)
413
+ │ ├── setup-guide.md (from docs/setup.md)
414
+ │ └── ...
415
+ ```
416
+
417
+ **Option B: Specialized Workflow (Separate Concerns)**
418
+ ```
419
+ curator-codex-agent INPUT=/project/src OUTPUT=/vault # Code only
420
+ curator-agent INPUT=/project/docs OUTPUT=/vault # Docs only
421
+ ```
422
+
423
+ ## Troubleshooting
424
+
425
+ ### No manifest found. Will process ALL X files.
426
+
427
+ Normal on first run. Creates `.codex-manifest.json` to track analyzed files.
428
+
429
+ ### Files showing ⊘ (unchanged)
430
+
431
+ Good! Manifest detected no hash change. Skipped to save LLM costs. Run with file modifications to reanalyze.
432
+
433
+ ### Model not found error
434
+
435
+ Check `CURATOR_MODEL` is valid for your provider:
436
+ - DeepSeek: `deepseek-reasoner`, `deepseek-chat`
437
+ - OpenAI: `o3-mini`, `gpt-4o`, `o1`
438
+ - Anthropic: `claude-opus-4-8`, `claude-sonnet-4-6`
439
+ - Ollama: `llama3.2`, `qwen2.5-coder:7b`
440
+
441
+ ### API key rejected
442
+
443
+ Verify `CURATOR_API_KEY` is valid. Check provider's authentication method.
444
+
445
+ ### Memory/timeout on large files
446
+
447
+ Files > 20KB are truncated to 20KB of code. Increase `maxInputChars` in code if needed:
448
+
449
+ ```typescript
450
+ const analyzer = new CodeAnalyzer({
451
+ provider,
452
+ vaultPath,
453
+ maxInputChars: 40_000, // increase limit
454
+ });
455
+ ```
456
+
457
+ ## Performance
458
+
459
+ | Metric | Baseline |
460
+ |--------|----------|
461
+ | Analysis per file | 3-8 seconds (reasoning model) |
462
+ | Skipped files | < 100ms (hash check only) |
463
+ | 500 files, 1st run | ~40-60 minutes (depends on model) |
464
+ | 500 files, 2nd run (1% changed) | ~2-3 minutes |
465
+ | Vault size (500 files analyzed) | ~50-100 MB |
466
+
467
+ ## License
468
+
469
+ MIT
470
+
471
+ ## See Also
472
+
473
+ - [curator-agent](../curator-agent) — Documentation curator
474
+ - [bk-agent](../bk-agent) — Multi-agent framework
475
+ - [knowledge-agent](../knowledge-agent) — RAG knowledge retrieval
@@ -0,0 +1,44 @@
1
+ import type { CuratorLLMProvider } from './providers/types.js';
2
+ import type { CodeAnalysisResult, AssociatedDocs } from './types.js';
3
+ export interface CodeAnalyzerOptions {
4
+ provider: CuratorLLMProvider;
5
+ vaultPath: string;
6
+ maxInputChars?: number;
7
+ }
8
+ export declare class CodeAnalyzer {
9
+ private readonly provider;
10
+ private readonly vaultPath;
11
+ private readonly maxInputChars;
12
+ private readonly docCurator;
13
+ constructor(opts: CodeAnalyzerOptions);
14
+ /**
15
+ * Find documentation files associated with a code file
16
+ */
17
+ findAssociatedDocs(filePath: string, allFiles: Array<{
18
+ fullPath: string;
19
+ relativePath: string;
20
+ }>): Promise<AssociatedDocs>;
21
+ /**
22
+ * Analyze a file (code or documentation) with unified dispatcher
23
+ */
24
+ analyzeFile(filePath: string, relativePath: string, allFiles?: Array<{
25
+ fullPath: string;
26
+ relativePath: string;
27
+ }>): Promise<CodeAnalysisResult>;
28
+ /**
29
+ * Analyze a code file with optional associated documentation
30
+ */
31
+ private analyzeCode;
32
+ /**
33
+ * Analyze a documentation file (.md, .txt)
34
+ */
35
+ private analyzeDocumentation;
36
+ /**
37
+ * Check if file is a documentation file
38
+ */
39
+ private isDocFile;
40
+ private getSourcesCombined;
41
+ private callLLM;
42
+ private writeNote;
43
+ }
44
+ //# sourceMappingURL=analyzer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAoB,kBAAkB,EAAuB,cAAc,EAAE,MAAM,YAAY,CAAC;AAsI5G,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;gBAEtC,IAAI,EAAE,mBAAmB;IAUrC;;OAEG;IACG,kBAAkB,CACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,GAC5D,OAAO,CAAC,cAAc,CAAC;IAqC1B;;OAEG;IACG,WAAW,CACb,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,GAC7D,OAAO,CAAC,kBAAkB,CAAC;IAS9B;;OAEG;YACW,WAAW;IA8FzB;;OAEG;YACW,oBAAoB;IAIlC;;OAEG;IACH,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,kBAAkB;YA2BZ,OAAO;YAgCP,SAAS;CAuB1B"}