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

Install • Quick Start • Agent Skills • How It Works • LLM Adoption Roadmap • Docs

---

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

Install it into a repo, then ask Codex, Claude Code, OpenCode, Cursor, Cline, Continue, Roo Code, Gemini CLI, or an MCP host to analyze the codebase and generate review-first tests. TestGen handles source scanning, framework detection, capability discovery, 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.

Agent need	What TestGen provides
Generate tests safely	Dry-run first, patch artifacts, explicit write controls
Match the repo	Detects nearby test files and adapts to existing framework, fixtures, mocks, naming, and assertions
Avoid blind edits	Agents inspect JSON results before touching files
Plan cost before API calls	Offline code analysis and provider-aware cost estimates
Work across stacks	JS/TS, Python, Go, Rust, Java, C#, PHP, Ruby, C++, and Kotlin adapters
Fit agent workflows	Codex skill, Claude command, OpenCode command, and MCP server
Help LLM hosts discover capabilities	testgen languages --output-format=json and planned capability manifests
Keep logic consistent	One shared engine across every agent integration

For the open-source roadmap that makes TestGen easier to use from LLM tools like Cursor, Cline, Continue, Roo Code, and Gemini CLI, see docs/LLM_AGENT_ADOPTION.md.

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

Cursor, Cline, Continue, Roo Code, or Gemini CLI:

curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --agent cursor
curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --agent cline
curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --agent continue
curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --agent roo
curl -fsSL https://raw.githubusercontent.com/princepal9120/testgen/main/scripts/install-agent-skill.sh | bash -s -- --agent gemini

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
• .cursor/rules/testgen.mdc
• .clinerules/testgen.md
• .continue/prompts/testgen.md
• .roo/commands/testgen.md
• GEMINI.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 doctor --path=. --output-format json
testgen capabilities --output-format json
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 doctor --path=. --output-format json
testgen capabilities --output-format json
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.