testgen-cli

Agent-native test generation for Codex, Claude Code, OpenCode, and MCP

Install • Quick Start • Agent Skills • How It Works • Docs

TestGen gives coding agents a production-safe test-generation skill.

Install it into a repo, then ask Codex, Claude Code, OpenCode, or an MCP host to analyze the codebase and generate review-first tests. TestGen handles source scanning, existing-test style detection, cost-aware planning, generated test artifacts, patch output, and validation through one agent-friendly workflow.

The public product is the agent skill. The testgen binary is the local engine that the skill calls behind the scenes.

Supported languages: JavaScript/TypeScript, Python, Go, Rust, Java, C#, PHP, Ruby, C++, and Kotlin.

Why TestGen

Plain agent prompts are good for one-off test files. TestGen is for repeatable, production-grade test generation inside real repos.

Why not just ask Claude or Codex directly?

You still use Claude, Codex, or OpenCode. TestGen gives them a dedicated workflow instead of a loose prompt:

• analyze first, so the agent knows what files and functions exist
• reuse existing tests as style context, so output fits the repo
• dry-run patches before writes, so changes are reviewable
• report token and cost usage, so large repos stay controlled
• validate generated tests through the local project toolchain

Installation

1. Install the TestGen engine

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/princepal9120/testgen/main/install.ps1 | iex

Go install alternative:

go install github.com/princepal9120/testgen-cli@latest

2. Install the agent skill into your repo

From inside the repo you want your agent to work on:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash

If you cloned the repo, you can use the shorter local entrypoint:

./skills.sh --agent all

Skills CLI install alternative:

npx skills add princepal9120/testgen@testgen

Codex only:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --agent codex

Claude Code only:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --agent claude

OpenCode only:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --agent opencode

Install into another repo:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --target /path/to/repo --agent all

Installed files:

• .codex/skills/testgen/SKILL.md
• .claude/commands/testgen.md
• .opencode/commands/testgen.md

3. Set one provider key

export ANTHROPIC_API_KEY="..."
# or OPENAI_API_KEY / GEMINI_API_KEY / GROQ_API_KEY

Quick Start

Ask your coding agent:

Use TestGen to analyze this repo and generate review-first unit tests for ./src.
Do not write files until you inspect the dry-run patch.

For a single file:

Use TestGen to create unit tests for ./src/utils.py.
Start with a dry-run patch, then validate the generated test after review.

For a larger repo:

Use TestGen to estimate test generation cost for ./src first.
Then generate review-first patches folder by folder.

The agent skill will run the safe flow:

testgen cost --path=./src --output-format json
testgen generate --path=./src --recursive --type=unit --dry-run --emit-patch --report-usage --output-format json

Friendly command aliases and capability discovery are included for agent and human workflows:

testgen testcase --file=./src/utils.py --dry-run --emit-patch
testgen comparison --path=./src
testgen languages --output-format json

Then it writes only when approved or explicitly requested:

testgen generate --path=./src --recursive --type=unit --validate --output-format json

Agent Skills

Skills CLI

TestGen is also packaged as a standard agent skill at skills/testgen/SKILL.md:

npx skills add princepal9120/testgen@testgen

Codex

TestGen installs a repo-local skill at:

.codex/skills/testgen/SKILL.md

Codex uses this skill when you ask for AI-generated tests, dry-run patches, test coverage improvement, or validation.

Claude Code

TestGen installs a command wrapper at:

.claude/commands/testgen.md

Use it when you want Claude Code to run the same review-first generation flow.

OpenCode

TestGen installs a command wrapper at:

.opencode/commands/testgen.md

Use it for the same agent-safe workflow in OpenCode.

MCP

Run the MCP server for MCP-compatible hosts:

testgen mcp

Print a config snippet from the TestGen repo:

./scripts/print-mcp-config.sh testgen

How It Works

Coding agent
     |
     v
TestGen skill or command wrapper
     |
     v
Local TestGen engine
     |
     +--> estimate cost with testgen cost
     +--> generate dry-run test artifacts with testgen generate/testcase
     +--> compare plain LLM vs TestGen skill with testgen comparison
     +--> emit structured patches
     +--> validate generated tests when writing is allowed
     |
     v
Agent reviews JSON, explains the patch, then applies changes

Four principles guide the workflow:

1. Agent-first onboarding. Users install a skill into their repo and talk to their agent.
2. Review before write. Dry-run and patch artifacts come before file edits.
3. Machine-readable by default. Agents get JSON results, artifacts, patches, usage, and errors.
4. One engine, many agents. Codex, Claude Code, OpenCode, and MCP all use the same behavior.

Upgrade

Update the local engine:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/install.sh | bash

Refresh the repo-local agent skill:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash

Documentation

• Agent integrations
• Codex integration
• Claude Code integration
• OpenCode integration
• MCP integration
• Architecture
• Release and distribution guide

License

Apache 2.0. See LICENSE.