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.
- package/.env.example +24 -1
- package/CONTRIBUTING.md +275 -0
- package/OPEN_SOURCE_MANIFESTO.md +172 -0
- package/README.md +340 -27
- package/dist/adapters/claude.d.ts +28 -2
- package/dist/adapters/claude.d.ts.map +1 -1
- package/dist/adapters/claude.js +273 -20
- package/dist/adapters/claude.js.map +1 -1
- package/dist/adapters/grok.d.ts +73 -0
- package/dist/adapters/grok.d.ts.map +1 -0
- package/dist/adapters/grok.js +430 -0
- package/dist/adapters/grok.js.map +1 -0
- package/dist/adapters/openai.d.ts +1 -1
- package/dist/adapters/openai.d.ts.map +1 -1
- package/dist/adapters/openai.js +6 -1
- package/dist/adapters/openai.js.map +1 -1
- package/dist/auth/grok.d.ts +73 -0
- package/dist/auth/grok.d.ts.map +1 -0
- package/dist/auth/grok.js +211 -0
- package/dist/auth/grok.js.map +1 -0
- package/dist/auth/index.d.ts +9 -6
- package/dist/auth/index.d.ts.map +1 -1
- package/dist/auth/index.js +23 -6
- package/dist/auth/index.js.map +1 -1
- package/dist/cli/commands/auth.d.ts +1 -1
- package/dist/cli/commands/auth.d.ts.map +1 -1
- package/dist/cli/commands/auth.js +79 -8
- package/dist/cli/commands/auth.js.map +1 -1
- package/dist/cli/commands/create.d.ts.map +1 -1
- package/dist/cli/commands/create.js +15 -4
- package/dist/cli/commands/create.js.map +1 -1
- package/dist/cli/interactive.d.ts.map +1 -1
- package/dist/cli/interactive.js +406 -35
- package/dist/cli/interactive.js.map +1 -1
- package/dist/config/defaults.d.ts +3 -0
- package/dist/config/defaults.d.ts.map +1 -1
- package/dist/config/defaults.js +9 -0
- package/dist/config/defaults.js.map +1 -1
- package/dist/config/index.d.ts +9 -0
- package/dist/config/index.d.ts.map +1 -1
- package/dist/config/index.js +16 -3
- package/dist/config/index.js.map +1 -1
- package/dist/config/schema.d.ts +27 -0
- package/dist/config/schema.d.ts.map +1 -1
- package/dist/config/schema.js +24 -3
- package/dist/config/schema.js.map +1 -1
- package/dist/generators/fullstack.d.ts +32 -0
- package/dist/generators/fullstack.d.ts.map +1 -0
- package/dist/generators/fullstack.js +497 -0
- package/dist/generators/fullstack.js.map +1 -0
- package/dist/generators/index.d.ts +4 -3
- package/dist/generators/index.d.ts.map +1 -1
- package/dist/generators/index.js +15 -1
- package/dist/generators/index.js.map +1 -1
- package/dist/generators/python.d.ts +17 -1
- package/dist/generators/python.d.ts.map +1 -1
- package/dist/generators/python.js +34 -21
- package/dist/generators/python.js.map +1 -1
- package/dist/generators/templates/fullstack.d.ts +113 -0
- package/dist/generators/templates/fullstack.d.ts.map +1 -0
- package/dist/generators/templates/fullstack.js +1004 -0
- package/dist/generators/templates/fullstack.js.map +1 -0
- package/dist/generators/typescript.d.ts +19 -1
- package/dist/generators/typescript.d.ts.map +1 -1
- package/dist/generators/typescript.js +37 -21
- package/dist/generators/typescript.js.map +1 -1
- package/dist/types/cli.d.ts +4 -0
- package/dist/types/cli.d.ts.map +1 -1
- package/dist/types/cli.js.map +1 -1
- package/dist/types/consensus.d.ts +119 -2
- package/dist/types/consensus.d.ts.map +1 -1
- package/dist/types/consensus.js +12 -1
- package/dist/types/consensus.js.map +1 -1
- package/dist/types/project.d.ts +76 -0
- package/dist/types/project.d.ts.map +1 -1
- package/dist/types/project.js +1 -1
- package/dist/types/project.js.map +1 -1
- package/dist/types/workflow.d.ts +170 -16
- package/dist/types/workflow.d.ts.map +1 -1
- package/dist/types/workflow.js +26 -3
- package/dist/types/workflow.js.map +1 -1
- package/dist/workflow/consensus.d.ts +29 -3
- package/dist/workflow/consensus.d.ts.map +1 -1
- package/dist/workflow/consensus.js +334 -27
- package/dist/workflow/consensus.js.map +1 -1
- package/dist/workflow/execution-mode.d.ts +2 -0
- package/dist/workflow/execution-mode.d.ts.map +1 -1
- package/dist/workflow/execution-mode.js +20 -0
- package/dist/workflow/execution-mode.js.map +1 -1
- package/dist/workflow/index.d.ts +2 -0
- package/dist/workflow/index.d.ts.map +1 -1
- package/dist/workflow/index.js +11 -0
- package/dist/workflow/index.js.map +1 -1
- package/dist/workflow/milestone-workflow.d.ts +2 -0
- package/dist/workflow/milestone-workflow.d.ts.map +1 -1
- package/dist/workflow/milestone-workflow.js +19 -2
- package/dist/workflow/milestone-workflow.js.map +1 -1
- package/dist/workflow/plan-mode.d.ts +66 -2
- package/dist/workflow/plan-mode.d.ts.map +1 -1
- package/dist/workflow/plan-mode.js +187 -11
- package/dist/workflow/plan-mode.js.map +1 -1
- package/dist/workflow/plan-storage.d.ts +252 -8
- package/dist/workflow/plan-storage.d.ts.map +1 -1
- package/dist/workflow/plan-storage.js +580 -33
- package/dist/workflow/plan-storage.js.map +1 -1
- package/dist/workflow/project-verification.js +1 -1
- package/dist/workflow/project-verification.js.map +1 -1
- package/dist/workflow/task-workflow.d.ts +2 -0
- package/dist/workflow/task-workflow.d.ts.map +1 -1
- package/dist/workflow/task-workflow.js +23 -1
- package/dist/workflow/task-workflow.js.map +1 -1
- package/dist/workflow/test-runner.d.ts +8 -0
- package/dist/workflow/test-runner.d.ts.map +1 -1
- package/dist/workflow/test-runner.js +92 -0
- package/dist/workflow/test-runner.js.map +1 -1
- package/dist/workflow/workspace-manager.d.ts +342 -0
- package/dist/workflow/workspace-manager.d.ts.map +1 -0
- package/dist/workflow/workspace-manager.js +733 -0
- package/dist/workflow/workspace-manager.js.map +1 -0
- package/package.json +1 -1
- package/src/adapters/claude.ts +322 -25
- package/src/adapters/grok.ts +492 -0
- package/src/adapters/openai.ts +8 -2
- package/src/auth/grok.ts +255 -0
- package/src/auth/index.ts +27 -9
- package/src/cli/commands/auth.ts +89 -10
- package/src/cli/commands/create.ts +13 -4
- package/src/cli/interactive.ts +453 -34
- package/src/config/defaults.ts +9 -0
- package/src/config/index.ts +17 -3
- package/src/config/schema.ts +25 -3
- package/src/generators/fullstack.ts +551 -0
- package/src/generators/index.ts +25 -1
- package/src/generators/python.ts +65 -21
- package/src/generators/templates/fullstack.ts +1047 -0
- package/src/generators/typescript.ts +69 -21
- package/src/types/cli.ts +4 -0
- package/src/types/consensus.ts +135 -3
- package/src/types/project.ts +82 -1
- package/src/types/workflow.ts +58 -4
- package/src/workflow/consensus.ts +461 -31
- package/src/workflow/execution-mode.ts +32 -0
- package/src/workflow/index.ts +12 -0
- package/src/workflow/milestone-workflow.ts +24 -2
- package/src/workflow/plan-mode.ts +238 -10
- package/src/workflow/plan-storage.ts +835 -35
- package/src/workflow/project-verification.ts +1 -1
- package/src/workflow/task-workflow.ts +29 -1
- package/src/workflow/test-runner.ts +110 -0
- package/src/workflow/workspace-manager.ts +912 -0
package/README.md
CHANGED
|
@@ -1,7 +1,16 @@
|
|
|
1
1
|
# Popeye CLI
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/popeye-cli)
|
|
4
|
+
[](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
|
-
|
|
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
|
|
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:
|
|
233
|
-
- Up to
|
|
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
|
|
358
|
-
/create <idea>
|
|
359
|
-
/
|
|
360
|
-
/
|
|
361
|
-
/
|
|
362
|
-
/
|
|
363
|
-
/
|
|
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
|
-
|
|
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
|
|
378
|
-
arbitrator: gemini # Arbitrator when stuck (openai or
|
|
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
|
|
651
|
+
# Rate limit settings
|
|
396
652
|
rateLimit:
|
|
397
|
-
maxRetries:
|
|
398
|
-
baseWaitMs:
|
|
399
|
-
maxWaitMs:
|
|
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
|
|
426
|
-
POPEYE_ARBITRATOR=gemini # Arbitrator (openai or
|
|
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.
|
|
434
|
-
3.
|
|
435
|
-
4.
|
|
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
|
|
572
|
-
2. **
|
|
573
|
-
3. **
|
|
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
|
-
│
|
|
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;
|
|
1
|
+
{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}
|