{"id":50100822,"url":"https://github.com/hop-top/usp","last_synced_at":"2026-05-23T07:15:56.575Z","repository":{"id":358579366,"uuid":"1205548090","full_name":"hop-top/usp","owner":"hop-top","description":"Browse, fork or resume any coding session across any AI assistant. One command.","archived":false,"fork":false,"pushed_at":"2026-05-18T02:28:03.000Z","size":468,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T04:43:12.027Z","etag":null,"topics":["ai-session","ai-session-logs","ai-sessions","cross-agency","cross-agent","cross-agent-memory","cross-agent-review","cross-ai-collaboration","interoperable-ai-agents"],"latest_commit_sha":null,"homepage":"https://hop.top/usp","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hop-top.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-09T04:06:45.000Z","updated_at":"2026-05-18T02:27:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hop-top/usp","commit_stats":null,"previous_names":["hop-top/usp"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/hop-top/usp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fusp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fusp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fusp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fusp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hop-top","download_url":"https://codeload.github.com/hop-top/usp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fusp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33386349,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-session","ai-session-logs","ai-sessions","cross-agency","cross-agent","cross-agent-memory","cross-agent-review","cross-ai-collaboration","interoperable-ai-agents"],"created_at":"2026-05-23T07:15:55.868Z","updated_at":"2026-05-23T07:15:56.565Z","avatar_url":"https://github.com/hop-top.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# USP — Universal Sessions Protocol\n\n[![Release](https://img.shields.io/github/v/release/hop-top/usp?include_prereleases\u0026sort=semver)](https://github.com/hop-top/usp/releases)\n[![CI](https://github.com/hop-top/usp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/hop-top/usp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nFind any coding session across any AI assistant. One command.\n\n## Jobs this solves\n\n**\"Which tool did I use for that auth fix last Tuesday?\"**\nYou switch between Claude, Gemini, Codex, OpenCode. Each\nburies sessions in different formats, different paths. USP\nreads all of them, gives you one sorted list — and can\nresume where you left off in any other tool.\n\n**\"I need to replay what happened in that failed refactor.\"**\n`usp session show \u003cid\u003e` — metadata, turns, tool calls.\nWorks regardless of which CLI created the session.\n\n**\"I'm building a devtool that needs session data.\"**\nUSP normalizes every CLI's native format into one envelope.\nImplement one interface, get detection + diagnostics free.\n\n**\"New dev joining — which sessions touched this project?\"**\n`usp session list --project .` — every assistant's sessions\nfor this directory, newest first.\n\n**\"I want my session history queryable as part of my knowledge\ngraph.\"**\nUSP ships a companion bridge, `usp-ctxt`, that walks every\ndetected CLI's session list and projects each session into a\n[ctxt](https://github.com/jadb/ContextHelp) knowledge object.\nOnce bridged, your sessions are searchable next to your notes,\ndocuments, and other captured context — and they participate in\nctxt's entity graph via stable mentions like\n`@usp.session.\u003cuuid\u003e`, `@cli.\u003cname\u003e`, and `@agent.\u003cid\u003e`.\n\n## The ctxt bridge\n\n`usp-ctxt sync` is a separate binary in this repo\n([cmd/usp-ctxt/](cmd/usp-ctxt/)). It's idempotent: re-running\nover the same session updates the matching ctxt entity rather\nthan creating duplicates, and a high-water-mark file at\n`~/.local/share/usp-ctxt/last_run.json` tracks per-CLI\nprogress so subsequent runs only ingest new sessions.\n\n```sh\ngo install hop.top/usp/cmd/usp-ctxt@latest\n\nusp-ctxt sync                        # walk all CLIs since last run\nusp-ctxt sync --cli claude          # only Claude Code sessions\nusp-ctxt sync --project ~/code/myapp # only sessions in this project\nusp-ctxt sync --dry-run              # project + log; do not write\n```\n\nRun it on cron, after each work block, or whenever you want\nyour session history reflected in ctxt. The full ingestion +\nretrieval design — including the live-capture path that runs\non top of UHP, and the three retrieval shapes built on the\ncombined data — lives in §4 of the spec at\n\u003chttps://github.com/hop-top/hop/blob/main/docs/ingestion-retrieval/spec.md\u003e.\n\n## The killer feature: cross-CLI resume\n\nStart in one assistant, continue in another. Full context\ncarries over — no copy-paste, no re-explaining.\n\n```sh\n# Start a session in Claude\nclaude\n# ... work on auth feature, exit\n\n# Resume the same conversation in Codex\nusp resume --cli codex\n# Codex picks up with full conversation context\n\n# Resume again in Gemini\nusp resume --cli gemini\n# Gemini continues where Codex left off\n\n# See the full lineage\nusp session lineage \u003cid\u003e\n```\n\nSample lineage output:\n\n```\nSession: a1b2c3d4-e5f6-7890-abcd-ef1234567890\nProject: ~/projects/myapp\n\n  #  CLI       Native ID     Started              Turns\n  1  claude    fe2eb947-ec…  2026-04-10 04:40:25  142\n  2  codex     019d70b5-83…  2026-04-10 05:10:00   38\n  3  gemini    usp-resume-…  2026-04-10 05:30:00   12\n\nTotal: 192 turns across 3 CLIs\n```\n\n## Signals\n\nUSP lifts four signal classes off raw transcripts into the\nnormalized envelope, then surfaces them through `usp-ctxt` so\nctxt indexes can search by file, intent, model, and cost.\n\n| Signal | Source | Emitted as | Consumer |\n|---|---|---|---|\n| File touched | tool calls (Read/Edit/Write/MultiEdit/NotebookEdit/Glob/Grep + codex `apply_patch` / `shell` cwd) | `@file.\u003cslug\u003e` mention (writes sort first; capped) | `ctxt find \"@file.x\"` |\n| Intent | `Turn.Subtype=\"slash-command\"` rendered as `/\u003cname\u003e` | `## Intents` body section | session search; future agents view |\n| Model | claude / codex `turn_context` / gemini event header / opencode `modelID` | `@model.\u003cslug\u003e` mention | `ctxt find \"@model.claude-opus-4-7\"` |\n| Tokens | claude `message.usage` (input/output/cache_read/cache_write) | `Session.Metadata[\"usage.tokens.*\"]` + `#tokens:small\\|med\\|large` hint | dashboards; cost reports |\n| Cost | claude pricing table × tokens | `Session.Metadata[\"usage.cost_usd\"]` + `#cost:low\\|med\\|high` hint | `ctxt find \"#cost:high\"` |\n| Duration | `EndedAt - StartedAt` | `Session.Metadata[\"performance.duration_ms\"]` | telemetry section |\n| CLI version | claude `version` / codex `meta.payload.cli_version` | `Session.Metadata[\"cli_version\"]` | debugging adapter quirks |\n| Sub-agent | claude `isSidechain:true` + `parentToolUseID` | `Turn.Subtype=\"sidechain\"`, ordered after parent Task tool_use | agents view (T-0071) |\n\nAdapters populate any subset the source provides; missing keys\nremain absent (no zero values written). See\n[`session/envelope.go`](session/envelope.go) for the full key\nnamespace registry, and\n[`internal/uspctxt/projection.go`](internal/uspctxt/projection.go)\nfor the mention/hint vocabulary emitted into ctxt.\n\n## Install\n\n| Platform | Command |\n|---|---|\n| macOS / Linux | `brew install hop-top/tap/usp` |\n| Windows | `scoop bucket add hop-top https://github.com/hop-top/scoop-bucket \u0026\u0026 scoop install usp` |\n| Any with Go ≥ 1.26 | `go install hop.top/usp/cmd/usp@latest` |\n| Pre-built binary | Download from [Releases](https://github.com/hop-top/usp/releases/latest) |\n\nThe `usp-ctxt` bridge (see [The ctxt bridge](#the-ctxt-bridge) above)\ninstalls alongside `usp` in the Homebrew + Scoop paths. For the\nGo path, install it separately:\n`go install hop.top/usp/cmd/usp-ctxt@latest`.\n\n## Quickstart\n\n```sh\nusp doctor               # what's installed, what's readable\nusp setup                # index detected CLIs\nusp session list         # all sessions, all CLIs, sorted\nusp session show \u003cid\u003e    # full session detail\nusp session show \u003cid\u003e --skills  # detail + skill invocations\nusp session search auth  # find sessions mentioning \"auth\"\nusp session skills --name review  # every session that fired the review skill\nusp session tools --category edit # tool calls grouped by universal taxonomy\n\nusp resume --cli codex        # resume last session in Codex\nusp session lineage \u003cid\u003e      # cross-CLI conversation history\n```\n\nSee [docs/architecture/session-introspection.md](docs/architecture/session-introspection.md)\nfor the `session skills` data model + adapter contract.\n\n### Flags\n\n```sh\n--cli claude            # narrow to one assistant\n--project /path/to/x     # explicit working directory\n--since 7d               # sessions from the last 7 days\n--limit 10               # cap results\n--format json            # json | yaml | table\n```\n\n## Sample output\n\n### `usp session list --since 2d`\n\nIDs are TypeIDs (`sess_…`) — type-safe, prefixed, k-sortable.\nNative CLI session ids (UUIDs, `ses_…` for OpenCode) still work\nanywhere a session id is expected. JSON output includes both via\n`id` and `native_id`.\n\n```\nID                CLI     PROJECT                    STARTED  TURNS\nsess_01h455vb4p…  claude  ~/projects/tlc             1h ago   32\nsess_01h455w8ke…  claude  ~/projects/uhp             1h ago   499\nsess_01h455yn3a…  claude  ~/projects/kit             1h ago   292\nsess_01h456b2qx…  claude  ~/projects/usp             2h ago   649\nsess_01h457dvkm…  claude  ~/projects/tep             4h ago   95\n```\n\n### `usp session show sess_01h455vb4p…`\n\nEither form resolves the same session:\n\n```sh\nusp session show sess_01h455vb4pex5vsknk084sn02q  # TypeID\nusp session show fe2eb947-eca…                    # native UUID prefix\n```\n\n```\nID:        sess_01h455vb4pex5vsknk084sn02q\nNativeID:  fe2eb947-ecab-4293-a26c-3485062e8e6a\nCLI:       claude\nProject:   ~/projects/tlc\nStarted:   2026-04-10 04:40:25\nEnded:     2026-04-10 05:08:20\nTurns:     142\n\nTurn 1 [system] 2026-04-10 04:40:25\n\nTurn 2 [user] 2026-04-10 04:40:26\n  ❯ tlc init libc_darwin.go:224: ...\n\nTurn 3 [assistant] 2026-04-10 04:40:29\n  That looks like a panic or crash in `tlc init`. Let me...\n  Tool calls: Bash\n\nTurn 4 [assistant] 2026-04-10 04:40:30\n  Tool calls: Bash\n```\n\n## Supported CLIs\n\n| CLI | Store format | Status |\n|-----|-------------|--------|\n| Claude Code | JSONL per-session | v1 |\n| Codex CLI | date-partitioned JSONL | v1 |\n| Gemini CLI | JSON snapshots | v1 |\n| OpenCode | 12-table SQLite | v1 |\n| Copilot CLI | normalized SQLite | planned |\n| Kimi Code | dual JSONL + metadata index | planned |\n| Amp | server-side API | planned |\n| Cursor Agent | SQLite CAS (metadata-only) | planned |\n| Qwen, Vibe, Antigravity, Windsurf, Tabnine | various | planned |\n\n## For devtool authors\n\nEvery session becomes:\n\n```go\ntype Session struct {\n    ID         string\n    CLI        string        // \"claude\", \"codex\", ...\n    ProjectCwd string\n    StartedAt  time.Time\n    EndedAt    *time.Time\n    TurnCount  int\n    Metadata   map[string]any\n}\n```\n\nAdd your CLI: implement `SessionAdapter` (detection, list,\nget, stream turns). Shared infra handles the rest — registry,\nproject key derivation, doctor checks.\n\nAdapters are thin: 250-600 LOC each. See\n[docs/architecture.md](docs/architecture.md) for the contract\nand data flow.\n\n## Project docs\n\n- [AGENTS.md](AGENTS.md) — what an agent needs to know to use `usp`.\n- [CHANGELOG.md](CHANGELOG.md) — release history.\n- [docs/usp/api-cli.md](docs/usp/api-cli.md) — full subcommand reference.\n- [docs/usp/configuration.md](docs/usp/configuration.md) — config keys\n  and env vars.\n- [docs/architecture.md](docs/architecture.md) — internal layout.\n\n## Status\n\nAlpha. Envelope schema may change before the first stable release.\nSee [CHANGELOG.md](CHANGELOG.md) for what's landed and\n[releases](https://github.com/hop-top/usp/releases) for the\nlatest tag.\n\n## License\n\n[MIT](LICENSE). Contributions welcome — see\n[CONTRIBUTING.md](CONTRIBUTING.md) and\n[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). For security\ndisclosures, see [SECURITY.md](SECURITY.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhop-top%2Fusp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhop-top%2Fusp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhop-top%2Fusp/lists"}