## Prerequisites

- [Entire CLI installed](https://docs.entire.io/installation)
- [Factory installed](https://docs.factory.ai/cli/getting-started/quickstart)
- A Git repository with Entire enabled

## Enable

```
entire agent add factoryai-droid
droid
```

`entire agent add factoryai-droid` installs hooks into `.factory/settings.json` automatically.

### How it works

The hooks track the full session lifecycle:

1. **Session Start** — fires when Factory launches, creating a new Entire session.
2. **Turn Tracking** — each user prompt triggers tracking via `user-prompt-submit` hooks.
3. **Subagent Tracking** — `pre-tool-use` and `post-tool-use` hooks capture Task tool invocations for nested session support.
4. **Session End** — fires when Factory exits, finalizing the session.
5. **Transcript Capture** — session transcript is read from Factory’s JSONL log files.
6. **Session Storage** — data saved to the `entire/checkpoints/v1` branch.

### What gets captured

| Data           | Description                                        |
|----------------|----------------------------------------------------|
| Conversation    | Full transcript of prompts and responses            |
| File changes    | All files modified during the session              |
| Tool calls      | Tool invocations with inputs and outputs            |
| Token usage     | Input, output, reasoning, and cache tokens          |
| Timestamps      | Session, message, and checkpoint timing             |

### Features

**Nested session support.** When Factory spawns sub-agents via the Task tool, Entire captures these as nested sessions through `pre-tool-use` and `post-tool-use` hooks:

```
Main Session
├── Checkpoint 1
├── Sub-agent Session (Task: "Run tests")
│   ├── Sub-checkpoint 1
│   └── Sub-checkpoint 2
└── Checkpoint 2
```

**Rewind during sessions.** Use `entire checkpoint rewind` to restore to a previous checkpoint during or after a Factory session. See the [`checkpoint rewind` command reference](https://docs.entire.io/cli-reference/checkpoint#checkpoint-rewind) for full flag documentation.

**Resume previous sessions.** Switch to a session’s branch with `entire session resume BRANCH`. The CLI restores the session log if needed and prints `droid --session-id ID`. See the [`session resume` command reference](https://docs.entire.io/cli-reference/sessions#session-resume) for full flag documentation.

**Explain commits.** Inspect any commit or checkpoint with `entire checkpoint explain`. See the [`checkpoint explain` command reference](https://docs.entire.io/cli-reference/checkpoint#checkpoint-explain) for full flag documentation.

### Caveats and limitations

- The integration is in preview and may have rough edges.
- Session detection relies on hook-based process detection.
- Transcript capture depends on Factory writing JSONL session logs.

### Best practices

**Commit at logical points.** Commit when you’ve made meaningful progress:

```
git add .
git commit -m "Implement feature with Factory assistance"
```

**Check status regularly.** Monitor your session with `entire status`.

### Example workflow

```
# 1. Enable Entire with Factory
cd my-project
entire agent add factoryai-droid

# 2. Start Factory
droid

# 3. Work with Factory
# Ask it to write code, make changes, etc.

# 4. Check session (in another terminal)
entire status

# 5. Rewind if needed
entire checkpoint rewind

# 6. Commit when ready
git add .
git commit -m "Add feature with Factory"

# 7. Push to see on entire.io
git push
```

Your session is now visible on [entire.io](/content/site-root.html) with full context for code review.

## Troubleshooting

### Session not detected

1. Ensure you’re in an Entire-enabled repo: `entire status`
2. Verify Factory is running from within the repository
3. Check that hooks are installed in `.factory/settings.json`
4. Check Git hooks are installed: `ls .git/hooks`

### No checkpoints created

1. Checkpoints require file changes — ensure Factory is modifying files
2. Check your settings in `.entire/settings.json`
3. Verify the `.factory/settings.json` hooks are present

### Transcript not captured

1. Ensure Factory’s session storage exists at `~/.factory/sessions/<repo>/`
2. Check that JSONL transcript files are being written
3. Look for errors in the Entire hook output.