TraceNest

Understand every change your AI agent makes.

TraceNest is a production-minded, cross-platform, local-first open-source CLI tool for reviewing, inspecting, comparing, and documenting changes made during AI-assisted coding sessions.

---

💡 The Problem

Autonomous and AI-assisted coding agents (such as Claude Code, OpenCode, Cline, Cursor, Codex) execute code modifications, refactorings, and file creations at high speed. While agents accelerate development, they frequently:

• Introduce subtle security vulnerabilities (e.g. eval(), unescaped subprocesses, verify=False).
• Leave hardcoded development credentials, tokens, or JWTs in code.
• Touch files outside the intended task scope or alter CI/CD workflows (.github/workflows/).
• Modify project dependencies (requirements.txt, package.json, pyproject.toml) unexpectedly.
• Produce large multi-file diffs that are difficult for human reviewers to audit.

TraceNest solves this by establishing a deterministic review layer between your AI agent and your codebase.

---

🌟 Core Features

• Local-First & Privacy-By-Default: No cloud account, no telemetry, no paid API required. Works completely offline.
• Deterministic Review Engine: Fast, rule-based scanning for secrets, configuration tampering, dependency drift, and dangerous patterns.
• Git Baseline Snapshots: Capture clean checkpoints before unleashing your AI agent, and accurately measure exactly what changed.
• Automated Secret Redaction: Detected credentials and high-entropy secrets are masked before appearing in terminal output, logs, or reports.
• Multi-Format Reports: Export comprehensive review reports in Markdown and structured JSON.
• Session Delta Comparison: Track changes across multiple agent iterations using tracenest compare <session_a> <session_b>.
• Optional Local & Remote AI Explanations: Integrate with local Ollama or OpenAI-compatible models for high-level summaries without sacrificing privacy.

---

🚀 Quick Start

Installation

Install TraceNest into your Python 3.12+ environment:

pip install tracenest

Or install from source in editable mode:

git clone https://github.com/tracenest/tracenest.git
cd tracenest
pip install -e .

1. Initialize TraceNest in your Repository

cd /path/to/your/project
tracenest init

This creates .tracenest/ for local session storage and creates a documented tracenest.toml configuration file.

2. Capture a Baseline Snapshot Before Running an AI Agent

tracenest snapshot create --label "before-ai-refactor" --note "Baseline state before agent run"

3. Review Agent Modifications

After the AI agent makes edits to your codebase, run:

tracenest review

TraceNest will scan the working tree diff, run all deterministic security and scope rules, display a formatted Rich terminal summary, and export reports to .tracenest/reports/.

4. Compare Across Iterations

tracenest compare sess_20261024_010000_abc123 sess_20261024_020000_def456

---

🛠 Command Reference

Command	Description
tracenest init	Initialize TraceNest storage and generate default configuration.
tracenest status	Display repository state, active branch, pending changes, and recent snapshots.
tracenest snapshot create	Record a baseline snapshot of the current working tree.
tracenest snapshot list	List recorded baseline snapshots with timestamps and commit references.
tracenest review	Analyze repository changes, evaluate deterministic rules, and save review session.
tracenest review --ai	Run review with optional AI provider advisory explanation.
tracenest report	Export or display Markdown / JSON report for a session.
tracenest compare <sess_a> <sess_b>	Compare two sessions to see newly introduced or resolved findings.

---

🔒 Security & Privacy Model

TraceNest is built on strict engineering security principles:

1. No Code Execution: TraceNest never executes commands found in repository files or generated by LLMs.
2. Safe Subprocesses: Subprocess invocations never use shell=True for untrusted arguments.
3. No Unsolicited Network Calls: In default mode, TraceNest makes zero network requests.
4. Remote Data Sharing Guard: Remote AI providers are blocked unless allow_remote_data_sharing = true is explicitly configured.
5. Secret Redaction: High-entropy credentials and API keys are automatically redacted in terminal output, logs, and AI prompts.

---

📄 License

TraceNest is open-source software licensed under the MIT License.