{"id":50938009,"url":"https://github.com/bcorfman/codex-history-archiver","last_synced_at":"2026-06-17T11:03:36.911Z","repository":{"id":364799626,"uuid":"1269196888","full_name":"bcorfman/codex-history-archiver","owner":"bcorfman","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-14T15:49:31.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T16:25:28.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bcorfman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":null,"dco":null,"cla":null}},"created_at":"2026-06-14T12:22:58.000Z","updated_at":"2026-06-14T15:49:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bcorfman/codex-history-archiver","commit_stats":null,"previous_names":["bcorfman/codex-history-archiver"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bcorfman/codex-history-archiver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fcodex-history-archiver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fcodex-history-archiver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fcodex-history-archiver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fcodex-history-archiver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcorfman","download_url":"https://codeload.github.com/bcorfman/codex-history-archiver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fcodex-history-archiver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34445186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-17T11:03:25.142Z","updated_at":"2026-06-17T11:03:36.904Z","avatar_url":"https://github.com/bcorfman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex History Archiver\n\nA safe, private, searchable local archive for every Codex conversation.\n\nCodex History Archiver automatically exports each Codex conversation at the end\nof every turn, creating durable per-project HTML history outside the built-in\nVS Code sidebar.\n\nBuilt for the real workflow:\n\n- automatic export after every Codex interaction\n- strong WSL2 + VS Code + Codex support\n- clean HTML session pages plus a per-project index\n- archive storage that stays outside your public repo\n\nIt uses the official Codex `Stop` hook, so the archive stays up to date with\nminimal setup and minimal risk of losing useful conversation history.\n\nPrimary target:\n\n- WSL2 + VS Code + Codex\n\nAlso intended to work with:\n\n- generic Ubuntu/Linux setups\n- native Windows setups\n\nThis tool is specifically meant to work with the Codex VS Code extension. It\nuses the same `~/.codex/config.toml` hook surface that Codex documents for the\nIDE extension, app, and CLI.\n\nThe archiver keeps:\n\n- a session HTML export per conversation\n- a per-project HTML index\n\nIt is designed for people who want project chat history preserved outside the\nVS Code sidebar, with a durable archive they control.\n\n## How It Works\n\nCodex fires a `Stop` hook at the end of a turn. The hook payload includes a\n`transcript_path`, `cwd`, `session_id`, and `turn_id`.\n\nThis project uses that event to:\n\n1. determine the project root from the current working directory\n2. regenerate an HTML export for that session\n3. regenerate a per-project session index\n\n## Export Backends\n\nHTML is the only archived artifact.\n\nHTML export defaults to the builtin conversation renderer, with optional\nPATH-based backend overrides if you want a different renderer.\n\nSupported HTML backend values:\n\n- `builtin`\n- `codex-transcript-viewer`\n- `codex-transcripts`\n\nSet the default backend at install time with:\n\n```bash\nuvx --from git+https://github.com/bcorfman/codex-history-archiver \\\n  codex-history-install-hook \\\n  --config ~/.codex/config.toml \\\n  --archive-root /mnt/c/Users/your-user/codex-history-archive \\\n  --html-backend builtin\n```\n\nIf you do not pass `--html-backend`, the builtin renderer is used. If a\nrequested external backend is not installed on `PATH`, the tool falls back\nautomatically to the builtin HTML export.\n\n### Command Override\n\nIf you prefer to run an external exporter through a wrapper command instead of a\nplain executable on `PATH`, set:\n\n```bash\nexport CODEX_HISTORY_HTML_BACKEND_CMD='uvx --from git+https://github.com/masonc15/codex-transcript-viewer codex-transcript-viewer {input} {output}'\n```\n\nThe archiver will use that command first for HTML export and substitute:\n\n- `{input}` for the transcript path\n- `{output}` for the output HTML path\n- `{output_dir}` for a temporary output directory\n\nWhen `CODEX_HISTORY_HTML_BACKEND_CMD` is set, it takes precedence over the\nnamed backend selection.\n\n## Archive Layout\n\nThe archive location is normally written directly into the managed Codex hook by\nthe installer.\n\nInside that root, archives are written like this:\n\n```text\nprojects/\u003cproject-slug\u003e/\n  index.html\n  sessions/\n    \u003csession-id\u003e.html\n```\n\n## Configure A Private Archive Directory\n\nChoose a private archive location outside the repo, for example:\n\n```text\n/mnt/c/Users/your-user/codex-history-archive\n```\n\nPass that path to the installer with `--archive-root`. The managed hook then\nkeeps using that path without depending on shell startup files or inherited\nenvironment variables.\n\nOptional overrides:\n\n- `CODEX_HISTORY_ARCHIVE_ROOT`\n  If set, overrides the archive directory embedded in the hook command.\n- `CODEX_HISTORY_HTML_BACKEND`\n  If set, overrides the backend embedded in the hook command.\n\nEnvironment variables still work well for temporary overrides, but they are no\nlonger the recommended primary configuration mechanism.\n\n## Install\n\nInstall the managed Codex hook directly from GitHub with `uvx`:\n\n```bash\nuvx --from git+https://github.com/bcorfman/codex-history-archiver \\\n  codex-history-install-hook \\\n  --config ~/.codex/config.toml \\\n  --archive-root /mnt/c/Users/your-user/codex-history-archive \\\n  --html-backend builtin\n```\n\nThis appends or updates a managed hook block in `~/.codex/config.toml`.\n\n- On WSL2/Linux, the installed hook runs through `uvx` via `bash -lc`.\n- On Windows, the installed hook uses a Windows command entry in the same\n  managed block.\n- The archive root and backend are written directly into the hook command, so\n  the default install does not depend on login-shell environment propagation.\n\n### WSL2 Example\n\n```bash\nuvx --from git+https://github.com/bcorfman/codex-history-archiver \\\n  codex-history-install-hook \\\n  --config ~/.codex/config.toml \\\n  --archive-root /mnt/c/Users/your-user/codex-history-archive \\\n  --html-backend builtin\n```\n\nRestart VS Code after installing so the Codex extension picks up the updated\nhook config.\n\n### Native Windows Example\n\n```powershell\nuvx --from git+https://github.com/bcorfman/codex-history-archiver `\n  codex-history-install-hook `\n  --config $HOME\\.codex\\config.toml `\n  --archive-root C:\\Users\\your-user\\codex-history-archive `\n  --html-backend builtin\n```\n\nRestart VS Code after installing so the Codex extension picks up the updated\nhook config.\n\n### Local Checkout Alternative\n\nIf you are developing locally and want the hook to point at the checkout instead\nof `uvx`, run:\n\n```bash\npython3 bin/install-hook.py \\\n  --config ~/.codex/config.toml \\\n  --archive-root /mnt/c/Users/your-user/codex-history-archive \\\n  --html-backend builtin \\\n  --launcher local\n```\n\n## Verify\n\nAfter installation, finish a Codex turn in VS Code and check:\n\n```bash\nfind /mnt/c/Users/your-user/codex-history-archive -maxdepth 4 -type f | sort\n```\n\n## Backfill Existing Sessions\n\nTo archive the Codex transcripts you already have on disk:\n\n```bash\nuvx --from git+https://github.com/bcorfman/codex-history-archiver \\\n  codex-history-backfill \\\n  --archive-root /mnt/c/Users/your-user/codex-history-archive\n```\n\n## Privacy Model\n\n- The repo is safe to publish publicly.\n- Transcript exports are written only to the private archive directory you\n  choose at install time, unless you deliberately override it.\n- No transcript data is stored inside the tool repo unless you do that\n  deliberately yourself.\n\n## Related Tools\n\nThis project is intentionally small and focused on automatic incremental\narchiving from the Codex hook system.\n\nIf you want richer browsing or standalone export tools, these are worth a look:\n\n- `agent-trace`\n  Terminal UI for browsing and exporting local session histories.\n- `CodexMonitor`\n  Session inspection and monitoring tools, including VS Code extension session\n  support.\n- `codex-trace-viewer`\n  Local trace viewer focused on inspecting session internals.\n- `codex-transcript-viewer`\n  Single-session HTML viewer with sidebar filters such as `No tools`,\n  `User only`, `Answers`, and `All`.\n- `codex-transcripts`\n  More capable HTML/TUI/export tool with picker flows, multi-select archives,\n  `--cwd` filtering, and one-off `uvx` usage.\n\n## Why This Exists\n\nThis repo stays intentionally narrow: reliable automatic archiving for Codex in\nthe workflow many people actually use, especially VS Code on WSL2.\n\nThe builtin renderer is the recommended default because it groups each user\nprompt with the related Codex commentary and final answer, while keeping tool\nactivity collapsed into optional details.\n\n## Notes\n\n- The private archive keeps HTML only.\n- The HTML exporter choice determines how much tool/system detail is visible.\n- The VS Code UI may still show only a recent subset of threads, but the full\n  archived session set remains available on disk.\n\n## Troubleshooting\n\n### Archive files are not being written where you expect\n\nSymptoms:\n\n- no archive files are written\n- files are written to an old archive path\n- the hook returns a message saying the archive root is not set\n\nChecks:\n\n- inspect the managed hook block in `~/.codex/config.toml`\n- confirm the `--archive-root` value is the path you meant to install\n- if you are using env var overrides, verify them explicitly\n\nOn WSL2/Linux:\n\n```bash\nbash -lc 'echo \"$CODEX_HISTORY_ARCHIVE_ROOT\"'\n```\n\nOn Windows:\n\n```powershell\n$env:CODEX_HISTORY_ARCHIVE_ROOT\n```\n\nFix:\n\n- reinstall the hook with the archive path you actually want\n- restart VS Code completely after reinstalling\n- remove `CODEX_HISTORY_ARCHIVE_ROOT` if an old override is shadowing the hook\n  config\n\n### Hook is installed but does not seem to fire\n\nChecks:\n\n- confirm the hook block exists in `~/.codex/config.toml`\n- confirm the repo/project is trusted in Codex\n- finish a full Codex turn in the VS Code extension, then inspect the archive\n  root\n\nReinstall:\n\n```bash\nuvx --from git+https://github.com/bcorfman/codex-history-archiver \\\n  codex-history-install-hook \\\n  --config ~/.codex/config.toml \\\n  --archive-root /mnt/c/Users/your-user/codex-history-archive \\\n  --html-backend builtin\n```\n\nWindows:\n\n```powershell\nuvx --from git+https://github.com/bcorfman/codex-history-archiver `\n  codex-history-install-hook `\n  --config $HOME\\.codex\\config.toml `\n  --archive-root C:\\Users\\your-user\\codex-history-archive `\n  --html-backend builtin\n```\n\n### Archive files appear under the wrong project slug\n\nThe tool uses `git rev-parse --show-toplevel` when available and falls back to\nthe current working directory otherwise.\n\nChecks:\n\n- verify the Codex session is actually running in the repo you expect\n- verify that repo is a real Git checkout\n- open the session HTML and inspect the embedded archive metadata block in page\n  source if you need to confirm the stored `cwd`\n\nIf needed, you can still find the transcript by session ID in the archive even\nif the project slug is not what you expected.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcorfman%2Fcodex-history-archiver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcorfman%2Fcodex-history-archiver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcorfman%2Fcodex-history-archiver/lists"}