CLI Application & Context

Relevant source files

The following files were used as context for generating this wiki page:

• src/cli/tdd-guard.test.ts
• src/cli/buildContext.test.ts
• src/validation/context/context.ts
• src/config/Config.test.ts
• CLAUDE.md
• README.md

The TDD Guard CLI application serves as the primary entry point for intercepting and validating file operations initiated by AI agents like Claude Code. It functions as a hook that captures tool calls (Edit, MultiEdit, Write), gathers environmental state, and orchestrates the validation process against Test-Driven Development (TDD) principles.

The system relies on a robust context-building mechanism that aggregates information from various sources—including pending modifications, test results, linting data, and user-defined TODOs—to provide the AI validator with a comprehensive view of the current development state. This ensures that validation decisions are grounded in the actual state of the codebase and the specific requirements of the TDD cycle.

Sources: CLAUDE.md, README.md, src/cli/tdd-guard.test.ts

CLI Entry Point & Hook Execution

The CLI is designed to be executed as a shell command, typically triggered by Claude Code hooks such as PreToolUse, UserPromptSubmit, and SessionStart. It receives hook data via standard input, which it must parse and process to determine the appropriate action.

Hook Lifecycle

When the CLI runs, it performs the following high-level sequence:

1. Data Capture: Reads JSON data from stdin representing the hook event.
2. Persistence: Saves the captured modifications or metadata to local storage for future reference.
3. Context Assembly: Gathers all relevant data (test results, previous edits) to build a validation context.
4. Validation: If the guard is enabled, it sends the context to an AI model for TDD compliance checking.
5. Feedback: Returns a decision (block or allow) and a descriptive reason to the calling agent.

Sources: README.md, src/cli/tdd-guard.test.ts:24-40, CLAUDE.md

The diagram shows the standard execution flow of the CLI application when invoked as a hook.
Sources: src/cli/tdd-guard.test.ts:24-40, CLAUDE.md

Context Building Mechanism

The buildContext and generateDynamicContext functions are responsible for transforming raw stored data into a structured format suitable for the AI validator. This process involves aggregating data from several JSON files stored in the .claude/tdd-guard/data directory.

Context Components

A complete validation context includes several key sections:

Component	Source File	Description
Modifications	modifications.json	The proposed code changes (Edit, MultiEdit, or Write).
Test Results	test.json	Captured results from the language-specific test reporter.
TODOs	todos.json	Pending or in-progress tasks that define the goal.
Lint Data	lint.json	Issues identified by linters (ESLint, golangci-lint).
Instructions	instructions.md	Custom TDD rules provided by the user.

Sources: src/cli/buildContext.test.ts:13-33, src/config/Config.test.ts:40-60, src/validation/context/context.ts:32-49

Dynamic Context Generation

The generateDynamicContext function assembles these components into a final string prompt. It applies specific formatting rules, such as pretty-printing JSON for readability and wrapping code in markdown blocks.

Sources: src/cli/buildContext.test.ts:80-100, src/validation/context/context.ts:32-49

The sequence diagram illustrates how the system pulls raw data from storage and processes it into a human-readable context.
Sources: src/cli/buildContext.test.ts:35-130, src/validation/context/context.ts:89-105

Data Persistence & Storage

The CLI manages data persistence through FileStorage, which uses a specific directory structure relative to the project root. This ensures that context is maintained across multiple hook invocations in the same session.

Directory Structure

By default, the application stores data in the following paths:

• Project Root: Determined by projectRoot config or CLAUDE_PROJECT_DIR environment variable.
• Data Directory: .claude/tdd-guard/data/.
• Modifications: modifications.json stores the current tool call input.
• Configuration: config.json stores the toggle state (enabled/disabled) and ignore patterns.

Sources: src/config/Config.test.ts:26-38, src/cli/tdd-guard.test.ts:43-63

Handling Tool Operations

The CLI specifically handles three types of tool modifications:

1. Edit: Partial modification of an existing file.
2. MultiEdit: Multiple sequential edits to a single file.
3. Write: Creation of a new file.

Sources: src/cli/tdd-guard.test.ts:65-90, src/validation/context/context.ts:52-68

Configuration & Environment

The Config class manages the application's behavior through options and environment variables. It handles paths, validation client selection, and model versioning.

Key Configuration Options

Option	Env Var	Default	Description
projectRoot	CLAUDE_PROJECT_DIR	(Relative path)	The base directory of the project.
validationClient	VALIDATION_CLIENT	cli	The client used to talk to the AI (cli, sdk, api).
modelType	MODEL_TYPE	claude_cli	Type of model being invoked.
useSystemClaude	USE_SYSTEM_CLAUDE	false	Whether to use system-installed Claude binary.

Sources: src/config/Config.test.ts:133-145, src/config/Config.test.ts:200-240, src/config/Config.test.ts:324-345

Conclusion

The CLI and Context systems form the backbone of TDD Guard's enforcement capabilities. By intercepting tool calls and synthesizing a rich, multi-dimensional context from storage, the CLI provides the necessary "eyes" for the AI validator to make informed TDD compliance decisions. This architecture allows the tool to maintain state across different phases of the TDD cycle without requiring the user to manually provide context or history.

Sources: CLAUDE.md, src/validation/context/context.ts