Configuration

All three tailtest plugins (Claude Code, Cursor, Codex) read the same config file:

.tailtest/config.json in your project root.

You don't need this file. Tailtest works out of the box without any configuration.

---

Options

depth

Controls how many scenarios tailtest generates per file.

Value	Scenarios	What's covered
simple	2-3	Happy path only
standard	5-8	Happy path + key edge cases (default)
thorough	10-15	Happy path + edge cases + failure modes

Example:

{
  "depth": "thorough"
}

Use simple for scaffolding-heavy sessions where you just want a sanity check. Use thorough for business-critical code (auth, billing, payment flows).

---

ramp_up_limit

How many files to queue during the initial coverage scan (first session on an existing project).

Value	Behavior
0	Disable the initial scan entirely
1-15	Queue this many files (default: 7)

Example:

{
  "ramp_up_limit": 3
}

The scan ranks files by git activity, path signal (services, models, handlers score higher), and size. The top N are queued.

---

impact_tracing

Enable Python import graph analysis. When a file is queued, tailtest walks the project AST to find which other files import it and surfaces an impact note: "Impact: billing.py is imported by checkout.py, orders.py."

Value	Behavior
false	Disabled (default)
true	Enabled (Python only)

Example:

{
  "impact_tracing": true
}

Opt-in because it walks up to 500 Python files per queued file. Has no effect on JavaScript, TypeScript, Go, or Rust files.

---

api_validation

Verify that a Python source file's public functions and classes are importable before generating tests. If the file has an import error, tailtest warns the agent: "billing.py has an import error (import error: ...). Verify imports before writing tests."

Value	Behavior
false	Disabled (default)
true	Enabled (Python only)

Example:

{
  "api_validation": true
}

Opt-in because it runs importlib.import_module for each queued Python file. Has no effect on non-Python files.

---

Ignoring files

Create .tailtest-ignore at your project root using gitignore syntax to exclude paths:

# Generated code
src/generated/
migrations/

# Test fixtures
fixtures/
test_data/

# Infrastructure
k8s/
infra/

Tailtest also automatically ignores: node_modules/, .venv/, .git/, dist/, build/, and other common build output directories.

---

Detected runners

Tailtest auto-detects test runners from project manifests. No configuration needed.

Language	Runner	Detection signal
Python	pytest	pyproject.toml
Python (async)	pytest with pytest-asyncio plugin	pytest-asyncio in pyproject deps; recorded as async_framework on the runner
TypeScript / JavaScript	vitest (default) or jest	package.json deps + scripts.test field
TypeScript / JavaScript	bun test	bun test in scripts.test OR bunfig.toml present
TypeScript	deno test	deno.json or deno.jsonc
Go	go test	go.mod
Ruby	rspec or bundle exec rake test	Gemfile
Java	./mvnw test or ./gradlew test	pom.xml or build.gradle
PHP	./vendor/bin/phpunit	composer.json + phpunit.xml
Rust	cargo test	Cargo.toml

Precedence (Node ecosystem): when multiple signals exist, the explicit scripts.test field wins over deps, which wins over bunfig.toml. Project with both bunfig.toml AND vitest in devDependencies resolves to whichever is named in the test script. If no test script is set, deps are checked, then bunfig.toml as tiebreaker.

Precedence (Node vs Deno): when both package.json and deno.json exist in the same directory, Node wins. Deno is only selected when no package.json is present.

---

Platform-specific notes

Claude Code

Config file: .tailtest/config.json

Cursor

Config file: .tailtest/config.json

Session state is separate at .cursor/hooks/state/tailtest.json. Add .cursor/hooks/state/ to your .gitignore.

Codex

Config file: .tailtest/config.json

The ramp_up_limit default for Codex is 10 (higher than Claude Code's 7, since Codex sessions tend to be longer).