ClearTrace
Start beta

For agents and developers

Connect Codex or Claude in a few minutes.

Agents work with ClearTrace through the CLI, the MCP server, or the HTTP API. Each one uses a scoped API key that you create in the app. Keep the key in the CLEARTRACE_API_KEY environment variable, never in a repository.

API docsOpenAPI (JSON)Discovery (/.well-known)

Run the CLI

Current release: 0.1.108

Needs Node 20 or later. npm exec runs the pinned release, so nothing is installed globally.

shell
export CLEARTRACE_API_KEY="<your ClearTrace API key>"

npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace --version

npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace doctor --solution-id <your-solution-id>

Add the MCP server

https://mcp.cleartrace.dev/mcp

Remote MCP over HTTP. Send your key in the X-ClearTrace-Api-Key header. This Claude Code entry reads it from your environment; other MCP clients, such as Codex, use the same URL and header.

.mcp.json
{
  "mcpServers": {
    "cleartrace": {
      "type": "http",
      "url": "https://mcp.cleartrace.dev/mcp",
      "headers": {
        "X-ClearTrace-Api-Key": "${CLEARTRACE_API_KEY}"
      }
    }
  }
}

Then ask in plain words

ClearTrace tells your agent how to handle short requests, so you do not have to spell out the steps.

  • Refresh ClearTrace across all projects.
  • Scan this solution into ClearTrace.
  • What is open in ClearTrace for this project?
  • Report this bug in ClearTrace.
  • Record the retest in ClearTrace.
  • Resolve ClearTrace architecture gaps.

What to expect

Your first week with one project.

Start with one project. Clarity grows with each task your agents close out.

  1. Day 1

    Connect

    • Create a workspace, a solution and an API key in the app.
    • Put the key in CLEARTRACE_API_KEY, never in a repository.
    • Ask your agent: "Scan this solution into ClearTrace." It installs the kit and shows a preview first.
  2. Day 1

    First scan

    • The scan reports coverage per area: complete, partial or not scanned.
    • Expect a partial picture at first. That is normal.
    • It lists what it could not read and which declarations are missing.
  3. Days 2 to 3

    Declarations

    • The agent drafts small files under architecture/ and headers on living documents.
    • You review them together and agree. Then the agent pushes them.
    • From then on, the declarations are the truth for your architecture.
  4. Days 2 to 5

    First closeouts

    • At the end of each task, the agent records what changed, the outcome, why, the evidence and any doubts.
    • Each closeout appears in the app with its files, tests and open items.

Over time

  • More closeouts give a longer, more useful history: who changed what, why and with what proof.
  • Declarations fill the gaps from the first scan, so the architecture moves from partial toward complete.
  • Test runs and operation runs answer what proved a change and what ran where.
  • Some limits stay. ClearTrace does not read every technology, and it says so instead of guessing.

Best practices

How to get more clarity from ClearTrace.

Small habits, repeated on every task.

  1. 01

    Close out every task

    Say the change, the outcome, why, the evidence and the doubts. An empty reason is allowed. An honest doubt is worth more than a confident summary.

  2. 02

    Agree declarations, then push them

    Let the agent draft the files in architecture/ and review them with it. What you agree becomes the truth.

  3. 03

    Record tests as test runs

    "Tests pass" in a sentence proves little. A test run with its result and scope answers what proved the change.

  4. 04

    Record operation runs at closeout

    Deploys, migrations, database clones and key rotations. Then you can see what ran against which environment, and when.

  5. 05

    One source of truth per database

    Migrations, an ORM or the live schema. Pick one. Two sources for one database give two different answers.

  6. 06

    Headers on living documents only

    Plans, designs and runbooks still in use. Leave old notes alone, and mark replaced documents as superseded.

  7. 07

    One orchestration project for many repositories

    One repository can declare connections, environments and services for the whole solution. "Refresh ClearTrace" from there covers every project.

  8. 08

    Fix the gaps; what is not covered needs no action

    Gaps are missing declarations in your project; your agent can fill them. What is not covered by ClearTrace is not a gap in your project; there is nothing to fix.

Beta

Start with one project.

Connect one repository, run the first scan, and let your agents close out their next tasks. You will see what changed, why, and what is still open.

Start betaSign in