codemap_macro_create

Create a new shell macro for quick, repeatable commands.

macroshellautomation

Parameters

Name	Type	Required	Description
`name`	`string`	✅ Required	Macro name (e.g., 'build', 'test', 'lint')
`description`	`string`	✅ Required	Macro description
`cmd`	`string`	✅ Required	Shell command to execute
`shell`	`string`cmd \| powershell \| pwsh \| bash \| sh	❌ Optional	Shell to use (default: cmd on Windows, sh on Unix)
`cwd`	`string`	❌ Optional	Working directory (relative to project root)
`timeout`	`number`	❌ Optional	Timeout in milliseconds (default: 30000)
`env`	`object`	❌ Optional	Environment variables as key-value pairs

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_macro_create",
  "arguments": {
    "name": "build",
    "description": "Build the project",
    "cmd": "npm run build"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "macro": {
      "name": "build",
      "description": "Build the project",
      "cmd": "npm run build",
      "shell": "cmd",
      "cwd": null
    },
    "message": "Created macro \"build\". Run with codemap_macro_run(name: \"build\")."
  }
}

ℹ️When to Use This Tool

codemap_macro_create

Simplify complex commands - Turn long command chains into simple macro names
Standardize workflows - Ensure team uses same commands for build/test/deploy
Reduce typing - Replace repetitive commands with short macro names
Environment management - Bundle environment variables with commands
Workspace automation - Create macros for monorepo workspace operations
Cross-platform compatibility - Define platform-specific commands in one place
Development shortcuts - Quick access to dev server, tests, linting, formatting

💡Common Patterns

Standard Dev Workflow

// Create complete development macro set
const macros = [
  { name: 'dev', cmd: 'npm run dev' },
  { name: 'build', cmd: 'npm run build' },
  { name: 'test', cmd: 'npm test' },
  { name: 'lint', cmd: 'npm run lint' },
  { name: 'format', cmd: 'npm run format' }
];

for (const { name, cmd } of macros) {
  await codemap.macros.create({
    name,
    description: Run ${name},
    cmd
  });
}

Environment-Specific Macros

// Create test macros with different environments
await codemap.macros.create({
  name: 'test-unit',
  description: 'Unit tests',
  cmd: 'npm run test:unit',
  env: { NODE_ENV: 'test' }
});

await codemap.macros.create({
  name: 'test-integration',
  description: 'Integration tests',
  cmd: 'npm run test:integration',
  env: { 
    NODE_ENV: 'test',
    DB_HOST: 'localhost'
  }
});

Monorepo Package Macros

// Create build macros for each workspace
const packages = ['frontend', 'backend', 'shared'];

for (const pkg of packages) {
  await codemap.macros.create({
    name: build-${pkg},
    description: Build ${pkg},
    cmd: 'npm run build',
    cwd: packages/${pkg}
  });
}

Chained Command Macros

// Create macro for complex command chains
await codemap.macros.create({
  name: 'deploy',
  description: 'Build and deploy',
  cmd: 'npm run build && npm run test && npm run deploy',
  timeout: 300000 // 5 minutes
});

💡Pro Tips

Use descriptive names - Macro names should be clear and memorable. Prefer 'test-integration' over 'ti'.

Set appropriate timeouts - Build and deployment commands may need longer timeouts (60s+). Default is 30s.

Specify shell explicitly - For cross-platform repos, explicitly set shell to ensure consistency.

Group related macros - Use naming conventions like 'test-unit', 'test-integration', 'test-e2e' for related operations.

Include environment variables - Bundle required env vars with macros to avoid configuration errors.

Document in macro description - Use the description field to explain what the macro does and any prerequisites.

✅Best Practices

Start simple - Begin with basic npm script macros, then add complexity as needed.

Test macros after creation - Run codemap_macro_run immediately to verify the macro works.

Use relative paths in cwd - Working directories should be relative to project root for portability.

Don't hardcode secrets - Never put API keys, passwords, or tokens in macros. Use environment variables instead.

Version control friendly - Macros are stored in .codemap/ directory, which should be gitignored if it contains sensitive data.

Create team macros - Document common macros in team README for consistency across developers.

⚠️Common Mistakes

❌ Mistake: Using absolute paths

await codemap.macros.create({
  name: 'build',
  cmd: 'npm run build',
  cwd: 'C:/Users/John/projects/myapp/packages/backend' // Bad!
});

✅ Instead: Use relative paths

await codemap.macros.create({
  name: 'build',
  cmd: 'npm run build',
  cwd: 'packages/backend' // Relative to project root
});

---

❌ Mistake: Hardcoding sensitive data

await codemap.macros.create({
  name: 'deploy',
  cmd: 'deploy-script',
  env: {
    API_KEY: 'sk-1234567890abcdef' // Sensitive!
  }
});

✅ Instead: Reference environment variables

await codemap.macros.create({
  name: 'deploy',
  cmd: 'deploy-script',
  env: {
    API_KEY: process.env.API_KEY || ''
  }
});

---

❌ Mistake: Creating duplicate macros

await codemap.macros.create({ name: 'build', cmd: 'npm run build' });
// Later...
await codemap.macros.create({ name: 'build', cmd: 'npm run build:prod' });
// Error: macro 'build' already exists

✅ Instead: Use unique names or delete first

await codemap.macros.create({ name: 'build', cmd: 'npm run build' });
await codemap.macros.create({ name: 'build-prod', cmd: 'npm run build:prod' });

---

❌ Mistake: Not setting timeout for long operations

await codemap.macros.create({
  name: 'deploy',
  cmd: 'npm run deploy'
  // No timeout - will fail after 30s default
});

✅ Instead: Set appropriate timeout

await codemap.macros.create({
  name: 'deploy',
  cmd: 'npm run deploy',
  timeout: 300000 // 5 minutes
});

---

❌ Mistake: Platform-specific commands without shell specification

await codemap.macros.create({
  name: 'clean',
  cmd: 'rm -rf dist' // Fails on Windows
});

✅ Instead: Specify shell or use cross-platform commands

const isWindows = process.platform === 'win32';

await codemap.macros.create({
  name: 'clean',
  cmd: isWindows ? 'rmdir /s /q dist' : 'rm -rf dist',
  shell: isWindows ? 'cmd' : 'bash'
});