USEE: Software that assembles like LEGO pieces
An open protocol for creating interchangeable software pieces,
understandable and resilient over time.
Today's software is broken
UNNECESSARY COMPLEXITY
Programs that should do one thing, do a hundred.
ACCELERATED OBSOLESCENCE
Systems that should last decades break in months.
HIGH ENTRY BARRIER
Tools that should be accessible require years to learn.
CONTEXT DEPENDENCY
Solutions that should be universal only work in specific places.
"Every project reinvents the wheel. Login, QR, analytics, validations...
over and over again, with the same mistakes."
USEE: Four principles, software that lasts
USEFUL
Solves a concrete problem that people have today
SIMPLE
Few parts, low complexity, easy to understand
ESSENTIAL
Does one thing completely without extras
ENDURING
Resilient to changes, works years later
Pieces that speak the same language
Universal communication via plain text
(USEE Text Format)
Anatomy of a USEE piece
File structure:
Usage example:
text: https://my-site.com
width: 256
status: ok
format: png
image: iVBORw0KGgo... (base64)
"One piece = One problem solved. Documented, tested, ready to use."
The power is in composition
extract data
temporal analytics
generate report
./extract-data | ./temporal-analytics | ./generate-report
"Build complex solutions by connecting simple pieces.
No extra code, no configuration, no headaches."
Explore the protocol
Getting started
Learn to run and connect USEE pieces in minutes
Quick Guide: Running and Connecting USEE Pieces
Everything you need to know to use USEE pieces: UTF format, basic execution, pipe connections, JSON/HTTP adapters, and complete practical examples.
- USEE Text Format (UTF)
- How to run a piece
- Connect pieces with pipes
- JSON and HTTP adapters
- Debug and common errors
Integration scripts
Ready-to-use tools and examples
ejemplo-pipeline.sh
Pipeline connecting analytics-temporal β generar-qr
transformar-ftu.sh
Utility to transform UTF fields between pieces
Example pieces
Explore real USEE pieces to understand the protocol structure
generar-qr
Generates customizable QR codes from text
analytics-temporal
Processes visit data in temporal periods with aggregations
Create USEE pieces with an AI
Copy the context below and paste it into any AI (Claude, ChatGPT, Geminiβ¦). It gives everything needed to design and write a correct USEE piece from scratch.
You are an expert assistant in the USEE protocol. Your task is to help me create a correct USEE piece according to the protocol standard.
## What a USEE piece is
A USEE piece is an atomic program (a CLI) that does ONE single thing: it reads from stdin and writes to stdout using FTU (USEE Text Format, plain text). Errors go to stderr. A piece name is always "verb + noun" (e.g. generate-order-number, calculate-stock, convert-unit).
## The 4 principles (must always hold)
- Useful: solves a concrete problem someone has today.
- Simple: few pieces, low complexity, easy to understand.
- Essential: does one complete thing, no extras or "convenience" features.
- Stable: backward-compatible inputs and outputs. A breaking change = a NEW piece with a new name, never break the existing one.
## Mandatory folder structure (pieces/<name>/)
PIEZA.usee β manifest in FTU
ejecutar β executable entry point (reads stdin, writes stdout)
ENTRADA.ejemplo β example input in FTU
SALIDA.ejemplo β example output in FTU (must be produced literally by ./ejecutar < ENTRADA.ejemplo)
LEEME.md β human documentation; must explicitly state what the piece does NOT do
pruebas/ β cases: <name>.entrada + <name>.salida (or .codigo for expected errors)
## FTU format
- "key: value" syntax, one pair per line.
- Comments with #.
- Multi-line blocks with | and 2-space indentation.
- Repeated keys (e.g. linea:, orden:) represent lists/arrays.
- UTF-8 encoding.
## PIEZA.usee manifest (sections, in this order)
1. # Identity β name, version, creator, creation_date
2. # Description β short_description, long_description (| block)
3. # Classification β category, tags
4. # Capability β action, input_description, output_description
5. # Requirements β language, min_language_version, external_dependencies, usee_dependencies
6. # Commercial β cost_per_use, currency, billing_model
7. # Configuration β configuration_options, required_configuration
8. # Performance β average_response_time_ms, max_memory_mb
9. # Compatibility β operating_systems, requires_network, requires_storage
10. # Additional metadata β usee_protocol, license
## Contract of the "ejecutar" executable
- Supports --ayuda/-h and --version/-v.
- If it receives no stdin input (TTY) β error with exit code 2.
- Parses FTU from stdin, validates every field, and on error emits to stderr: estado: error / codigo / mensaje / sugerencia.
- OK output to stdout: estado: ok / <result fields>.
- Exit codes: 0 = ok, 2 = input/validation error, 1 = general/fatal error.
- Optional configuration via environment variables prefixed USEE_<NAME>_<OPTION>. Never mandatory configuration for the common case.
- No external dependencies if possible. For money, use fixed decimals (2), never raw floats.
- The piece does NOT access a database or the network unless its action explicitly requires it: it receives everything through the input so the consumer decides the source.
- Deterministic and composable: it must chain with other pieces (pieceA | pieceB | pieceC).
## Checklist before considering it done
- The purpose fits in "verb + noun".
- PIEZA.usee has all required fields and is valid FTU.
- "ejecutar" reads from stdin and writes FTU to stdout; errors go to stderr.
- ENTRADA.ejemplo produces SALIDA.ejemplo literally.
- LEEME.md documents what the piece does NOT do.
- No unjustified external dependencies; no mandatory configuration.
## What I need from you
1. Ask me what the piece should do if I haven't said so.
2. Propose a "verb + noun" name and check it is atomic (one single thing).
3. Generate the complete files: PIEZA.usee, ejecutar, ENTRADA.ejemplo, SALIDA.ejemplo, LEEME.md and at least one case in pruebas/.
4. Show the command to test it locally and verify that ENTRADA.ejemplo produces SALIDA.ejemplo.
Want the full protocol detail? Check the Manifesto and documentation before publishing your piece.