Usage

Quick start

# Generate context for the current directory
pctx

# Include a file tree
pctx --tree

# Copy generated context to the clipboard
pctx --clipboard

# Write generated context to a file
pctx --output context.md

# Overwrite an existing output file
pctx --output context.md --force

# Generate structured JSON
pctx --json

# Preview files without writing the final context
pctx --dry-run

Command overview

# Generate context
pctx [OPTIONS] [PATHS...]

# List files that would be included
pctx files list [OPTIONS]

# Display the included file tree
pctx files tree [OPTIONS]

# Configuration management
pctx config show
pctx config init
pctx config defaults

# Shell completions
pctx completions bash
pctx completions zsh
pctx completions fish
pctx completions powershell
pctx completions elvish

If no path is supplied, pctx scans the current directory:

pctx

You can pass files or directories explicitly:

pctx src README.md Cargo.toml

Output options

Examples:

pctx --format markdown
pctx --format xml
pctx --format plain
pctx --tree --stats
pctx --absolute-paths

Filtering options

Examples:

# Include only Rust and TOML files
pctx --include "*.rs" --include "*.toml"

# Exclude test files
pctx --exclude "*.test.ts" --exclude "__tests__"

# Disable built-in exclusions
pctx --no-default-excludes

# Ignore .gitignore files
pctx --no-gitignore

# Include files up to 2 MiB
pctx --max-size 2048

# Only scan immediate children
pctx --max-depth 1

# Scan children and grandchildren
pctx --max-depth 2

Hidden files and directories

Dot-prefixed paths are hidden by default. Examples include:

• .github
• .vscode
• .env
• project/.config/file.toml

Use --hidden to include them:

pctx --hidden .github
pctx --hidden .github/workflows

Hidden-path filtering is separate from default exclusions and .gitignore rules.

This does not include .github:

pctx --no-default-excludes .github

Use:

pctx --hidden --no-default-excludes .github

The filtering layers are independent:

Truncation options

Defaults:

Examples:

# Keep more of long files
pctx --max-lines 1000 --head-lines 50 --tail-lines 25

# Disable only line-count truncation
pctx --max-lines 0

# Disable only long-line truncation
pctx --max-line-length 0

# Disable all truncation
pctx --no-truncation

When a file is truncated, pctx preserves the beginning and end of the file and inserts an omission marker between them.

Stdin mode

Use --stdin to read paths from standard input:

find . -name "*.rs" -mtime -1 | pctx --stdin

This is useful for composing with other tools:

# Recently changed Rust files
find . -name "*.rs" -mtime -7 | pctx --stdin

# Files from a saved list
cat files_to_review.txt | pctx --stdin

# Files selected by pctx itself
pctx files list --quiet | grep -v test | pctx --stdin

# Changed files in git
git diff --name-only HEAD~5 | pctx --stdin

# Files found by fd
fd -e rs -e toml --changed-within 2weeks | pctx --stdin

Behavior in stdin mode:

• Empty lines are ignored.
• Whitespace around each line is trimmed.
• File paths are processed directly.
• Directory paths are expanded recursively.
• Positional paths are ignored when --stdin is used.
• Non-existent paths are reported as file errors; if some files succeed, the command exits with partial success.

NUL-delimited path input

--stdin splits on newlines, which breaks for paths that contain them. Use --stdin0 or --paths-file0 for NUL-delimited input instead:

# NUL-delimited stdin (pairs naturally with `find -print0`)
find . -type f -print0 | pctx --stdin0

# NUL-delimited path file — avoids command-line length limits and does not
# require keeping an interactive stdin pipe open
pctx --paths-file0 selected-paths.bin

--stdin, --stdin0, and --paths-file0 are mutually exclusive. Positional paths are ignored whenever any of them is used, and an empty input is treated as no matching files (exit code 6).

Path aliases

--path-alias ALIAS=PATH maps files under an absolute directory to a short display name, which is useful for combining unrelated roots (e.g. multiple repositories) without leaking absolute paths into the generated output:

pctx \
  /home/me/api/src/main.rs \
  /home/me/shared/src/lib.rs \
  --path-alias api=/home/me/api \
  --path-alias shared=/home/me/shared

This renders paths as api/src/main.rs and shared/src/lib.rs. Notes:

• PATH must exist and resolve to a directory.
• Aliases must be unique, and each PATH may only be aliased once.
• When aliased roots are nested, the most specific (deepest) root wins.
• --absolute-paths overrides aliases and always shows the full path.

Configuration file selection

By default, pctx searches the current directory and its parents for .pctx.toml. Override this with:

# Explicit configuration
pctx --config /workspace/.pctx.toml

# Ignore all config files
pctx --no-config

--config and --no-config are mutually exclusive. Only an automatically discovered malformed config warns and falls back to defaults; an explicitly supplied --config file that is missing or malformed is a hard error.

Capabilities

pctx capabilities reports which machine-readable features this build supports, which is useful for integrations that need to detect support before using a flag:

pctx --json capabilities

Listing files

# Human-readable file list
pctx files list

# Bare paths only, one per line
pctx files list --quiet

# JSON output
pctx files list --json

--quiet is designed for pipelines:

pctx files list --quiet | xargs wc -l

File tree

pctx files tree
pctx files tree --json

To include the same tree in generated context:

pctx --tree

Dry run

Use --dry-run to inspect what would be included:

pctx --dry-run
pctx --dry-run --json

Dry run still scans and processes files so it can report truncation and approximate token counts, but it does not write the final context document.

Global options

Practical recipes

# Generate compact context for a Rust crate
pctx --include "*.rs" --include "*.toml" --tree

# Prepare context for a code review from changed files
git diff --name-only main...HEAD | pctx --stdin --tree

# Generate XML for a downstream parser
pctx --format xml --output context.xml

# Copy only source-like files to clipboard
pctx src Cargo.toml README.md --clipboard

# Show what would be included after filters
pctx --include "*.ts" --exclude "*.test.ts" --dry-run

# Find files pctx would include, then post-filter with grep
pctx files list --quiet | grep -E '\.(rs|toml)$' | pctx --stdin