> ## 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 System quickstart: install and configure

> Install the two-file context system, run init, and start your first agent session with persistent project knowledge — in under 5 minutes.

Getting Agent Context System running takes two steps: copy the files into your project, then run `agent-context init`. After that, every agent session starts with your project's patterns, boundaries, and gotchas already loaded — no re-explaining required.

## Choose your install method

<Tabs>
  <Tab title="GitHub Copilot (recommended)">
    Use the official Copilot skill registry. This installs the system as a managed skill and makes it easy to pull updates later.

    ```bash theme={null}
    npx skills add AndreaGriffiths11/agent-context-system
    bash .agents/skills/agent-context-system/scripts/init-agent-context.sh
    ```

    That's it — the init script creates your files and wires up `copilot-instructions.md` automatically.
  </Tab>

  <Tab title="Manual / any agent">
    Copy only the files you need. Works with any agent: Claude Code, Cursor, Windsurf, OpenClaw, or any tool that reads an instruction file.

    ```bash theme={null}
    git clone https://github.com/AndreaGriffiths11/agent-context-system.git /tmp/acs
    cp /tmp/acs/AGENTS.md /tmp/acs/agent-context ./
    cp -r /tmp/acs/agent_docs /tmp/acs/scripts ./
    rm -rf /tmp/acs
    ./agent-context init
    ```
  </Tab>

  <Tab title="OpenClaw">
    Clone directly into your skills directory. OpenClaw picks it up as a workspace skill on the next session.

    ```bash theme={null}
    git clone https://github.com/AndreaGriffiths11/agent-context-system.git skills/agent-context-system
    ```

    Restart your OpenClaw session. It reads `AGENTS.md` automatically — no `init` step required.
  </Tab>

  <Tab title="New project from template">
    Start a brand-new repo from the GitHub template, then initialize.

    ```bash theme={null}
    gh repo create my-project --template AndreaGriffiths11/agent-context-system
    cd my-project
    ./agent-context init
    ```
  </Tab>
</Tabs>

## What init creates

After running `agent-context init`, your project will contain:

```
your-repo/
├── AGENTS.md                    # Committed. Always loaded. Under 120 lines.
├── .agents.local.md             # Gitignored. Personal scratchpad.
├── CLAUDE.md                    # Symlink → AGENTS.md (for Claude Code)
├── agent-context                # The CLI script
├── agent_docs/
│   ├── conventions.md           # Full code patterns and naming
│   ├── architecture.md          # System design and data flow
│   └── gotchas.md               # Extended known traps
└── scripts/
    └── init-agent-context.sh    # Wrapper for npx skills installs
```

`init` also adds `.agents.local.md` to your `.gitignore` so your personal scratchpad is never committed.

<Note>
  If you're using Claude Code, `init` creates a `CLAUDE.md` symlink pointing to `AGENTS.md`. Claude doesn't read `AGENTS.md` directly yet — the symlink bridges this automatically.
</Note>

## Set up your project context

<Steps>
  <Step title="Edit AGENTS.md">
    Open `AGENTS.md` and replace the placeholder content with your actual project details. Fill in your project name, stack, package manager, build and test commands, and the real patterns and gotchas from your codebase.

    ```bash theme={null}
    # Open AGENTS.md in your editor
    $EDITOR AGENTS.md
    ```

    <Tip>
      Editing `AGENTS.md` is the highest-leverage action you can take after setup. Every line loads into every agent session. A well-filled `AGENTS.md` eliminates the most common "wrong answer" mistakes agents make on your specific codebase. Keep it under 120 lines — dense beats verbose.
    </Tip>
  </Step>

  <Step title="Fill in agent_docs/">
    Add deeper references to the `agent_docs/` directory for content that doesn't fit in `AGENTS.md`'s compressed format: full naming conventions, architecture decisions, extended gotcha explanations. Delete the templates that don't apply to your project.

    ```
    agent_docs/
    ├── conventions.md   # Naming, file structure, code style
    ├── architecture.md  # System design, data flow, key decisions
    └── gotchas.md       # Extended traps with full explanations
    ```

    The agent loads these files on demand — only when a task requires more depth than `AGENTS.md` provides.
  </Step>

  <Step title="Customize .agents.local.md">
    Open `.agents.local.md` and add your personal preferences: coding style, planning preferences, tone preferences. This file is gitignored and only affects your sessions.

    ```bash theme={null}
    $EDITOR .agents.local.md
    ```
  </Step>

  <Step title="Verify your setup">
    Run `agent-context validate` to confirm everything is in place before your first session.

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

    The validator checks that `AGENTS.md` exists and is under 120 lines, `.agents.local.md` is gitignored, and the `CLAUDE.md` symlink is wired up correctly.
  </Step>

  <Step title="Start working">
    Open your agent tool and start a session. The agent reads both `AGENTS.md` and `.agents.local.md` at session start, applies your project knowledge, and logs learnings to the scratchpad at session end.

    For most agents (Copilot Chat, Cursor, Windsurf), prompt the agent to log the session when you're done with meaningful work:

    ```
    Log this session to the scratchpad.
    ```

    Claude Code handles this automatically via its auto memory system.
  </Step>

  <Step title="Promote stable patterns">
    Over time, your scratchpad accumulates session notes. When a pattern recurs across 3 or more sessions, the agent flags it in `.agents.local.md` under "Ready to Promote." Run `agent-context promote` to review what's been flagged.

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

    To auto-append all flagged patterns directly to `AGENTS.md`:

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

    Review the changes, then commit `AGENTS.md` to share the promoted knowledge with your team.
  </Step>
</Steps>

## CLI reference

All commands operate in the current working directory.

```bash theme={null}
agent-context init              # Set up context system in current project
agent-context validate          # Check setup is correct
agent-context promote           # Find patterns to move from scratchpad to AGENTS.md
agent-context promote --autopromote  # Auto-append patterns recurring 3+ times
```

## How knowledge flows

Once the system is running, knowledge follows a one-way promotion path:

```
Session notes → .agents.local.md → agent flags stable patterns → you promote to AGENTS.md
                    (personal)                                         (shared)
```

The scratchpad is where things are still experimental. `AGENTS.md` is where proven knowledge lives. The agent flags candidates — you make the call.

<Info>
  For a deeper look at the session logging lifecycle, compression, and auto-reflect observation mode, see [how it works](/concepts/how-it-works).
</Info>