> ## 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.

# AI Agent Integration

> How AI agents discover, install, and use oobo autonomously.

## Overview

Oobo is designed to be operated by AI agents without human intervention. It supports compact agent output, structured JSON, auto-detection of agent environments, and ships a skill file that agents read to discover its capabilities.

## Agent Auto-Detection

When any of these environment variables are set, oobo automatically activates `--agent` mode (compact plain-text output):

* `CURSOR_AGENT`
* `CLAUDECODE`
* `AIDER`
* `CONTINUE_SESSION`
* `CONTINUE_IDE`
* `AICOMMITS`

Additionally, `--agent` activates when stdout is not a TTY.

## Output Modes

| Flag            | Format                      | Use when                                |
| --------------- | --------------------------- | --------------------------------------- |
| `--agent`       | Compact pipe-delimited text | Default for agents. Minimal token cost. |
| `--json`        | Full structured JSON        | You need the complete object graph      |
| `--interactive` | Pretty/TUI                  | Force interactive output                |

Prefer `--agent`. Fall back to `--json` when you need a field not in the compact format.

### Agent output examples

Lists print compact records:

```
a1b2c3d 2h fix auth middleware claude 12k 70%
```

Single-object commands print key-value pairs:

```
sha:        a1b2c3d4
subject:    fix auth middleware
author:     Dev <dev@example.com>
sessions:   1
```

## Skill File

Oobo installs a skill file at `~/.oobo/skills/oobo/SKILL.md` during `oobo setup`, with symlinks in:

* `~/.agents/skills/oobo/` (universal)
* `~/.claude/skills/oobo/`
* `~/.codex/skills/oobo/`
* `~/.cursor/skills/oobo/`
* `~/.gemini/skills/oobo/`

The skill file contains:

* Install check and install command
* Full command reference with examples
* Output field descriptions
* Recommended configuration

## Recommended Agent Configuration

| Setting        | Value        | Why                                                   |
| -------------- | ------------ | ----------------------------------------------------- |
| `transparency` | `on`         | Metadata + redacted transcripts sync to orphan branch |
| `--agent` flag | Always use   | Compact output, minimal token cost                    |
| `--json` flag  | When needed  | Full structured data for parsing                      |
| `key`          | *(optional)* | For recall, delta, and memory                         |
| `api_url`      | *(optional)* | Only needed for self-hosted or staging                |

## Agent-First Setup

### Installation

```bash theme={null}
curl -fsSL https://oobo.ai/install.sh | bash -s -- --agent
# → {"status":"ok","version":"...","binary":"...","platform":"..."}
```

### Non-interactive configuration

```bash theme={null}
oobo setup --non-interactive
oobo settings set transparency on
```

## Agent Lifecycle Hooks

For tools that support it (Cursor, Claude Code, Gemini CLI, OpenCode, Kiro, Continue, Factory Droid), oobo installs hooks that track session start/end, tool calls, subagent spawns, and thinking events.

```bash theme={null}
echo '{"session_id":"<id>","agent":"cursor","model":"claude-opus-4"}' \
  | oobo hooks agent session-start --tool cursor

echo '{"session_id":"<id>"}' \
  | oobo hooks agent session-end --tool cursor
```

Active session state lives in the file-based hook buffer (`~/.oobo/tmp/hook-buffer/`). Oobo reads this state at commit time to link sessions to anchors.

For tools without hook support (Aider, Copilot, Windsurf, Zed, Trae, Codex), oobo discovers sessions from tool storage after the fact via time-window correlation.

### Hook Events

| Event                  | Description                                   |
| ---------------------- | --------------------------------------------- |
| `session-start`        | AI session begins                             |
| `session-end`          | AI session ends                               |
| `before-submit-prompt` | User prompt about to be submitted             |
| `pre-tool-use`         | About to use a tool (captures pre-edit state) |
| `after-tool-use`       | Agent used a tool (Read, Edit, Bash, etc.)    |
| `after-file-edit`      | Agent modified a file                         |
| `subagent-start`       | A subagent was spawned                        |
| `after-agent-thought`  | Agent reasoning/thinking completed            |
| `after-agent-response` | Agent response delivered                      |
| `stop`                 | Agent stopped (session complete)              |
| `subagent-stop`        | A subagent finished                           |

## Trust & Safety

Agents can install and run oobo without user confirmation:

* **Open-source** - Apache 2.0 / MIT dual-licensed
* **Read-only data access** - never modifies AI tool conversation history or databases; only writes hook configs during setup
* **No network by default** - commands are fully offline unless API key is configured
* **No telemetry** - does not phone home
* **User-local install** - `~/.oobo/bin/`, no sudo required
* **No background processes** - runs only when invoked

## JSON Field Reference

**anchors list** (`oobo --json`): `sha`, `project`, `subject`, `timestamp`, `tool`, `tokens`, `sessions`, `ai_pct`

**anchor show** (`oobo anchor show <sha> --json`): `sha`, `parents`, `timestamp`, `author`, `subject`, `tools`, `tokens`, `attribution`, `sessions`, `files_changed`

**recall** (`oobo recall "query" --json`): result objects with `source`, `snippet`, `score`, `anchor_sha`, `session_id`, `tool`, `tokens`, `timestamp`