codemap_create

Create a new file. Fails if file exists (conflict envelope returned).

iowritecreatenewscaffold

Parameters

Name	Type	Required	Description
`target`	`string`	✅ Required	Path to the file or directory to create (relative or absolute)
`content`	`string`	❌ Optional	Content to write to the file (not used for directories)
`type`	`string`file \| directory	❌ Optional	Type of entity to create: 'file' or 'directory' (default: `file`)
`skipValidation`	`boolean`	❌ Optional	Skip syntax validation (default: false) (default: `false`)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_create",
  "arguments": {
    "target": "src/utils/logger.ts",
    "content": "export class Logger {\n  log(message: string): void {\n    console.log(`[${new Date().toISOString()}] ${message}`);\n  }\n}",
    "type": "file"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "created": "/home/user/project/src/services/users.service.ts",
    "type": "file",
    "bytes": 456
  },
  "hint": "💡 Be sure to consider adding this file to any relevant groups it may belong to with codemap_group_add"
}

ℹ️When to Use This Tool

codemap_create

Scaffold new project files and directories (routes, controllers, models, tests)
Generate boilerplate code from templates without risk of overwriting existing files
Create configuration files for new environments or features
Initialize new modules or components as part of development workflows
Ensure safety by failing if a file already exists rather than accidentally overwriting

💡Common Patterns

Project Scaffolding Pattern

1. Define file structure: const files = [{ path, content }, ...]
2. Create each file: for (file of files) { call codemap_create with file }
3. Handle conflicts: try/catch to detect existing files
4. Log results: track created vs skipped files
5. Reindex: call codemap_reindex() to update code graph

Use this when initializing new projects or adding new feature modules.

Template-Based Generation

1. Load template: const template = readTemplateFile('controller.template')
2. Fill placeholders: const filled = template.replace('{{name}}', entityName)
3. Create file: {"name": "codemap_create", "arguments": {"path": target, "content": filled}}
4. Verify syntax: check response.validated field
5. Follow up: create related files (tests, types, etc.)

Efficient for code generation tools and scaffolding systems.

Safe Creation with Fallback

1. Try create: {"name": "codemap_create", "arguments": {"path": path, "content": content}}
2. Catch conflict error
3. Prompt user: "File exists, overwrite?"
4. If yes: {"name": "codemap_write", "arguments": {"path": path, "content": content}}
5. If no: choose alternate filename

Best practice for interactive tools where user control is important.

💡Pro Tips

Use create for scaffolding, write for updates: Create fails if file exists - this is intentional safety. Use it when generating new files, use write when you specifically want to overwrite.
Batch create with error handling: When creating multiple files, wrap each create in try/catch. One conflict shouldn't halt the entire batch. Track which succeeded and which failed.
Check the conflict response: When create fails due to existing file, the error response includes existingSize and suggestions. Use this info to decide whether to prompt the user or choose an alternate action.
Validate generated code: For source files, always check response.validated. If validation fails, your template might have syntax errors. With skipValidation: false (default), you catch these early.
Create parent directories first: Before creating nested files like src/api/v2/users.ts, ensure parent directories exist. Consider using path utilities to create directory structure first.

✅Best Practices

Always handle conflict errors gracefully - provide users with clear options (overwrite, rename, skip)
Use descriptive filenames when scaffolding - avoid generic names like file1.ts, temp.txt
Include header comments in generated files: "// AUTO-GENERATED - Modify with care"
After creating source files, run codemap_reindex() to update the code graph immediately
For batch operations, track created files in case you need to rollback on error
Test your templates with skipValidation: false to catch syntax errors early

⚠️Common Mistakes

❌ Mistake: Not handling "file already exists" errors, causing workflow failures
✅ Instead: Always wrap create calls in try/catch and provide fallback logic (write, rename, or user prompt)

❌ Mistake: Using create in scripts where files might already exist, causing brittle automation
✅ Instead: Either check for existence first (codemap_peek()) or use write if you're okay with overwriting

❌ Mistake: Creating files without parent directories, leading to "ENOENT" errors
✅ Instead: Ensure directory structure exists before creating nested files, or use a library that creates parent dirs automatically

❌ Mistake: Forgetting to reindex after creating source files, leaving code graph stale
✅ Instead: Call codemap_reindex() after batch file creation to update symbols and dependencies

❌ Mistake: Scaffolding files with hardcoded paths, making templates not reusable
✅ Instead: Use path utilities to build relative paths dynamically. Templates should work in any project structure.

❌ Mistake: Creating files with incomplete or invalid code, then being surprised when skipValidation catches it
✅ Instead: Test your templates thoroughly. If you need to create incomplete code, explicitly set skipValidation: true and document why.

Changelog

2 releases

- 🆕AddedOptional summary parameter to document files at creation time — persisted immediately in .codemap/summaries.json with no rescan required
- 🐛FixedFile creation via codemap_write now correctly tracked as filesCreated instead of filesUpdated in session summaries

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_io_write

codemap_io_read

codemap_io_delete

codemap_io_list