Content
# Codex History Hub
[English](README.en.md)
Local-first, read-only Codex session aggregator. Indexes one or more `CODEX_HOME` into a standalone SQLite database, and provides cross-project, archived, and sub-agent history queries via local web and MCP.
> Currently in alpha. Please read [Privacy and Security](#privacy-and-security) before uploading Hub database or real session files.
## Capabilities and Limitations
- Indexes `state_5.sqlite` as threads, and incrementally reads `sessions/` and `archived_sessions/` by `rollout_path`.
- Covers main sessions, archived sessions, sub-agents, user/assistant messages, and tool events.
- Provides local read-only web and 5 MCP tools for recent context, search, thread reading, and project overview.
- Does not read `auth.json`, Cookies, API Keys, or `logs_2.sqlite`, and does not modify Codex original databases, JSONL, or sidebars.
- Does not merge or overwrite Codex native account session libraries; all indexes and long-term summaries are written to Hub's own database.
## Installation
Requires Python 3.10 or later, with no third-party runtime dependencies.
```powershell
git clone <YOUR_REPOSITORY_URL>
cd codex-history-hub
python -m venv .venv
.\.venv\Scripts\python -m pip install -e .
```
Register current Windows user's Codex Home:
```powershell
codex-history-hub --db data/history-hub.db add-source `
--name local-codex `
--path "$env:USERPROFILE\.codex"
codex-history-hub --db data/history-hub.db sync
codex-history-hub --db data/history-hub.db status
```
macOS/Linux users can use `${CODEX_HOME:-$HOME/.codex}` as the path. Another independent `CODEX_HOME` can be registered with a different `--name`. Legacy pure JSONL directories can be registered with `--type jsonl`.
Database location can also be set via environment variable:
```powershell
$env:HISTORY_HUB_DB = "D:\private\codex-history\history-hub.db"
codex-history-hub status
```
## Local Web
Windows users can double-click `open-history-hub.cmd`. Alternatively, run:
```powershell
codex-history-hub --db data/history-hub.db serve
```
Then access `http://127.0.0.1:8765`. The service performs an initial sync, and then increments every 30 seconds by default. The page includes main sessions, sub-agents, archives, sources, model providers, projects, and keyword filters, with tool events collapsed by default.
The web is only bound to `localhost`, `127.0.0.1`, or `::1`. The project does not have a remote authentication mechanism, so it rejects `0.0.0.0` and other non-loopback addresses.
## Global MCP Configuration
Add the following configuration to the user-level Codex `config.toml`. All paths should be replaced with actual absolute paths on the machine; it is recommended to use the virtual environment's Python directly to avoid dependencies on the current working directory or system PATH.
```toml
[mcp_servers.history_hub]
command = "D:\\path\\to\\codex-history-hub\\.venv\\Scripts\\python.exe"
args = [
"-m", "history_hub",
"--db", "D:\\private\\codex-history\\history-hub.db",
"mcp"
]
```
After restarting Codex or starting a new task, you can call:
- `history_get_recent_context`: Project overview and recent 3 main sessions; sub-agents are excluded by default.
- `history_search`: Search all sessions, including archives and sub-agents.
- `history_get_thread`: Read the selected thread on demand; tool outputs are excluded by default.
- `history_get_project_summary`: Read the long-term project overview.
- `history_update_project_summary`: Update the project overview only in the Hub database.
Incremental sync is performed before each MCP tool call, so the web does not need to be constantly open.
## Privacy and Security
The Hub performs de-identification of common API Keys, access tokens, private keys, JWTs, email addresses, and user home directory paths when writing and outputting. Web/MCP outputs also remove source root directories, rollout file paths, and Git URLs that may contain credentials. Upgraded databases perform a one-time de-identification migration within the Hub; original Codex files remain unchanged.
These rules cannot identify all personally identifiable information in natural language. Please follow these guidelines:
- `data/`, `*.db`, SQLite sidecars, and logs are excluded by `.gitignore` and should never be committed.
- The Hub database still contains complete chat content and local source paths required for incremental sync; it should be treated as sensitive.
- Share screenshots, export results, or databases only after manual review.
- Do not expose the local web directly through port forwarding, proxy, or public network addresses.
- Report security issues privately according to [SECURITY.md](SECURITY.md), and do not paste real sessions or credentials in issues.
## Development and Validation
```powershell
python -m compileall -q history_hub tests
python -m unittest discover -s tests -v
```
CI performs installation, compilation, and all tests on Windows and Ubuntu, with Python 3.10 and 3.13. Contribution requirements and privacy testing specifications are in [CONTRIBUTING.md](CONTRIBUTING.md).
## License
This project is licensed under the [MIT License](LICENSE). The version follows semantic versioning, and this security and generalization upgrade is `0.3.0`.
