tdai

tdai is an open-source CLI agent that drives software changes through a strict 3-stage workflow:

1. Stage 1 (spec -> tests): generate objective tests from a user goal.
2. Stage 2 (implementation loop): iterate code changes until tests pass.
3. Stage 3 (anti-cheat review): verify the solution is real and not test dodging.

It is built with nest-commander and deepagents.

Install

npm install
npm run build
npm link

Requirements

• Node.js 20+
• OPENAI_API_KEY set in your environment

Usage

Start interactive mode (default):

tdai

tdai start uses a rich Ink TUI when running in an interactive terminal. If TTY is unavailable (for example redirected output or CI), it automatically falls back to plain line-based logs.

Start interactive mode with an initial goal:

tdai start --goal "Add pagination to the users API"

Run once in the current directory:

tdai run --goal "Add pagination to the users API"

Apply successful sandbox changes back to your real project:

tdai run --goal "Add pagination to the users API" --apply

Target a different project and override the test command:

tdai run \
  --path /absolute/path/to/project \
  --goal "Implement CSV export for reports" \
  --test-command "npm run test:ci"

Command options

tdai start (interactive session):

• --goal: initial goal before prompt loop starts.
• --path: project root path for all runs in the session.
• --test-command: explicit test command shared across session runs.
• --max-iterations: max implementation loops per run (default: 8).
• --apply: apply successful sandbox changes to source project.
• --keep-sandbox: keep .tdai/runs/<runId>/workspace after each run.
• --model: LLM model name (default: gpt-5-codex).
• --timeout-ms: shell timeout for execute/test commands.

TUI controls during a running goal:

• x: abort current run.
• q: abort current run and quit session.

tdai run (one-shot):

• --goal: required when goal is not passed as positional arguments.
• --path: project root path (default: current working directory).
• --test-command: explicit test command.
• --max-iterations: max implementation loops (default: 8).
• --apply: apply successful sandbox changes to source project.
• --keep-sandbox: keep .tdai/runs/<runId>/workspace even after successful run.
• --model: LLM model name (default: gpt-5-codex).
• --timeout-ms: shell timeout for execute/test commands.

Sandbox behavior

Each run works inside:

<project>/.tdai/runs/<runId>/workspace

node_modules is symlinked from the source project when available to reduce startup time.

Workflow details

Stage 1

• Creates tests and writes .tdai/stage1-plan.json.
• Declares testCommand, testFiles, and rationale.

Stage 2

• Runs testCommand.
• If failing, asks the implementation agent to fix code.
• Repeats until green or max iterations.
• Protects stage-1 test files and key test config files from mutation.

Stage 3

• Performs a review pass.
• Writes .tdai/stage3-review.json with approved, findings, and rationale.

Notes

• The tool currently targets OpenAI chat models via @langchain/openai.
• If stage-1 cannot infer a runnable test command, pass --test-command explicitly.
• tdai start emits rich real-time stage progress in TUI mode.
• tdai start also shows latest DeepAgents tool/model action so long stages are visibly productive.
• tdai run emits live stage + iteration progress lines in plain text.
• Long LLM stage waits emit heartbeat progress every 10 seconds with elapsed time.
• Detailed command output remains concise by default and full failure context is printed in the final summary when tests fail.