Idea in. Code out. You just watch.
lgtm --idea "Rewrite it in Rust"lgtm is an AI coding agent harness that plugs into Claude Code or OpenCode to implement your ideas. It generates a PRD, breaks it into tasks, implements each with TDD, reviews its own code, fixes issues, and commits. You review the final result.
You have Claude Code or OpenCode. They're great coding agents when you tell them what to do. But you still have to:
- Break down work into tasks
- Decide what to implement next
- Review the output
- Ask for fixes
- Repeat
lgtm is the harness that does this loop for you. It plans, implements, verifies, and commits until the PRD is done.
AI coding agent (pick one):
- Claude Code - Install and authenticate first
- OpenCode - Install and authenticate first
These do the actual coding. lgtm is the harness that orchestrates them.
Also needed:
- Go 1.23+ (for installation)
- Git
Pick one:
Go install (any OS)
go install github.com/yarlson/lgtm@latestDownload from releases (any OS)
- Go to https://github.com/yarlson/lgtm/releases
- Download the archive for your OS/arch
- Extract and move
lgtminto yourPATH
Homebrew (macOS)
brew install yarlson/homebrew-tap/lgtm# From idea (generates PRD, then implements)
lgtm --idea "your idea here"
# From existing PRD.md
lgtm┌─────────────────────────────────────────┐
│ 1. Read PRD.md + progress │
│ 2. Plan next task │
│ 3. Implement (writes code, runs tests) │
│ 4. Verify (runs task.verify commands) │
│ 5. Review + auto-fix │
│ 6. Commit │
│ 7. Loop until PRD complete │
└─────────────────────────────────────────┘
Each task goes through up to 3 retry attempts if verification fails. The AI analyzes failures and fixes them. If all retries fail, lgtm resets the workspace and re-plans with the failure recorded in .lgtm/findings.md.
Good fit:
- Greenfield features with clear requirements
- Refactoring with defined scope
- Adding tests to existing code
- Mechanical changes across many files
Not ideal:
- Exploratory work where requirements are unclear
- Performance tuning (needs human judgment)
- Security-critical code (needs human review)
| Flag | Description | Default |
|---|---|---|
--idea |
Generate PRD from idea, then implement | - |
--ask |
Pause after each task for approval | auto-run |
--force |
Skip uncommitted changes confirmation | prompt |
--provider |
AI provider to use | claude |
Input:
| File | Purpose |
|---|---|
PRD.md |
Product requirements (input) |
Generated (root):
| File | Purpose |
|---|---|
AGENTS.md |
AI agent instructions (generated if missing) |
CLAUDE.md |
Symlink to AGENTS.md (for Claude Code compatibility) |
Generated (in .lgtm/):
| File | Purpose |
|---|---|
task.yaml |
Current task specification |
progress.md |
Completed tasks checklist |
findings.md |
Learned patterns from codebase |
review.md |
Latest code review results |
logs/ |
AI session logs (for debugging) |
The .lgtm/ directory is auto-added to .gitignore.
Optional. Defaults work for most cases.
Create ~/.config/lgtm/lgtm.yaml:
provider: claude # or opencode
providers:
claude:
default: "haiku" # fast model for exploration
capable: "opus" # powerful model for implementation
opencode:
default: "anthropic/claude-haiku-4-5"
capable: "anthropic/claude-sonnet-4-5"Model strategy:
default: Used for codebase exploration, planningcapable: Used for implementation, complex reasoning, retries
lgtm expects a PRD.md file in your working directory. Format is flexible, but include:
- What you're building
- Acceptance criteria
- Constraints (if any)
Example:
# Feature: User Authentication
Add JWT-based authentication to the API.
## Requirements
- POST /login accepts email + password, returns JWT
- Protected routes require valid JWT in Authorization header
- Tokens expire after 24 hours
## Constraints
- Use existing User model
- No external auth providersThe more specific your PRD, the better the output.
"claude: command not found" or "opencode: command not found"
Install and authenticate your AI coding agent first. lgtm calls these CLIs directly.
Tasks keep failing verification
Check .lgtm/logs/ for the full AI session output. Common causes:
- Tests require dependencies not installed
- Verification commands are wrong in task.yaml
- PRD requirements are ambiguous
"uncommitted changes" prompt
lgtm warns if you have uncommitted changes (it will make commits). Use --force to skip, or commit/stash first.
Task keeps failing
After 3 failed attempts, lgtm automatically recovers: it resets the workspace (reverts uncommitted changes, removes untracked files), records the failure in .lgtm/findings.md, and re-plans the task. If the same task keeps failing, check .lgtm/findings.md for patterns and consider simplifying the PRD requirements.
For contributors working on lgtm itself.
go build ./ # build
go test -v -race -timeout=30s ./... # unit tests
golangci-lint run ./... --fix # lintRequire Claude Code or OpenCode CLI installed and authenticated:
go test -v -race -tags=integration ./internal/provider/...cmd/ # CLI entry point
internal/
agents/ # AGENTS.md generation and symlink setup
app/ # main orchestration loop
decomposer/ # PRD -> task planning
implementer/ # task -> code (TDD + verification)
reviewer/ # code review
fixer/ # auto-fix review issues
prd/ # idea -> PRD generation
provider/ # claude/opencode abstraction
workflow/ # multi-step AI session execution
setup/ # git init, gitignore setup
git/ # commit operations
progress/ # progress tracking
task/ # task.yaml parsing
config/ # user configuration
ui/ # terminal output
logs/ # session logging
Write the test first. Then implement. This is non-negotiable.
# Before committing
golangci-lint run ./... --fix
go test -v -race ./...
bunx prettier --write "**/*.md"See AGENTS.md for detailed coding conventions.
MIT