ecat — Embedded Cat

Embedded concatenation for context engineering.

ecat works like cat, but wraps every source — files, shell commands, and URLs — in a labelled Markdown code fence before writing it to stdout. The result is ready to pipe directly into an LLM CLI or any tool that reads a prompt from stdin.

ecat [OPTIONS] [SOURCE ...]

A source is one of:

All blocks are joined with a blank line and written to stdout.

Install

pip install ecat

Quick Start

# Embed a file
ecat src/ecat/ecat.py

# Embed command output
ecat "git log --oneline -20"

# Embed a web page
ecat https://docs.python.org/3/library/pathlib.html

# Read a question from stdin and pipe everything to Claude
ecat schema.sql "SELECT * FROM orders LIMIT 5" \
  | claude "$(cat question.txt)"

Usage

Options

Sources

Files are fenced with their path as the language tag:

```src/ecat/ecat.py
… file contents …
```

Commands are fenced as bash with a $ prompt line:

```bash
$ git log --oneline -20
abc1234 fix typo
…
```

URLs are fetched, converted from HTML to Markdown, and fenced as bash with the equivalent curl invocation shown:

```bash
$ curl -s https://example.com | html2markdown
… page content in Markdown …
```

Stdin (-) is embedded as plain text — no fence is added so you can supply free-form prose or a question directly.

Context Engineering Patterns

ecat is designed to be composed with other tools via pipes. The idea is simple: build a rich context block, then ask a question.

Explain a bug

ecat src/app.py "pytest tests/ 2>&1 | tail -30" \
  | llm "Why is the test suite failing and how do I fix it?"

Review a diff

git diff main | ecat - \
  | llm "Review this diff. Call out logic errors and security issues."

Summarise a web page

ecat https://news.ycombinator.com \
  | llm "Give me the five most interesting links and a one-line summary of each."

Generate code from a schema

ecat schema.sql \
  | llm "Generate a SQLAlchemy model file for every table in this schema."

Combine multiple sources

ecat \
  README.md \
  src/ecat/ecat.py \
  "pip show ecat" \
  | llm "Write a CHANGELOG entry for the next release."

Use a different shell

ecat --shell fish "status" "functions --all"

How It Works

argv tokens
    │
    ├── "-"          → read stdin            ┐
    ├── file path    → read file             ├─→ Markdown code fence
    ├── https?://…   → fetch + html2md       │
    └── other        → run in shell          ┘
                                             │
                                    join with "\n\n"
                                             │
                                          stdout

Each source becomes one self-contained block. The LLM always knows where each piece of context came from because the fence label carries the origin (file path, URL, or the literal command that was run).

Development

git clone https://github.com/rodolfovillaruz/ecat
cd ecat
pip install -e ".[dev]"

make check      # format-check + lint + typecheck + test
make format     # auto-format with black + isort
make test       # pytest only

License

MIT © Rodolfo Villaruz