# Agent Traces with Entire

Track and analyze your AI coding agent sessions using Entire (https://entire.dev).

## Overview

Agent Traces helps you understand what your AI coding agents (Claude Code, Codex, Cursor, etc.) are doing in your codebase. It captures session logs, detects agent activity, and provides quality checks on AI-generated code.

## Installation

```bash
npx -y @haystackeditor/cli@latest hooks install
```

This command installs:

1. **Entire CLI binary** - Session tracking tool (installed to `~/.haystack/bin/entire`)
2. **Git hooks** - Automated hooks in your repo's `hooks/` directory
3. **Configuration** - `.entire/settings.json` for your project
4. **LLM Rules template** - `LLM_RULES.md` for customizing agent behavior

## What Gets Installed

### Git Hooks

| Hook | Purpose |
|------|---------|
| `pre-commit` | Agent detection, truncation checking, LLM rules review |
| `commit-msg` | Session tracking (powered by Entire) |
| `post-commit` | Session condensing (powered by Entire) |
| `pre-push` | Session log push (powered by Entire) |
| `prepare-commit-msg` | Commit preparation (powered by Entire) |

### TypeScript Modules

- `hooks/agent-context/` - Detects which AI agent made changes (Claude, Codex, Cursor, etc.)
- `hooks/truncation-checker/` - Catches truncated code from AI (incomplete functions, missing imports)

## CLI Commands

```bash
# Install hooks and Entire CLI
haystack hooks install

# Check installation status
haystack hooks status

# Update Entire CLI to latest version
haystack hooks update

# Force reinstall (overwrites existing hooks)
haystack hooks install --force

# Skip Entire CLI download (hooks only)
haystack hooks install --skip-entire

# Install specific Entire version
haystack hooks install --version 0.1.5
```

## How It Works

1. **Agent Detection**: The pre-commit hook analyzes your changes to detect which AI agent made them
2. **Truncation Checking**: Catches incomplete code (functions without bodies, missing imports, etc.)
3. **LLM Rules Review**: Validates changes against your project's `LLM_RULES.md`
4. **Session Tracking**: Entire captures the full session context (prompts, responses, tool calls)
5. **Session Push**: On `git push`, session logs are uploaded for analysis

## Configuration

### .entire/settings.json

Created automatically during installation. Contains project-specific settings for Entire.

### LLM_RULES.md

A template file for defining rules your AI agents should follow. Customize this for your project:

```markdown
# LLM Rules for MyProject

## Code Style
- Use TypeScript strict mode
- Prefer functional components in React
- Always add error handling

## Architecture
- Keep files under 300 lines
- One component per file
- Use the repository pattern for data access
```

## Files to Commit

After running `haystack hooks install`, commit these files:

```
hooks/                    # Git hook scripts and TypeScript modules
.entire/settings.json     # Entire configuration
.entire/.gitignore        # Ignores session data
LLM_RULES.md             # Your project's LLM rules (customize this!)
```

## Troubleshooting

### Hooks not running

Make sure git is configured to use the hooks directory:

```bash
git config core.hooksPath hooks
```

### Entire CLI not found

The binary should be at `~/.haystack/bin/entire`. Reinstall with:

```bash
haystack hooks install --force
```

### TypeScript errors in hooks

Install hook dependencies:

```bash
cd hooks && npm install
```

## Links

- [Entire](https://entire.dev) - Session tracking platform
- [Haystack CLI](https://www.npmjs.com/package/@haystackeditor/cli) - NPM package
- [Verification Flow](/docs/verification-flow) - Set up PR verification