pluqqy-terminal: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Pluqqy is a terminal-based tool for managing LLM prompt pipelines. It stores everything as plain text files (Markdown and YAML) and provides both a TUI and CLI for managing contexts, prompts, and rules that can be combined into reusable pipelines.

Development Commands

Building and Running

# Build the application
make build

# Build and run the TUI
make run

# Install to $GOBIN or $HOME/go/bin
make install

# Run tests
make test

# Format code
make fmt

# Run go vet for static analysis
make vet

# Update dependencies
make deps

# Build for all platforms (Darwin, Linux, Windows)
make build-all

Testing Commands

# Run all tests with verbose output
go test -v ./...

# Run tests for a specific package
go test -v ./pkg/files/...
go test -v ./pkg/tui/...
go test -v ./pkg/composer/...

# Run tests with coverage
go test -cover ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Architecture and Code Structure

Package Organization

The codebase follows a clean architecture with clear separation of concerns:

• cmd/ - Entry points and CLI command definitions

  • cmd/pluqqy/main.go - Main entry point with root command and TUI launcher
  • cmd/commands/ - Individual CLI command implementations (set, list, show, etc.)

• pkg/ - Core business logic and features

  • pkg/files/ - File operations, YAML/Markdown handling, atomic writes
  • pkg/models/ - Data structures (Pipeline, Component, Settings, Tags)
  • pkg/tui/ - Terminal UI components using Bubble Tea framework
  • pkg/composer/ - Pipeline composition and output generation
  • pkg/search/unified/ - Search engine with query parsing and filtering
  • pkg/utils/ - Utility functions (token counting, etc.)

• internal/ - Internal utilities not exposed as public API

  • internal/cli/ - CLI helpers, formatters, and validators