---
since: 1.0.0
---

# Configuration Guide

astwire works with zero configuration — every setting has a sane default and can be overridden per-run with CLI flags. `.astwire.toml` exists for when you want a project's defaults to be shared across a team without everyone remembering the same flags.

## `.astwire.toml`

Place this file at your project root (or any ancestor directory of your run — astwire searches upward for it):

```toml
[general]
format = "llm"
strip_waste = true
show_tree = true
output = "context.xml"

[targeting]
languages = ["python", "javascript", "go"]
skip = [
    "tests/**",
    "migrations/**",
    "docs/**",
]

[ai]
max_tokens = 4000
```

Every value here maps to a CLI flag, and **CLI flags always win** when both are supplied:

| `.astwire.toml` key | CLI flag |
| --- | --- |
| `general.format` | `-f`/`--format` |
| `general.strip_waste` | `--strip-waste` |
| `general.output` | `-o`/`--output` |
| `targeting.languages` | `--lang` (overrides, does not merge) |
| `targeting.skip` | *(default-path target resolution only)* |
| `ai.max_tokens` | `--max-tokens` |

`general.show_tree` has no CLI flag — it's config-only, controlling whether Markdown output includes the `## Project Structure` ASCII tree.

For the full field-by-field contract (types, defaults, coercion behavior), see [`../api/configuration.md`](../api/configuration.md).

### Typical use: excluding noise from a default (non `-i`) run

```toml
[targeting]
skip = [
    "tests/",
    "migrations/",
    "*.pyc",
    "__pycache__/",
]
```

This is the built-in default if you don't supply `[targeting]` at all. Override it when your project has additional generated or vendored directories to exclude:

```toml
[targeting]
skip = [
    "tests/",
    "migrations/",
    "*.pyc",
    "__pycache__/",
    "vendor/",
    "static/",
]
```

> `skip` (and `.gitignore`/`.astwireignore`) apply whether or not `-i`/`--resolve-imports` is set: `expand_local_imports()` checks every resolved import target against the same skip/ignore rules as a plain target walk, and excludes it if either would — per SPEC-1.0.md §5, skip/ignore win over the import graph, not the other way around. `-i` additionally hard-denies vendor-style dirnames (`node_modules/`, `vendor/`, `.venv/`, etc.) regardless of `skip`/`.gitignore`.

### Typical use: always bundling as compact LLM-XML with a token ceiling

```toml
[general]
format = "llm"
strip_waste = true

[ai]
max_tokens = 8000
```

Now `astwire src/ -i` alone produces token-bounded, whitespace-stripped, XML-formatted partitions without repeating `-f llm --strip-waste --max-tokens 8000` on every invocation.

## `.astwireignore`

A sibling file to `.gitignore`, using the same pattern syntax, consumed via `IgnoreEngine` by both the default target-resolution path and `-i`'s import expansion. Use it for files you want astwire to skip but don't want to add to your actual `.gitignore` (for example, generated context bundles you don't want astwire to re-bundle on a later run):

```text
# .astwireignore
context.md
context_part_*.md
*.astwire-cache
```

`.astwireignore` and `.gitignore` are both honored, per-directory, at every level of the tree being walked — not just at the project root.

## Precedence, end to end

```text
CLI flags
   │  (always win when set)
   ▼
.astwire.toml  [general] / [targeting] / [ai]
   │  (used when the corresponding flag is omitted)
   ▼
astwireConfig defaults
   format=llm, strip_waste=False, skeleton=False,
   show_tree=True, max_tokens=None, output=context.xml,
   languages=None, skip=[tests/, migrations/, *.pyc, __pycache__/]
```

## Why configuration lives in the project, not the user's home directory

Unlike some developer tools, astwire's config is project-scoped (`.astwire.toml` discovered by walking up from the target), not machine-scoped under `$HOME`. This keeps a team's bundling defaults (skip patterns, preferred format, token ceiling) in version control alongside the code they apply to.