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

# Contexity Quickstart: Attach a Project and Connect an Agent

> Attach Contexity to a project, connect an agent host, and let AI agents call context tools automatically. Takes less than 5 minutes to set up.

This guide walks you through attaching Contexity to an existing Git project, connecting an agent host, and verifying that everything is working. Before you begin, make sure you have built or installed the `contexity` CLI — see the [Installation guide](/install) if you have not done that yet.

<Steps>
  <Step title="Attach a Project">
    Run the following two commands from any directory, replacing `/path/to/project` with the absolute path to your Git repository:

    ```bash theme={null}
    contexity --project /path/to/project init --yes
    contexity --project /path/to/project attach
    ```

    The `init` command bootstraps the project and the `--yes` flag accepts all prompts non-interactively. The `attach` command registers the project with your local Contexity state home. After these two commands complete, you will have:

    * `.cxcap/project.identity.json` written into the project root — this file carries the project's stable identity across sessions and should be committed to version control.
    * Local durable state created in the Contexity state home — this is where run ledgers, memory entries, and source captures are persisted.
  </Step>

  <Step title="Retrieve Context">
    Test that Contexity can assemble a context pack for a real task:

    ```bash theme={null}
    contexity --project /path/to/project resume --task "fix the current issue"
    ```

    The output is a bounded context pack. Each entry in the pack includes trust level, freshness score, original source, and selection metadata that explains why Contexity chose to include it. This lets you — and the agent — verify that the retrieved context is current and traceable before acting on it.
  </Step>

  <Step title="Connect an Agent Host">
    Contexity integrates with agent hosts through a generated configuration. Always preview the configuration before applying it:

    ```bash theme={null}
    contexity --project /path/to/project host install codex --dry-run
    ```

    The `--dry-run` flag prints exactly what Contexity would write without making any changes. Review the output, then apply it:

    ```bash theme={null}
    contexity --project /path/to/project --yes host install codex
    ```

    Contexity supports the following host profiles out of the box:

    | Profile       | Host                                                 |
    | ------------- | ---------------------------------------------------- |
    | `codex`       | OpenAI Codex CLI                                     |
    | `claude-code` | Anthropic Claude Code                                |
    | `cursor`      | Cursor editor                                        |
    | `vscode`      | Visual Studio Code with a compatible agent extension |

    Replace `codex` in the commands above with whichever profile matches your agent host.
  </Step>

  <Step title="Let the Agent Use It">
    Once the host configuration is in place, your agent host calls Contexity automatically over the MCP tool interface — you do not need to invoke these tools yourself during normal use. The host calls them in sequence across a task lifecycle:

    * `context_start_run` — called at the start of every agent task to open a tracked run in the ledger.
    * `context_retrieve_pack` — called before the agent begins editing to fetch a bounded, task-aware context pack.
    * `context_impact` — called before the agent edits a file that Contexity has an existing record for, to surface any known implications.
    * `context_detect_changes` — called after meaningful edits to record what changed and update freshness signals.
    * `context_close_run` — called at task closeout to seal the run record and persist any candidate memory entries for review.

    You only need to interact with Contexity directly when you want to review or promote candidate memory entries, ingest an external source, or run diagnostics.
  </Step>

  <Step title="Verify the Setup">
    Run the built-in doctor check to confirm the project is healthy and all connections are configured correctly:

    ```bash theme={null}
    contexity --project /path/to/project doctor
    ```

    The doctor command inspects the project identity file, validates the state home, and checks the host configuration. It reports any issues with actionable remediation steps.

    <Note>
      If you are working from a source checkout and want to run the full test suite, use `cargo test --workspace` from the repository root.
    </Note>
  </Step>
</Steps>