Skip to main content

​
Overview

Oobo is designed to be used by AI agents, not just humans. Every command supports the --agent flag for structured JSON output, and oobo ships with a skill file that agents can read to discover its capabilities.

​
The —agent flag

Add --agent to any command for structured JSON output. It is a global flag that works on every command. 
oobo sessions --agent            # JSON list of sessions
oobo sessions list --agent       # same (explicit subcommand)
oobo sessions show <id> --agent  # full conversation as JSON
oobo sessions search <q> --agent # search results as JSON
oobo projects --agent            # JSON list of projects
oobo projects show <n> --agent   # project detail as JSON
oobo anchors --agent             # enriched commit history as JSON
oobo stats --agent               # analytics as structured data
oobo card --agent                # developer stats card as JSON
oobo sources --agent             # data source coverage as JSON
oobo dash --agent                # configuration overview as JSON
oobo version --agent             # version info as JSON
oobo inspect --agent             # diagnostics as JSON
oobo share <id> --agent          # shared session as JSON
oobo scan --agent                # suppresses interactive output
Always use --agent instead of --json. The --agent flag is the single entry point for machine-readable output.

​
Skill file

Oobo installs a skill file at ~/.agents/skills/oobo/SKILL.md during oobo setup. This file describes oobo’s capabilities in a format that AI coding agents (Cursor, Claude Code, Codex, Gemini CLI, OpenCode) can read and understand. To print the skill file: 
oobo agent
The skill file includes:
  • Install check (command -v oobo) and install command (curl -fsSL https://oobo.ai/install.sh | bash -s -- --agent)
  • All available commands with examples
  • JSON response field descriptions for each command
  • Agent configuration recommendations
  • Architecture overview

​
How agents discover oobo

Most AI coding tools scan ~/.agents/skills/ (or similar paths) for skill files. When an agent finds oobo’s skill, it learns:
  1. That oobo is available as a CLI tool
  2. What commands it can run (sessions, anchors, stats, etc.)
  3. What JSON fields to expect in responses
  4. How to use --agent for machine-readable output
SettingValueWhy
transparency.modeonMetadata + redacted transcripts sync with repo for team visibility
git.alias_enabledtrueAutomatic enrichment on every commit
server.synctrueAuto-push anchor data to backend on every commit
--agent flagAlways useStructured JSON output for parsing

​
Agent lifecycle hooks

Oobo installs lifecycle hooks into supported AI tools so it can track when sessions start and end. This enables real-time session linking during commits.

​
Supported hook targets

ToolHook mechanism
CursorMCP server config or Rules file
Claude CodeCLAUDE.md project file
Gemini CLIGEMINI.md project file
OpenCodeAGENTS.md project file

​
How hooks work

When an AI agent starts a session, the hook calls: 
echo '{"session_id":"<id>","agent":"cursor","model":"claude-opus-4"}' | oobo hooks agent session-start
This creates a session state file at .git/oobo-sessions/<id>.json. When oobo intercepts a commit, it reads these files to link active sessions to the anchor. When the session ends: 
echo '{"session_id":"<id>"}' | oobo hooks agent session-end
For tools without native hook support (Aider, Copilot, Windsurf, Zed, Trae, Codex), oobo uses a scan fallback: it discovers sessions from tool storage after the fact and links them to commits based on time-window correlation.

​
Agent-first setup

​
Installation

The install script supports --agent for machine-friendly output: 
curl -fsSL https://oobo.ai/install.sh | bash -s -- --agent
With --agent, the installer:
  • Suppresses colors and progress messages
  • Outputs a single JSON result on success: {"status":"ok","version":"...","binary":"...","platform":"..."}
  • Outputs JSON errors on failure: {"error":"..."}
  • Still adds oobo to PATH (both shell RC and current session)

​
Configuration

For automated environments (CI, agent workstations), skip the interactive wizard and write config directly: 
mkdir -p ~/.oobo
cat > ~/.oobo/config.toml << 'EOF'
[git]
alias_enabled = true

[transparency]
mode = "on"
EOF
Then install the alias and discover existing sessions: 
oobo alias install
oobo scan

​
JSON response reference

​
anchors —agent

{
  "commit_hash": "abc123...",
  "message": "fix auth middleware",
  "author": "Dev <dev@co.com>",
  "author_type": "assisted",
  "branch": "main",
  "committed_at": 1741528800,
  "contributors": [
    { "name": "Dev <dev@co.com>", "role": "human" },
    { "name": "cursor", "role": "agent", "model": "claude-sonnet-4" }
  ],
  "files_changed": ["src/auth.rs"],
  "added": 42,
  "deleted": 10,
  "file_changes": [
    { "path": "src/auth.rs", "added": 42, "deleted": 10, "attribution": "ai", "agent": "cursor" }
  ],
  "ai_added": 42,
  "ai_deleted": 10,
  "human_added": 0,
  "human_deleted": 0,
  "ai_percentage": 100.0,
  "sessions": [
    {
      "session_id": "abc12def-...",
      "agent": "cursor",
      "model": "claude-sonnet-4",
      "link_type": "explicit",
      "files_touched": ["src/auth.rs"],
      "is_subagent": false,
      "is_estimated": false
    }
  ],
  "transparency_mode": "off"
}

​
sessions list —agent

{
  "session_id": "abc12def-...",
  "name": "Fix auth middleware",
  "source": "cursor",
  "mode": "composer",
  "project_path": "/Users/dev/myapp",
  "created_at": "2026-03-09T12:00:00Z",
  "updated_at": "2026-03-09T14:00:00Z",
  "model": "claude-sonnet-4",
  "input_tokens": 5000,
  "output_tokens": 12000,
  "duration_secs": 7200,
  "is_estimated": false,
  "files_touched": ["src/auth.rs"],
  "tool_calls": 8
}

​
stats —agent

{
  "sessions": 42,
  "input_tokens": 150000,
  "output_tokens": 320000,
  "total_tokens": 470000,
  "per_tool": [
    { "tool": "cursor", "sessions": 30, "tokens": 350000 }
  ],
  "per_model": [
    { "model": "claude-sonnet-4", "sessions": 25, "tokens": 280000 }
  ],
  "ai_code": {
    "ai_percentage": 45.2,
    "ai_lines": 1200,
    "human_lines": 1460
  },
  "productivity": { ... },
  "daily": [ ... ]
}