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

# agent-context CLI reference: init, validate, promote

> Complete reference for every agent-context command and helper script — init, validate, promote, and consolidation scripts — with flags and expected output.

The `agent-context` CLI manages your Agent Context System from the terminal. It initializes the file structure in a project, validates your setup, and moves proven patterns from your personal scratchpad into the shared `AGENTS.md`. All commands operate within your current working directory — the CLI never writes outside the project root.

## Main commands

<AccordionGroup>
  <Accordion title="agent-context init">
    Sets up the Agent Context System in your current project. Run this once per clone. It is safe to re-run — it will not overwrite files that already exist.

    ```bash theme={null}
    agent-context init
    ```

    **What it does:**

    1. Creates `.agents.local.md` from the bundled template (or a minimal fallback if the template is not found).
    2. Adds `.agents.local.md` to `.gitignore`, creating the file if it does not exist.
    3. Creates a `CLAUDE.md` symlink pointing to `AGENTS.md` so Claude Code picks up your context.
    4. Creates the `agent_docs/` directory with starter files (`conventions.md`, `architecture.md`, `gotchas.md`) if `AGENTS.md` is present but `agent_docs/` is not.

    **When to use it:** Run `init` immediately after cloning a project that uses the Agent Context System, or when setting up a new project for the first time.

    **Expected output:**

    ```text theme={null}
    Initializing Agent Context System

    ✓ Created .agents.local.md from template
    ✓ Added .agents.local.md to .gitignore
    ✓ Created CLAUDE.md symlink → AGENTS.md
    ✓ Created agent_docs/ with templates

    Setup complete!

    Next steps:
      1. Edit AGENTS.md with your project specifics
      2. Fill in agent_docs/ with deeper references
      3. Run 'agent-context validate' to check setup
    ```

    <Note>
      If `AGENTS.md` is not present when you run `init`, the CLAUDE.md symlink step is skipped. Copy `AGENTS.md` to your project first, then re-run `init`.
    </Note>
  </Accordion>

  <Accordion title="agent-context validate">
    Checks that your Agent Context System setup is correct. Use this after `init` and any time you want to verify nothing has drifted.

    ```bash theme={null}
    agent-context validate
    ```

    **What it checks:**

    * `AGENTS.md` exists and is under 120 lines.
    * `.agents.local.md` exists.
    * `.agents.local.md` is listed in `.gitignore`.
    * `CLAUDE.md` is a symlink pointing to `AGENTS.md`.
    * `agent_docs/` directory exists (warning if missing, not an error).
    * `AGENTS.md` does not contain obvious secrets (API keys, tokens, passwords).

    **When to use it:** After initial setup, after manually editing `AGENTS.md`, or as part of a CI check to catch accidental secret commits.

    **Expected output (all passing):**

    ```text theme={null}
    Validating Agent Context System

    ✓ AGENTS.md exists
    ✓ AGENTS.md is under 120 lines (87 lines)
    ✓ .agents.local.md exists
    ✓ .agents.local.md is in .gitignore
    ✓ CLAUDE.md symlink → AGENTS.md
    ✓ agent_docs/ directory exists
    ✓ No obvious secrets in AGENTS.md

    All checks passed!
    ```

    The command exits with a non-zero status if any errors are found, making it suitable for use in scripts and CI pipelines.

    <Warning>
      `validate` checks for common secret patterns (API keys matching `sk-...`, GitHub tokens matching `ghp_...`, and key-value patterns with words like `password` or `token`). It is not a substitute for a dedicated secrets scanner — treat it as a quick sanity check.
    </Warning>
  </Accordion>

  <Accordion title="agent-context promote">
    Shows patterns that your agent has flagged in the `## Ready to Promote` section of `.agents.local.md`, and displays stats about how many sessions have been logged. Use this to decide what to move into `AGENTS.md`.

    ```bash theme={null}
    agent-context promote
    ```

    **What it does:**

    Reads `.agents.local.md` and prints anything in the `## Ready to Promote` section. Also shows the total number of sessions logged so you can judge how much history has accumulated.

    **When to use it:** Periodically — after several sessions have built up, or when your agent tells you it has flagged new patterns during compression.

    **Expected output:**

    ```text theme={null}
    Finding Patterns to Promote

    Ready to Promote (flagged by agent):

      Result<T> for error handling | src/lib/errors.ts
      DB_URL required for unit tests | set even in test env

    Stats:
      Sessions logged: 8
      Use --autopromote to automatically append patterns recurring 3+ times
    ```

    If no patterns have been flagged yet, it prints `(none flagged yet)`.
  </Accordion>

  <Accordion title="agent-context promote --autopromote">
    Automatically appends all patterns from the `## Ready to Promote` section of `.agents.local.md` into `AGENTS.md`, then clears the promoted items from the scratchpad.

    ```bash theme={null}
    agent-context promote --autopromote
    ```

    **What it does:**

    1. Reads the `## Ready to Promote` section of `.agents.local.md`.
    2. Checks that `AGENTS.md` is under 120 lines before proceeding.
    3. Appends each pipe-delimited pattern to `AGENTS.md` (creating a `## Patterns` section if one does not exist).
    4. Clears the promoted patterns from the scratchpad and logs the promotion date.

    **When to use it:** When you have reviewed flagged patterns with `agent-context promote` and are ready to commit them to `AGENTS.md` without manually copying each line.

    **Expected output:**

    ```text theme={null}
    Auto-Promoting Patterns (threshold: 3 sessions)

    ✓ Auto-promoted 2 pattern(s) to AGENTS.md

    → Cleared promoted patterns from scratchpad
    → Review AGENTS.md and commit when ready
    ```

    <Warning>
      `--autopromote` writes directly to `AGENTS.md`. Review the result with `git diff` before committing. If `AGENTS.md` already has 120 lines, the command will refuse to run — compress or trim the file first.
    </Warning>

    <Note>
      You can adjust the recurrence threshold with `--threshold N`. The default is 3 sessions. Patterns with fewer recurrences are still shown by `promote` but are not auto-appended.
    </Note>
  </Accordion>

  <Accordion title="agent-context help">
    Prints usage information for all commands.

    ```bash theme={null}
    agent-context help
    # also accepts: --help or -h
    ```
  </Accordion>
</AccordionGroup>

## Helper scripts

These scripts live in `scripts/` and handle memory consolidation and migration. Run them from your project root.

<AccordionGroup>
  <Accordion title="auto-consolidation-trigger.sh">
    Checks whether automatic memory consolidation should run, based on time elapsed and session count, then triggers consolidation if the conditions are met.

    <CodeGroup>
      ```bash Check whether consolidation should trigger theme={null}
      ./scripts/auto-consolidation-trigger.sh --check
      ```

      ```bash Force consolidation regardless of gates theme={null}
      ./scripts/auto-consolidation-trigger.sh --force
      ```
    </CodeGroup>

    **Gates checked:**

    * **Time gate:** At least 24 hours since the last consolidation.
    * **Session gate:** At least 5 sessions accumulated since last consolidation.
    * **Lock gate:** No consolidation already running (checked via `.agents/.consolidation-lock`).

    **When to use it:** Add `--check` to a shell hook or run it manually when you want to let the system decide whether consolidation is warranted. Use `--force` when you want consolidation to run immediately regardless of thresholds.
  </Accordion>

  <Accordion title="consolidate-memory.sh">
    Runs the full 4-phase memory consolidation: orient, gather, consolidate, prune. Reads recent daily logs from `.agents/logs/` and merges them into the curated topic files under `.agents/topics/`.

    <CodeGroup>
      ```bash Run consolidation theme={null}
      ./scripts/consolidate-memory.sh
      ```

      ```bash Preview what would happen without writing theme={null}
      ./scripts/consolidate-memory.sh --dry-run
      ```

      ```bash Consolidate only the last N days of logs theme={null}
      ./scripts/consolidate-memory.sh --days 14
      ```
    </CodeGroup>

    **What it produces:**

    * Updated `.agents/topics/patterns.md`, `.agents/topics/gotchas.md`, `.agents/topics/preferences.md`.
    * An updated `.agents/local.md` index (kept under 200 lines / 25 KB).
    * Approximately a 9:1 compression ratio on accumulated session logs.

    **When to use it:** When you want to manually trigger consolidation rather than waiting for the auto-trigger thresholds.
  </Accordion>

  <Accordion title="migrate-to-daily-logs.sh">
    Migrates an older flat `.agents.local.md` scratchpad to the structured daily logs format (`.agents/logs/YYYY-MM-DD.md` and `.agents/topics/`).

    <CodeGroup>
      ```bash Run migration theme={null}
      ./scripts/migrate-to-daily-logs.sh
      ```

      ```bash Preview migration without writing theme={null}
      ./scripts/migrate-to-daily-logs.sh --dry-run
      ```
    </CodeGroup>

    **When to use it:** If you set up the Agent Context System before the daily logs format was introduced and your project still uses the legacy flat `.agents.local.md` file. Run once — the script exits early if it detects the migration has already happened.
  </Accordion>
</AccordionGroup>