codemap_execute_shell

Execute shell commands like compile checks, npm scripts, tests, or builds. Returns stdout, stderr, and exit code. Supports different shells (cmd, powershell, bash).

sessionshellexeccommandbuildtest

Parameters

Name	Type	Required	Description
`cmd`	`string`	✅ Required	Shell command to execute (e.g., 'npm test', 'tsc --noEmit', 'git status')
`cwd`	`string`	❌ Optional	Working directory (default: project root)
`timeout`	`number`	❌ Optional	Timeout in milliseconds (default: 30000)
`shell`	`string`	❌ Optional	Shell to use: 'cmd', 'powershell', 'pwsh', 'bash', or 'sh' (default: cmd on Windows, sh on Unix)

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_execute_shell",
  "arguments": {
    "cmd": "npm test"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "data": {
    "stdout": "> [email protected] test\n> jest\n\nPASS  tests/auth.test.ts\n  ✓ validates JWT tokens (15 ms)\n  ✓ rejects expired tokens (8 ms)\n  ✓ handles malformed tokens (5 ms)\n\nPASS  tests/api.test.ts\n  ✓ GET /users returns user list (22 ms)\n  ✓ POST /users creates new user (18 ms)\n\nTest Suites: 2 passed, 2 total\nTests:       5 passed, 5 total\nSnapshots:   0 total\nTime:        2.45 s",
    "stderr": "",
    "exitCode": 0
  }
}

ℹ️When to Use This Tool

codemap_execute_shell

Run compile checks (tsc, eslint, etc.)
Execute test suites
Run build scripts
Check git status or run git commands
Install dependencies (npm, yarn, pnpm)
Execute custom project scripts
Verify project state before closing session

💡Common Patterns

Pre-Close Quality Gate

1. Work on feature
2. codemap_execute_shell({ cmd: "npm test" })
3. If tests pass, codemap_close()
4. If tests fail, fix and repeat

Ensure quality before ending session.

Build Verification

1. Make code changes
2. codemap_execute_shell({ cmd: "npm run build" })
3. Check exitCode === 0
4. Continue or fix build errors

Catch build errors early.

Multi-Step Checks

1. codemap_execute_shell({ cmd: "npm run lint" })
2. codemap_execute_shell({ cmd: "tsc --noEmit" })
3. codemap_execute_shell({ cmd: "npm test" })
4. All pass → ready to commit

Run full quality checklist.

💡Pro Tips

Exit code 0 = success: Check exitCode to determine success/failure
stderr not always error: Some tools write to stderr even on success
Default timeout is 30s: Override for long operations (builds, tests)
Use shell parameter for cross-platform: Explicitly set shell for PowerShell or bash-specific commands
Working directory matters: Use cwd parameter for monorepo subdirectories
Macros for common commands: Create macros for frequently-run commands

✅Best Practices

Always check exitCode to verify success
Set appropriate timeouts for long-running operations
Use macros (codemap_macro_create) for frequently-run commands
Capture stdout for processing (file lists, test output, etc.)
Run quality checks before closing sessions
Use specific shell parameter for platform-specific commands

⚠️Common Mistakes

❌ Mistake: Assuming stderr means failure
✅ Instead: Check exitCode - some tools write warnings to stderr even when successful

❌ Mistake: Using default timeout for long builds
✅ Instead: Set timeout: 60000 or higher for builds that take > 30 seconds

❌ Mistake: Running commands in wrong directory
✅ Instead: Use cwd parameter for subdirectories in monorepos

❌ Mistake: Not handling timeout errors
✅ Instead: Wrap in try/catch and handle timeout separately

❌ Mistake: Running interactive commands
✅ Instead: Only run non-interactive commands - no prompts or user input

❌ Mistake: Repeating same commands manually
✅ Instead: Create macros for frequently-run commands

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_session_audit

codemap_session_close

codemap_macro_run