How it works
Agents report. You read the record.
The app is read-only for work records. Agents write through the project kit, CLI, API and MCP, so every record has a source.
Create a workspace, a solution and its projects in the app. Create an API key for your agents.
Your agent installs the project kit and scans each repository. It shows you a preview before it applies anything.
Agree the declarations with your agent: databases, environments, services, operations and flows. They become the truth for your architecture.
At the end of each task, the agent records a closeout: the change, the outcome, the reason, the evidence and the doubts.
Tickets, findings, test runs, releases and operation runs link to the changes they concern.
Review each change and the solution's current state in the app.
In the app
- OverviewAvailable
- Changes, with files and diffsAvailable
- Tickets and findingsAvailable
- Test runs and evidenceAvailable
- ReleasesAvailable
- System architectureAvailable
- Cloud and deployment, with operation runsAvailable
- Data modelPartial
- Data flow (declared flows)Available
- Plans and documentsAvailable
- Intake: bugs, questions and requests from your appsAvailable
- GitHub connection: read-only diffs from GitHubAvailable
- Request support for a technologyPlanned
Partial: the view exists, but the scanner does not read every technology yet. Planned: not built yet.
Scope
What ClearTrace does, and what it does not.
ClearTrace is a record of delivery. Your agents report each task, and the app shows that record. You do not edit work records in the app.
ClearTrace does
- Record each finished task as a closeout: change, outcome, reason, evidence and open doubts.
- Keep tickets, findings, test runs, releases and evidence linked to the changes they concern.
- Show where a change landed: solution, project, repository, service, table or flow.
- Show your architecture as context: components and connections, environments and services, databases and tables, agreed data flows and their documents.
- Scan your repositories, suggest declarations, and say what it could and could not read.
ClearTrace does not
- Watch running services, runtime traffic or installed versions. It is not monitoring or APM.
- Take an inventory of your cloud account.
- Store your documents' text. It keeps the title, the header and the commit history.
- Store your source code unless you choose to. You pick per solution: links only (file names, lines and commits) or the reviewed diff of each change.
- Invent flows or documents. Detection only suggests; what you and your agent declare is the truth.
- List every integration or interface of every component.
- Replace your Git host, ticket tool or coding assistant. It works beside them.
Packages never carry secrets, credentials or local paths. Signed links are stripped.
Own the missing layer
ClearTrace connects what existing tools leave separate.
The gap is not another board, repository, catalog or monitor. The gap is the record between planned work, the actual change, its architecture context and its proof.
| Tool | What it owns | What ClearTrace adds |
|---|---|---|
| GitHub, GitLab, Azure DevOps | Code, PRs, CI, issues | Why each change was made and what proved it, across projects |
| Jira, Linear | Planned work and ticket flow | The actual change and its evidence |
| Backstage, Cortex, OpsLevel | Service catalogs and ownership | Change-by-change proof and impact |
| Sourcegraph | Code search and code intelligence | Delivery evidence and open doubts |
| Datadog, New Relic | Runtime observability | Intent and verification before release (ClearTrace does not monitor) |
| Codex, Claude, coding assistants | Implementation assistance | A record of what the work affected |
Neutral product example
ACME Payments Platform: one feature, many surfaces.
A fictional payments team asks agents to add refund status visibility. ClearTrace shows the chain from intent to commit, API contract, data-model impact, tests, finding, ticket and final decision.
- Guide: product intent, refund workflow, API contract and project boundaries.
- Generate: commits, changed files, data model updates and the closeout.
- Verify and Solve: test run, open finding, remediation ticket and decision.
FAQ
Questions teams ask first.
Does ClearTrace read my code?
The scanner runs on your machine through the CLI. It reads your repository to detect databases, services, workflows and documents, and sends metadata, declarations and coverage.
You choose per solution what it keeps for each change: links only (file names, line ranges, commits and links, never code), or the reviewed diff. It never uploads or keeps your whole repository.
If you connect GitHub, ClearTrace reads the diff of each reported commit live from GitHub when you open it, and does not store it.
Does ClearTrace connect to GitHub?
Optionally, through ClearTrace's own read-only GitHub App. You install it on your account or organization and pick the repositories; it can read repository contents and nothing else, and it never writes to GitHub.
It is separate from your agents' access: Codex and Claude keep pushing to GitHub as they do today, and write to ClearTrace with their agent keys.
In ClearTrace you confirm which repository belongs to each project; only confirmed repositories are read. Repositories elsewhere keep working with the diffs your agents send.
Storing reviewed diffs in ClearTrace is a separate choice: use either, both or neither. When both are on, ClearTrace shows its stored copy first.
Does it store my documents?
No. For plans, designs and runbooks it keeps the title, the header and the commit history. The text is never stored.
Does it watch production?
No. ClearTrace does not watch running services, traffic, installed versions or your cloud account.
It records what your agents report: releases, deploys and other operation runs.
What do my agents need?
An API key in CLEARTRACE_API_KEY, and one way in: the CLI (Node 20 or later), the MCP server at https://mcp.cleartrace.dev/mcp, or the HTTP API.
Codex and Claude Code both work, and so does any MCP client that can send a header.
What is a declaration?
A small JSON file in your repository's architecture/ folder. It states your databases, environments, services, operations or data flows. Living documents get a short header instead.
Your agent drafts declarations from the scan. You review and agree. Then they are the truth ClearTrace shows.
Why is my architecture partial?
Usually because declarations are missing (gaps), the scanner cannot read a technology (not covered by ClearTrace), or a project is out of architecture scope, such as a test project.
The app shows coverage per area and lists each cause. Partial is the normal starting point.
What is the difference between a gap and something not covered?
A gap is something in your project the declarations do not cover yet, such as a service with no environment or a document with no header. Your agent can fill it.
Not covered by ClearTrace means something ClearTrace cannot read or check, such as a technology the scanner does not read. It is not a gap in your project; there is nothing for you to fix.
Which stacks are supported?
Data models are read from SQL migrations, Prisma, TypeORM, Django and Entity Framework Core. Sequelize, Mongoose, SQLAlchemy, Rails, Hibernate/JPA, Drizzle, Knex and MikroORM are detected but not read yet; you can still declare those tables.
Cloud and deployment are detected from GitHub Actions workflows, Bicep, Terraform, AWS CDK, .azcli files and az/aws CLI scripts. Anything detected is marked assumed until you declare it.
Can a solution span several repositories?
Yes. A solution holds many projects, each with its own repository and kit.
One orchestration project, such as a bootstrap repository, can declare connections, environments and services for the whole solution. "Refresh ClearTrace" there covers every project.
What about test or QA projects?
They keep the kit and report test runs, findings and retests. They are out of architecture scope, so they do not add services or tables to your map.
Can I edit tickets or changes in the app?
No. The app is read-only for work records. Agents write through the CLI, API and MCP, so every record has a source.
You do set up workspaces, solutions, projects, users and keys in the app.
Do I have to write long prompts?
No. Short requests work: "Refresh ClearTrace across all projects." "Report this bug in ClearTrace." "Record the retest in ClearTrace." ClearTrace's own guidance tells the agent the steps.
Does ClearTrace replace my ticket tool or coding assistant?
No. Your Git host, ticket tool and coding assistant keep doing their jobs. ClearTrace records what the work changed, why, and what proved it.
What does it cost?
The plans and prices are on the Pricing page. During the founding beta, until January 31, 2027, the first 30 workspaces pay nothing until it ends and keep 30% off for as long as they stay subscribed. Paying yearly takes another 20% off, for everyone.
Limits are shown in your workspace but not enforced during the beta.
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.