popeye-cli 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/.env.example +24 -1
  2. package/CONTRIBUTING.md +275 -0
  3. package/OPEN_SOURCE_MANIFESTO.md +172 -0
  4. package/README.md +340 -27
  5. package/dist/adapters/claude.d.ts +28 -2
  6. package/dist/adapters/claude.d.ts.map +1 -1
  7. package/dist/adapters/claude.js +273 -20
  8. package/dist/adapters/claude.js.map +1 -1
  9. package/dist/adapters/grok.d.ts +73 -0
  10. package/dist/adapters/grok.d.ts.map +1 -0
  11. package/dist/adapters/grok.js +430 -0
  12. package/dist/adapters/grok.js.map +1 -0
  13. package/dist/adapters/openai.d.ts +1 -1
  14. package/dist/adapters/openai.d.ts.map +1 -1
  15. package/dist/adapters/openai.js +6 -1
  16. package/dist/adapters/openai.js.map +1 -1
  17. package/dist/auth/grok.d.ts +73 -0
  18. package/dist/auth/grok.d.ts.map +1 -0
  19. package/dist/auth/grok.js +211 -0
  20. package/dist/auth/grok.js.map +1 -0
  21. package/dist/auth/index.d.ts +9 -6
  22. package/dist/auth/index.d.ts.map +1 -1
  23. package/dist/auth/index.js +23 -6
  24. package/dist/auth/index.js.map +1 -1
  25. package/dist/cli/commands/auth.d.ts +1 -1
  26. package/dist/cli/commands/auth.d.ts.map +1 -1
  27. package/dist/cli/commands/auth.js +79 -8
  28. package/dist/cli/commands/auth.js.map +1 -1
  29. package/dist/cli/commands/create.d.ts.map +1 -1
  30. package/dist/cli/commands/create.js +15 -4
  31. package/dist/cli/commands/create.js.map +1 -1
  32. package/dist/cli/interactive.d.ts.map +1 -1
  33. package/dist/cli/interactive.js +406 -35
  34. package/dist/cli/interactive.js.map +1 -1
  35. package/dist/config/defaults.d.ts +3 -0
  36. package/dist/config/defaults.d.ts.map +1 -1
  37. package/dist/config/defaults.js +9 -0
  38. package/dist/config/defaults.js.map +1 -1
  39. package/dist/config/index.d.ts +9 -0
  40. package/dist/config/index.d.ts.map +1 -1
  41. package/dist/config/index.js +16 -3
  42. package/dist/config/index.js.map +1 -1
  43. package/dist/config/schema.d.ts +27 -0
  44. package/dist/config/schema.d.ts.map +1 -1
  45. package/dist/config/schema.js +24 -3
  46. package/dist/config/schema.js.map +1 -1
  47. package/dist/generators/fullstack.d.ts +32 -0
  48. package/dist/generators/fullstack.d.ts.map +1 -0
  49. package/dist/generators/fullstack.js +497 -0
  50. package/dist/generators/fullstack.js.map +1 -0
  51. package/dist/generators/index.d.ts +4 -3
  52. package/dist/generators/index.d.ts.map +1 -1
  53. package/dist/generators/index.js +15 -1
  54. package/dist/generators/index.js.map +1 -1
  55. package/dist/generators/python.d.ts +17 -1
  56. package/dist/generators/python.d.ts.map +1 -1
  57. package/dist/generators/python.js +34 -21
  58. package/dist/generators/python.js.map +1 -1
  59. package/dist/generators/templates/fullstack.d.ts +113 -0
  60. package/dist/generators/templates/fullstack.d.ts.map +1 -0
  61. package/dist/generators/templates/fullstack.js +1004 -0
  62. package/dist/generators/templates/fullstack.js.map +1 -0
  63. package/dist/generators/typescript.d.ts +19 -1
  64. package/dist/generators/typescript.d.ts.map +1 -1
  65. package/dist/generators/typescript.js +37 -21
  66. package/dist/generators/typescript.js.map +1 -1
  67. package/dist/types/cli.d.ts +4 -0
  68. package/dist/types/cli.d.ts.map +1 -1
  69. package/dist/types/cli.js.map +1 -1
  70. package/dist/types/consensus.d.ts +119 -2
  71. package/dist/types/consensus.d.ts.map +1 -1
  72. package/dist/types/consensus.js +12 -1
  73. package/dist/types/consensus.js.map +1 -1
  74. package/dist/types/project.d.ts +76 -0
  75. package/dist/types/project.d.ts.map +1 -1
  76. package/dist/types/project.js +1 -1
  77. package/dist/types/project.js.map +1 -1
  78. package/dist/types/workflow.d.ts +170 -16
  79. package/dist/types/workflow.d.ts.map +1 -1
  80. package/dist/types/workflow.js +26 -3
  81. package/dist/types/workflow.js.map +1 -1
  82. package/dist/workflow/consensus.d.ts +29 -3
  83. package/dist/workflow/consensus.d.ts.map +1 -1
  84. package/dist/workflow/consensus.js +334 -27
  85. package/dist/workflow/consensus.js.map +1 -1
  86. package/dist/workflow/execution-mode.d.ts +2 -0
  87. package/dist/workflow/execution-mode.d.ts.map +1 -1
  88. package/dist/workflow/execution-mode.js +20 -0
  89. package/dist/workflow/execution-mode.js.map +1 -1
  90. package/dist/workflow/index.d.ts +2 -0
  91. package/dist/workflow/index.d.ts.map +1 -1
  92. package/dist/workflow/index.js +11 -0
  93. package/dist/workflow/index.js.map +1 -1
  94. package/dist/workflow/milestone-workflow.d.ts +2 -0
  95. package/dist/workflow/milestone-workflow.d.ts.map +1 -1
  96. package/dist/workflow/milestone-workflow.js +19 -2
  97. package/dist/workflow/milestone-workflow.js.map +1 -1
  98. package/dist/workflow/plan-mode.d.ts +66 -2
  99. package/dist/workflow/plan-mode.d.ts.map +1 -1
  100. package/dist/workflow/plan-mode.js +187 -11
  101. package/dist/workflow/plan-mode.js.map +1 -1
  102. package/dist/workflow/plan-storage.d.ts +252 -8
  103. package/dist/workflow/plan-storage.d.ts.map +1 -1
  104. package/dist/workflow/plan-storage.js +580 -33
  105. package/dist/workflow/plan-storage.js.map +1 -1
  106. package/dist/workflow/project-verification.js +1 -1
  107. package/dist/workflow/project-verification.js.map +1 -1
  108. package/dist/workflow/task-workflow.d.ts +2 -0
  109. package/dist/workflow/task-workflow.d.ts.map +1 -1
  110. package/dist/workflow/task-workflow.js +23 -1
  111. package/dist/workflow/task-workflow.js.map +1 -1
  112. package/dist/workflow/test-runner.d.ts +8 -0
  113. package/dist/workflow/test-runner.d.ts.map +1 -1
  114. package/dist/workflow/test-runner.js +92 -0
  115. package/dist/workflow/test-runner.js.map +1 -1
  116. package/dist/workflow/workspace-manager.d.ts +342 -0
  117. package/dist/workflow/workspace-manager.d.ts.map +1 -0
  118. package/dist/workflow/workspace-manager.js +733 -0
  119. package/dist/workflow/workspace-manager.js.map +1 -0
  120. package/package.json +1 -1
  121. package/src/adapters/claude.ts +322 -25
  122. package/src/adapters/grok.ts +492 -0
  123. package/src/adapters/openai.ts +8 -2
  124. package/src/auth/grok.ts +255 -0
  125. package/src/auth/index.ts +27 -9
  126. package/src/cli/commands/auth.ts +89 -10
  127. package/src/cli/commands/create.ts +13 -4
  128. package/src/cli/interactive.ts +453 -34
  129. package/src/config/defaults.ts +9 -0
  130. package/src/config/index.ts +17 -3
  131. package/src/config/schema.ts +25 -3
  132. package/src/generators/fullstack.ts +551 -0
  133. package/src/generators/index.ts +25 -1
  134. package/src/generators/python.ts +65 -21
  135. package/src/generators/templates/fullstack.ts +1047 -0
  136. package/src/generators/typescript.ts +69 -21
  137. package/src/types/cli.ts +4 -0
  138. package/src/types/consensus.ts +135 -3
  139. package/src/types/project.ts +82 -1
  140. package/src/types/workflow.ts +58 -4
  141. package/src/workflow/consensus.ts +461 -31
  142. package/src/workflow/execution-mode.ts +32 -0
  143. package/src/workflow/index.ts +12 -0
  144. package/src/workflow/milestone-workflow.ts +24 -2
  145. package/src/workflow/plan-mode.ts +238 -10
  146. package/src/workflow/plan-storage.ts +835 -35
  147. package/src/workflow/project-verification.ts +1 -1
  148. package/src/workflow/task-workflow.ts +29 -1
  149. package/src/workflow/test-runner.ts +110 -0
  150. package/src/workflow/workspace-manager.ts +912 -0
package/README.md CHANGED
@@ -1,7 +1,16 @@
1
1
  # Popeye CLI
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/popeye-cli.svg)](https://www.npmjs.com/package/popeye-cli)
4
+ [![npm downloads](https://img.shields.io/npm/dm/popeye-cli.svg)](https://www.npmjs.com/package/popeye-cli)
5
+
3
6
  A fully autonomous code generation tool that transforms your ideas into complete, tested, deployable code projects using AI-powered planning, consensus, and implementation.
4
7
 
8
+ ## Quick Install
9
+
10
+ ```bash
11
+ npm install -g popeye-cli
12
+ ```
13
+
5
14
  ## What is Popeye?
6
15
 
7
16
  Popeye is an autonomous software development agent that takes a simple project idea and builds it into a fully functional codebase. Unlike traditional code assistants that require constant guidance, Popeye operates autonomously through a structured workflow:
@@ -68,8 +77,148 @@ Popeye uses multiple AI systems that must agree before implementation begins:
68
77
  - **Claude (via Claude Agent SDK)**: Primary code execution engine that generates plans, implements code, and runs tests
69
78
  - **OpenAI GPT-4** (default reviewer): Evaluates plans for completeness, feasibility, and quality
70
79
  - **Google Gemini** (optional): Can be configured as reviewer or arbitrator when consensus gets stuck
80
+ - **xAI Grok** (optional): Can be configured as reviewer or arbitrator as an alternative to Gemini
81
+
82
+ Plans are iteratively refined until systems reach **95%+ consensus**, ensuring well-thought-out implementations. When consensus cannot be reached, an arbitrator (configurable) makes the final decision.
83
+
84
+ ---
85
+
86
+ ## The AI Development Team Model
87
+
88
+ Popeye is built around a simple belief:
89
+
90
+ > **One AI writing code is dangerous. Multiple AIs disagreeing, reviewing, and resolving conflict is powerful.**
91
+
92
+ Instead of a single "genius" model, Popeye operates as a **virtual AI development team**, each role with a clear responsibility.
93
+
94
+ Every decision is recorded. Every disagreement is traceable. Nothing happens silently.
95
+
96
+ ### The Three Roles
97
+
98
+ #### 1. Planner & Builder (The Implementer)
99
+
100
+ This role is responsible for **moving from idea to code**.
101
+
102
+ It:
103
+ - expands your idea into a full technical specification
104
+ - proposes architecture and project structure
105
+ - generates backend, frontend, configs, and tests
106
+ - makes concrete implementation choices
107
+
108
+ Think of this role as:
109
+ > *A senior engineer translating product intent into working software.*
110
+
111
+ #### 2. Reviewer (The Skeptic)
112
+
113
+ This role **does not write code**. Its job is to **challenge it**.
114
+
115
+ It:
116
+ - reviews the spec for gaps, contradictions, or risky assumptions
117
+ - checks generated code for correctness, maintainability, and structure
118
+ - looks for missing edge cases and test coverage
119
+ - flags anything that "works" but shouldn't ship
120
+
121
+ Think of this role as:
122
+ > *A strict code reviewer who wasn't emotionally attached to the solution.*
123
+
124
+ #### 3. Arbitrator (The Tie-Breaker)
125
+
126
+ When the Planner and Reviewer disagree, Popeye does **not** pick randomly.
127
+
128
+ The Arbitrator:
129
+ - evaluates both sides' arguments
130
+ - weighs correctness, simplicity, safety, and scope
131
+ - makes a final decision when consensus cannot be reached
132
+ - documents *why* the decision was made
133
+
134
+ Think of this role as:
135
+ > *A tech lead making the call after a heated design review.*
136
+
137
+ ### How the Loop Works
138
+
139
+ ```
140
+ 1. You describe your idea
141
+ 2. Planner generates a spec and implementation
142
+ 3. Reviewer audits the plan and code
143
+ 4. If the Reviewer approves → continue
144
+ 5. If the Reviewer objects → feedback is sent back
145
+ 6. If disagreement persists → Arbitrator decides
146
+ 7. Final decision is applied and logged
147
+ ```
148
+
149
+ No silent overrides. No "AI magic happened here".
150
+
151
+ ### Everything Is Recorded
152
+
153
+ Popeye keeps a **paper trail**.
154
+
155
+ For each project, it records:
156
+ - the original user intent
157
+ - the expanded specification
158
+ - reviewer feedback
159
+ - arbitration decisions
160
+ - applied fixes and changes
161
+
162
+ This makes the system:
163
+ - debuggable
164
+ - auditable
165
+ - explainable
166
+ - reproducible
167
+
168
+ You can always answer: *"Why was this built this way?"*
169
+
170
+ ### Why This Matters
171
+
172
+ Most AI code generators fail because:
173
+ - they don't question themselves
174
+ - they optimize for speed over correctness
175
+ - they hide mistakes behind confidence
176
+
177
+ Popeye assumes:
178
+ - first drafts are wrong
179
+ - disagreement is healthy
180
+ - quality emerges from review, not generation
181
+
182
+ This is how real engineering teams work. Popeye simply encodes that discipline into software.
183
+
184
+ ### Not Perfect — Intentionally Transparent
185
+
186
+ The AI team can:
187
+ - miss edge cases
188
+ - argue poorly
189
+ - make suboptimal calls
71
190
 
72
- Plans are iteratively refined until systems reach **95%+ consensus**, ensuring well-thought-out implementations. When consensus cannot be reached, an arbitrator (Gemini by default) makes the final decision.
191
+ That's why:
192
+ - logs are visible
193
+ - prompts are editable
194
+ - decisions are inspectable
195
+ - contributors can improve the process itself
196
+
197
+ You're not just reviewing code — you're reviewing **how decisions are made**.
198
+
199
+ ### An Open Experiment
200
+
201
+ Popeye is not claiming:
202
+ > "This is how AI development *must* work."
203
+
204
+ It's saying:
205
+ > "This is one honest attempt — in the open."
206
+
207
+ If you believe there should be more roles, better arbitration logic, stronger review heuristics, or domain-specific reviewers — you can build them. The AI team is **part of the product**, not a black box.
208
+
209
+ ### Where This Can Go
210
+
211
+ Over time, Popeye can evolve into:
212
+ - specialized reviewers (security, performance, UX)
213
+ - human-in-the-loop arbitration
214
+ - configurable team topologies
215
+ - per-project governance rules
216
+
217
+ But it starts with one principle:
218
+
219
+ > **AI should argue before it commits.**
220
+
221
+ ---
73
222
 
74
223
  ## Prerequisites
75
224
 
@@ -108,6 +257,7 @@ claude --version
108
257
  | **OpenAI API Key** | Yes | Plan review and consensus (default reviewer) |
109
258
  | **Claude Auth** | Yes | Code generation (via Claude Code CLI) |
110
259
  | **Gemini API Key** | Optional | Alternative reviewer or arbitrator |
260
+ | **Grok API Key** | Optional | Alternative reviewer or arbitrator (xAI) |
111
261
 
112
262
  ## Installation
113
263
 
@@ -146,6 +296,9 @@ popeye auth openai
146
296
 
147
297
  # Set up Gemini API key (optional - for arbitration or alternative reviewer)
148
298
  popeye auth gemini
299
+
300
+ # Set up Grok API key (optional - alternative to Gemini)
301
+ popeye auth grok
149
302
  ```
150
303
 
151
304
  ### 2. Create a Project
@@ -156,6 +309,9 @@ popeye create "A REST API for managing todo items with SQLite storage" --languag
156
309
 
157
310
  # Create a TypeScript project
158
311
  popeye create "A React component library for data visualization" --language typescript
312
+
313
+ # Create a Fullstack project (React frontend + FastAPI backend)
314
+ popeye create "A task management app with user authentication" --language fullstack
159
315
  ```
160
316
 
161
317
  ### 3. Monitor Progress
@@ -190,7 +346,7 @@ Popeye provides real-time feedback:
190
346
 
191
347
  - **Fully Autonomous**: Runs from idea to complete project without manual intervention
192
348
  - **Dual-AI Consensus**: Plans validated by multiple AI systems before execution
193
- - **Multi-Language Support**: Generate projects in Python or TypeScript
349
+ - **Multi-Language Support**: Generate projects in Python, TypeScript, or Fullstack (React + FastAPI)
194
350
  - **Automatic Testing**: Tests are generated and run for each implementation
195
351
  - **Error Recovery**: Failed tests trigger automatic fix attempts (up to 3 retries)
196
352
  - **Auto-Generated README**: At project completion, generates a comprehensive README with:
@@ -222,6 +378,36 @@ Popeye automatically handles all UI/UX decisions, eliminating the need for manua
222
378
 
223
379
  The UI design specification is saved to `.popeye/ui-spec.json` and is used to guide all code generation, ensuring consistent styling throughout the project.
224
380
 
381
+ ### Fullstack Project Support
382
+
383
+ Popeye supports generating complete fullstack applications with coordinated frontend and backend development:
384
+
385
+ - **Frontend Stack**: React 18 + Vite 5 + TypeScript + Tailwind CSS + shadcn/ui + Vitest
386
+ - **Backend Stack**: FastAPI (Python) + PostgreSQL
387
+ - **Monorepo Structure**: `apps/frontend/` and `apps/backend/` directories
388
+ - **App-Aware Planning**: Tasks are tagged with `[FE]`, `[BE]`, or `[INT]` for frontend, backend, and integration work
389
+ - **Coordinated Development**: Plans ensure proper sequencing of frontend and backend tasks
390
+ - **Integration Testing**: Dedicated integration tasks ensure frontend and backend work together
391
+
392
+ Example fullstack task in a plan:
393
+ ```markdown
394
+ #### Task 1.1 [FE]: Create user login form
395
+ **App**: frontend
396
+ **Files**:
397
+ - `apps/frontend/src/components/LoginForm.tsx`
398
+ - `apps/frontend/src/pages/Login.tsx`
399
+
400
+ #### Task 1.2 [BE]: Implement authentication endpoint
401
+ **App**: backend
402
+ **Files**:
403
+ - `apps/backend/src/api/routes/auth.py`
404
+ - `apps/backend/src/models/user.py`
405
+
406
+ #### Task 1.3 [INT]: Connect login form to auth API
407
+ **App**: unified
408
+ **Dependencies**: Task 1.1, Task 1.2
409
+ ```
410
+
225
411
  ### Reliability Features
226
412
 
227
413
  - **Rate Limit Handling**: Automatically waits and retries when API rate limits are hit
@@ -229,14 +415,22 @@ The UI design specification is saved to `.popeye/ui-spec.json` and is used to gu
229
415
  - Distinguishes actual rate limit errors from plan content mentioning "rate limits"
230
416
  - Parses reset times from error messages (e.g., "resets 3pm")
231
417
  - Extracts clean error messages without including extraneous plan content
232
- - Configurable wait times (default: 5 min base, 2 hour max)
233
- - Up to 5 retry attempts before failing
418
+ - Configurable wait times (default: 1 min base, **10 min max**)
419
+ - Up to 3 retry attempts before failing gracefully
420
+ - **Capped wait time**: Will not wait longer than 10 minutes; fails with helpful message if reset time is too far
234
421
  - Progress updates during wait periods
235
422
 
236
423
  - **Resume Capability**: Resume interrupted projects from where they left off
237
424
  - State persisted in `.popeye/state.json`
238
425
  - Tracks completed milestones and tasks
239
426
  - Survives crashes, rate limits, and manual interruptions
427
+ - Automatically loads `popeye.md` configuration on resume
428
+
429
+ - **Smart Project Naming**: Generates meaningful project names from your idea
430
+ - Detects explicit project names (e.g., "planning Gateco" becomes `gateco`)
431
+ - Recognizes CamelCase names (e.g., "TodoMaster" becomes `todo-master`)
432
+ - Filters out action verbs like "read", "start", "planning"
433
+ - Falls back to extracting key nouns from the description
240
434
 
241
435
  - **Plan File Extraction**: Handles various Claude response formats
242
436
  - Detects when Claude saves plans to `~/.claude/plans/`
@@ -354,18 +548,80 @@ popeye
354
548
 
355
549
  **Available Commands:**
356
550
  ```
357
- /help Show available commands
358
- /create <idea> Start a new project
359
- /status Check current project status
360
- /resume Resume interrupted project
361
- /auth Manage authentication
362
- /config View/edit configuration
363
- /exit Exit interactive mode
551
+ /help Show available commands
552
+ /create <idea> Start a new project
553
+ /new <idea> Force create new project (skips existing check)
554
+ /status Check current project status
555
+ /resume Resume interrupted project
556
+ /auth Manage authentication
557
+ /config View/edit configuration
558
+ /config reviewer <ai> Set reviewer (openai/gemini/grok)
559
+ /config arbitrator <ai> Set arbitrator (openai/gemini/grok/off)
560
+ /lang <lang> Set language (py/ts/fs or python/typescript/fullstack)
561
+ /info Show system info (Claude CLI status, API keys, etc.)
562
+ /clear Clear screen
563
+ /exit Exit interactive mode
364
564
  ```
365
565
 
566
+ **Language Shortcuts:**
567
+ - `/lang py` or `/lang python` - Python projects
568
+ - `/lang ts` or `/lang typescript` - TypeScript projects
569
+ - `/lang fs` or `/lang fullstack` - Fullstack projects (React + FastAPI)
570
+
571
+ **Status Bar Indicators:**
572
+ The input box shows current configuration:
573
+ - Language: `py`, `ts`, or `fs`
574
+ - Reviewer: `O` (OpenAI), `G` (Gemini), or `X` (Grok)
575
+ - Arbitrator: `O`, `G`, `X`, or `-` (disabled)
576
+ - Auth status: Filled circle when all required APIs are authenticated
577
+
578
+ ## Configuration
579
+
580
+ ### Project Configuration File (`popeye.md`)
581
+
582
+ When you create a new project, Popeye automatically generates a `popeye.md` file in the project directory. This file:
583
+
584
+ - **Persists project settings**: Language, reviewer, and arbitrator choices are saved
585
+ - **Auto-loads on resume**: When you resume a project, settings are restored automatically
586
+ - **Contains project notes**: Add guidance or context for Claude in the Notes section
587
+ - **Tracks session history**: Records when the project was created and last accessed
588
+
589
+ **Example `popeye.md`:**
590
+ ```markdown
591
+ ---
592
+ # Popeye Project Configuration
593
+ language: fullstack
594
+ reviewer: openai
595
+ arbitrator: gemini
596
+ created: 2024-01-15T10:30:00.000Z
597
+ lastRun: 2024-01-15T14:45:00.000Z
598
+ projectName: task-manager
599
+ ---
600
+
601
+ # task-manager
602
+
603
+ ## Description
604
+ A task management app with user authentication and real-time updates.
605
+
606
+ ## Notes
607
+ Add any guidance or notes for Claude here...
608
+ - Focus on simplicity
609
+ - Use PostgreSQL for the database
610
+ - Include dark mode support
611
+
366
612
  ## Configuration
613
+ - **Language**: fullstack
614
+ - **Reviewer**: openai
615
+ - **Arbitrator**: gemini
367
616
 
368
- ### Configuration File
617
+ ## Session History
618
+ - 2024-01-15: Project created
619
+ - 2024-01-15: Last session
620
+ ```
621
+
622
+ This means you no longer need to run `/lang fullstack` every time you resume a project - the configuration is automatically restored.
623
+
624
+ ### Global Configuration File
369
625
 
370
626
  Create `popeye.config.yaml` in your project or `~/.popeye/config.yaml` globally:
371
627
 
@@ -374,8 +630,8 @@ Create `popeye.config.yaml` in your project or `~/.popeye/config.yaml` globally:
374
630
  consensus:
375
631
  threshold: 95 # Minimum agreement percentage
376
632
  max_iterations: 10 # Max revision rounds
377
- reviewer: openai # Primary reviewer (openai or gemini)
378
- arbitrator: gemini # Arbitrator when stuck (openai or gemini)
633
+ reviewer: openai # Primary reviewer (openai, gemini, or grok)
634
+ arbitrator: gemini # Arbitrator when stuck (openai, gemini, grok, or off)
379
635
  enable_arbitration: true # Enable automatic arbitration
380
636
  arbitration_threshold: 85 # Score threshold to trigger arbitration
381
637
  stuck_iterations: 3 # Iterations without improvement before arbitration
@@ -392,11 +648,11 @@ apis:
392
648
  temperature: 0.3
393
649
  max_tokens: 4096
394
650
 
395
- # Rate limit settings (new)
651
+ # Rate limit settings
396
652
  rateLimit:
397
- maxRetries: 5 # Max retry attempts
398
- baseWaitMs: 300000 # 5 minutes base wait
399
- maxWaitMs: 7200000 # 2 hours max wait
653
+ maxRetries: 3 # Max retry attempts
654
+ baseWaitMs: 60000 # 1 minute base wait
655
+ maxWaitMs: 600000 # 10 minutes max wait (capped to prevent long waits)
400
656
 
401
657
  # Project defaults
402
658
  project:
@@ -422,17 +678,19 @@ POPEYE_OPENAI_MODEL=gpt-4o # OpenAI model
422
678
  POPEYE_GEMINI_MODEL=gemini-2.0-flash # Gemini model
423
679
  POPEYE_CONSENSUS_THRESHOLD=95 # Consensus threshold (0-100)
424
680
  POPEYE_MAX_ITERATIONS=10 # Max iterations before escalation
425
- POPEYE_REVIEWER=openai # Primary reviewer (openai or gemini)
426
- POPEYE_ARBITRATOR=gemini # Arbitrator (openai or gemini)
681
+ POPEYE_REVIEWER=openai # Primary reviewer (openai, gemini, or grok)
682
+ POPEYE_ARBITRATOR=gemini # Arbitrator (openai, gemini, grok, or off)
683
+ POPEYE_GROK_KEY=... # Grok API key (optional)
427
684
  POPEYE_LOG_LEVEL=debug # Enable verbose logging
428
685
  ```
429
686
 
430
687
  ### Configuration Priority
431
688
 
432
689
  1. Environment variables (highest)
433
- 2. Project-level `popeye.config.yaml` or `.popeyerc.yaml`
434
- 3. Global `~/.popeye/config.yaml`
435
- 4. Built-in defaults (lowest)
690
+ 2. Project-level `popeye.md` (for language, reviewer, arbitrator)
691
+ 3. Project-level `popeye.config.yaml` or `.popeyerc.yaml`
692
+ 4. Global `~/.popeye/config.yaml`
693
+ 5. Built-in defaults (lowest)
436
694
 
437
695
  ## Generated Project Structure
438
696
 
@@ -455,6 +713,7 @@ my-project/
455
713
  ├── .gitignore
456
714
  ├── .env.example
457
715
  ├── Dockerfile
716
+ ├── popeye.md # Project configuration (auto-generated)
458
717
  └── .popeye/
459
718
  └── state.json # Project state
460
719
  ```
@@ -493,11 +752,59 @@ my-project/
493
752
  ├── .gitignore
494
753
  ├── .env.example
495
754
  ├── Dockerfile
755
+ ├── popeye.md # Project configuration (auto-generated)
496
756
  └── .popeye/
497
757
  ├── state.json # Project state
498
758
  └── ui-spec.json # UI design specification
499
759
  ```
500
760
 
761
+ ### Fullstack Projects
762
+
763
+ ```
764
+ my-project/
765
+ ├── apps/
766
+ │ ├── frontend/ # React + Vite frontend
767
+ │ │ ├── src/
768
+ │ │ │ ├── components/
769
+ │ │ │ │ └── ui/ # shadcn/ui components
770
+ │ │ │ ├── pages/
771
+ │ │ │ ├── hooks/
772
+ │ │ │ ├── lib/
773
+ │ │ │ │ └── utils.ts
774
+ │ │ │ ├── index.css
775
+ │ │ │ └── main.tsx
776
+ │ │ ├── tests/
777
+ │ │ │ └── setup.ts # Vitest setup
778
+ │ │ ├── tailwind.config.ts
779
+ │ │ ├── vite.config.ts
780
+ │ │ ├── vitest.config.ts
781
+ │ │ └── package.json
782
+ │ │
783
+ │ └── backend/ # FastAPI backend
784
+ │ ├── src/
785
+ │ │ ├── api/
786
+ │ │ │ └── routes/
787
+ │ │ ├── models/
788
+ │ │ ├── services/
789
+ │ │ └── main.py
790
+ │ ├── tests/
791
+ │ │ └── conftest.py
792
+ │ ├── pyproject.toml
793
+ │ └── requirements.txt
794
+
795
+ ├── docs/
796
+ │ ├── PLAN.md # Development plan with [FE], [BE], [INT] tags
797
+ │ └── WORKFLOW_LOG.md
798
+ ├── README.md
799
+ ├── .gitignore
800
+ ├── .env.example
801
+ ├── docker-compose.yml # Full stack orchestration
802
+ ├── popeye.md # Project configuration
803
+ └── .popeye/
804
+ ├── state.json
805
+ └── ui-spec.json
806
+ ```
807
+
501
808
  ## UI Design System
502
809
 
503
810
  Popeye automatically generates a complete UI design system for frontend projects. The design decisions are based on analyzing your project idea and are fully customizable.
@@ -568,11 +875,14 @@ The UI specification is automatically injected into Claude's context when genera
568
875
 
569
876
  If you see "You've hit your limit" errors:
570
877
 
571
- 1. **Automatic Handling**: Popeye automatically waits and retries (up to 5 times)
572
- 2. **Manual Resume**: If Popeye exits, use `popeye resume` to continue
573
- 3. **Check Limits**: Verify your API usage at:
878
+ 1. **Automatic Handling**: Popeye automatically waits and retries (up to 3 times)
879
+ 2. **Capped Wait Time**: If the reset time is more than 10 minutes away, Popeye will fail gracefully with a "Please try again later" message instead of waiting for hours
880
+ 3. **Manual Resume**: If Popeye exits, use `popeye resume` to continue
881
+ 4. **Check Limits**: Verify your API usage at:
574
882
  - Claude: https://console.anthropic.com
575
883
  - OpenAI: https://platform.openai.com/usage
884
+ - Gemini: https://console.cloud.google.com
885
+ - Grok: https://console.x.ai
576
886
 
577
887
  ### Plan Validation Failures
578
888
 
@@ -582,6 +892,8 @@ If plans fail validation:
582
892
  2. Ensure your idea is clear and specific enough
583
893
  3. Try rephrasing your project description
584
894
 
895
+ **Note on False Positives**: Plan validation has been improved to avoid false positives. Phrases like "data is saved to database" in plan content no longer trigger garbage plan detection. Only actual meta-commentary (e.g., Claude describing what it did rather than outputting the plan) triggers validation failures.
896
+
585
897
  ### Authentication Issues
586
898
 
587
899
  ```bash
@@ -638,7 +950,8 @@ src/
638
950
  ├── adapters/ # AI service adapters
639
951
  │ ├── claude.ts # Claude Agent SDK (with rate limiting)
640
952
  │ ├── openai.ts # OpenAI API (default reviewer)
641
- └── gemini.ts # Google Gemini API (reviewer/arbitrator)
953
+ ├── gemini.ts # Google Gemini API (reviewer/arbitrator)
954
+ │ └── grok.ts # xAI Grok API (reviewer/arbitrator)
642
955
  ├── auth/ # Authentication
643
956
  │ ├── keychain.ts # Credential storage
644
957
  │ └── server.ts # OAuth callback server
@@ -6,6 +6,10 @@ import { type SDKMessage } from '@anthropic-ai/claude-agent-sdk';
6
6
  /**
7
7
  * Options for executing a prompt through Claude
8
8
  */
9
+ /**
10
+ * User's choice when rate limit wait time exceeds maximum
11
+ */
12
+ export type RateLimitChoice = 'wait' | 'pause';
9
13
  export interface ClaudeExecuteOptions {
10
14
  cwd?: string;
11
15
  allowedTools?: string[];
@@ -23,6 +27,12 @@ export interface ClaudeExecuteOptions {
23
27
  baseWaitMs?: number;
24
28
  maxWaitMs?: number;
25
29
  } | false;
30
+ /**
31
+ * Callback when rate limit wait time exceeds maximum.
32
+ * Returns 'wait' to wait for the full duration, or 'pause' to exit gracefully.
33
+ * If not provided, defaults to 'pause' behavior.
34
+ */
35
+ onRateLimitChoice?: (waitTimeMs: number, resetMessage: string) => Promise<RateLimitChoice>;
26
36
  }
27
37
  /**
28
38
  * Result from Claude execution
@@ -32,6 +42,19 @@ export interface ClaudeExecuteResult {
32
42
  response: string;
33
43
  toolCalls: ToolCallRecord[];
34
44
  error?: string;
45
+ /**
46
+ * True if the operation was paused due to rate limiting (not a failure).
47
+ * When true, the user can resume later without losing progress.
48
+ */
49
+ rateLimitPaused?: boolean;
50
+ /**
51
+ * Information about the rate limit if applicable
52
+ */
53
+ rateLimitInfo?: {
54
+ resetTime?: Date;
55
+ waitTimeMs?: number;
56
+ message?: string;
57
+ };
35
58
  }
36
59
  /**
37
60
  * Record of a tool call made by Claude
@@ -80,15 +103,18 @@ export declare function analyzeCodebase(cwd: string, onProgress?: (message: stri
80
103
  *
81
104
  * @param specification - The project specification
82
105
  * @param context - Additional context (existing code, etc.)
106
+ * @param language - Target programming language (default: 'python')
83
107
  * @param onProgress - Progress callback
84
108
  */
85
- export declare function createPlan(specification: string, context?: string, onProgress?: (message: string) => void): Promise<ClaudeExecuteResult>;
109
+ export declare function createPlan(specification: string, context?: string, language?: 'python' | 'typescript' | 'fullstack', onProgress?: (message: string) => void): Promise<ClaudeExecuteResult>;
86
110
  /**
87
111
  * Revise a plan based on feedback
88
112
  *
89
113
  * @param originalPlan - The original plan
90
114
  * @param feedback - Feedback to incorporate
91
115
  * @param concerns - Specific concerns to address
116
+ * @param language - Target programming language (default: 'python')
117
+ * @param onProgress - Progress callback
92
118
  */
93
- export declare function revisePlan(originalPlan: string, feedback: string, concerns: string[], onProgress?: (message: string) => void): Promise<ClaudeExecuteResult>;
119
+ export declare function revisePlan(originalPlan: string, feedback: string, concerns: string[], language?: 'python' | 'typescript' | 'fullstack', onProgress?: (message: string) => void): Promise<ClaudeExecuteResult>;
94
120
  //# sourceMappingURL=claude.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,mBAAmB,GAAG,MAAM,CAAC;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IAC1C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;OAGG;IACH,eAAe,CAAC,EAAE;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,KAAK,CAAC;CACX;AAiRD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,UAWjC,CAAC;AAmPF;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAmF9B;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAyB9B;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,mBAAmB,CAAC,CAoB9B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACrC,OAAO,CAAC,mBAAmB,CAAC,CAoB9B;AAiDD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,MAAW,EACpB,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACrC,OAAO,CAAC,mBAAmB,CAAC,CA4I9B;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACrC,OAAO,CAAC,mBAAmB,CAAC,CA4F9B"}
1
+ {"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}