Skip to content

AGENTS.md: trim the sections that repeat other files, to cut every session's starting context #167

Closed

Description

@CaffeinatedCoder

Problem

AGENTS.md loads into every agent session in this repository: 22,230 characters, about 6k tokens. In a fresh session it is most of the roughly 10k tokens of memory files, out of a starting context of about 42k (measured 2026-10-29 with two Sonnet sessions and this session's context breakdown). Several sections repeat what another file already holds, or detail what an agent only needs at one moment:

  • Finding code (~920 tokens): most of it is the dated list of what the code graph misses, as measured on 2026-10-13.
  • Commands (~920): the BuildVerdict, BashGuard and session-start paragraph repeats what the guard prints when it refuses a command, and decisions 92 and 105.
  • Issues (~450): largely CONTRIBUTING's "Issues and labels" and "Pull requests", plus the maintainer's global tracking rule, which also loads into every session.
  • Workflow step 7 (~400): the oracle-kit mechanics that test/oracles/README.md already holds.
  • Releasing (~300): CONTRIBUTING's "Releasing" step 1.

Change

Trim those five sections to what an agent must have before it acts, and point to where the rest lives. Move the graph measurements into a design note of their own, linked from design/plan.md. Keep "Rules that are easy to break" word for word. Keep every heading another document cites: decision 93 cites "Finding code".

Done when

Activity

  1. added this to the 2.3.0 milestone on Oct 29, 2026
  2. added
    documentationImprovements or additions to documentation
    area/toolingThe repository's tools: prober, verdict, guard, docs-query, smoke test
    on Oct 29, 2026
  3. changed the title [-]AGENTS.md: trim the sections that repeat other files, about 2k tokens off every session's start[/-] [+]AGENTS.md: trim the sections that repeat other files, to cut every session's starting context[/+] on Oct 29, 2026
  4. CaffeinatedCoder commented on Oct 29, 2026

    @CaffeinatedCoder
    OwnerAuthor

    Done in #168, merged into release/2.3.0 (d64a545): AGENTS.md 22,230 to 17,956 characters, about 1.1k tokens less per session start; the graph's measurements are in design/code-graph.md.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/toolingThe repository's tools: prober, verdict, guard, docs-query, smoke testdocumentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions