human-tar 3.0.2

A human-readable tar format for text files, based on grep . -r output

human-tar

@readwithai - X - blog - machine-aided reading - 📖⚡️🖋️

A human-readable tar format for text files. Easy for AIs to write and read.

This includes AI generated code. The interface is liable to change -- so do not use this in programs.

Motivation

I've been doing a little vibe-coding with online LLMs and found myself occasionally producing a number of files to share. While some online LLMs can produce tar files, this process is often buggy and slow compared to producing output like this (using prompts)

Alternatives and prior Work

This format is based on the output of grep . -r . - which can be used to produce output to give to an LLM (with the appropriate ignore flags)

You could use claude code cursor/windsurf or another AI tool to circumvent the need for this sort of tool. There are various tools to wrap up a codebase ready to be sent into an AI, but not necessarily the other way.

Installation

Install human-tar from PyPI using pipx

pipx install human-tar

Usage

human-tar will give you the output for the current git repo in this format. human-tar bytes tells you how many bytes each file is taking up. human-tar exclude '*.json' excludes all json iles human-tar exclude files excludes a files. human-untar unpacks the output in the form of grep . -r into the original file structure. It reads input from a file or stdin and writes files to the current directory by default.

Compression

While very-readable, and the output of a grep a standard tool, the default output is longer than it needs to be causing claude to hit up against limits.

Examples

As a demonstraction, this command produces human-tar input using grep and feeds this into human-tar.

grep . -r /path/to/dir | human-untar

You can also provide a path on the current directory or from the clipboard using xclip on linux or pblaste on mac

human-untar file.txt
human-untar <(xclip -o -selection CLIPBOARD)

For testing purposes, you might want to output into a different directory using the -o option

human-tar file.text -o file

Input Format

The input should be in the format of grep . -r output, e.g.:

src/main.c:int main() {
src/main.c:    printf("Hello, world!\n");
src/utils/helper.c:void help() {

This will create (in the current directory by default):

./
├── src/
│   ├── main.c
│   └── utils/
│       └── helper.c

Options

• -o, --output-dir: Specify the output directory (default: current directory).
• Example: human-tar -o my_output_dir grep_output.txt

About me

I am @readwithai. I create tools for reading, research and agency sometimes using the markdown editor Obsidian.

I also create a stream of tools like this that are related to carrying out my work. As users of tool are likely interesting in AI you might like to read my blog about tools for reading with ai.

I write about lots of things - including tools like this - on X. My blog is more about reading and research and agency.