superopen

module

v0.0.0-...-75696bf Latest Latest Go to latest Published: Oct 13, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ishanjainn/superopen

Links

Open Source Insights

README ¶

Getting started · Install · Docs · Agents · Commands

Superopen is not another coding agent. It builds the open source harness around Claude Code, Cursor, Codex, and similar agents so every coding session improves the next with less token waste and lower cost.

It builds a Tree-sitter graph into SQLite. Agents query a scoped subgraph instead of grepping files. No embeddings, no similarity search, no index to keep warm. The graph is a local so.db your agent reads via so graph query.
Session hooks run in the background so every turn is recorded to .so/sessions/. Follow-ups skip re-exploration because the context is already there.
Distill compresses what mattered into a short index (at most about 350 tokens) so the next session starts with signal, not noise (90.8% / 82% recall@10).
Harvest proposes playbook patches from the session with reusable guidance you apply only when you want it.

In one small SWE-bench Verified run (5 tasks), Claude Code with Superopen used fewer tokens, cost less, and finished faster, with the same number of tasks passed. Results varied by task; this is an early, small-sample benchmark, not a general accuracy claim:

Metric	Cold Claude Code	Claude Code with Superopen	Improvement
Correctness	4 / 5 (80%)	4 / 5 (80%)	Same pass count
Tokens	61.4M	36.9M	40% fewer
Cost	$4.31	$2.70	37% lower
Tool calls	249	161	35% fewer
API requests	254	166	35% fewer
Wall-clock	1,429s	933s	35% faster

Source: BENCHMARKS.md

Getting Started

Full walkthrough: docs/installation.md.

1. Install `so`

macOS

brew install ishanjainn/superopen/so
so install

Linux (curl)

The installer downloads the latest release, puts so on your PATH, and runs so install.

curl -fsSL https://raw.githubusercontent.com/ishanjainn/superopen/main/scripts/install.sh | sh

Open a new terminal if so is not found, or run export PATH="$HOME/.superopen/bin:$PATH".

Windows (PowerShell)

Same installer path as curl, via PowerShell. It places so.exe on your user PATH and runs so install.

iwr -useb https://raw.githubusercontent.com/ishanjainn/superopen/main/scripts/install.ps1 | iex

Open a new PowerShell window after install. In a terminal, run so init with no leading slash. PowerShell treats /so as a path.

2. Initialize the repository

From the repo root, or /so init in agent chat:

so init

That creates .so/ in the repository along with the repository knowledge graph:

.so/
  .gitignore    # sessions/, db/, harvest/ (do not commit)
  sessions/     # session events, transcripts, checkpoints
  db/so.db      # SQLite store: graph + memory

Reopen Claude Code, Cursor, Codex, or any other supported harness and keep working as you were. Superopen automatically tracks sessions and provides local graph and memory tools. In the five-task SWE-bench run above, Claude Code used 40% fewer tokens and passed the same number of tasks as the baseline.

3. Open the UI (optional)

Needs Node.js 20+. -d starts the UI in the background and opens it when ready.

so dev -d

The Problem

Every session, your coding agent starts from zero. It greps, opens files, follows imports, backtracks, tries again, rebuilding a mental map of the codebase it already navigated yesterday and threw away. That rediscovery burns most of a run's tokens, tool calls, and latency, and it is pure overhead:

Repeated: Every task pays the exploration cost again, from scratch.
Discarded: Whatever the agent figured out dies with the session.
Unshared: The next teammate (or your own next session) starts cold too.

Humans onboard to a codebase once. Agents onboard every single time.

See it in action

Run the agent
    ↓
Record the session
    ↓
Answer from the graph
    ↓
Distill what mattered
    ↓
Review harvest
    ↓
Reuse it next time

After so init, agents ask these four surfaces instead of grepping and re-reading transcripts:

$ so graph query "how do session hooks steer Cursor?"
Traversal: BFS depth=2 | Start: [emitSteerContext HookReminder] | 8 nodes
NODE emitSteerContext [qn=internal.agent.hook.emitSteerContext src=internal/agent/hook/steer_context.go loc=L27-82]
EDGE emitSteerContext --CALLS --> steerDecisionFor at=internal/agent/hook/steer_context.go:L28
help[1]:
  so graph snippet internal.agent.hook.emitSteerContext

$ so memory recall "login timeout"
hits: 1  anti_hits: 0  budget: 1500
memories[1]{id,kind,title,tokens}:
  42,knowledge,login timeout is 30s,18
count: 1 of 1
#42  medium  2026-09-07  login timeout is 30s
Login timeout is 30s. Check the gateway before raising it.
help[2]:
  so memory get 42 --full
  so memory timeline --around 42

$ so memory distill --apply sess_abc
applied sess_abc via live written=1 → #42

$ so harvest list
proposals[1]{id,status,kind,target,title,plus,minus}:
  7,open,improve,AGENTS.md,prefer graph query before grep,12,0
count: 1 of 1
help[3]:
  so harvest show <id>
  so harvest apply <id>
  so harvest decline <id>

$ so harvest apply 7
applied #7 improve AGENTS.md

query is the code map. recall is the project diary (cite #id). Distill compresses a finished session into knowledge (--brief then --apply, or [] if nothing durable). Harvest stages a playbook diff until you apply. More: graph, memory, harvest.

Supported agents

so install wires all of these. Hooks only run in repos where you ran so init.

Agent	`--vendor`
Claude Code	`claude-code`
Cursor	`cursor`
Codex	`codex`
Gemini	`gemini`
OpenCode	`opencode`
Copilot	`copilot-cli`
Pi	`pi`
Antigravity	`antigravity`
Cline	`cline`
DeepSeek Harness	`dsh`
Devin	`devin`
Factory Droid	`factory`
Grok	`grok`
Hermes	`hermes`
Kimi Code	`kimi`
Kiro	`kiro`
Muse	`muse`
Oh My Pi	`omp`
OpenClaw	`openclaw`
OpenHands	`openhands`
Prime	`prime`
Qwen Code	`qwen`
Senpi	`senpi`
VS Code	`vscode`

What a session records

Hooks append spans while you work in an inited repo. so sessions turns those into a document with token and cost totals.

Recorded: session start and end, user prompts, assistant turns, tool calls, and file paths on Read, Edit, and Write.

Not recorded as-is: prompt and tool-argument text is redacted. Shell commands are not stamped with a file path. Hooks fail open, so a telemetry error never blocks the agent.

so sessions
so sessions show <id>
so sessions tokens

Prerequisites

Requirement	Minimum	Check	Install
Node.js (for `so dev` only)	20+	`node --version`	nodejs.org

Uninstall

Works from any directory. No source checkout required.

so uninstall                 # agent wiring + project index + marketplace + caches + .so data
# --keep-data                # leave per-repo .so/ in place
# --vendor=cursor            # drop one vendor's hooks only

Then remove the binary the same way you installed it:

How you installed `so`	Remove the binary
Homebrew (macOS / Linux)	`brew uninstall so`
Windows `install.ps1` / curl installer	already gone (`so uninstall` deletes `~/.superopen`)

Restart the coding agent so it drops in-memory hooks.

Learn more

Installation - binary, so install, so init, upgrade, uninstall
Architecture - components, data flow, storage map
Commands - full so CLI reference
Configuration - config file, env vars, flags, paths
Graph - build, query, trace, impact
Sessions - how agent sessions are recorded
Memory - project diary over sessions
Harvest - playbook patches gated on human apply
Scan - detection rules over recorded tool calls
Troubleshooting - install, PATH, hooks, UI, stale graph
Contributing - local build from source

Contributing

Issues and pull requests are welcome. End users install a release binary. To build from a checkout, use the same installer scripts as production: CONTRIBUTING.md.

License

Apache 2.0

Directories ¶

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

Path	Synopsis
cmd
so command
internal
agent
agent/classify Package classify decides whether a coding-agent session is "work" or "personal" based on high-confidence signals only.	Package classify decides whether a coding-agent session is "work" or "personal" based on high-confidence signals only.
agent/config Package config resolves the CLI's runtime configuration from (in order):	Package config resolves the CLI's runtime configuration from (in order):
agent/detect Package detect contains tiny, dependency-free string helpers the per-vendor hook adapters use to recognise high-signal patterns in shell commands and code patches:	Package detect contains tiny, dependency-free string helpers the per-vendor hook adapters use to recognise high-signal patterns in shell commands and code patches:
agent/export Package export wraps local OTel span generation for the CLI's hot path.	Package export wraps local OTel span generation for the CLI's hot path.
agent/git Package git collects the minimal VCS context every hook adapter stamps on its spans (vcs.repository.url.full, vcs.ref.head.revision, vcs.ref.head.name, coding_agent.vcs.dirty).	Package git collects the minimal VCS context every hook adapter stamps on its spans (vcs.repository.url.full, vcs.ref.head.revision, vcs.ref.head.name, coding_agent.vcs.dirty).
agent/headless Package headless probes authenticated coding-agent CLIs for one-shot session distill and harvest.	Package headless probes authenticated coding-agent CLIs for one-shot session distill and harvest.
agent/hook Package hook implements `so sessions hook --vendor=...	Package hook implements `so sessions hook --vendor=...
agent/hook/claudecode Package claudecode implements the Claude Code hook adapter.	Package claudecode implements the Claude Code hook adapter.
agent/hook/codex Package codex implements the Codex CLI hook adapter.	Package codex implements the Codex CLI hook adapter.
agent/hook/cursor Package cursor implements the Cursor hook adapter.	Package cursor implements the Cursor hook adapter.
agent/hook/generic Package generic provides a minimal hook adapter for coding agents that do not have a dedicated adapter (Gemini CLI, Copilot CLI, and any unknown --vendor).	Package generic provides a minimal hook adapter for coding agents that do not have a dedicated adapter (Gemini CLI, Copilot CLI, and any unknown --vendor).
agent/hook/opencode Package opencode implements the OpenCode coding-agent hook adapter.	Package opencode implements the OpenCode coding-agent hook adapter.
agent/hook/pi Package pi implements the Pi coding-agent hook adapter.	Package pi implements the Pi coding-agent hook adapter.
agent/identity Package identity resolves the canonical user identity to stamp on every emitted span.	Package identity resolves the canonical user identity to stamp on every emitted span.
agent/install Package install implements per-vendor host plugin manifest writes for `so install --vendor=...`.	Package install implements per-vendor host plugin manifest writes for `so install --vendor=...`.
agent/install/hooks
agent/install/hooks/assets/cline
agent/install/hooks/assets/omo
agent/install/hooks/assets/omp
agent/install/hooks/assets/openclaw
agent/install/hooks/assets/prime
agent/install/hooks/testenv
agent/normalize Package normalize defines the contract every per-vendor hook adapter implements, plus the canonical Span/Event types they emit.	Package normalize defines the contract every per-vendor hook adapter implements, plus the canonical Span/Event types they emit.
agent/pricing Package pricing returns realized USD cost from token counts using a small static table of public list prices.	Package pricing returns realized USD cost from token counts using a small static table of public list prices.
agent/sessionstate Package sessionstate persists tiny per-session facts that the CLI needs to remember across hook invocations.	Package sessionstate persists tiny per-session facts that the CLI needs to remember across hook invocations.
agent/skills Package skills installs the user-global /so skill into coding-agent skill dirs.	Package skills installs the user-global /so skill into coding-agent skill dirs.
agent/steer Package steer installs user-level graph-first durable context and produces compact hook reminders for coding agents.	Package steer installs user-level graph-first durable context and produces compact hook reminders for coding agents.
agent/tailfile Package tailfile reads the last N bytes of a file as a slice of JSONL lines, dropping a partial first line.	Package tailfile reads the last N bytes of a file as a slice of JSONL lines, dropping a partial first line.
agent/uninstall Package uninstall implements per-vendor hook teardown for `so uninstall --vendor=...`.	Package uninstall implements per-vendor hook teardown for `so uninstall --vendor=...`.
agent/vendors Package vendors lists coding agents whose hooks Superopen installs in addition to Claude Code, Cursor, Codex, Gemini, OpenCode, Copilot CLI, and Pi.	Package vendors lists coding agents whose hooks Superopen installs in addition to Claude Code, Cursor, Codex, Gemini, OpenCode, Copilot CLI, and Pi.
artifact Package artifactmeta keeps every Superopen-owned artifact self-describing.	Package artifactmeta keeps every Superopen-owned artifact self-describing.
checkpoint Package checkpoint stores restorable file snapshots for a session under .so/sessions/<id>/checkpoints/<n>/.	Package checkpoint stores restorable file snapshots for a session under .so/sessions/<id>/checkpoints/<n>/.
cli Package cli implements shared CLI output helpers for Superopen.	Package cli implements shared CLI output helpers for Superopen.
graph/api Package api defines the native graph protocol used by `so`.	Package api defines the native graph protocol used by `so`.
graph/buildpool Package buildpool caps concurrent graph builds across repositories.	Package buildpool caps concurrent graph builds across repositories.
graph/client Package client is the in-process native graph client used by `so`.	Package client is the in-process native graph client used by `so`.
graph/engine
graph/engine/cpreproc Package cpreproc expands C/C++/CUDA macros with vendored simplecpp.	Package cpreproc expands C/C++/CUDA macros with vendored simplecpp.
graph/engine/cypher
graph/engine/tsnative
graph/format Package format renders compact agent-facing text views of graph API results.	Package format renders compact agent-facing text views of graph API results.
graph/langspec Package langspec holds Superopen language extraction specifications.	Package langspec holds Superopen language extraction specifications.
graph/leiden
graph/watch
guards The hook client consults an external provider named by SO_GUARD_PROVIDER for an allow/deny decision on an imminent tool call.	The hook client consults an external provider named by SO_GUARD_PROVIDER for an allow/deny decision on an imminent tool call.
guards/rules Package rules loads the detection corpus.	Package rules loads the detection corpus.
harvest
memory
paths Package userpaths resolves Superopen config and data directories on macOS, Linux, and Windows (XDG / %APPDATA% / %LOCALAPPDATA%).	Package userpaths resolves Superopen config and data directories on macOS, Linux, and Windows (XDG / %APPDATA% / %LOCALAPPDATA%).
projects Package projects maintains a global registry of Superopen roots so one UI/CLI can browse sessions across multiple local clones.	Package projects maintains a global registry of Superopen roots so one UI/CLI can browse sessions across multiple local clones.
redact Package redact strips obvious secrets from strings before they're emitted as OTel attributes.	Package redact strips obvious secrets from strings before they're emitted as OTel attributes.
repofile Package repofile is the shared choke point for coding-agent file identity.	Package repofile is the shared choke point for coding-agent file identity.
retention
scope
session Package otlp contains OpenTelemetry attribute normalization shared by session ingestion and vendor hooks.	Package otlp contains OpenTelemetry attribute normalization shared by session ingestion and vendor hooks.
session/agentlinks Package agentlinks persists child-agent → parent-session mappings so Task / subagent traffic does not appear as top-level Sessions rows.	Package agentlinks persists child-agent → parent-session mappings so Task / subagent traffic does not appear as top-level Sessions rows.
session/replay Package viz builds session map replay traces from local session telemetry.	Package viz builds session map replay traces from local session telemetry.
session/trace
version Package version exposes the CLI build version and a `version` subcommand.	Package version exposes the CLI build version and a `version` subcommand.
sdk
go module
tools
graph-assets command Command graph-assets reproducibly compiles the pinned generated Tree-sitter grammars into combined WASI parser modules.	Command graph-assets reproducibly compiles the pinned generated Tree-sitter grammars into combined WASI parser modules.
graph-model-assets command Command graph-model-assets installs the pinned, content-verified semantic model into internal/graph/engine/assets/model.	Command graph-model-assets installs the pinned, content-verified semantic model into internal/graph/engine/assets/model.
graph-specs command Command graph-specs validates Superopen language extraction specs JSON and optionally regenerates a checked-in copy.	Command graph-specs validates Superopen language extraction specs JSON and optionally regenerates a checked-in copy.