> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oobo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Anchors, sessions, transparency, and how oobo organizes AI context.

## Commits and Anchors

A git commit stores a diff, a message, an author, and a timestamp. It tells you what changed but says nothing about how the change was produced.

An **anchor** extends a commit with AI context. It records which AI sessions were active, how many tokens were spent, and which lines came from AI vs. the developer.

| Field                           | What it stores                                                     |
| ------------------------------- | ------------------------------------------------------------------ |
| `commit_hash`                   | The git commit this anchor is attached to                          |
| `message`                       | Commit message                                                     |
| `author`                        | Git author                                                         |
| `author_type`                   | `agent`, `assisted`, `human`, or `automated`                       |
| `contributors`                  | All participants (humans + AI tools with model info)               |
| `branch`                        | Branch name                                                        |
| `committed_at`                  | Timestamp                                                          |
| `session_ids`                   | Array of linked AI session IDs                                     |
| `files_changed`                 | List of modified files                                             |
| `added` / `deleted`             | Aggregate diff stats                                               |
| `file_changes`                  | Per-file: path, added/deleted, attribution (ai/human/mixed), agent |
| `ai_added` / `ai_deleted`       | Lines attributed to AI                                             |
| `human_added` / `human_deleted` | Lines attributed to human                                          |
| `ai_percentage`                 | AI contribution percentage (0-100)                                 |

### Author Types

| Type        | When it applies                                             |
| ----------- | ----------------------------------------------------------- |
| `agent`     | An AI agent made the commit autonomously                    |
| `assisted`  | A human committed while one or more AI sessions were active |
| `human`     | No AI session was active during the commit                  |
| `automated` | Non-interactive commit (CI, scripts, bots)                  |

### Where Anchors Are Stored

Anchors are stored on the **git orphan branch** `oobo/anchors/v2`. This branch:

* Travels with the repo (pushed alongside your code)
* Is invisible to normal git operations (`git log`, `git diff`, working tree)
* Is created automatically on the first tracked commit
* Is pushed via the pre-push hook

The orphan branch is the single source of truth for anchor data. There is no separate database or cloud service required.

## Sessions

A session represents a single AI coding conversation. Oobo discovers sessions through agent lifecycle hooks (for tools that support them) and by reading the local storage of each supported tool (Cursor's workspace state, Claude Code's JSONL files, Gemini's JSON files, etc.).

| Field                       | What it stores                                                                      |
| --------------------------- | ----------------------------------------------------------------------------------- |
| `session_id`                | UUID (prefix-matchable)                                                             |
| `name`                      | Session title or first message                                                      |
| `source`                    | Tool name (`cursor`, `claude`, `gemini`, etc.)                                      |
| `mode`                      | Interaction mode (`agent`, `composer`, `chat`, `ask`) - available at discovery time |
| `project_path`              | Associated project directory                                                        |
| `created_at` / `updated_at` | Timestamps (from file metadata)                                                     |

When a session is linked to an anchor, additional data is stored in the **SessionLink** (on the orphan branch):

| Field                                         | What it stores                          |
| --------------------------------------------- | --------------------------------------- |
| `model`                                       | AI model used                           |
| `input_tokens` / `output_tokens`              | Token counts (native or estimated)      |
| `cache_read_tokens` / `cache_creation_tokens` | Prompt cache stats                      |
| `duration_secs`                               | How long the session lasted             |
| `tool_calls`                                  | Total tool invocations                  |
| `files_touched`                               | Files the session interacted with       |
| `is_estimated`                                | `true` if tokens are tiktoken estimates |
| `is_subagent`                                 | Whether this was a child/sub session    |

See the [full schema reference](/anchor-schema) for all SessionLink fields including tool usage breakdown, bash commands, thinking time, and subagent details.

### Token Sources

Some tools store exact token counts (Claude Code, Gemini CLI, OpenCode, Codex CLI, Zed). For tools that don't (Cursor, Copilot), oobo estimates tokens using tiktoken and marks them with `is_estimated: true`.

## Transparency

Transparency controls whether **redacted session transcripts** are written to the orphan branch alongside anchor metadata.

| Mode           | What syncs to orphan branch                    |
| -------------- | ---------------------------------------------- |
| `on` (default) | Anchor metadata + redacted session transcripts |
| `off`          | Anchor metadata only. Transcripts stay local.  |

Set via config:

```toml theme={null}
[privacy]
transparency = "off"    # or "on"
```

When transparency is `on`, session transcripts are redacted (secrets removed via gitleaks patterns) before being written to the orphan branch.

Transparency has a global default in `~/.oobo/config` and can be overridden per-project in `.oobo/config`.

## Turns

A **turn** is a single exchange within a session - one user prompt and the agent's response. Oobo captures per-turn state through agent lifecycle hooks, recording tool calls, hook events, file edits, and workspace tree hashes. Turn snapshots are stored on git refs (`refs/oobo/turns/v1/...`) and enable `oobo goto` to restore exact workspace state at any point in a session.

### Turn Snapshots

Each turn snapshot records:

* Files changed during the turn (with pre/post blob hashes)
* Tool calls and hook events observed
* Model and token usage
* Cross-repo file edits (when an agent modifies files outside the home repo)
* Transcript path (when transparency is on)

Turn data feeds into anchors at commit time, providing per-turn provenance for every committed line.

## Projects

A project is any git repository where oobo is enabled. Projects are found during `oobo setup` or normal command use.

Run bare `oobo` outside a repo to see a project picker.

### Disabling a Project

```bash theme={null}
oobo disable           # stop tracking the current repo
oobo enable            # re-enable tracking
```

When a repo is disabled, hooks do not fire - no anchor creation, no orphan branch writes, no session discovery.

On first use in a new repo, oobo prints a one-time notice:

```
oobo: enriching commits in <project> with AI attribution. Run `oobo disable` to opt out.
```