[Pew Pew Plx Hero]

Pew Pew Plx #

A Dart CLI for project file monitoring and tooling automation.

Features #

• Real-time file change monitoring with throttled JSON output
• Bidirectional communication via stdin/stdout JSON protocol
• File read (get) and directory listing (list) operations
• Clipboard-to-file paste via pbpaste
• File content appending with duplicate detection
• Image generation from text prompts via Gemini API (plx create image)
• List feedback markers (plx list feedback) and PR comments (plx list comments) with markdown/JSON/YAML output
• Copy feedback markers or PR comments to clipboard (plx copy feedback, plx copy comments)
• Authentication with PLX backend (plx login, plx logout, plx show auth)
• Configurable watch extensions, ignore folders, and throttle rate
• Path traversal protection and extension validation

Platform Support #

Table of Contents #

• Platform Support
• Installation
• External Dependencies
• Commands
• Usage
  • Watch Project Files
  • Paste Clipboard to File
  • Append File Content
  • Create Image
  • List Feedback
  • List Comments
  • Copy Feedback
  • Copy Comments
  • Authentication
• Configuration
• How It Works
• Development
• Troubleshooting
• License

Installation #

Homebrew (macOS / Linux) #

brew tap appboypov/tap
brew install plx

pub.dev #

From the repo (path-based, for development or when using local symlinks):

dart pub global activate --source path .

When the package is published to pub.dev:

dart pub global activate pew_pew_plx

External Dependencies #

These tools must be available on your PATH for full functionality:

Commands #

Usage #

Watch Project Files #

Monitor project files for changes with throttled JSON output:

plx watch project

Output (stdout)

File changes are emitted as JSON:

{"event": "create", "path": "docs/readme.md", "content": "# Hello"}
{"event": "modify", "path": "docs/readme.md", "content": "# Hello World"}
{"event": "delete", "path": "docs/readme.md", "content": null}

Input (stdin)

Send JSON requests to write or delete files:

{"event": "create", "path": "docs/new.md", "content": "# New File", "id": "req-1"}
{"event": "modify", "path": "docs/existing.md", "content": "Updated content", "id": "req-2"}
{"event": "delete", "path": "docs/old.md", "id": "req-3"}

Responses mirror the request structure:

{"event": "create", "path": "docs/new.md", "content": "# New File", "id": "req-1"}
{"event": "error", "path": "docs/invalid.txt", "content": "File extension not allowed", "id": "req-4"}

Read Operations (stdin)

Request file content or directory listings:

{"event": "get", "path": "docs/readme.md", "id": "req-5"}
{"event": "list", "path": "docs", "id": "req-6"}

Get response (single file):

{"event": "get", "path": "docs/readme.md", "content": "# Hello", "lastModified": 1737475200000, "id": "req-5"}

List response (directory contents):

{"event": "list", "path": "docs", "files": [{"path": "docs/readme.md", "content": "# Hello", "lastModified": 1737475200000}], "id": "req-6"}

Event Schema

Constraints:

• Paths must be within the watched directory
• File extension must match configured extensions
• Paths in ignored folders are rejected
• Parent directories are created automatically for writes

Paste Clipboard to File #

Write clipboard content to a file in the current directory using pbpaste (macOS only):

plx paste notes.md

This reads the system clipboard and writes its content to the specified file, creating parent directories if needed.

Append File Content #

Append the content of a source file to a target file, then delete the source:

plx append fragment.md document.md

The command:

• Verifies both files exist
• Checks the target does not already contain the source content (duplicate detection)
• Appends source content to the end of the target
• Deletes the source file after a successful append

Create Image #

Generate images from text prompts using the Gemini API:

plx create image "a red apple"
plx create image "a blue cat" --output ./my-images
plx create image "sunset over mountains" --filename landscape.png --count 4

Options:

• --output, -o: Output directory (default: workspace/images)
• --filename, -f: Output filename or path
• --count, -n: Number of images to generate (1-8, default: 1)
• --model, -m: Gemini model override (e.g. gemini-2.0-flash-exp)

API key resolution (first found): GEMINI_API_KEY env, PLX_GEMINI_API_KEY env, or create_image.api_key in config.

List Feedback #

List feedback markers (#FEEDBACK) found in source files. Default output is markdown; use -o json or -o yaml for structured output:

plx list feedback
plx list feedback -o json
plx list feedback -o yaml

Requires feedback config in .plx/config.yaml (marker, extensions, ignore_folders).

List Comments #

List unresolved PR review comments from the current branch. Requires gh and a branch with an open PR. Default output is markdown:

plx list comments
plx list comments -o json
plx list comments -o yaml

Copy Feedback #

Find all feedback markers (#FEEDBACK) in source files and copy a categorized report to the clipboard. Uses pbcopy (macOS only). Requires feedback config in .plx/config.yaml:

plx copy feedback

The report is printed to stdout and copied to the clipboard.

Copy Comments #

Fetch unresolved PR review comments from the current branch and copy a formatted report to the clipboard. Uses pbcopy (macOS only). Requires gh and a branch with an open PR:

plx copy comments

The report is printed to stdout and copied to the clipboard.

Authentication #

Authenticate with the PLX backend for features that require it:

plx login

Opens a browser for sign-in. If the browser does not open, the verification URL and code are printed. Credentials are stored locally.

Check current status:

plx show auth

Clear stored credentials:

plx logout

Configuration #

Configuration is split across two files. Run plx init to merge new config keys or migrate legacy keys.

User config (~/.plx/config.yaml) #

Stores personal credentials and per-user settings:

• auth: Firebase authentication credentials
• agent: Agent configuration
• create_image.api_key: Gemini API key (fallback if env vars not set)

Project config (.plx/config.yaml) #

Stored in the project root (auto-created with defaults) and checked in per project:

watch:
  throttle_ms: 1000
  extensions:
    - .md
  ignore_folders:
    - .git
    - node_modules
    - build
    - .dart_tool
    - .plx

create_image:
  default_output_dir: workspace/images
  default_model: gemini-2.0-flash-exp

feedback:
  marker: "#FEEDBACK"
  extensions: [.dart, .ts, .tsx, .js, .jsx, .kt, .swift, .java, .go]
  ignore_folders: [.git, node_modules, build, .dart_tool, .plx]

How It Works #

This section explains the architecture of plx watch project for developers new to the project.

What is it? #

Pew Pew Plx is a Dart CLI that:

1. Watches project files and reports changes as JSON
2. Accepts JSON commands on stdin and responds on stdout
3. Can run Claude Code agents and list their sessions

It's designed to be driven by another app (e.g. plaza) that sends JSON and reads JSON back.

The Big Picture: plx watch project #

When you run plx watch project, the process:

1. Starts watching the current directory for file changes
2. Reads JSON lines from stdin
3. Writes JSON lines to stdout

It's a long-running process that communicates via stdin/stdout using JSON.

Two Kinds of Output #

There are two main output streams:

Both go to stdout, but they're distinguished by fields like event vs type.

How stdin Requests Are Handled #

Every line from stdin is JSON. The first thing the system does is look at the type field to decide what to do:

stdin line → parse JSON → check "type" → route to the right handler

The router (StdinRequestRouter) does this branching:

So the router is a dispatcher: one JSON line in, one or more JSON lines out.

Agent Flow: agent.run #

When you send:

{"type":"agent.run","prompt":"Say hi","args":["--output-format","stream-json"],"cwd":"/path/to/project"}

the flow is:

1. StdinRequestRouter parses the JSON and sees type: "agent.run".
2. It calls AgentRunHandler.handleRun().
3. AgentRunHandler validates that cwd exists and is a directory, generates a run_id if you didn't provide one, then calls the ClaudeCodeBackend to run the agent.
4. ClaudeCodeBackend spawns claude -p "Say hi" --output-format stream-json in the given cwd, reads the subprocess stdout line-by-line, parses the JSON, and converts it into AgentEventDto objects that it yields as a stream.
5. AgentRunHandler receives each event and pushes it to the AgentEventBus.
6. ProjectCommand has subscribed to the bus and writes each event to stdout as {"type":"agent","run_id":"...","stream":"lifecycle","data":{"phase":"start"},...}.

So: stdin request → handler → backend (subprocess) → event bus → stdout.

Agent Event Bus #

The AgentEventBus is a simple pub/sub:

• Publish: emitAgentEvent(event) — anyone can emit events
• Subscribe: onAgentEvent(callback) — returns an unsubscribe function

There's typically one subscriber: the one that writes agent events to stdout. That keeps the "write to stdout" logic in one place instead of scattered across handlers.

Session List: agent.sessions.list #

When you send {"type":"agent.sessions.list"}:

1. StdinRequestRouter sees type: "agent.sessions.list".
2. It calls SessionStore.listSessions().
3. SessionStore resolves the Claude data dir (env PLX_CLAUDE_DATA_DIR, config, or ~/.claude), scans ~/.claude/projects/... for JSONL session files, and reads the first line of each file to build session summaries.
4. The router writes the response directly to stdout: {"type":"agent.sessions.list","sessions":[{"session_id":"...","project_dir":"..."},...]}.

No event bus here — the router writes the response itself.

Dependency Injection (GetIt) #

The project uses GetIt for dependency injection:

• Lazy singletons: e.g. AgentEventBus, SessionStore — created on first use
• Factories: e.g. AgentRunHandler, StdinRequestRouter — new instance each time

Registration happens in LocatorService at startup. Commands and services get their dependencies via GetIt.I.get<SomeType>() instead of constructing them manually.

Summary Diagram #

                    stdin (JSON lines)
                         │
                         ▼
              ┌──────────────────────┐
              │  StdinRequestRouter  │
              │  (parse, switch on    │
              │   "type")             │
              └──────────┬────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
   agent.run      agent.sessions   watch (get/list/
         │              .list       create/modify)
         │               │               │
         ▼               ▼               ▼
  AgentRunHandler   SessionStore   FileReader/
         │               │         FileWriter
         ▼               │               │
  ClaudeCodeBackend      │               │
  (spawn claude)        │               │
         │               │               │
         ▼               │               │
  AgentEventBus ◄────────┘               │
         │                               │
         └───────────────┬────────────────┘
                         │
                         ▼
                    stdout (JSON lines)

Key Takeaways #

1. plx is a JSON-over-stdin/stdout CLI for file watching and agent control.
2. StdinRequestRouter routes each JSON line by type to the right handler.
3. AgentEventBus is a pub/sub for agent events; one subscriber writes them to stdout.
4. ClaudeCodeBackend spawns the claude CLI and converts its output into events.
5. SessionStore reads Claude's session files from disk.
6. ProjectCommand ties everything together: file watcher, stdin loop, and bus subscriber.

Development #

Local setup: This package uses path dependencies under symlinks/ that must point to the turbo_* packages (e.g. turbo_plx_cli, turbo_promptable, turbo_response, turbo_serializable). Create the symlinks if missing:

# From pew_pew_plx repo root, with turbo_packages as sibling directory:
ln -sf ../turbo_packages/turbo_plx_cli symlinks/turbo_plx_cli
ln -sf ../turbo_packages/turbo_promptable symlinks/turbo_promptable
ln -sf ../turbo_packages/turbo_response symlinks/turbo_response
ln -sf ../turbo_packages/turbo_serializable symlinks/turbo_serializable

# Then get dependencies and activate
dart pub get && dart pub global activate --source path .

# Run in development mode
dart run bin/plxdev.dart watch project

# Full CI pipeline (get, build, analyze, test)
make all

# Individual commands
make get        # Get dependencies
make build      # Generate code (build_runner)
make analyze    # Static analysis
make test       # Run tests with coverage
make format     # Format code
make dev        # Compile and install plxdev
make prod       # Compile and install plx (requires PLX_FIREBASE_API_KEY)

# Production build requires Firebase API key
make prod PLX_FIREBASE_API_KEY=<your-key>

# Firebase Functions (contact form, auth) require RESEND_API_KEY, RESEND_FROM_EMAIL, RESEND_TO_EMAIL — see firebase/README.md

# Or compile manually:
dart compile exe bin/plx.dart -o build/plx --define=env=prod --define=PLX_FIREBASE_API_KEY=<your-key>

Troubleshooting #

If you see "The current activation of pew_pew_plx cannot resolve to the same set of dependencies", ensure the four symlinks/ path dependencies exist, then from the repo root run:

rm -rf .dart_tool/pub/bin/pew_pew_plx && dart pub get && dart pub global activate --source path .

License #

See LICENSE for details.