Claude CLI Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Claude CLI Integration serves as one of the primary validation backends for TDD Guard. It allows the system to leverage the claude command-line tool to analyze code changes and test outputs against Test-Driven Development (TDD) principles. By executing the CLI as a subprocess, TDD Guard can perform complex reasoning tasks using Anthropic's models without requiring a direct SDK connection in environments where the CLI is already configured.
This integration is encapsulated within the ClaudeCli class, which manages the construction of shell commands, subprocess execution via execFileSync, and the parsing of JSON-formatted responses from the CLI output. It supports both system-wide installations and local binary paths, ensuring flexibility across different developer setups.
Sources: src/validation/models/ClaudeCli.test.ts:31-40, src/config/Config.ts:18-28, README.md:15-25
Architecture and Command Execution
The integration operates by spawning the claude CLI as a child process. The system passes the generated TDD validation prompt through the standard input (stdin) of the process to avoid command-line length limitations and ensure security.
Command Structure
The CLI is invoked with specific flags to ensure the output is machine-readable and restricted to the validation task.
| Flag | Purpose |
|---|---|
- | Instructs the CLI to read the prompt from standard input. |
--output-format json | Forces the CLI to return results in a structured JSON format. |
--max-turns 5 | Limits the conversation depth to prevent excessive token usage. |
--model | Specifies the model to use (defaults to sonnet or as configured). |
--disallowed-tools | Blocks specific tools like TodoWrite to prevent side effects during validation. |
--strict-mcp-config | Enforces strict Model Context Protocol configuration. |
Sources: src/validation/models/ClaudeCli.test.ts:34-52, src/config/Config.ts:10-15
Execution Logic
The following diagram illustrates the flow of a validation request through the CLI integration:
The integration uses a 60-second timeout for CLI calls and executes commands from a specific .claude subdirectory to isolate the execution environment.
Sources: src/validation/models/ClaudeCli.test.ts:65-80, src/validation/context/context.ts:40-55
Configuration and Environment
The behavior of the Claude CLI integration is governed by the Config class, which resolves settings from environment variables and project-specific files.
Key Configuration Parameters
- useSystemClaude: A boolean determining whether to use the
claudecommand in the system PATH or a specific local binary path (typically~/.claude/local/claude). - validationClient: Must be set to
clito activate this specific implementation. - dataDir: The directory where TDD Guard stores temporary data, defaults to
.claude/tdd-guard/data.
Sources: src/config/Config.ts:35-50, src/config/Config.test.ts:160-180
Platform Compatibility
The integration handles cross-platform differences in subprocess execution. On Windows (win32), the shell: true option is enabled to correctly resolve the claude command, which often points to .cmd or .bat files.
Sources: src/validation/models/ClaudeCli.test.ts:98-115
Response Processing
The Claude CLI returns a JSON object where the actual model analysis is contained within a result field. TDD Guard must extract this field and further parse it to determine the TDD compliance decision.
json\n{...}\n```"}
C->>C: Parse CLI JSON
C->>C: Extract 'result' string
C-->>V: Return raw model response
V->>V: Extract Decision JSON from markdown
The system is designed to handle "complex" CLI responses where the `result` field might contain conversational text surrounding the JSON decision block.
Sources: [src/validation/models/ClaudeCli.test.ts:125-145](https://github.com/marlon-costa-dc/tdd-guard/blob/0f01104ebd2c87956467d89a63cdf7749e7d099f/src/validation/models/ClaudeCli.test.ts#L125-L145), [src/validation/validator.test.ts:40-60](https://github.com/marlon-costa-dc/tdd-guard/blob/0f01104ebd2c87956467d89a63cdf7749e7d099f/src/validation/validator.test.ts#L40-L60)
## Security Considerations
The CLI integration implements several security measures to ensure safe execution:
1. **Path Traversal Protection**: When using `CLAUDE_PROJECT_DIR`, the system validates that the path is absolute and does not contain `..` sequences.
2. **Restricted Tools**: The CLI is invoked with `--disallowed-tools` to ensure the AI model cannot perform unauthorized file system modifications or network requests during the validation phase.
3. **Execution Isolation**: Operations are performed within a `.claude` subdirectory to keep queries out of the main project history and prevent accidental hook triggers.
Sources: [src/config/Config.ts:125-145](https://github.com/marlon-costa-dc/tdd-guard/blob/0f01104ebd2c87956467d89a63cdf7749e7d099f/src/config/Config.ts#L125-L145), [src/validation/models/ClaudeCli.test.ts:45-55](https://github.com/marlon-costa-dc/tdd-guard/blob/0f01104ebd2c87956467d89a63cdf7749e7d099f/src/validation/models/ClaudeCli.test.ts#L45-L55), [README.md:270-285](https://github.com/marlon-costa-dc/tdd-guard/blob/0f01104ebd2c87956467d89a63cdf7749e7d099f/README.md#L270-L285)
## Summary
The Claude CLI Integration provides a robust, shell-based alternative to SDK-based validation. By wrapping the standard `claude` CLI tool, TDD Guard maintains high-level reasoning capabilities while respecting local environment configurations and security boundaries. It manages the full lifecycle of the AI interaction, from secure prompt delivery via stdin to the extraction of structured TDD decisions from conversational output.