ox

module
v0.11.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 2, 2026 License: MIT

README

SageOx CLI (ox)

The hivemind for human–agent teams. SageOx makes your team's decisions, conventions, and architectural intent persistent — and loads them automatically into every coding session, human or AI.

Today, that context lives in scattered places: a meeting nobody recorded, a Slack thread three weeks deep, the head of whoever wrote the code. So humans repeat themselves and AI coworkers drift — rebuilding the same lost context every session. ox closes that gap. Decisions become shared memory; every session starts with the full picture instead of from zero.

Ask your coding agent what the team already figured out — even if it happened in a different agent, on a different machine, days ago.

One session, every moment that matters: it recalls a teammate's Codex work and your own prior Claude Code session, coordinates by murmuring and noticing a teammate already in the same files, and proposes a plan enriched with collisions, prior art, and who owns the area. All of it because every session is recorded to a shared, queryable Ledger.

The loop

flowchart LR
    REC["Record at sageox.ai<br/>discussions, decisions"]
    KB["Knowledge Bubbles<br/>team context plus ledger"]
    PRIME["ox agent prime<br/>loads context"]
    WORK["AI Coworker session"]
    CAP["Session captured<br/>to the Ledger"]
    REC --> KB --> PRIME --> WORK --> CAP --> KB

Record a discussion once. It's distilled into Knowledge Bubbles — your team's shared memory. The next time anyone primes a coding session, that context flows in. The session itself is captured back to the Ledger, so the next coworker inherits it too. Context compounds instead of evaporating.

Works with your coding agent

ox is agent-agnostic. The same recorded context is primed into, and queryable from, whichever agent your team uses.

Agent Prime context Record sessions Murmur (coordinate) Query past work
Claude Code
Codex CLI
Cursor
Windsurf / Cline / Copilot / Aider

✅ supported · ➖ planned. Claude Code is the primary, most-tested target.

Agent names are trademarks of their respective owners; ox is compatible with, not affiliated with, them.

Install

Quick install (macOS / Linux / FreeBSD):

curl -sSL https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh | bash

From source:

git clone https://github.com/sageox/ox.git && cd ox
make build && make install

Verify with ox version.

Quickstart

cd ~/src/my-project     # your code repo
ox login                # authenticate with sageox.ai

ox init                 # one-time per repo: creates .sageox/
git add .sageox/ && git commit -m "initialize SageOx"

ox doctor               # diagnose (ox doctor --fix auto-repairs)
ox status               # setup, sync state, and your Knowledge Bubbles

That's the whole setup. From here, session capture is automatic — when an AI coworker runs ox agent prime at the start of a session, team context loads in and the session is recorded to the Ledger when it ends. No manual start/stop ritual.

Then just ask your AI coworker things it couldn't have known on its own:

  • "What did we decide about the daemon design, and who worked on it?"
  • "Draft a plan from this week's SageOx team discussions."
  • "Show me an effective prompt a teammate used on this repo recently."

What you get

Capability Command Learn more
Team context + repo memory as Knowledge Bubbles ox status, ox kb list jit-discovery
Query past sessions, discussions, and code — across agents and machines ox query "..." query
Auto-recorded coworker sessions (Ledger) ox agent prime, ox session list session capture
Real-time coordination signals between coworkers ox murmur "..."
Team-context-enriched implementation plans ox plan enrich, ox plan render plan
Planning-relevant code insights (hotspots, contention) ox code insights
Load an expert AI coworker into context ox coworker load <name>
Diagnose and auto-fix your setup ox doctor --fix doctor

How it works

ox init writes a .sageox/ directory that ties the repo to your team. From then on, ox agent prime injects team context — conventions, security requirements, architectural decisions, prior sessions — into each AI coworker before it writes a line. Coworkers, human and AI, share that context through the Team Context and the per-repo Ledger.

The payoff is multiplayer by default. When a discussion, an implementation session, and the resulting code all carry the same shared context, a reviewer opening the PR has the full story — the original reasoning, the session that built it, and the diff — without chasing anyone down.

Configuration

SageOx reads configuration from, in order:

  1. CLI flags (--verbose, --quiet, --json)
  2. Environment variables
  3. Config file (.sageox/config.yaml)

Tools we love

We build ox in great company. These are the tools we rely on — and love — every day. Gratitude to the teams behind them, and to the wider developer community.

Socket        SageOx        CodeRabbit        Greptile        Charm

Socket · SageOx · CodeRabbit · Greptile · Charm

Directories

Path Synopsis
cmd
ox command
session_push_summary.go is the `inline` summarization endpoint: it accepts a summary JSON produced by the calling agent (in response to the summary_prompt returned by `ox session stop`), validates and enriches it, then commits and pushes summary.json to the ledger.
session_push_summary.go is the `inline` summarization endpoint: it accepts a summary JSON produced by the calling agent (in response to the summary_prompt returned by `ox session stop`), validates and enriches it, then commits and pushes summary.json to the ledger.
ox-adapter-aider command
detect.go handles adapter detection and diagnostics.
detect.go handles adapter detection and diagnostics.
ox-adapter-amp command
detect.go handles adapter detection and diagnostics.
detect.go handles adapter detection and diagnostics.
ox-adapter-claude-code command
ox-adapter-claude-code is the external adapter binary for Claude Code sessions.
ox-adapter-claude-code is the external adapter binary for Claude Code sessions.
ox-adapter-codex command
detect.go — detection and diagnostics for codex adapter.
detect.go — detection and diagnostics for codex adapter.
ox-adapter-droid command
ox-adapter-droid is the external adapter binary for Factory Droid sessions.
ox-adapter-droid is the external adapter binary for Factory Droid sessions.
ox-adapter-gemini command
detect.go handles adapter detection and diagnostics.
detect.go handles adapter detection and diagnostics.
ox-adapter-opencode command
ox-adapter-opencode is the external adapter binary for OpenCode sessions.
ox-adapter-opencode is the external adapter binary for OpenCode sessions.
ox-adapter-pi command
detect.go handles adapter detection and diagnostics.
detect.go handles adapter detection and diagnostics.
ox-adapter-test command
ox-adapter-test is a test adapter for validating ox's adapter protocol integration without requiring a real coding agent.
ox-adapter-test is a test adapter for validating ox's adapter protocol integration without requiring a real coding agent.
extensions
internal
adapter
Package adapter provides the embedded adapter registry and lookup functions.
Package adapter provides the embedded adapter registry and lookup functions.
adapterstamp
Package adapterstamp holds the frontmatter-aware drift-stamp helpers shared by ox's per-agent adapter binaries (ox-adapter-claude-code, ox-adapter-droid).
Package adapterstamp holds the frontmatter-aware drift-stamp helpers shared by ox's per-agent adapter binaries (ox-adapter-claude-code, ox-adapter-droid).
agenttask
Package agenttask implements a shared, project-local queue of work items scheduled by internal producers (the daemon, doctor, scripts) for the next available AI coworker to execute — typically as a fresh-context subagent.
Package agenttask implements a shared, project-local queue of work items scheduled by internal producers (the daemon, doctor, scripts) for the next available AI coworker to execute — typically as a fresh-context subagent.
api
api/kbconfig
Package kbconfig vendors the canonical KBConfig Go types from sageox-mono's packages/kb/config.go into the ox CLI.
Package kbconfig vendors the canonical KBConfig Go types from sageox-mono's packages/kb/config.go into the ox CLI.
badge
Package badge handles SageOx README badge detection and suggestion.
Package badge handles SageOx README badge detection and suggestion.
carts
Package carts provides work item tracking backed by DoltDB.
Package carts provides work item tracking backed by DoltDB.
claude
Package claude provides utilities for discovering and parsing team Claude customizations.
Package claude provides utilities for discovering and parsing team Claude customizations.
cli
codedb/comments
Package comments extracts comments from source code using a character-level scanner configured by language-specific syntax families.
Package comments extracts comments from source code using a character-level scanner configured by language-specific syntax families.
codedb/diffformat
Package diffformat produces the simple "before vs after" diff text CodeDB indexes for diff search and re-derives at search-read time for snippets (ADR-018 phase 2 Option A).
Package diffformat produces the simple "before vs after" diff text CodeDB indexes for diff search and re-derives at search-read time for snippets (ADR-018 phase 2 Option A).
codedb/symbols
Package symbols extracts symbol definitions and references from source code using tree-sitter via gotreesitter (pure Go, no CGO required).
Package symbols extracts symbol definitions and references from source code using tree-sitter via gotreesitter (pure Go, no CGO required).
daemon
Package daemon provides background sync operations for the ledger.
Package daemon provides background sync operations for the ledger.
daemon/testutil
Package testutil provides testing utilities for daemon functionality.
Package testutil provides testing utilities for daemon functionality.
dashboard/app
Package app contains the BubbleTea application layer for the dashboard: messages, key bindings, layout geometry, and focus management.
Package app contains the BubbleTea application layer for the dashboard: messages, key bindings, layout geometry, and focus management.
dashboard/domain
Package domain defines the core value types the dashboard operates on.
Package domain defines the core value types the dashboard operates on.
dashboard/effects
Package effects defines the interface for dashboard side effects (daemon IPC, session store queries) and provides the production implementation.
Package effects defines the interface for dashboard side effects (daemon IPC, session store queries) and provides the production implementation.
dashboard/overlays/palette
Package palette implements the ⌘K command palette overlay for the dashboard TUI.
Package palette implements the ⌘K command palette overlay for the dashboard TUI.
dashboard/panes
Package panes defines the Pane interface and shared types used by every panel in the dashboard TUI.
Package panes defines the Pane interface and shared types used by every panel in the dashboard TUI.
dashboard/panes/inspector
Package inspector implements the right-hand detail inspector pane for the dashboard TUI.
Package inspector implements the right-hand detail inspector pane for the dashboard TUI.
dashboard/panes/nav
Package nav implements the left-hand navigation tree pane for the dashboard TUI.
Package nav implements the left-hand navigation tree pane for the dashboard TUI.
dashboard/panes/statusbar
Package statusbar implements the single-line status bar shown at the bottom of the dashboard TUI.
Package statusbar implements the single-line status bar shown at the bottom of the dashboard TUI.
dashboard/panes/timeline
Package timeline implements the center activity feed pane for the dashboard TUI.
Package timeline implements the center activity feed pane for the dashboard TUI.
dashboard/state
Package state defines the application state for the dashboard TUI and the read-only interface panes use to access that state without importing app.
Package state defines the application state for the dashboard TUI and the read-only interface panes use to access that state without importing app.
dashboard/theme
Package theme provides semantic design tokens and lipgloss styles for the dashboard TUI.
Package theme provides semantic design tokens and lipgloss styles for the dashboard TUI.
distill/history/memoryio
Package memoryio is the shared on-disk format helper for memory/daily, memory/weekly, and memory/monthly entries.
Package memoryio is the shared on-disk format helper for memory/daily, memory/weekly, and memory/monthly entries.
distill/history/read
Package read is the read-only distill-history reader for memory/daily, memory/weekly, and memory/monthly under a team-context root.
Package read is the read-only distill-history reader for memory/daily, memory/weekly, and memory/monthly under a team-context root.
doctor/autofix
Package autofix is the daemon-side periodic auto-fix scheduler (ox-0xgx).
Package autofix is the daemon-side periodic auto-fix scheduler (ox-0xgx).
doctorapi
Package doctorapi provides types and client for the cloud doctor API.
Package doctorapi provides types and client for the cloud doctor API.
endpoint
Package endpoint provides centralized SageOx endpoint URL management.
Package endpoint provides centralized SageOx endpoint URL management.
envutil
Package envutil sanitizes subprocess environments so the daemon and CLI never leak secrets (SAGEOX_TOKEN, GITHUB_TOKEN, AWS_*, …) into untrusted or long-lived child processes (third-party adapters, user-defined hooks).
Package envutil sanitizes subprocess environments so the daemon and CLI never leak secrets (SAGEOX_TOKEN, GITHUB_TOKEN, AWS_*, …) into untrusted or long-lived child processes (third-party adapters, user-defined hooks).
ephemeral
Package ephemeral is the legacy operator-facing facade for the capability-based runtime in internal/runtime.
Package ephemeral is the legacy operator-facing facade for the capability-based runtime in internal/runtime.
fileutil
Package fileutil — advisory file lock for cross-process serialization of read-modify-write sequences on shared config / manifest files.
Package fileutil — advisory file lock for cross-process serialization of read-modify-write sequences on shared config / manifest files.
flags
Package flags provides a layered feature flag resolver for the ox CLI.
Package flags provides a layered feature flag resolver for the ox CLI.
gitutil
Package gitutil provides shared git safety primitives used by both the daemon (pull/fetch) and CLI (push/commit) code paths.
Package gitutil provides shared git safety primitives used by both the daemon (pull/fetch) and CLI (push/commit) code paths.
identity
Package identity provides unified identity resolution for ox.
Package identity provides unified identity resolution for ox.
kb
Package kb is shared infrastructure for ox's knowledge-base git repos: the per-project ledger and team-context clones.
Package kb is shared infrastructure for ox's knowledge-base git repos: the per-project ledger and team-context clones.
ledger
Package ledger provides functionality for managing project ledgers.
Package ledger provides functionality for managing project ledgers.
ledger/automerge
Package automerge resolves git merge conflicts in tiers.
Package automerge resolves git merge conflicts in tiers.
ledgersearch
Package ledgersearch provides zero-network, local-only full-text search over the cached ledger contents: session summaries/markdown, recent murmurs, and captured plans (data/plans/<dated-slug>/plan.md).
Package ledgersearch provides zero-network, local-only full-text search over the cached ledger contents: session summaries/markdown, recent murmurs, and captured plans (data/plans/<dated-slug>/plan.md).
lfs
Package lfs provides a pure-HTTP client for the Git LFS Batch API.
Package lfs provides a pure-HTTP client for the Git LFS Batch API.
llmprompt
Package llmprompt provides helpers for safely embedding untrusted content inside LLM prompt templates.
Package llmprompt provides helpers for safely embedding untrusted content inside LLM prompt templates.
markers
Package markers holds SageOx repo-marker filenames that must be referenced from packages which cannot import each other without an import cycle.
Package markers holds SageOx repo-marker filenames that must be referenced from packages which cannot import each other without an import cycle.
observability
Package observability provides OpenTelemetry tracing for the ox CLI.
Package observability provides OpenTelemetry tracing for the ox CLI.
paths
Package paths provides centralized path resolution for all SageOx directories.
Package paths provides centralized path resolution for all SageOx directories.
perf
Package perf collects OpenTelemetry spans into an in-process tree so `ox` commands and the daemon can render per-phase timing to a local sink (stderr, daemon log) without needing the OTLP backend.
Package perf collects OpenTelemetry spans into an in-process tree so `ox` commands and the daemon can render per-phase timing to a local sink (stderr, daemon log) without needing the OTLP backend.
plan
Package plan enriches agent-generated implementation plans with SageOx team context.
Package plan enriches agent-generated implementation plans with SageOx team context.
proc
Package proc provides process tree utilities for identifying long-lived ancestor processes (e.g., the agent binary that launched a hook subprocess chain).
Package proc provides process tree utilities for identifying long-lived ancestor processes (e.g., the agent binary that launched a hook subprocess chain).
promptintent
Package promptintent implements lightweight classification of a user's freshly submitted prompt to decide whether it is worth firing a local recall query against the ledger / team-context cache.
Package promptintent implements lightweight classification of a user's freshly submitted prompt to decide whether it is worth firing a local recall query against the ledger / team-context cache.
repotools
Package repotools provides VCS abstraction for repository operations.
Package repotools provides VCS abstraction for repository operations.
runtime
Package runtime probes the *capabilities* of the environment ox is running in — persistent disk, daemon viability, browser availability, network reachability, env lifetime — and exposes them as a single struct.
Package runtime probes the *capabilities* of the environment ox is running in — persistent disk, daemon viability, browser availability, network reachability, env lifetime — and exposes them as a single struct.
session
Package session provides shared entry parsing utilities for session recordings.
Package session provides shared entry parsing utilities for session recordings.
session/cmd/gitleaks-port command
Command gitleaks-port translates the gitleaks default rule catalog (config/gitleaks.toml from the gitleaks repo) into Go SecretPattern entries for ox's session.RawWriter chokepoint.
Command gitleaks-port translates the gitleaks default rule catalog (config/gitleaks.toml from the gitleaks repo) into Go SecretPattern entries for ox's session.RawWriter chokepoint.
session/pipeline
Package pipeline defines types and constants for the session upload pipeline.
Package pipeline defines types and constants for the session upload pipeline.
sessionid
Package sessionid generates and validates session-recording identifiers.
Package sessionid generates and validates session-recording identifiers.
signing
Package signing provides Ed25519 cryptographic signing and verification for embedded artifacts in the ox CLI.
Package signing provides Ed25519 cryptographic signing and verification for embedded artifacts in the ox CLI.
testenv
Package testenv provides shared process-environment isolation for test binaries.
Package testenv provides shared process-environment isolation for test binaries.
testguard
Package testguard provides test isolation primitives that prevent ox subprocesses from hitting production endpoints during tests.
Package testguard provides test isolation primitives that prevent ox subprocesses from hitting production endpoints during tests.
testutil/slogquiet
Package slogquiet silences the default slog logger inside test binaries.
Package slogquiet silences the default slog logger inside test binaries.
tips
internal/tips/content.go
internal/tips/content.go
tui
twinapi
Package twinapi provides a digital twin of the SageOx cloud API for testing.
Package twinapi provides a digital twin of the SageOx cloud API for testing.
ui
uicatalog
Package uicatalog is a runnable registry of reusable UX components in the ox CLI.
Package uicatalog is a runnable registry of reusable UX components in the ox CLI.
uninstall
Package uninstall provides functionality for removing SageOx from repositories.
Package uninstall provides functionality for removing SageOx from repositories.
vtt
whisper/store
Package store provides a SQLite-backed whisper store for the daemon.
Package store provides a SQLite-backed whisper store for the daemon.
pkg
adapterprotocol
Package adapterprotocol defines the wire types for the ox adapter protocol.
Package adapterprotocol defines the wire types for the ox adapter protocol.
adapterruntime
Package adapterruntime is a Go SDK for ox adapter authors.
Package adapterruntime is a Go SDK for ox adapter authors.
discussion
Package discussion defines types for server-generated discussion artifacts.
Package discussion defines types for server-generated discussion artifacts.
faultdaemon
Package faultdaemon provides a generic fault injection daemon for testing IPC.
Package faultdaemon provides a generic fault injection daemon for testing IPC.
ndjson
Package ndjson provides shared NDJSON (newline-delimited JSON) framing utilities for both daemon IPC and adapter serve-mode communication.
Package ndjson provides shared NDJSON (newline-delimited JSON) framing utilities for both daemon IPC and adapter serve-mode communication.
sessionpipeline
Package sessionpipeline defines the shape convention and runner for streaming session transforms in the ox session-stop pipeline.
Package sessionpipeline defines the shape convention and runner for streaming session transforms in the ox session-stop pipeline.
sessionsummary
Package sessionsummary provides shared types, filtering, and prompt logic for AI coworker session summarization.
Package sessionsummary provides shared types, filtering, and prompt logic for AI coworker session summarization.
summaryeval
Package summaryeval is a quality-gate harness for session summaries.
Package summaryeval is a quality-gate harness for session summaries.
tokenopt
Package tokenopt reduces the token footprint of session raw.jsonl streams before they are handed to a summarization LLM.
Package tokenopt reduces the token footprint of session raw.jsonl streams before they are handed to a summarization LLM.
tokenstrip
Package tokenstrip is a streaming, token-aware compaction stage for session raw.jsonl streams.
Package tokenstrip is a streaming, token-aware compaction stage for session raw.jsonl streams.
scripts
sign-manifest command
sign-manifest signs ox artifacts and updates the release-signatures.json file.
sign-manifest signs ox artifacts and updates the release-signatures.json file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL