Skip to content

docs: update READMEs #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
albu-razvan merged 1 commit into from
May 15, 2026
Merged

docs: update READMEs #113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 177 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,113 +1,239 @@
# Tracybot

![Representative](./public/representative.png)
[![GitHub Release](https://img.shields.io/github/v/release/TracyTeam/tracybot)](https://github.com/TracyTeam/tracybot/releases/latest) [![License](https://img.shields.io/github/license/TracyTeam/tracybot)](LICENSE) [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/TracyTeam/tracybot/release.yml)](https://github.com/TracyTeam/tracybot/actions)

Tracybot is a tool that traces AI-generated code back to the prompts that created it. It enables tracking for AI-assisted development by recording snapshots of your codebase at each AI interaction.

## Goal
## Features

Provide complete traceability between AI-generated code changes and the prompts that produced them, enabling developers to understand, audit, and verify AI-assisted work.
- **AI Traceability** - Map AI-generated lines of code back to their originating prompt
- **Non-Invasive Storage** - Hidden Git commits and refs keep your history clean
- **Seamless Integration** - Works with OpenCode CLI and Visual Studio Code
- **Audit Trail** - Review AI interactions to verify, debug, or understand code origins
- **Team Sync** - Push traces to remote for team collaboration

## Architecture

Tracybot consists of three components that work together:

- **[opencode-plugin](./opencode-plugin/README.md)** - Plugin for opencode CLI that records snapshots during AI interactions
- **[vscode-extension](./vscode-extension/README.md)** - VS Code extension to view AI blame information
- **[tracking](./tracking/README.md)** - Git hooks and scripts for state tracking using hidden commits and synced git notes

```
┌───────────────────┐ ┌──────────────────┐ ┌────────────────────┐
│ opencode-plugin │────▶│ tracking/hooks │◀────│ vscode-extension │
│ (snapshots AI) │ │ tracy.py │ │ (displays blame) │
│ (interactions) │ │ (stores state) │ │ │
└───────────────────┘ └──────────────────┘ └────────────────────┘
```

### How Components Communicate

1. **opencode-plugin** invokes **`tracy.py`** (from `tracking/`) after each AI interaction to create a snapshot
2. **`tracy.py`** stores snapshots as hidden commits in the Git repository (using `refs/tracy-local/*` namespace)
3. **vscode-extension** queries Git to build a history timeline and displays blame information in VS Code

## Quick Getting Started
```mermaid
graph TB
subgraph "opencode-plugin"
Plugin["Snapshot Capture<br/>on AI Interaction"]
end

subgraph "tracking"
direction LR
TracyPy["<strong>tracy.py</strong><br/>Create Hidden Commit"]
Hooks["<strong>Git Hooks</strong><br/>reference-transaction<br/>pre-commit post-commit<br/>post-rewrite post-merge<br/>pre-push"]
Refs["<strong>Git Refs</strong><br/>refs/tracy/*<br/>refs/tracy-local/*"]
end

subgraph "vscode-extension"
BlameView["AI Blame View"]
end

Plugin --> TracyPy
TracyPy --> Hooks
Hooks --> Refs
BlameView --> Refs
```

### 1. Initialize a Repository
### Information Flow Scenarios

```mermaid
sequenceDiagram
participant D as Developer
participant O as OpenCode
participant P as OpenCode Plugin
participant T as tracy.py
participant G as Git

note left of D: Snapshot Creation
D->>O: Prompts
O->>P: Finishes interaction with changes
P->>T: Invoke tracy.py
T->>G: Read working tree
T->>G: Create hidden commit<br/>refs/tracy-local/{uuid}
```

```bash
cd your-target-repository
python /path/to/tracybot/init.py
```mermaid
sequenceDiagram
participant D as Developer
participant G as Git
participant H as Git Hooks

note left of D: On Commit
D->>G: git commit
H->>G: Promote to refs/tracy/{uuid}
H->>G: Add tracy-id note
```

This requires:
- A Git repository
- An `origin` remote configured
```mermaid
sequenceDiagram
participant D as Developer
participant G as Git
participant H as Git Hooks

note left of D: On Push
D->>G: git push
H->>G: Fetch remote notes
H->>G: Merge notes
H->>G: Push refs/tracy/* and notes
```

### 2. Deploy the Plugin
```mermaid
sequenceDiagram
participant D as Developer
participant G as Git
participant H as Git Hooks

```bash
cd opencode-plugin
bun run deploy
note left of D: On Rebase
D->>G: git rebase
H->>G: Merge refs/tracy/*
H->>G: Update tracy-id note
```

### 3. Install the VSCode Extension
```mermaid
sequenceDiagram
participant D as Developer
participant V as VS Code Extension
participant G as Git

note left of D: Display Flow
D->>V: Open AI Blame
V->>G: Query refs/tracy/* and refs/tracy-local/*
V->>G: Read snapshot metadata
V->>D: Display trace results
```

## Quick Start

### 1. Install the VS Code Extension

#### Automated installation (recommended)
This is the recommended entry point. The extension can open AI Blame, prompt to initialize Tracybot in the current repository, and offer to install the OpenCode plugin.

##### Linux & macOS
#### Linux and macOS

In the terminal, run
```bash
curl -fsSL https://raw.githubusercontent.com/TracyTeam/tracybot/main/vscode-extension/install.sh | bash
```

##### Windows
#### Windows

In Powershell, run
```powershell
powershell -Command "irm https://raw.githubusercontent.com/TracyTeam/tracybot/main/install.ps1 | iex"
irm https://raw.githubusercontent.com/TracyTeam/tracybot/main/vscode-extension/install.ps1 | iex
```

#### Manual installation
The install scripts use the `code` CLI, so make sure the VS Code command line tools are available first.

Alternatively, the extension can be installed manually.
### 2. Open Your Repository in VS Code

When the extension activates, it adds an `AI Blame` status bar item on the right side of VS Code.

If Tracybot has not been initialized in that repository yet, the extension offers to run initialization for you.

If you prefer to initialize from the terminal instead, run:

1. Download the packaged extension from the [latest release](https://github.com/TracyTeam/tracybot/releases/latest)
or with
```bash
curl -fsSL -o tracy.vsix https://github.com/TracyTeam/tracybot/releases/latest/download/vscode-extension.vsix
python /path/to/tracybot/init.py /path/to/your-target-repository
```

2. In VSCode, go to `EXTENSIONS tab --> Click on the 3 dots --> Install from vsix` and choose the downloaded .vsix file

### 4. Install the OpenCode Plugin
Requirements:
- A Git repository
- Python 3 available as `python3` or `python`
- An `origin` remote is optional; it is only needed for syncing Tracy refs and notes with a remote

If you wish to use the Tracybot OpenCode integration, the OpenCode plugin needs to be installed.
### 3. Install the OpenCode Plugin

#### From VSCode
If the VS Code extension is installed, it will prompt you to install the OpenCode plugin when it is missing.

If the VSCode extension is installed, you will be prompted to install the plugin if it was not yet installed.
You may choose to install it globally (global OpenCode plugin directory), or per project (.opencode directory in the project).
You can install it either:
- Globally at `~/.config/opencode/plugin/tracybot-oc.js`
- Per project at `.opencode/plugin/tracybot-oc.js`

#### Automated Installation
If you want to install the released plugin directly from the terminal instead of using the VS Code prompt:

To install the plugin from the terminal, run:
#### Linux and macOS

##### Linux & macOS
```bash
curl -fsSL https://raw.githubusercontent.com/TracyTeam/tracybot/main/opencode-plugin/install.sh | bash
```

##### Windows
#### Windows

```powershell
powershell -Command "irm https://raw.githubusercontent.com/TracyTeam/tracybot/main/opencode-plugin/install.sh | iex"
irm https://raw.githubusercontent.com/TracyTeam/tracybot/main/opencode-plugin/install.ps1 | iex
```

### 4. Start Using AI Blame

After OpenCode makes changes in an initialized repository, Tracybot records snapshots automatically. Click `AI Blame` in VS Code to inspect the prompt history behind the current file.

## Troubleshooting

### Common Issues

**No AI blame information showing**
- Ensure the repository was initialized with `init.py`
- Verify VS Code extension is installed
- Check that OpenCode has already produced tracked changes in this repository

**Snapshots not being created**
- Check that the OpenCode plugin is installed and loaded
- Verify Tracybot was initialized successfully in the repository
- Verify Git hooks are installed under `.git/hooks/`
- Check for errors in the OpenCode output

**Push sync not working**
- Ensure an `origin` remote is configured
- Check that the `pre-push` hook is installed
- Verify Git notes are being pushed

## Getting Started for Developers

### Initialize a Repository Manually

```bash
python ./init.py /path/to/target-repository
```

#### Manual Installation
If you run `init.py` from inside a Git repository, you can omit the explicit path.

### Work on the VS Code Extension

1. Download the built plugin (`tracybot-oc.js`) from the [latest release](https://github.com/TracyTeam/tracybot/releases/latest)
or with
```bash
curl -fsSL -o tracy.vsix https://github.com/TracyTeam/tracybot/releases/latest/download/tracybot-oc.js
cd vscode-extension
npm install
npm run compile
```

Open `vscode-extension` in VS Code and press `F5` to launch the extension host.

### Work on the OpenCode Plugin

```bash
cd opencode-plugin
bun install
bun run deploy
```

`bun run deploy` builds the plugin and installs it into the global OpenCode plugin directory.

### Manual Installation from Release Assets

2. Place the downloaded file into the following directory: `$HOME/.config/opencode/plugin`
If you are testing packaging or release artifacts manually:

1. Download `vscode-extension.vsix` from the [latest release](https://github.com/TracyTeam/tracybot/releases/latest) and install it with `code --install-extension vscode-extension.vsix` or VS Code's `Install from VSIX...` action.
2. Download `tracybot-oc.js` from the same release and place it in either `~/.config/opencode/plugin/` or `<repo>/.opencode/plugin/`.
Loading
Loading