Command Reference

usage: astwire [-h] [--targets PATH [PATH ...]] [-i] [--languages] [--lang NAME[,NAME]] [--analysis] [--strip-waste] [--skeleton] [--since REF] [--max-depth N] [--decay-depth N] [--graph]
               [--max-tokens MAX_TOKENS] [-f {markdown,llm,json}] [-o OUTPUT] [-v] [--uninstall]
               [targets ...]

Dependency-aware context compiler and token tree-shaker.

positional arguments:
  targets               Target files or directories to process (default: current directory).

options:
  -h, --help            show this help message and exit
  --targets PATH [PATH ...]
                        Same as positional targets. `astwire --skeleton --targets src/` is valid.
  -i, --resolve-imports
                        Follow local imports from supported languages (Python, JS/TS, Go).
  --languages           Print the language capability table and exit.
  --lang NAME[,NAME]    Only include these languages (names or extensions, comma-separated).
  --analysis            Dry-run audit displaying recoverable token waste without writing files.
  --strip-waste         Scrub trailing whitespace and collapse empty lines.
  --skeleton            Strip function/method bodies in languages that support skeletonization.
  --since REF           Seed from files changed since this git ref instead of the given targets (tracked + untracked, gitignore-aware). REF is taken as given -- no base branch or remote is auto-
                        detected. Combine with -i to also pull in what the changed files import; without -i, bundles just the changed files.
  --max-depth N         Only with -i: exclude files more than N import-hops from a seed. Manifests (package.json/go.mod) are always kept. No effect without -i.
  --decay-depth N       Only with -i: skeletonize files more than N import-hops from a seed, even without --skeleton. Non-skeletonizable languages still pass through in full, never dropped. No effect
                        without -i.
  --graph               Only with -i: emit a dependency-graph block (edges between bundled files) before the file contents. No-op with a stderr note if used without -i.
  --max-tokens MAX_TOKENS
                        Ceiling for token budget per output partition.
  -f {markdown,llm,json}, --format {markdown,llm,json}
                        Output format (default: llm). Inferred from -o extension if omitted.
  -o OUTPUT, --output OUTPUT
                        Destination context file (default: context.xml). .md/.json/.xml infer format.
  -v, --version         show program's version number and exit
  --uninstall           Completely remove astwire binary and associated local configuration files.

#Targets

astwire                     # current directory
astwire src/                # a directory
astwire cli.py          # a single file
astwire cli.py config.py   # multiple targets

Defaults to . when no targets are given.

#--targets PATH

Alias for positional targets — useful when another flag would otherwise swallow the path (argparse can misparse astwire --skeleton src/ in some shells; --targets sidesteps that).

astwire --skeleton --targets src/
# same as:
astwire --skeleton src/

#--languages

Prints the language capability table (which extensions are recognized, and which support -i import-following and --skeleton) and exits immediately — no file discovery or other heavy imports run.

astwire --languages

#--lang NAME[,NAME]

Restricts the bundle to specific languages after discovery (including anything pulled in by -i). Accepts language names or extensions, comma-separated.

astwire src/ --lang python,go
astwire src/ --lang ts,tsx,js

An unrecognized name is an error; run astwire --languages for the supported list. Overrides .astwire.toml's targeting.languages outright when both are set.

#-i, --resolve-imports

Recursively discover and bundle local imported modules, starting from each target.

astwire cli.py -i -o context.xml

If a target is a directory, every registered file under it (any language in the capability table, not just Python) seeds the crawl. From there, only languages with an import engine — Python, JavaScript/TypeScript/TSX, and Go — are traced: local import/from ... import for Python, relative ./ specifiers for JS/TS, and in-module paths (via go.mod) for Go. Standard-library, third-party, and node_modules/vendor-style paths are never followed, and imports never escape the project root. See ../architecture/diagrams.md#2-import-resolution--i---resolve-imports for the algorithm.

#--since REF

Seed the bundle from files changed against REF (tracked changes plus new untracked files, gitignore-aware) instead of walking the given targets. Accepts at most one scope path.

astwire src/ --since main -i --skeleton

REF is always taken exactly as given — astwire never auto-detects a base branch or remote. Requires the scope to be inside a git repository and REF to resolve to a real commit; otherwise astwire exits with an error (exit code 2). Combine with -i to also pull in what the changed files import; without -i, the bundle is just the changed files themselves. If -i is on and --decay-depth isn't set explicitly, --since implies --decay-depth 0 (changed files stay full text, everything pulled in via import gets skeletonized).

#--max-depth N

Only meaningful with -i (a stderr note is printed and the flag ignored otherwise). Drops files more than N import-hops from the nearest seed.

astwire src/ -i --max-depth 2

Manifests (package.json, go.mod) are always kept regardless of depth.

#--decay-depth N

Only meaningful with -i. Instead of dropping files past N import-hops, skeletonizes them — even without --skeleton set. Languages that don't support skeletonization still pass through in full; they're never dropped.

astwire src/ -i --decay-depth 1

#--graph

Only meaningful with -i. Emits the dependency edges between bundled files as a graph block ahead of the file contents, in whatever output format is selected.

astwire src/ -i --graph -o context.md

#--analysis

Dry-run audit — prints a token-waste table to stdout, writes no files.

astwire src/ -i --analysis

📊 Token Analysis Report

  File Path (Relative)            Tokens     Wasted   Waste Lines   Waste Bytes   Recoverable %
  ─────────────────────────────────────────────────────────────────────────────────────────────
  cli.py                       1,568         13            16           121           0.83%
  config.py                      556          1             2             4           0.18%
  ast_crawler.py               1,538          1             1             4           0.07%
  skeleton.py                    490          0             0             0           0.00%
  ─────────────────────────────────────────────────────────────────────────────────────────────
  Overall                      4,152         15            19           129           0.36%

Combined with -i, the table gains a Depth column (import-hops from the nearest seed; seeds themselves show 0). The column is omitted entirely when -i isn't used.

Use this before committing to --strip-waste on a large codebase, to see how much is actually recoverable.

#--strip-waste

Scrub trailing whitespace and collapse consecutive empty lines in the written output.

astwire src/ -i --strip-waste -o context.md

#--skeleton

Extract symbol signatures (classes, functions, types) and strip implementation bodies to ....

astwire src/ --skeleton -o skeleton.md

Docstrings, decorators, type annotations, and class structure are preserved — only executable statement bodies inside function/method definitions are removed. Use this to give an LLM the shape of a codebase (public interfaces) without the full implementation, at a fraction of the token cost.

#--max-tokens N

Ceiling for token budget per output partition. When the combined content would exceed N tokens, astwire writes multiple numbered files instead of one.

astwire src/ -i --max-tokens 4000 -o context.md
# → context_part_1.md, context_part_2.md, ...

A single file never gets split across two partitions — if one file alone exceeds N tokens, it becomes the sole member of its own (oversized) partition.

#-f, --format {markdown,llm,json}

Output format. Defaults to llm. See output-formats.md for a full comparison.

astwire src/ -f llm -o prompt.xml
astwire src/ -f json -o context.json

#-o, --output DEST

Destination context file. Defaults to context.xml (or the .astwire.toml output value). -f always wins for format selection; if -f is omitted, a recognized -o extension (.xml/.llm, .md/.markdown, .json) infers the format instead.

astwire src/ -o bundle.md

When partitioning is active, each partition's filename is derived from this stem: bundle_part_1.md, bundle_part_2.md, etc.

#-v, --version

astwire --version

#-h, --help

astwire --help

#--uninstall

astwire --uninstall

Completely removes the astwire binary and associated local configuration files. See installation.md#uninstallation for platform-specific behavior.

#Combining flags

All flags compose. A common "give me a tight, dependency-complete, budgeted LLM bundle" invocation:

astwire cli.py -i --strip-waste --max-tokens 6000 -f llm -o prompt.xml

This traces cli.py's full internal import closure, strips whitespace waste, caps each partition at 6,000 tokens, and writes minimal XML instead of Markdown.

A "review just what I changed, in context" invocation:

astwire src/ --since main -i --graph -o review.md

This bundles only the files changed since main, pulls in what they import (skeletonized by default, since --since implies --decay-depth 0), and prepends a dependency-graph section.