Origin CLI Documentation

August 12, 2026 · View on GitHub

Origin is an AI coding governance platform that tracks, attributes, and governs AI-assisted code across your team. The CLI hooks into AI coding agents (Claude Code, Cursor, Gemini, Windsurf, Aider) to capture session data, enforce policies, and provide attribution analytics.

Installation
Quick Start
Authentication & Setup
Hook Management
Session Tracking
Attribution & Blame
Search & Analysis
Time Travel & Resume
Trail System
Cross-Agent Handoff
Session Memory
AI TODO Tracker
Configuration
Local Database
CI/CD Integration
Plugin System
Git Proxy
Maintenance
Upgrade
Hook Architecture
Data Storage
Supported Agents

Installation

# Install from Origin platform
npm i -g https://getorigin.io/cli/origin-cli-latest.tgz

Verify:

origin --version

Quick Start (Standalone — no server required)

# 1. Enable global hooks (tracks all repos automatically)
origin enable --global

# 2. Code with any AI agent (Claude Code, Gemini CLI, Cursor, etc.)

# 3. View attribution
origin blame src/index.ts    # Line-level AI/human tags
origin stats                 # AI vs human breakdown
origin diff                  # Annotated diff
origin sessions              # List all AI sessions
origin session <id>          # Full session transcript

No login, no API keys. All data stored locally in git notes and origin-sessions branch.

Quick Start (Connected — with Origin server)

# 1. Login to your Origin instance
origin login

# 2. Register this machine
origin enable

# 3. Enable hooks (auto-detects installed agents)
origin enable

# 4. Start coding with your AI agent — Origin tracks everything automatically

# 5. View your session
origin sessions

Authentication & Setup

Authenticate with your Origin server.

origin login
# Prompts for:
#   API URL (default: https://getorigin.io)
#   API Key (from your Origin dashboard)

Config saved to ~/.origin/config.json.

`origin enable`

origin enable
# Detects: claude, cursor, aider, gemini, windsurf
# Registers machine with Origin API
# Saves to ~/.origin/agent.json

`origin whoami`

Show current authentication status.

origin whoami
# Output: API URL, Org ID, user email/name/role, machine info

Hook Management

`origin enable`

Install Origin hooks for session tracking. Hooks capture AI prompts, file changes, token usage, and costs.

# Auto-detect and install for all found agents
origin enable

# Install for a specific agent
origin enable --agent claude-code
origin enable --agent cursor
origin enable --agent gemini
origin enable --agent codex
origin enable --agent windsurf
origin enable --agent aider

# Install globally (all repos tracked automatically)
origin enable --global

# Install and link to a specific Origin agent
origin enable --link my-agent-slug

# Override the agent slug used for session attribution
origin enable --agent-slug my-custom-slug

# Replace existing hooks instead of chaining
origin enable --no-chain

What gets installed:

Agent	Config File	Events
Claude Code	`~/.claude/settings.json`	SessionStart, Stop, UserPromptSubmit, SessionEnd, PreToolUse, PostToolUse
Cursor	`~/.cursor/hooks.json`	sessionStart, stop, beforeSubmitPrompt, sessionEnd
Codex CLI	`~/.codex/config.json`	SessionStart, Stop, UserPromptSubmit
Gemini	`~/.gemini/settings.json`	SessionStart, SessionEnd, BeforeAgent, AfterAgent
Windsurf	`~/.windsurf/hooks.json`	sessionStart, stop, beforeSubmitPrompt, sessionEnd
Aider	`~/.aider.conf.yml`	git-commit-verify, notifications-command
Git	`.git/hooks/post-commit`	post-commit (for commit attribution)
Git	`.git/hooks/pre-push`	pre-push (auto-push session data)

Hook chaining: By default, Origin preserves existing hooks and chains them. Use --no-chain to replace instead.

Permission deny rules: Origin installs deny rules so AI agents can't read their own session metadata (.git/origin-session*.json, .origin.json).

`origin disable`

Remove all Origin hooks.

origin disable           # Remove from current repo
origin disable --global  # Remove global hooks

`origin link`

Link a repo to a specific Origin agent for session attribution.

origin link my-agent     # Link to agent "my-agent" (writes .origin.json)
origin link              # Show current mapping
origin link --clear      # Remove mapping

Session Tracking

`origin status`

Show current session status, repo info, and connection health.

origin status
# Shows:
#   Login status
#   Active session (ID, model, duration, branch, HEAD)
#   Repository info
#   Policy count
#   API health

`origin sessions`

List coding sessions with filters.

origin sessions                          # List recent sessions
origin sessions --status unreviewed      # Only unreviewed
origin sessions --model claude-sonnet-4  # Filter by model
origin sessions --limit 50              # Show more results

`origin session <id>`

View full details of a session.

origin session abc123
# Shows: model, repo, commits, author, tokens, cost, duration,
#        files changed, review status

`origin sessions end <id>`

End a running session. Kills the heartbeat process, ends the session on the platform, cleans local state files, and updates the origin-sessions git branch.

origin sessions end abc123      # End by session ID
origin sessions end abc1        # Partial ID match works

`origin sessions clean`

End all stale RUNNING sessions in bulk.

origin sessions clean           # Clean sessions for current repo
origin sessions clean --all     # Clean all repos

`origin explain [sessionId]`

Explain a coding session with prompts, file changes, cost, and review status.

# Explain active session
origin explain

# Explain by session ID
origin explain abc123

# Look up by commit SHA
origin explain --commit a1b2c3d

# Short output (skip prompt mappings)
origin explain --short

# AI-powered summary
origin explain --summarize

# JSON output
origin explain --json

The --summarize flag generates:

A structured metrics summary (scope, efficiency, velocity)
An AI-powered analysis (requires ANTHROPIC_API_KEY or origin config set anthropicApiKey <key>) with:
- Intent — what the developer was trying to accomplish
- Outcome — what was actually achieved
- Learnings — patterns and techniques used
- Friction — signs of struggle or inefficiency
- Time saved — estimate vs writing manually

`origin session-compare <id1> <id2>`

Compare two sessions side by side.

origin session-compare abc123 def456
# Shows:
#   Session    abc123       def456
#   Model      claude-4     gpt-4o
#   Duration   5m 30s       12m 15s
#   Tokens     15,234       42,891
#   Cost       \$0.0456      \$0.1234
#   Lines +    89           45
#   Lines -    12           30
#
#   Efficiency
#   Tokens/line  151        574
#   Lines/min    18         6
#
#   AI Comparison
#   Session 1 was 3.8x more token-efficient...

If an Anthropic API key is available, includes an AI-powered comparison analysis.

`origin review <sessionId>`

Review and approve/reject/flag a session.

origin review abc123 --approve
origin review abc123 --reject --note "Introduces security vulnerability"
origin review abc123 --flag --note "Needs team review"

Attribution & Blame

`origin blame <file>`

Show AI vs human attribution per line, like git blame but for AI authorship.

origin blame src/index.ts
# Output:
#   Line  Tag   Author/Model              Content
#   ─────────────────────────────────────────────────
#     1  [AI]  gemini-3-flash-preview     hello world
#     2  [AI]  claude-sonnet-4            import express from 'express';
#     3  [HU]  Artem Dolobanko            const port = 8080;
#
# Summary: AI: 2 (67%)  Human: 1 (33%)  Mixed: 0 (0%)

# Show specific line range
origin blame src/index.ts --line 10-20

# JSON output (for IDE integration)
origin blame src/index.ts --json

Tags:

[AI] (green) — Line written by AI agent (shows model name)
[HU] (white) — Line written by human (shows git author)
[MX] (yellow) — AI wrote initial version, human modified

`origin diff [range]`

Show diff with AI/human attribution annotations.

origin diff                    # Diff of current changes
origin diff HEAD~5..HEAD       # Diff over last 5 commits
origin diff --ai-only          # Only AI-authored changes
origin diff --human-only       # Only human-authored changes
origin diff --json             # JSON output

`origin stats`

View dashboard statistics with attribution breakdown.

# API stats (sessions, costs, agents)
origin stats

# Local git-based stats with attribution
origin stats --local
# Shows:
#   Total commits (AI vs human)
#   Lines added by AI vs human
#   Per-tool breakdown with bar graph:
#     claude-code  ████████████████████░░░░  82%  (340 lines)
#     cursor       ██████░░░░░░░░░░░░░░░░░░  25%  (45 lines)
#   Acceptance rate (AI lines humans kept vs edited)

# Custom commit range
origin stats --local --range HEAD~100..HEAD

Search & Analysis

`origin search <query>`

Search across all AI prompt history.

origin search "authentication"              # Search all prompts
origin search "refactor" --model claude     # Filter by model
origin search "database" --limit 50         # More results
origin search "API" --repo /path/to/repo    # Filter by repo
origin search "auth" --from 7d             # Only last 7 days
origin search "fix" --from 2w              # Last 2 weeks
origin search "deploy" --agent claude      # Filter by agent
origin search "bug" --from 1m --agent cursor # Combined filters

Searches across multiple data sources:

Connected mode — Origin API sessions
Local state files — ~/.origin/sessions/*.json
Git notes — refs/notes/origin commit metadata
Local DB — ~/.origin/db/ prompt database (run origin db import to populate)

`origin ask <query>`

Query the context behind AI-generated code. Find which session and prompts generated a specific file or line.

# Ask about a specific file
origin ask "auth" --file src/auth.ts
# Shows: sessions that modified this file, matching prompts

# Ask about a specific line
origin ask "why" --file src/index.ts --line 42

# Search within a specific session
origin ask "refactor" --session local-f7a2b3

# Global prompt search
origin ask "authentication"

How it works:

If --file is given, looks up sessions via git notes on commits touching that file
If --session is given, searches that session's prompts
Otherwise, searches all prompts matching the query
Falls back to searching the origin-sessions branch directly

`origin prompts <file>`

Show all AI prompts that led to changes in a specific file — like git log but for AI prompts. Shows which prompts, models, and sessions touched each file.

# See which AI prompts touched a file
origin prompts src/auth.ts

# See prompts + the actual code diff per prompt
origin prompts src/auth.ts --expand

# Limit results
origin prompts src/auth.ts --limit 5

Output:

  src/auth.ts — 3 AI sessions touched this file

  Mar 16, 19:42  Claude 3.5 Sonnet      (a1b2c3d4)
  > "add JWT validation middleware"
    feat: add JWT auth middleware

  Mar 16, 18:15  Gemini 2.5 Pro         (d4e5f6a7)
  > "refactor auth to use async/await"
    refactor: async auth handlers

  Mar 15, 14:30  Claude 3.5 Sonnet      (g7h8i9j0)
  > "implement login endpoint"
    feat: login endpoint

With --expand, each entry includes the full colored diff showing exactly what lines that prompt added/removed in the file.

`origin chat`

Interactive AI assistant for your repo's AI context. Ask natural language questions about your AI-authored code, sessions, costs, and attribution.

Requires ANTHROPIC_API_KEY environment variable.

# Interactive mode — ongoing conversation
origin chat

# Single question mode
origin chat -q "how much AI code is in this repo?"
origin chat -q "which model wrote the auth module?"
origin chat -q "what did AI touch last week?"
origin chat -q "show me the most expensive sessions"

Interactive session example:

  Origin Chat — ask anything about your AI-authored code

  you > who wrote src/auth.ts?
  3 AI sessions touched src/auth.ts. Claude 3.5 Sonnet wrote the initial
  login endpoint (session local-g7h8i9, Mar 15), then Gemini 2.5 Pro
  refactored it to async/await (session local-d4e5f6, Mar 16).

  you > how much have I spent on AI this month?
  Based on tracked sessions: \$4.32 across 23 sessions.
  Claude 3.5 Sonnet: \$3.18 (74%), Gemini 2.5 Pro: \$1.14 (26%).

  you > exit

The assistant automatically gathers context from:

Git notes (AI commit metadata)
Session history (origin-sessions branch)
Local prompt database
Commit log and authors

`origin web`

Launch a local web dashboard in your browser. Shows AI attribution stats, commit history, sessions, and prompts — no server or login required.

origin web              # Opens http://localhost:3141
origin web --port 8080  # Custom port

The dashboard includes:

Overview — stats cards (total commits, AI ratio, lines added), bar charts by tool and model
Commits — full commit list with [AI]/[HU] badges, model names, line counts
Sessions — all tracked AI sessions with model, tokens, cost
Prompts — prompt database browser with file change tracking

Data is gathered from git notes, the origin-sessions branch, and the local prompt database. The browser opens automatically.

`origin analyze`

Analyze AI prompting patterns and metrics.

origin analyze                    # Analyze last 30 days
origin analyze --days 90          # Custom date range
origin analyze --model claude     # Filter by model
origin analyze --export report.md # Export to file
origin analyze --json             # JSON output

Shows:

Total prompts, average/median length
Prompt-to-file-change ratio
Model breakdown (which AI models used most)
Common patterns (questions, commands, fixes, refactors)
Time distribution (when you prompt most)
Top changed files

`origin report`

Generate a sprint or time-range report with cost, model, user, and ROI metrics.

origin report                         # Default 7-day report
origin report --range 14d             # 14-day report
origin report --range 30d             # Monthly report
origin report --format json           # JSON output
origin report --format csv            # CSV output
origin report --output sprint.md      # Write to file

`origin audit`

Generate a compliance audit trail (SOC 2, ISO 27001).

origin audit                                    # Audit last 30 days
origin audit --from 2026-01-01 --to 2026-03-31  # Custom date range
origin audit --format json                      # JSON output
origin audit --format csv                       # CSV output
origin audit --output audit.md                  # Write to file

`origin backfill`

Retroactively tag old commits as AI or human-authored.

origin backfill                       # Dry-run — show what would be tagged
origin backfill --apply               # Actually write the tags
origin backfill --days 180            # Go back 6 months
origin backfill --min-confidence high # Only tag high-confidence matches

Scans .claude/, .cursor/, .codex/ session history, commit message patterns, and code style heuristics to identify AI-generated commits.

`origin verify`

Health check for agents, repo connection, and sessions.

origin verify           # Run all checks
origin verify --json    # JSON output

`origin review-pr`

Review a pull request with AI governance analysis.

origin review-pr 123              # Review PR #123
origin review-pr <pr-url>         # Review by URL

Reporting & Compliance

`origin agents`

List and manage registered AI agents (connected mode).

origin agents                     # List all agents
origin agents create --name "My Agent" --slug my-agent --model claude-opus-4-6

`origin policies`

View active governance policies for the organization.

origin policies

Policies are configured in the Origin dashboard and enforce rules like session review requirements, cost limits, model restrictions, and file access controls.

`origin repos`

List and manage repositories tracked by Origin.

origin repos                      # List all repos
origin repos add --name my-repo --path /path/to/repo

Time Travel & Resume

`origin rewind`

Rewind to a previous AI checkpoint (time travel). Restore your code to any previous AI session state.

# Interactive checkpoint browser
origin rewind --interactive
# Shows:
#   Checkpoints for session abc12345:
#     1. [14:30] feat: add auth middleware      +45 -3  (claude-sonnet-4)
#     2. [14:25] fix: route handler types       +12 -8  (claude-sonnet-4)
#     3. [14:20] refactor: extract validators   +89 -34 (claude-sonnet-4)
#   Select checkpoint (1-3):

# Rewind to specific commit
origin rewind --to a1b2c3d

# List checkpoints without rewinding
origin rewind --list

Safety: Always stashes current changes before rewinding. Requires confirmation.

`origin resume [branch]`

Resume an AI session from a previous branch. Builds context from the origin-sessions branch data.

# Resume from current branch
origin resume

# Resume from specific branch
origin resume feature/auth

# Auto-launch the AI agent with context
origin resume --launch

# Get context as JSON (for piping)
origin resume --json

With --launch, Origin detects the installed agent and launches it with the session context:

Claude Code: pipes context to claude --resume
Cursor: writes context to .cursor/context.md
Gemini: writes context to .gemini/context.md

Create a shareable prompt bundle from a session.

# Share entire session (copies to clipboard)
origin share abc123

# Share specific prompt
origin share abc123 --prompt 3

# Write to file
origin share abc123 --output session-bundle.md

Generates a self-contained markdown bundle with context, prompts, files changed, and diffs.

Trail System

Branch-centric work tracking. Trails describe the "why" and "what" of work while sessions capture the "how" and "when."

`origin trail`

Show the trail for the current branch.

origin trail
# Shows: Trail ID, name, branch, status, priority, labels,
#        reviewers, associated sessions

`origin trail list`

List all trails.

origin trail list                    # All trails
origin trail list --status active    # Filter by status

Statuses: active, review, done, paused

`origin trail create <name>`

Create a trail for the current branch.

origin trail create "Add user authentication"
origin trail create "Bug fix: login loop" --priority high
origin trail create "Refactor API" --priority critical --label backend --label api

`origin trail update`

Update the current trail.

origin trail update --status review
origin trail update --priority high
origin trail update --title "Updated: Add OAuth2 authentication"

`origin trail assign <user>`

Assign a reviewer.

origin trail assign john@example.com

`origin trail label <labels...>`

Add labels.

origin trail label frontend security

Trails are stored on the origin-sessions branch under trails/ and synced with remote.

Cross-Agent Handoff

Automatically pass context between different AI agents. When you finish a session in Claude Code and start one in Cursor (or any other agent), Origin carries over what you were working on.

How It Works

On session-end/stop: Origin writes .git/origin-handoff.json with the session's prompts, files changed, summary, and extracted TODOs
On next session-start (any agent): Origin reads the handoff and injects context into the new agent's system prompt

The new agent automatically knows:

What was done in the previous session
Which files are in progress
The last prompt and its context
Open TODOs from the previous session

`origin context handoff`

Preview the handoff context that will be passed to the next agent.

origin context handoff
# Output:
#   Cross-Agent Handoff Context
#
#   Agent:    claude-code
#   Model:    claude-sonnet-4
#   Session:  5c6c03a2
#   Ended:    15m ago
#   Branch:   feature/auth
#
#   Summary: Added JWT authentication middleware...
#
#   Last prompt: "add validation for expired tokens"
#
#   Files in progress (3):
#     src/auth/middleware.ts
#     src/auth/jwt.ts
#     tests/auth.test.ts
#
#   Open TODOs:
#     - add refresh token support
#     - handle edge case for expired tokens

`origin context clear --handoff-only`

Clear handoff data for the current repo.

origin context clear --handoff-only

Note: Handoff data expires after 24 hours automatically.

Session Memory

Accumulated context across sessions. Origin remembers what happened in previous sessions and injects summaries into new ones.

How It Works

Memory has two layers, both in refs/notes/origin-memory:

Session summaries — one evolving rollup per SESSION (upsert by session ID; regenerated as the session works and at session end). A session spans many commits — these IDs are sessions, not commits.
Commit history — an immutable record per commit (frozen when the commit lands, add-once by SHA): the commit message, that commit's files, and per-file change notes. Written on commit when memoryUpdate includes commit, and pruned to commits whose session is still in the retained window.

Both layers also capture decisions — the notable choices and trade-offs a session made and why (e.g. "used bcrypt over argon2 for broader Node compatibility"). These are the reasoning a future agent can't recover by re-reading the code. Decisions come from two sources:

[Origin: Decision] markers you (or an agent) emit in a response — ground truth, captured verbatim from the transcript, no LLM call needed.
LLM-inferred decisions — when memorySummary=llm, the summarizer also extracts decisions that are clearly evident from the diff/commits/prompts (a library or approach picked, something deliberately not done), and writes "none" when nothing real stands out.

When work is written: the session rollup upserts (summary, files, TODOs, decisions); each commit also appends its immutable record (with the decisions evident in that commit).
On the next session-start: Origin distills the substantive sessions into a short brief (it does not dump raw prompt logs) — plus the most recent commits and the key decisions — and injects it into the new agent's context.

The new agent gets context like:

Prior work in this repo — 3 sessions (claude-code, cursor):
- Most recent: [15m ago] Added JWT auth middleware
  Files: middleware.ts, jwt.ts
- Frequently touched: queries.ts, pool.ts, index.ts
Key decisions from previous sessions:
  - Used bcrypt over argon2 for broader Node compatibility
  - Kept refresh tokens server-side; access tokens stay short-lived
Open TODOs from previous sessions:
  - wire refresh-token rotation

Bake-off sandboxes, ignored repos, and trivial/benchmark turns are filtered out so real signal isn't buried under noise.

When memory is written: `memoryUpdate`

By default memory is written once, at session end. Commit-and-go agents that never reach a clean session end would be missed — so you can switch the trigger:

origin config set memoryUpdate session-end   # default — write at session end
origin config set memoryUpdate commit         # write/refresh on every commit
origin config set memoryUpdate both           # commit AND session end

commit is what captures agents that make a change, commit, and exit. The entry upserts by session ID, so repeated writes collapse to one latest entry.

How summaries are written: `memorySummary`

By default the summary is heuristic (the session's first prompt, or the commit message). Opt into an LLM-synthesized one-line "what this session did" — which reads better for multi-turn sessions — with:

origin config set memorySummary llm     # synthesize via your Anthropic key
origin config set memorySummary heuristic # default

llm mode makes one small LLM call at session end, grounded in the session's prompts + commit messages + a bounded code diff (so the summary reflects what actually changed, not just the opening prompt). Key resolution:

A local key (env ANTHROPIC_API_KEY / config.anthropicApiKey / local agent-keys / bake-off agent key) → the CLI calls Anthropic directly (works offline).
Otherwise, when connected, the CLI asks the server to summarize using the org's "AI provider" key (Settings → AI Chat — the same key behind PR summaries). That key never leaves the server, and this covers Anthropic/OpenAI/Google.

If neither resolves (offline + no local key, or the org has no LLM key), it falls back to the heuristic — commit messages, then the first prompt — so it's safe to leave on.

Per-file change notes. In llm mode the summarizer also records a one-line "what changed" per file (password_generator.py: added length/charset options), stored on the memory entry and shown in origin context memory + injected for the most recent session — so a future agent knows a file's recent change without re-reading the diff.

Decisions. Both memory layers also record the notable choices/trade-offs a session made and why — the reasoning a future agent can't recover from code. Sources: explicit [Origin: Decision] <choice> — <why> markers in a response (ground truth, captured verbatim, no LLM call) and, in llm mode, decisions the summarizer finds clearly evident in the diff/commits (it writes "none" when nothing real stands out). Shown under "Key decisions" in origin context memory and injected into the next session.

Continuation brief. With memorySummary = llm, Origin regenerates a short cross-session handoff brief for the next agent (recent focus, what's in flight/unfinished, watch-outs, open TODOs) — synthesized with the org LLM key and grounded in the most recent code diff, cached in a git note (refs/notes/origin-memory-brief). It's injected at the next session start in place of the deterministic distillation, which remains the offline fallback. Regenerated at session end and on every commit (so commit-and-go agents under memoryUpdate = commit get a fresh brief too), only when the underlying sessions change.

`origin context memory`

Display accumulated session memory for the current repo.

origin context memory              # Show last 10 sessions
origin context memory --limit 20   # Show more

`origin context clear --memory-only`

Clear all session memory for the current repo.

origin context clear --memory-only

Memory is stored in git notes (refs/notes/origin-memory) and travels with the repo automatically, in both directions, without anyone running anything by hand.

Out — pushed on the same triggers as attribution notes: session end, and the pre-push hook alongside your own push.

In — three paths, because no single one covers every case:

when	what happens
any `git fetch` / `git pull`	The fetch refspec `+refs/notes/origin:refs/notes/origin-remote` carries every Origin notes ref into a staging namespace. Pure git — Origin isn't running.
`post-merge` hook	Merges staging onto the live refs, so the pull's result is immediately readable. Local only, no network.
session start	Fetch + merge, throttled to once per 10 minutes per repo, with a 6s network ceiling. Covers clones that haven't been pulled and repos whose git hooks aren't installed.

The refspec is a glob on purpose. An explicit refspec naming a ref the remote doesn't have makes ordinary git fetch fail outright, so it could only be installed after a successful fetch — which is exactly when it was no longer needed. A glob matching nothing is a clean no-op, so it can be installed on the first sync and starts carrying notes the moment the remote gains them.

Staging is also deliberate: notes are never mapped straight onto a live ref. See the warning in AI_FEATURES.md.

A plain git pull therefore stages memory; it becomes readable once something folds it (post-merge, session start, or origin link / origin blame).

Two machines that both wrote memory are reconciled by unioning the payload — session rollups keyed by sessionId (newest write wins), commit records keyed by commitSha (frozen, first write wins). A plain git notes merge is deliberately not used: the whole payload is one note on the root commit, so any git-level strategy resolves the entire blob and would drop one machine's sessions wholesale.

Pushing memory respects the same privacy switch as attribution notes — with notesIncludePrompts: false (in .origin.json or ~/.origin/config.json) memory stays local to the machine that wrote it.

Repo Brief

Session memory captures what past sessions did. The repo brief captures what the repo is — a cached, LLM-written summary of its purpose, architecture, entry points, and gotchas — injected at session start so an agent is oriented before its first prompt.

Opt-in, because generating it sends repo context to Anthropic.

How It Works

Enable it per repo (origin context brief --enable).
Generation makes one LLM call over a bounded bundle — README, package manifests, the tracked-file tree, and recent commit subjects — not your whole codebase. The key is resolved from ANTHROPIC_API_KEY / origin config set anthropicApiKey, then a local agent-keys file, then (in team mode) your org's stored key.
Cache — the result is stored in git notes (refs/notes/origin-repo-brief) keyed by a signature of HEAD + manifests + file tree. It's only regenerated when the repo drifts, and (when enabled) can auto-generate in the background for the next session so it never blocks the current one.
Injection — at session start the cached brief is injected alongside session memory. This path is cache-only; it never runs an LLM in the hot path.

`origin context brief`

origin context brief --enable     # turn on injection for this repo
origin context brief              # show the cached brief
origin context brief --refresh    # generate/regenerate now (uses your Anthropic key)
origin context brief --disable    # stop injecting
origin context brief --clear      # remove the cached brief for this repo

Session memory is on by default and fully local. The repo brief is the only context layer that calls an external service, and only after you enable it.

AI TODO Tracker

Origin automatically extracts TODOs mentioned in AI session prompts and tracks them across repos.

How It Works

On session-end, Origin scans all prompts for patterns like:

TODO: ..., FIXME: ..., NOTE: ...
"need to fix X", "we should add Y", "handle Z later"
"still need to implement X"

Extracted TODOs are stored in ~/.origin/origin-todos.json across all repos.

`origin todo`

List open TODOs (alias for origin todo list).

origin todo
# Output:
#   Open TODOs (3)
#
#   ○ a1b2c3d4  add refresh token support
#     session:5c6c03a2  my-app  15m ago
#     branch: feature/auth
#
#   ○ e5f6g7h8  handle edge case for expired tokens
#     session:5c6c03a2  my-app  15m ago
#
#   ○ i9j0k1l2  add rate limiting to API endpoints
#     session:d4e5f6a7  api-server  2h ago

`origin todo list`

origin todo list                # Open TODOs for current repo
origin todo list --all          # Open TODOs from all repos
origin todo list --done         # Show completed TODOs

`origin todo done <id>`

Mark a TODO as complete.

origin todo done a1b2            # Partial ID match works
# ✓ Marked as done: add refresh token support

`origin todo show <id>`

Show full details of a TODO including the originating session.

origin todo show a1b2
# Output:
#   TODO a1b2c3d4
#   Text:      add refresh token support
#   Status:    open
#   Session:   5c6c03a2
#   Repo:      /Users/you/my-app
#   Branch:    feature/auth
#   Created:   2026-03-30T10:15:00Z (2h ago)
#   Source:    prompt

`origin todo add <text>`

Manually add a TODO.

origin todo add "migrate database to PostgreSQL"

`origin todo remove <id>`

Remove a TODO permanently.

origin todo remove a1b2

Configuration

`origin config`

Manage Origin configuration.

# List all config values with descriptions
origin config list

# Get a specific value
origin config get pushStrategy

# Set a value
origin config set commitLinking always
origin config set pushStrategy auto
origin config set secretRedaction true
origin config set telemetry true

Available Config Keys

Key	Values	Default	Description
`apiUrl`	URL	`https://getorigin.io`	Origin API URL
`apiKey`	string	—	API key (use `origin login`)
`commitLinking`	`always` \| `prompt` \| `never`	`always`	Add Origin-Session trailers to commits
`pushStrategy`	`auto` \| `prompt` \| `false`	`auto`	When to push origin-sessions branch
`telemetry`	`true` \| `false`	`false`	Enable anonymous telemetry (opt-in)
`autoUpdate`	`true` \| `false`	`true`	Check for CLI updates
`secretRedaction`	`true` \| `false`	`true`	Redact secrets before sending to API
`hookChaining`	`true` \| `false`	`true`	Chain existing hooks when installing
`anthropicApiKey`	string	—	Anthropic API key for AI features (`explain --summarize`, `chat`, `session-compare`)
`agentSlugs`	object	`{}`	Per-tool agent slug overrides (e.g., `{"claude-code": "claude-front"}`)

Agent Slug Overrides

Override which Origin agent a tool's sessions are attributed to:

# Map Claude Code sessions to a custom agent slug
origin config set agentSlugs.claude-code claude-frontend

# Map Cursor sessions to a different agent
origin config set agentSlugs.cursor cursor-backend

# View current overrides
origin config get agentSlugs

This is useful when you have multiple Origin agents (e.g., claude-frontend, claude-backend) and want different repos or tools to report to different agents.

Per-Repo Config (`.origin.json`)

{
  "agent": "my-agent-slug",
  "ignorePatterns": ["*.generated.ts", "dist/**"],
  "trackTabCompletions": true
}

Local Database

`origin db import`

Import prompts from the origin-sessions branch into the local prompt database for search and analysis.

origin db import
# Walks origin-sessions branch, extracts prompts, stores in ~/.origin/db/

`origin db stats`

Show local database statistics.

origin db stats
# Shows: Total prompts, stored blobs, blob storage size

CI/CD Integration

`origin ci check`

Report AI attribution stats in CI. Designed to run in GitHub Actions or similar CI systems.

origin ci check
origin ci check --range origin/main..HEAD

Output includes: total commits, AI vs human split, AI percentage, top AI models used.

`origin ci squash-merge <baseBranch>`

Preserve AI attribution data through squash merges. Collects attribution from all commits being squashed and writes a combined note to the new squash commit.

origin ci squash-merge main

`origin ci generate-workflow`

Generate a GitHub Actions workflow file for automated attribution checking.

origin ci generate-workflow
# Outputs a complete .github/workflows/origin-attribution.yml

Example GitHub Actions Workflow

name: Origin Attribution
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  attribution:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Origin CLI
        run: npm install -g @origin/cli

      - name: Attribution Check
        run: |
          echo "## Attribution Report" >> $GITHUB_STEP_SUMMARY
          origin ci check --range "${{ github.event.pull_request.base.sha }}..${{ github.sha }}" >> $GITHUB_STEP_SUMMARY

Required secrets: ORIGIN_API_KEY

GitHub Commit Annotations (Connected Mode)

When using Origin with the GitHub App integration, PRs automatically get:

Status Checks — origin/ai-governance check that blocks or allows merges based on session review status
PR Comments — detailed AI governance report table with sessions, costs, tokens, and policy violations
Commit Annotations — [AI 73%] badge via GitHub Check Runs API showing per-commit AI attribution breakdown

The Check Run appears as "Origin AI Attribution" on the PR Checks tab and includes:

Overall AI percentage across all PR commits
Number of AI sessions and total AI lines added
Models and agents used
Per-commit table showing which commits are [AI] vs [Human]

This is automatic when the GitHub App is installed and postChecks is enabled in integration settings.

Plugin System

Extend Origin with external agent plugins.

`origin plugin list`

List installed plugins.

origin plugin list

`origin plugin install <name> <command>`

origin plugin install my-agent /usr/local/bin/my-agent-hook

Plugins communicate via JSON-over-stdio:

Origin writes { "event": "session-start", "data": {...} } to plugin stdin
Plugin responds { "status": "ok", "data": {...} } on stdout

`origin plugin remove <name>`

Remove a plugin.

origin plugin remove my-agent

Plugin registry stored at ~/.origin/plugins.json.

Git Proxy

Transparent git proxy that intercepts git commands for automatic attribution tracking.

`origin proxy install`

Install the git proxy wrapper. Creates ~/.origin/bin/git that wraps the real git binary.

origin proxy install
# Adds ~/.origin/bin to PATH (add to shell profile)

What it intercepts: git commit, git push, git rebase, git cherry-pick, git stash

For each intercepted command, the proxy fires pre/post hooks for attribution preservation.

`origin proxy uninstall`

Remove the git proxy.

origin proxy uninstall

`origin proxy status`

Check proxy installation status.

origin proxy status

Warning: The git proxy modifies your PATH. It's opt-in only with a kill switch (origin proxy uninstall). If anything goes wrong, remove ~/.origin/bin from your PATH.

Maintenance

`origin doctor`

Scan for and fix stuck or orphaned sessions.

origin doctor            # Scan only
origin doctor --fix      # Auto-fix issues found
origin doctor --verbose  # Detailed output

Checks for:

Stuck sessions (>1hr old, auto-ends with --fix — ends on platform API + local git branch)
Stale "running" sessions on origin-sessions branch (>1hr, marks as ended with --fix)
Orphaned entries referencing non-existent commits
Stale session state files (>24h/48h)
Orphaned session files in ~/.origin/sessions/
Errors in hooks log
Oversized hooks log (>10MB)
API connection health

`origin clean`

Remove orphaned data and temp files.

origin clean             # Preview what would be cleaned
origin clean --dry-run   # Same as above
origin clean --force     # Clean without confirmation

Removes:

Orphaned origin-sessions branch entries
Stale .git/origin-session*.json files
Temp index files (.git/origin-tmp-index*)
Old hooks log entries (>7 days)

`origin reset`

Clear local session state for the current repo.

origin reset             # Warns if session <1h old
origin reset --force     # Force clear

Upgrade

`origin upgrade`

Upgrade Origin CLI to the latest version.

origin upgrade                    # Upgrade to latest stable
origin upgrade --channel beta     # Upgrade to beta channel
origin upgrade --channel canary   # Upgrade to canary channel
origin upgrade --check            # Only check, don't install

Origin also checks for updates automatically after commands run (configurable via origin config set autoUpdate false).

Hook Architecture

Origin uses a multi-layer hook system:

Agent Hooks (7 events)

Event	Trigger	Data Captured
`session-start`	AI agent process begins	Session ID, model, branch, HEAD
`user-prompt-submit`	User sends prompt	Prompt text
`stop`	AI finishes a turn	Tokens, files changed, cost
`session-end`	AI process terminates	Full transcript, git state, final metrics
`pre-tool-use`	AI about to use a tool	Tool name, input
`post-tool-use`	AI finished using a tool	Tool result, subagent tracking
`git-post-commit`	After every git commit	Commit SHA, message, files, diff
`git-pre-push`	Before git push	Pushes origin-sessions branch + attribution/memory/acceptance notes alongside
`git-post-rewrite`	After rebase/amend	Copies attribution notes to new SHAs
`git-post-checkout`	After branch checkout/stash	Preserves attribution through stash ops; syncs notes into a fresh clone
`git-post-merge`	After a `git pull` that merges	Folds fetched notes onto the live refs (local only, no network)

Data Flow

AI Agent → Agent Hook → Origin CLI → Origin API
                    ↓
            .git/origin-session-<tag>.json (local state)
                    ↓
            origin-sessions branch (git plumbing)
                    ↓
            refs/notes/origin (git notes per commit)
                    ↓
            .git/origin-handoff.json (cross-agent context)
                    ↓
            refs/notes/origin-memory (session memory)
                    ↓
            ~/.origin/origin-todos.json (extracted TODOs)

Session Lifecycle

Each agent handles session start/end differently:

Agent	Session Start	Session End	Fallback
Claude Code	`SessionStart` hook	`SessionEnd` hook	Heartbeat stale check (15 min)
Cursor	`sessionStart` hook	No explicit end	Heartbeat stale check (15 min)
Codex CLI	`user-prompt-submit` hook	No explicit end	Heartbeat stale check (15 min)
Gemini CLI	`SessionStart` hook	`SessionEnd` hook	Heartbeat stale check (15 min)

Heartbeat: A background process (~/.origin/heartbeats/<id>.pid) pings the Origin API every 30 seconds. If the state file hasn't been updated in 15 minutes (agent closed/crashed), the heartbeat auto-ends the session.

Server-side cleanup: The Origin platform also checks every 5 minutes and auto-completes any RUNNING sessions with no heartbeat ping in 15 minutes.

Per-Prompt Diff Tracking

Origin tracks file changes per prompt, not just per session:

headShaAtLastStop — HEAD SHA after each prompt's stop, used as baseline for the next prompt's diff
completedPromptMappings — accumulated per-prompt file change data across stops
On each Stop event, the current prompt's changes are merged with previously saved mappings
The API receives all prompt mappings and stores them as PromptChange records
The AI Blame view on the dashboard uses these to show which prompt wrote which lines

Concurrent Sessions

Claude Code supports multiple concurrent sessions on the same repo. Each session gets a unique tag derived from the Claude session ID, stored as .git/origin-session-<tag>.json.

Secret Redaction

When secretRedaction is enabled (default: true), Origin automatically redacts:

AWS keys (AKIA...)
GitHub tokens (ghp_, gho_, ghu_, ghs_, github_pat_)
OpenAI keys (sk-...)
Anthropic keys (sk-ant-...)
Stripe keys (sk_live_, sk_test_)
Slack tokens (xoxb-, xoxp-)
Private keys (-----BEGIN ... PRIVATE KEY-----)
JWTs (eyJ...)
Database connection strings (postgres://, mysql://, mongodb://)
High-entropy secrets (Shannon entropy > 4.5)

Data Storage

Local Files

Path	Purpose
`~/.origin/config.json`	API URL, key, org/user IDs, feature flags
`~/.origin/agent.json`	Machine registration (hostname, detected tools)
`~/.origin/hooks.log`	Debug log for all hook invocations
`~/.origin/db/prompts.json`	Local prompt database
`~/.origin/blobs/<hash>`	Content-addressable blob storage
`~/.origin/plugins.json`	Plugin registry
`~/.origin/last-update-check.json`	Update check cache (24h TTL)
`~/.origin/sessions/<id>.json`	Global session archive (backup state)
`~/.origin/heartbeats/<id>.pid`	Active heartbeat PID files
`~/.origin/origin-todos.json`	AI-extracted TODO tracker (cross-repo)
`.git/origin-session-<tag>.json`	Active session state (tagged per concurrent session)
`.git/origin-handoff.json`	Cross-agent handoff context (last session summary for next agent)
`.origin.json`	Per-repo config (agent slug, ignore patterns)

Git Refs

Ref	Purpose
`origin-sessions`	Orphan branch storing session data (metadata.json, prompts.md, changes.json per session)
`refs/notes/origin`	Git notes with AI attribution metadata per commit
`refs/notes/origin-memory`	Session memory — accumulated session summaries for context injection
`trails/`	Trail metadata (on origin-sessions branch)

Origin-Sessions Branch Structure

sessions/
  <sessionId>/
    metadata.json    # Session metrics, tokens, cost, git state
    prompts.md       # Human-readable markdown with all prompts
    changes.json     # Prompt-to-file mappings with diffs
trails/
  <trailId>.json     # Trail metadata

Git Notes Format

Each AI-assisted commit gets a note under refs/notes/origin:

{
  "origin": {
    "sessionId": "local-f7a2b3",
    "model": "gemini-3-flash-preview",
    "promptCount": 5,
    "promptSummary": "Add authentication middleware...",
    "tokensUsed": 15000,
    "costUsd": 0.45,
    "durationMs": 120000,
    "linesAdded": 89,
    "linesRemoved": 12
  }
}

View notes: git notes --ref=origin show <commit-sha> Push notes: git push origin refs/notes/origin

Supported Agents

Agent	Detection	Hook System	Session Reuse	Status
Claude Code	Session hooks + process detection	Claude Code hooks API	No (new session per conversation)	Stable
Cursor	Session hooks + Cursor DB	Cursor hooks API	Yes (reuses across prompts)	Stable
Codex CLI	Session hooks + SQLite state	Codex hooks API	No (new session per conversation)	Stable
Gemini CLI	Session hooks + process detection	Gemini settings hooks	No	Stable
Aider	Process detection	Config hooks	No	Stable
Windsurf	Session hooks + process detection	Windsurf hooks API	No	Preview
GitHub Copilot	Process detection	Global post-commit hook	N/A	Preview
Continue	Process detection	Global post-commit hook	N/A	Preview
Amp	Process detection	Global post-commit hook	N/A	Preview
Junie	Process detection	Global post-commit hook	N/A	Preview
OpenCode	Process detection	Global post-commit hook	N/A	Preview
Rovo Dev	Process detection	Global post-commit hook	N/A	Preview
Droid	Process detection	Global post-commit hook	N/A	Preview

Cost Estimation

Origin estimates costs for:

Claude Sonnet 4 / Opus 4 / Haiku
Gemini Pro / Ultra
GPT-4 / GPT-4o / o1 / o3
Custom models (configurable)

File Ignore Patterns

Origin automatically ignores these files in attribution tracking:

Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock, go.sum, etc. Generated: *.generated.*, *.min.js, *.min.css, *.map Directories: node_modules/, vendor/, dist/, .next/, build/, __snapshots__/

Override in .origin.json:

{
  "ignorePatterns": ["custom-generated/**", "*.auto.ts"]
}

Environment Variables

Variable	Purpose
`ORIGIN_API_URL`	Override API URL
`ORIGIN_API_KEY`	Override API key
`ORIGIN_DEBUG`	Enable debug logging
`ANTHROPIC_API_KEY`	Anthropic API key for AI features (`explain --summarize`, `chat`, `session-compare`)

Troubleshooting

Hooks not firing

origin doctor --verbose    # Check for issues
origin enable              # Reinstall hooks

Stale/stuck sessions

origin doctor --fix        # Auto-fix stuck sessions (local + origin-sessions branch)
origin sessions end <id>   # End a specific session
origin sessions clean      # End all stale sessions for current repo
origin sessions clean --all # End all stale sessions globally
origin clean --force       # Remove orphaned data
origin reset --force       # Clear current session state

Session still shows RUNNING after closing agent

The heartbeat process auto-ends sessions after 15 minutes of inactivity. If it persists:

# Check for orphaned heartbeats
ls ~/.origin/heartbeats/

# Force end
origin sessions end <id>

# Fix stuck git branch entries
origin doctor --fix

AI Blame shows 0 prompts

Check the hooks log for errors during the Stop event:

grep "stop.*ERROR" ~/.origin/hooks.log

Common causes: API payload too large (fixed in v0.20260330+), transcript path not found, or session state missing.

View hook logs

tail -100 ~/.origin/hooks.log

# Filter for specific events
grep "stop" ~/.origin/hooks.log | tail -20
grep "ERROR" ~/.origin/hooks.log | tail -20

Check connection

origin whoami              # Verify auth
origin status              # Check API health
origin verify              # Full health check