traceglass

Turn unfamiliar software into explanations you can verify.

A portable reverse-engineering skill for AI coding agents.
Trace features. Compare releases. Keep the receipts.

Quick start · Example investigation · Installation · Analysis backends

From “probably” to “here’s the evidence”

An app has an export button. A bundle contains an analytics URL. Two releases behave differently. What can you actually prove?

Traceglass gives your agent a repeatable way to answer: identify the artifact, follow the relevant code or behavior, and deliver a report that separates observations, inferences, and open questions.

Inspect the fixture and evidence →

Try it

Download or clone this repository, open a terminal in its root, and use Python 3.9+ to install into your target project:

git clone https://github.com/arhanali003/traceglass.git
cd traceglass

# Pick your client. Preview the destination first.
python3 scripts/install.py --client codex --project /path/to/project --dry-run
python3 scripts/install.py --client codex --project /path/to/project

Use --client claude, --client antigravity, or --client all instead. The installer copies the skill and its references; it refuses to overwrite an existing installation. It does not install analysis engines or change MCP settings.

Then start a fresh agent session in that project and ask:

Use Traceglass to explain how /absolute/path/to/app implements CSV export.
Trace the entry point through to the output. Cite the evidence and flag
anything that static analysis cannot establish.

Want a tiny first run? Install into this checkout using --project ., then ask your agent to investigate examples/demo-app/export.js. See the walkthrough for a checkable result. No MCP server or external package required.

Recover source that actually ships

The companion Source Recovery skill produces files, hashes, and a provenance manifest. It recovers readable scripts and embedded source-map text; it guides the agent to available decompilers for compiled components. Decompiled output is labeled approximate, never passed off as the original source project.

python3 scripts/install.py --client all --project /path/to/project --skill source-recovery

Ask: “Use source-recovery to recover available source from this installed app into a new local directory.”

For compiled macOS components, native_report.py exports static metadata, symbols, and optional assembly. The deep native workflow adds provider discovery, scoped decompilation, and explicit failure tracking. A compatible connected decompiler is required for pseudocode.

For complete local bundle file preservation, the companion collect_bundle.py copies regular files with SHA-256 verification and records symlink metadata. This preserves opaque binaries and resources; it does not decode them or recover cloud content.

The included helper supports loose UTF-8 source, standalone JSON source maps, inline data maps, and embedded indexed-map sections. Archives and native binaries require separate tools. It does not execute the target or fetch remote source maps. Read the skill →

Recheck evidence before an agent uses it

The Source Recovery companion includes a read-only bundle verifier:

python3 skills/source-recovery/scripts/verify_bundle.py --bundle /path/to/collected-output

It checks saved files against bundle-manifest.json, returning JSON and exit
codes for intact, failed, or invalid evidence. It detects changed/missing files
and preserves collection-error reporting. A matching manifest does not establish
authenticity or completeness. Installation and command contract
· Runnable example.

One workflow. Three clients.

These paths follow the clients’ documented skill discovery conventions. Installer behavior is tested locally; live end-to-end verification in all three clients is still pending. Details and sources →

Follow the trace

• Portable instructions. One skill, shared references, client-specific installation locations.
• Focused investigations. Start from a question; expand only where the evidence needs it.
• Useful handoffs. Reports preserve artifact identity, source locations, coverage, and next steps.
• Optional analysis backends. Use ordinary tools for readable artifacts, or connect REA for supported binary and runtime investigations.

Traceglass is an instruction package. Native decompilation, archive decoding, and runtime observation depend on tools available in your agent session. It does not bundle an analysis engine. Capability boundaries →

Built to be inspected

skills/traceglass/       Portable skill and investigation playbooks
examples/               Small fixture and worked investigation
scripts/install.py      Dependency-free, non-overwriting installer
assets/                 Editable banner, workflow, and report artwork
tests/                  Installer, recovery, preservation and verification checks

Read the skill, try the example, or contribute a reproducible investigation. If Traceglass helps you understand a piece of software, a star helps others find it.

Credits & license

Inspired by the evidence-oriented approach of Reverse Engineer Anything (REA). Traceglass provides separately authored instructions, packaging, examples, and presentation; REA is an optional external backend. This project is not affiliated with REA, OpenAI, Anthropic, or Google. See provenance.

MIT for this repository. External tools retain their own licenses.

Early beta: try the tools without a model

This checkout is preparing 0.2.0b1; it is not a published package-manager release.
Python 3.9+ is supported; CI targets 3.9 and 3.13 on Linux, macOS and Windows.
Native reports additionally require macOS tools. Live execution in each AI client
remains unverified.

From this repository root, choose fresh output directories:

python3 scripts/install.py --version
python3 skills/source-recovery/scripts/collect_bundle.py --target examples/demo-app --output demo-bundle
python3 skills/source-recovery/scripts/verify_bundle.py --bundle demo-bundle

Expected: Traceglass 0.2.0b1, one copied file, then JSON containing status: "ok",
checked_files: 1, and exit 0. This is useful for retaining a small artifact before
changing it and detecting later evidence tampering. It does not establish what a
production application executed. Use python instead of python3 on Windows if
needed. Recovery/collection output must be outside the target; reruns need new paths.

For a fuller local walkthrough, invalid inputs, larger fixtures and feedback, see
BETA_TESTING.md. CLI and troubleshooting explains
all exit codes. In particular, recovery exit 2 now indicates recorded skips.
Security boundaries describe private-data and filesystem limits.

Build a local distribution with
python3 scripts/build_release.py --output dist/traceglass-0.2.0b1.zip.
It includes an inventory of file hashes and preserves the installer layout.
python3 scripts/smoke_release.py builds and checks an unpacked copy in a temporary
directory. These commands do not publish anything. There is no pip-installable
Traceglass package in this repository. Draft beta notes.