Skip to main content
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.
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:
contexity --project /path/to/project host status
If the host config is missing or broken, reinstall it:
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.
If Contexity has no record of your project, the agent has nothing to work with. Initialize the project and attach it in one sequence:
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.
When the agent’s answers feel outdated, run a fast analysis to refresh project intelligence:
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:
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.
If metrics are cluttering the agent’s responses or your terminal output, disable visible metrics for the project:
contexity metrics disable --project /path/to/project
Structured metrics remain available for inspection at any time — disabling visibility does not delete the underlying data.
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:
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.
Run contexity doctor after any setup change to get a full health report for your project.