Quick start

The fastest path to the real ContextIQ workflow. Everything here runs locally and needs no API key.

1. Install

pipx install "contextiq[all]"      # isolated global install (recommended)
# or
pip install "contextiq[all]"       # into the current environment

You can also run the single file directly with zero dependencies for the core CLI:

python tokengraph_all.py --help

TIP

Both invocations are equivalent. This guide uses the tokengraph console script; substitute python tokengraph_all.py if you're running from source.

2. Build the graph

tokengraph index

This parses your repo into .tokengraph/graph.db. You rarely run this again — the graph auto-refreshes on every query, so it never goes stale.

3. Get a context pack for a task

tokengraph context "add retry logic to the http client" -b 6000

You get a token-budgeted pack of only the relevant symbols — paste it into your AI assistant instead of dumping whole files. The pack prints to stdout; save it to a file with -o when you want to reuse it (e.g. to judge the answer later):

tokengraph context "add retry logic to the http client" -b 6000 -o context.md

4. Ask, with intent + coverage + risk

tokengraph ask "explain the auth flow"

ask returns a focused pack plus metadata: what it thinks the task is, how well the context covers it, and the risk of acting on it.

5. Validate the coverage (CI-friendly gate)

tokengraph validate "auth login token" --min-coverage 60

Exits non-zero if coverage is below the threshold — wire it into a hook so an agent never acts on thin context.

6. Judge whether the answer is grounded

Save your assistant's answer, then score it against the context you gave it:

tokengraph judge --answer-file response.txt --context-file context.md

Outputs a 0–100% grounding score with a grounded=True/False verdict (threshold 50%).

7. Verify — catch fabricated files & symbols

tokengraph verify --answer-file response.txt

Flags any file / symbol / import the answer references that doesn't exist in your repo (with did-you-mean suggestions). Exits non-zero if any are found.

The loop, in one line

ask  →  validate  →  (AI answers)  →  judge  →  verify

Next steps

• Wire it into your editor once: MCP server
• Learn each stage: Retrieval · Validate · Judge · Verify
• Generate code safely: Conventions & scaffolding
• Prove the savings: Savings dashboard