tscribe

Concatenate TypeScript‑family files into a LLM‑ready dump.

What is tscribe for?

tscribe is a developer CLI tool that extracts .ts and .tsx source files from your project, transforms them into a readable Markdown structure, and outputs the result as either a plain text file or streamed to stdout.
It is especially useful for:

• Static code analysis or documentation generation
• Developer tooling and AI workflow integration

Supports mono-repos, source indexing, and flexible file filtering for efficient context window management in LLMs.

Quick Start

Basic usage

npx tscribe > out.txt

By default, this command recursively scans the current working directory (.), collects *.ts and *.tsx files, prepends Markdown-style section headers, and writes the result to stdout.

You can redirect this output to a file (e.g., out.txt) as shown above.

Optional flags

npx tscribe --src src           # choose a folder explicitly
npx tscribe --out dump.txt      # write straight to a file

These flags allow explicit control over the input source and output format, whether writing to a file or creating a bundled archive.

Examples

| Goal | Command | | ------------------------------ | ------------------------------------ | | Dump all source under src/ | tscribe --src src | | Use custom file extensions | tscribe --ext ts,mts,tsx | | Plain‑text headings | tscribe --format plain | | Alphabetical sort, ignore dist | tscribe --sort alpha --ignore dist | | List matched files only | tscribe --list | | Watch and rebuild | tscribe --watch |

Features

• Concatenate .ts, .tsx, or any extension list
• Set --ext * to match all files regardless of extension.
• Markdown or plain‑text headings (--format)
• Sort by alpha, path, or mtime
• Ignore patterns with safe defaults (node_modules,dist,.git), use POSIX-style globs relative to the working directory
• Output to stdout, file (--out)
• Watch mode with live rebuilds
• Quiet / verbose logging flags

Installation

npm add -D tscribe   # or npm install --save-dev tscribe

You can always use npx tscribe … without installing globally.

CLI Usage

tscribe [options]

| Flag | Description | Default | | ----------------------------- | --------------------------------------- | ------------------------ | | -s, --src <dir> | Root folder to scan | . | | -e, --ext <list> | Comma‑separated extensions | ts,tsx | | --ignore <patterns> | Glob ignore patterns | node_modules,dist,.git | | --heading <template> | Heading template ({file} placeholder) | auto | | --format <md\|plain> | Heading style | md | | --sort <alpha\|path\|mtime> | Sort mode | path | | -o, --out <file> | Write plain‑text output file | – | | --list | Print file list only | – | | --watch | Watch for changes | – | | --verbose | Debug output | – | | --quiet | Suppress logs | – |

Heading Templates

When you run tscribe, it prints each file’s contents prefixed by a heading showing the file’s relative path. This helps distinguish which content comes from which file.

Below is a simulated output when tscribe processes two files:

### src/utils/math.ts

import fs from 'fs'
import path from 'path'

export function add(a: number, b: number): number {
return a + b
}

### components/Button.tsx

import React from 'react'

export const Button = () => <button>Click me</button>

Built‑in Formats

1. Markdown (default)

Prefix each path with ### :

tscribe --format md

### src/utils/math.ts

### components/Button.tsx

2. Plain Text

Wrap the path in a code comment with --:

tscribe --format plain

// --- src/utils/math.ts ---
// --- components/Button.tsx ---

Custom Heading Templates

Use --heading to supply any template, inserting {file} where the path should go. This overrides --format.

tscribe --heading "/* === {file} === */"

/* === src/utils/math.ts === */
/* === components/Button.tsx === */

You can include emojis, metadata, or block comments:

tscribe --heading "// 🚀 File: {file} 🚀"

// 🚀 File: src/utils/math.ts 🚀
// 🚀 File: components/Button.tsx 🚀

Config file

tscribe.(c)js or .json files are merged with CLI flags (CLI wins).

// tscribe.config.js
export default {
  src: "packages",
  ext: "ts,tsx",
  format: "md",
  sort: "alpha",
  ignore: "node_modules,dist,coverage",
};

Library API

Use the same power as the CLI from code. Call tscribe(opts) and await the Promise.

Full example

import { tscribe } from "tscribe";

await tscribe({
  src: "src", // folder to scan
  ext: "ts,tsx", // file extensions
  ignore: "dist,.git", // optional ignore patterns
  format: "md", // "md" or "plain"
  sort: "alpha", // "alpha", "path", or "mtime"
  out: "dump.txt", // write to this file (else stdout)
  verbose: true, // show debug logs
});

You may omit most fields. If out is not provided, then output is sent to stdout.

Options reference

| Property | Type | Default | Description | | --------- | ------------------------------ | -------------------------- | --------------------------------------------------------------------------------------- | | src | string | "." | Root directory to scan. Relative or absolute. | | ext | string | "ts,tsx" | Comma‑separated extension, or * for all files. | | ignore | string | "node_modules,dist,.git" | Glob patterns to exclude (comma‑sep). | | heading | string | (auto) | Custom heading template; {file} replaced by relative path. | | format | 'md' \| 'plain' | 'md' | Heading style. | | sort | 'alpha' \| 'path' \| 'mtime' | 'path' | File ordering. | | out | string | – | Plain‑text output file. If out is not provided, then output is written to stdout. | | list | boolean | false | Print file list only (no concatenation). | | watch | boolean | false | Watch mode—re‑run on changes. | | quiet | boolean | false | Suppress normal logs. | | verbose | boolean | false | Extra debug logs. |

Return value

tscribe() returns Promise<void>. It either completes the side‑effect (write or stdout) or throws an error you can catch.

Helper Utilities

These low-level functions are exported for programmatic or test-specific use.

applySort

applySort(files: string[], mode: "alpha" | "path" | "mtime"): Promise<string[]>

Sorts file paths based on the selected strategy:

• alpha: alphabetical (Natural sort order)
• path: original input order
• mtime: by file modification time (ascending)

License

MIT © Soluble Labs Co., Ltd.