trace

# Trace > **Trace** · [English](README.en.md) Trace is a local version tracking tool designed for AI programming collaboration scenarios. It does not replace Git but complements it. When using tools like Claude Code, Codex CLI, Cursor, OpenCode, etc., to modify the same project simultaneously, Trace records in the background which agent made changes to which files at what time and saves each change as a local snapshot that allows viewing diffs, reverting files, and undoing changes made by a specific agent. The core goals of Trace are to solve three issues in multi-agent collaboration: - **Clear source**: Distinguish file changes from different sources, such as human manual modifications, Claude, Codex, Cursor, etc. - **Find the process**: Merge consecutive file changes occurring within a short period into a single version record for easy review. - **Safe recovery**: View diffs in the Electron console and recover a single file or a specific modification to a previous version. ## Architecture  Capture file changes → Filter noise → Wait for file stability → Attribute changes via MCP/activities/process evidence → Batch commit → Persist to SQLite and content-addressed blob → Provide data to UI through bridge service. ## How to Use ### 1. Select the Workspace to Track After launching Trace, select a project folder that needs tracking, such as your course project directory. Trace will create a `.trace/` folder under the selected directory to save the local database and file snapshots. The `.trace/` directory is Trace's local data directory and does not need manual editing. If the project uses Git, it is recommended to add `.trace/` to `.gitignore`. ### 2. Keep Trace Running in the Background After Trace starts, it will reside in the system tray or menu bar and launch the file listening service. You can then use the editor, terminal, or AI programming tools to modify project files as usual. Trace will automatically capture create, modify, delete, and move events. If running from source: ```bash uv sync uv run python code/main.py --workspace /path/to/your/project ``` If using a packaged version: - macOS: Open `Trace.app` and select the workspace. - Windows: Run `Trace.exe` and select the workspace or use the previously recorded last workspace. ### 3. Configure MCP for AI Tools Trace supports MCP. After configuration, agents like Codex and Claude Code can proactively tell Trace which files they modified, making attribution more accurate than relying solely on process scanning. The simplest method is to open the **MCP** page in the Electron console, click the "One-click add" button for the corresponding agent, and restart the AI tool to apply the new MCP configuration. ### 4. View History, Diffs, and Attribution After opening the Electron console of Trace, you can view: - Timeline: Each file change record. - Agents: Activity statistics for different agents. - Diff: Specific changes for each file in a commit. - Workspace: Current workspace, database location, and snapshot count. - MCP: Connection configuration status for tools like Codex and Claude Code. Trace supports version tracking for text, Office documents, PDFs, images, and binary files. Common text and document formats display more friendly diff summaries. ### 5. Recover Files or Undo Modifications After selecting a historical record in the console, you can view the diff of the corresponding file and perform recovery operations as needed. Common use cases include: - Recover a single file to a historical version. - Revert a batch of modifications caused by an agent. - Before recovery, retain the current version to avoid accidental overwriting of existing content. All data is saved in the `.trace/` directory of the current workspace and is not uploaded to the cloud. No large model API key configuration is required. ## Project Overview Trace is a multi-CLI agent collaboration version tracker. It listens to file changes in the workspace, identifies active agents like Claude Code, Codex CLI, Cursor, OpenClaw, OpenCode, Hermes, or Kimi Code, and writes each batch of changes to a local SQLite database, attributing changes to agents and saving file versions using content-addressed blobs. ## Core Capabilities - Automatically detect active CLI agents in the workspace and record attribution information like `confidence`, `candidates`, and `ambiguous`. - Use watchdog to listen to file create, modify, move, and delete events. - Filter noise for `.git`, `.trace`, temporary files, and duplicate events. - Debounce changes by agent for 2 seconds to merge consecutive changes into a commit. - Store arbitrary file types using SHA-256 blobs. - Support recovery to any historical point in time with full manifest commits. - Display diffs for text, `.docx`, `.pptx`, `.xlsx`, `.pdf`, images, and unknown binary files. - Provide macOS/Windows menu bar and Electron console. - Support `AgentActivityRecorder` for proactive sampling, GUI/script detection, ambiguous correction, selective undo by agent, and offline change compensation. ## Quick Start ```bash uv sync bash scripts/demo.sh ``` Launch the complete menu bar application (which will also open the Electron console by default; `--headless` runs the daemon without popping up the UI): ```bash uv run python code/main.py --workspace test_workspace ``` Launch the Electron console alone (for development and debugging): ```bash cd electron_app npm install npm start -- --workspace=../test_workspace ``` ## Trace MCP Interface Trace provides a local stdio MCP server for agents like Codex, Claude Code, and Cursor to proactively declare the files they modified. Codex can also install Trace hooks to automatically record file changes produced by `apply_patch`, `Write`, `Edit`, and `Bash` in the PreToolUse and PostToolUse phases, avoiding passive guessing of attribution when multiple agents run simultaneously. Declarations are written to `.trace/trace_activity.jsonl` in the workspace, and the attribution mechanism prioritizes these records. If no declaration is made, it falls back to transcript/process scanning. ### Quick Configuration **Claude Code CLI**: The `.mcp.json` file in the project root directory is automatically read, requiring no additional configuration. **Cursor**: One-click automatic configuration (recommended) ```bash python scripts/setup_cursor_mcp.py ``` For detailed configuration, refer to [CURSOR_SETUP.md](CURSOR_SETUP.md). Or manually configure by adding to the global MCP configuration file; on Windows, you can change `command` to `py`: ```json { "mcpServers": { "trace": { "type": "stdio", "command": "/path/to/project/.venv/bin/python", "args": ["/path/to/project/run_mcp_server.py", "--workspace", "/path/to/workspace"] } } } ``` Cursor configuration file locations: - macOS: `~/Library/Application Support/Cursor/User/mcp.json` - Linux: `~/.config/Cursor/User/mcp.json` - Windows: `%APPDATA%\Cursor\User\mcp.json` **Codex CLI**: Add to `~/.codex/config.toml`: ```toml [mcp_servers.trace] command = "/path/to/project/.venv/bin/python" args = ["-m", "mcp.trace_server", "--workspace", "/path/to/workspace"] [mcp_servers.trace.env] PYTHONPATH = "/path/to/project/code" ``` The MCP page in the Electron console will directly write the above configuration and replace the old `trace` section. It is recommended to use the one-click add feature. For detailed configuration and troubleshooting, refer to [MCP_SETUP.md](MCP_SETUP.md). ### MCP Tool - `trace_record_files(agent, files, operation="write", confidence=1.0)` Call this once before and after an agent writes files, e.g., setting `agent` to `codex`, `claude`, `cursor`, and passing a list of workspace relative or absolute file paths. ### Codex Hooks Codex hook module (automatically calls MCP): - `hooks.trace_codex_hook --workspace /path/to/workspace --phase pre` - `hooks.trace_codex_hook --workspace /path/to/workspace --phase post` The MCP page in the Electron console will write to `~/.codex/config.toml` and `~/.codex/hooks.json` with one click. After restarting Codex, run `/hooks` in Codex and trust the Trace hook once to take effect. ## Development Develop Electron renderer: ```bash cd electron_app npm run dev:renderer VITE_DEV_SERVER_URL=http://127.0.0.1:5173 npm run start:dev -- --workspace=../test_workspace ``` ## Testing ```bash uv run python -m unittest discover -s tests ``` The number of tests is based on the local `unittest` output. Current tests cover repository, watcher, batcher, activity recorder, agent detector, handler, menu bar, Electron renderer, build scripts, and multi-file type diffs. ## Building macOS build: ```bash bash scripts/build_macos_app.sh ``` This script builds the Electron console, embeds `Trace Console.app` into the main `Trace.app`, and then resigns and generates a DMG. Windows build requires execution on Windows: ```powershell pwsh .\scripts\build_windows_app.ps1 ``` This script builds the Electron Windows unpacked directory and generates `dist\Trace\Trace.exe` and `dist\Trace\TraceBridge.exe` using PyInstaller. Fallback source launcher: ```bash bash install.sh ``` Build products are located in `dist/`: - `Trace.app` - `Trace-macOS.dmg` - `Trace\Trace.exe` (after Windows build) - `Trace.command` ## Main Directories ```text code/ Python source code tests/ Unit tests and E2E tests electron_app/ Electron console scripts/ Demo and build scripts prompts/ Vibe Coding prompts screenshots/ Demo screenshots assets/ Static assets for documentation dist/ Local build products test_workspace/ Local demo workspace ``` ## Known Limitations - Windows build scripts and PyInstaller spec are complete, but `.exe` requires running scripts and acceptance on a real Windows machine. - Linux is currently code-compatible but requires real-machine verification. - Older `.ppt` files can be tracked and recovered as binary files but lack semantic diffs like `.pptx`. - Offline changes during daemon exit are not rescanned. - File permission bits are not stored; for example, script executable bits (`+x`) need manual confirmation after recovery.