Skip to content

PRD.md

Latest commit

 

History

History
540 lines (343 loc) · 9.01 KB

PRD.md

File metadata and controls

540 lines (343 loc) · 9.01 KB

codexfy — Product Requirements & Build Plan

1. Overview

Product Name: codexfy Platform: Windows (native-first) UI Framework: Flutter Desktop Backend Engine: OpenAI Codex App Server (stdio JSONL / JSON-RPC) Reference Architecture: CodexMonitor (client-driven app-server orchestration)

Purpose

Build a lightweight, professional, native Windows desktop IDE for Codex that provides full agent power with strong user control, without Electron overhead and without requiring WSL.

This application is a first-class Codex client, not a CLI wrapper.

2. Product Goals

Must-have (Production v1)

  • Multi-workspace Codex usage
  • One codex app-server per workspace
  • Thread discovery, resume, and management
  • Streaming conversation timeline
  • Safe diff review + apply/reject
  • Approval & permission system
  • Git awareness and rollback safety
  • Strong diagnostics and fault tolerance

Explicit Non-goals (v1)

  • Full code editor / LSP
  • Integrated terminal emulator
  • Team sync or cloud features
  • WSL dependency

3. Core Design Principles (Non-Negotiable)

  1. Protocol-first

    • UI is driven by Codex app-server events, not CLI flags.

  2. User-owned safety

    • Codex proposes actions; the app reviews, approves, applies, and can undo.

  3. Native Windows first

    • Codex runs natively if possible.
    • WSL is optional and deferred.

  4. Recoverability over automation

    • Every file or git change must be reversible.

  5. Future-proofing

    • Protocol schema generation and raw JSONL logging are mandatory.

4. High-Level Architecture

Process Model

  • One Codex app-server process per workspace

  • Each workspace manages:

    • Threads
    • Diffs
    • Approvals
    • Git state

Components

  • Flutter UI
  • Codex Process Supervisor
  • JSONL / JSON-RPC Client
  • Workspace Manager
  • Thread & Timeline Controller
  • Diff & Apply Engine
  • Git Integration Layer
  • Policy / Permissions Engine
  • Persistence Layer

5. Dependency Stack (Required)

Core

  • State management: riverpod
  • Persistence: isar (preferred) or hive
  • Folder picker: file_picker
  • Paths: path, path_provider
  • Secure storage: flutter_secure_storage
  • Markdown rendering: flutter_markdown
  • Syntax highlighting: flutter_highlight (or equivalent)
  • Diff library: diff_match_patch or similar

Platform UX

  • Window management: window_manager
  • Optional: tray_manager

6. EPICS, USER STORIES & ACCEPTANCE CRITERIA

EPIC A — Setup & Diagnostics

A1. Dependency Detection (“Doctor”)

User Story: As a user, I want to know if Codex and Git are installed and usable.

Acceptance Criteria

  • Detect Codex presence and version
  • Detect Codex app-server availability
  • Detect Git availability
  • Missing dependencies show clear install instructions
  • “Verify” button re-runs checks
  • App never crashes due to missing dependencies

Checklist

  • Detect codex
  • Detect codex app-server
  • Detect git
  • User-configurable codex path
  • Friendly error states

A2. Diagnostics Export

User Story: As a user, I want to export logs for debugging or support.

Acceptance Criteria

  • One-click ZIP export containing:

    • App logs
    • Codex stderr
    • Raw JSONL protocol logs

  • Sensitive data redacted

Checklist

  • Central logging
  • JSONL protocol recorder
  • ZIP export

EPIC B — Workspace Management

B1. Workspace Registry

User Story: As a user, I want to manage multiple repositories/workspaces.

Acceptance Criteria

  • Add/remove workspaces via folder picker

  • Persisted across restarts

  • Workspace list shows:

    • Path
    • Git branch
    • Dirty status
    • Last activity

Checklist

  • Workspace model
  • Persistent storage
  • Workspace list UI

B2. Codex Process Supervisor

User Story: As a user, Codex should reliably run per workspace.

Acceptance Criteria

  • One app-server per workspace
  • Auto-restart on crash
  • Exponential backoff on repeated failures
  • Manual restart control

Checklist

  • Process lifecycle manager
  • Crash detection
  • Restart logic
  • Error UI

EPIC C — Threads & Conversations

C1. Thread Discovery

User Story: As a user, I want to see all Codex threads for a workspace.

Acceptance Criteria

  • Call thread/list on workspace open
  • Display threads with status indicators

Checklist

  • Thread list request
  • Thread metadata model
  • UI rendering

C2. Thread Resume

User Story: As a user, I want to resume an existing thread.

Acceptance Criteria

  • Selecting a thread calls thread/resume
  • Timeline renders history
  • Partial/missing data handled gracefully

Checklist

  • Resume logic
  • Timeline hydration
  • Error tolerance

C3. New Thread Creation

Acceptance Criteria

  • Create new thread from UI
  • Thread appears immediately
  • First response streams correctly

Checklist

  • New thread command
  • UI update

EPIC D — Conversation Timeline

D1. Timeline Rendering

User Story: As a user, I want to understand what Codex is doing.

Acceptance Criteria

  • Timeline renders:

    • User messages
    • Agent messages
    • Tool calls
    • Diffs
    • Approval requests
    • Errors

  • Streaming updates are live

  • Filter and search supported

Checklist

  • Unified event model
  • Streaming UI
  • Filters
  • Search

D2. Raw Protocol Viewer (Dev Tool)

Acceptance Criteria

  • Toggleable raw JSONL view
  • Read-only
  • Helps diagnose protocol changes

Checklist

  • JSONL viewer panel

EPIC E — Diff Review & Change Management

E1. Proposed Changes

User Story: As a user, I want to review code changes before applying them.

Acceptance Criteria

  • Grouped by thread and file
  • Side-by-side diff view
  • Apply / Reject per change

Checklist

  • Change model
  • Diff renderer
  • Change list UI

E2. Apply & Rollback

Acceptance Criteria

  • Safe file writes
  • Git-backed undo when repo exists
  • Conflict detection

Checklist

  • Apply logic
  • Git restore fallback
  • Conflict detection

EPIC F — Approvals & Policy Engine

F1. Approval Prompts

User Story: As a user, I want to approve risky actions.

Acceptance Criteria

  • File writes, commands, git ops require approval
  • Clear context shown
  • Allow-once / allow-always options

Checklist

  • Approval UI
  • Policy persistence

F2. Policy Configuration

Acceptance Criteria

  • Per-workspace:

    • Read-only mode
    • Allowed paths
    • Allowed commands

  • Editable and persistent

Checklist

  • Policy editor
  • Enforcement logic

EPIC G — Git Integration (Baseline)

G1. Git Status

User Story: As a user, I want to see repository status.

Acceptance Criteria

  • Show staged/unstaged/untracked
  • Updates after changes
  • Non-fatal errors

Checklist

  • Git root detection
  • Status parsing

G2. Git Diff & Restore

Acceptance Criteria

  • Show diffs via git
  • Restore with confirmation

Checklist

  • Diff view
  • Restore action

EPIC H — Performance & Stability

H1. Responsiveness

Acceptance Criteria

  • Large repos remain responsive
  • Heavy work runs off UI thread
  • Lists virtualized

Checklist

  • Isolates
  • Virtualized lists

H2. Fault Tolerance

Acceptance Criteria

  • Survives Codex crashes
  • Survives partial protocol messages
  • Clear user-facing errors

Checklist

  • Error boundaries
  • Recovery UI

EPIC I — Security & Audit

I1. Secrets Handling

Acceptance Criteria

  • Secrets stored via OS secure storage
  • No plaintext secrets on disk

Checklist

  • Secure storage integration

I2. Audit Trail

Acceptance Criteria

  • All applied changes and approvals logged
  • Logs are human-readable

Checklist

  • Audit log model
  • Viewer UI

7. PHASED EXECUTION PLAN (STRICT)

Phase 1 — Foundation

  • Workspace registry
  • Codex process supervisor
  • Thread list & resume
  • Raw protocol logging
  • Activity timeline

Phase 2 — Safety & Review

  • Diff model
  • Apply/reject workflow
  • Approval engine
  • Git status & undo

Phase 3 — Production Polish

  • Performance tuning
  • Diagnostics export
  • Error recovery UX
  • Settings & policy UI

8. Deferred / Future Features (Explicit)

  • Embedded editor / LSP
  • Multi-agent dashboard
  • Remote Codex daemon
  • GitHub PR & Issues integration
  • Plugin system
  • WSL compatibility mode
  • Team collaboration

These must not influence core architecture.

9. Definition of “Production Ready”

  • App runs for hours without leaks
  • No data loss on crash
  • All Codex actions are reviewable and reversible
  • Clear upgrade path for protocol changes
  • Windows users do not need WSL

10. Final Instruction to Codex Model

Build incrementally. Validate each epic before moving forward. Log everything. Prefer safety and clarity over automation. Never assume protocol stability.