> ## Documentation Index
> Fetch the complete documentation index at: https://tashfiq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AE-CTX-004

> `.gitignore` should exclude common agent and local artifact noise.

**Rule ID:** AE-CTX-004 · **Severity:** <Badge color="yellow">Medium</Badge> · **Category:** Context · **Auto-fixable:** Yes

## Why this rule

Agent session files checked into git expose local machine state and session history to the repo's commit record. They also inflate the tracked file set every agent scans on each task, adding irrelevant noise to the agent's view of the codebase.

## What triggers it

Charter checks whether `.gitignore` excludes the following agent session artifact patterns:

| Pattern             | What it covers                              |
| ------------------- | ------------------------------------------- |
| `.charter/`         | Charter local run state and session cache   |
| `*.charter-session` | Charter session files                       |
| `.claude/local/`    | Claude Code local settings and session data |
| `.cursor/cache/`    | Cursor IDE agent cache                      |

The finding also fires if any of these patterns are **already tracked in git** — a `.gitignore` entry alone does not remove a file that was previously committed.

## Examples

<Tabs>
  <Tab title="Failing">
    ```gitignore .gitignore (missing entries) theme={null}
    node_modules/
    dist/
    # No entries for .charter/, *.charter-session, .claude/local/, .cursor/cache/
    ```

    ```
    # OR: any of these patterns are tracked in git
    $ git ls-files .claude/local/
    .claude/local/preferences.json   ← tracked, fires finding
    ```
  </Tab>

  <Tab title="Passing">
    ```gitignore .gitignore theme={null}
    node_modules/
    dist/

    # Agent artifacts
    .charter/
    *.charter-session
    .claude/local/
    .cursor/cache/
    ```
  </Tab>
</Tabs>

## How to fix

<Steps>
  <Step title="Preview the changes">
    Run [`charter fix`](/cli/fix) with `--rule AE-CTX-004 --dry-run` to see which `.gitignore` entries will be added.
  </Step>

  <Step title="Apply the fix">
    Run `charter fix --rule AE-CTX-004` to append the missing patterns to `.gitignore`.
  </Step>

  <Step title="Remove any already-tracked artifacts">
    If agent artifacts were previously committed, untrack them without deleting the local files:

    <CodeGroup>
      ```bash Remove tracked agent artifacts theme={null}
      git rm --cached .claude/local/ -r
      git rm --cached ".charter/" -r
      git commit -m "chore: untrack agent session artifacts"
      ```
    </CodeGroup>
  </Step>
</Steps>

## Score impact

`Medium` (−4 per finding). No hard cap — caps are reserved for raw-secret and Blocker findings. See [Scoring and caps](/docs/concepts/scoring-and-caps).

## Edge cases

Team-owned config files such as `.cursor/rules`, `.claude/settings.json`, and `hk.pkl` should stay committed. AE-CTX-004 targets local cache and session state, not shared configuration — those paths never fire the finding.

## Related rules

<CardGroup cols={2}>
  <Card title="AE-CTX-001" icon="file-text" href="/rules/AE-CTX-001">
    Context file must exist and be within budget.
  </Card>
</CardGroup>

## CLI

```bash theme={null}
charter explain AE-CTX-004
```