Skip to main content
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 if you have not done that yet.
1

Attach a Project

Run the following two commands from any directory, replacing /path/to/project with the absolute path to your Git repository:
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.
2

Retrieve Context

Test that Contexity can assemble a context pack for a real task:
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.
3

Connect an Agent Host

Contexity integrates with agent hosts through a generated configuration. Always preview the configuration before applying it:
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:
contexity --project /path/to/project --yes host install codex
Contexity supports the following host profiles out of the box:
ProfileHost
codexOpenAI Codex CLI
claude-codeAnthropic Claude Code
cursorCursor editor
vscodeVisual Studio Code with a compatible agent extension
Replace codex in the commands above with whichever profile matches your agent host.
4

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.
5

Verify the Setup

Run the built-in doctor check to confirm the project is healthy and all connections are configured correctly:
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.
If you are working from a source checkout and want to run the full test suite, use cargo test --workspace from the repository root.