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

# Troubleshoot Common Contexity Setup and Runtime Issues

> Diagnose and fix the most common Contexity problems: agents not calling tools, stale context, project initialization errors, and noisy metrics.

If something isn't working, Contexity's built-in health and doctor commands can diagnose most problems. This page covers the most common issues and how to fix them.

<Accordion title="Agent is not calling Contexity">
  The most frequent cause is a missing or broken host configuration. Run the following command to check whether the host is correctly set up for your project:

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

  If the host config is missing or broken, reinstall it:

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

  Restart the host after any config changes so it picks up the updated MCP server registration.
</Accordion>

<Accordion title="Project not initialized">
  If Contexity has no record of your project, the agent has nothing to work with. Initialize the project and attach it in one sequence:

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

  After `attach` completes, the project is registered and the MCP server can start serving context for it.
</Accordion>

<Accordion title="Context looks stale">
  When the agent's answers feel outdated, run a fast analysis to refresh project intelligence:

  ```bash theme={null}
  contexity --project /path/to/project analyze --depth fast
  contexity --project /path/to/project health --issues
  ```

  If a specific context item is wrong, ask the agent to invalidate it, or list all items manually to find the one you want to remove:

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

  Once you have identified the stale item, invalidate it through the agent or the CLI. Contexity will replace it the next time that context is observed or analyzed.
</Accordion>

<Accordion title="Metrics output is too noisy">
  If metrics are cluttering the agent's responses or your terminal output, disable visible metrics for the project:

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

  Structured metrics remain available for inspection at any time — disabling visibility does not delete the underlying data.
</Accordion>

<Accordion title="An external source was captured incorrectly">
  If Contexity captured an external reference — such as a Slack message, ticket, or document — that turns out to be wrong, obsolete, private, or superseded, signal the agent to invalidate it using the MCP tool:

  ```text theme={null}
  context_invalidate_external_context
  ```

  Agents should call this tool when you tell them an external update was incorrect. The reference and any signals extracted from it will be marked invalid and excluded from future retrieval.
</Accordion>

<Tip>
  Run `contexity doctor` after any setup change to get a full health report for your project.
</Tip>