agent-chat-reader 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_chat_reader-0.1.0/.github/PULL_REQUEST_TEMPLATE.md +33 -0
- agent_chat_reader-0.1.0/.github/workflows/ci.yml +137 -0
- agent_chat_reader-0.1.0/.github/workflows/release.yml +36 -0
- agent_chat_reader-0.1.0/.gitignore +27 -0
- agent_chat_reader-0.1.0/.pre-commit-config.yaml +39 -0
- agent_chat_reader-0.1.0/.python-version +1 -0
- agent_chat_reader-0.1.0/AGENTS.md +22 -0
- agent_chat_reader-0.1.0/LICENSE +21 -0
- agent_chat_reader-0.1.0/PKG-INFO +109 -0
- agent_chat_reader-0.1.0/README.md +81 -0
- agent_chat_reader-0.1.0/docs/api.md +15 -0
- agent_chat_reader-0.1.0/docs/ci-private-submodules.md +67 -0
- agent_chat_reader-0.1.0/pyproject.toml +148 -0
- agent_chat_reader-0.1.0/src/agent_chat_reader/__init__.py +7 -0
- agent_chat_reader-0.1.0/src/agent_chat_reader/claude.py +167 -0
- agent_chat_reader-0.1.0/src/agent_chat_reader/cli.py +183 -0
- agent_chat_reader-0.1.0/src/agent_chat_reader/codex.py +151 -0
- agent_chat_reader-0.1.0/src/agent_chat_reader/models.py +25 -0
- agent_chat_reader-0.1.0/src/agent_chat_reader/output.py +69 -0
- agent_chat_reader-0.1.0/src/agent_chat_reader/py.typed +0 -0
- agent_chat_reader-0.1.0/templates/licenses/Apache-2.0 +184 -0
- agent_chat_reader-0.1.0/templates/licenses/MIT +21 -0
- agent_chat_reader-0.1.0/templates/licenses/README.md +7 -0
- agent_chat_reader-0.1.0/tests/test_package.py +148 -0
- agent_chat_reader-0.1.0/uv.lock +443 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
One sentence explaining what this PR does.
|
|
2
|
+
|
|
3
|
+
Follow this format by default, but you can deviate if that makes the PR
|
|
4
|
+
clearer, for example for an unusually large PR.
|
|
5
|
+
|
|
6
|
+
## Related:
|
|
7
|
+
Optional. Use only if truly needed. Link related issues, docs, PRs, or
|
|
8
|
+
discussion.
|
|
9
|
+
- ...
|
|
10
|
+
|
|
11
|
+
## Changes:
|
|
12
|
+
What changed in the final state of the PR. Describe the current behavior the
|
|
13
|
+
reader needs to know. Do not narrate the whole implementation history of the PR.
|
|
14
|
+
Be concise.
|
|
15
|
+
- ...
|
|
16
|
+
- ...
|
|
17
|
+
|
|
18
|
+
## Why:
|
|
19
|
+
What problem this solves and why the changes were needed.
|
|
20
|
+
Be concise.
|
|
21
|
+
- ...
|
|
22
|
+
- ...
|
|
23
|
+
|
|
24
|
+
## Details:
|
|
25
|
+
Optional. Use only if truly needed. Use this for important details or gotchas
|
|
26
|
+
that would clutter the changes section.
|
|
27
|
+
- ...
|
|
28
|
+
|
|
29
|
+
## How To Try It:
|
|
30
|
+
Optional. Use only if truly needed. Use this when a reviewer would benefit
|
|
31
|
+
from commands, paths, task ids, or links to inspect the change directly. Do
|
|
32
|
+
not repeat generic CI or test output.
|
|
33
|
+
- ...
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
name: Checks
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
push:
|
|
6
|
+
branches: [main]
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
concurrency:
|
|
10
|
+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
|
|
11
|
+
cancel-in-progress: true
|
|
12
|
+
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
|
|
16
|
+
jobs:
|
|
17
|
+
ruff:
|
|
18
|
+
name: Ruff
|
|
19
|
+
runs-on: ubuntu-latest
|
|
20
|
+
timeout-minutes: 5
|
|
21
|
+
|
|
22
|
+
steps:
|
|
23
|
+
- name: Check out repository
|
|
24
|
+
uses: actions/checkout@v6
|
|
25
|
+
|
|
26
|
+
- name: Set up Python
|
|
27
|
+
uses: actions/setup-python@v6
|
|
28
|
+
with:
|
|
29
|
+
python-version: "3.11"
|
|
30
|
+
cache: pip
|
|
31
|
+
cache-dependency-path: pyproject.toml
|
|
32
|
+
|
|
33
|
+
- name: Install Ruff
|
|
34
|
+
run: python -m pip install ruff==0.15.9
|
|
35
|
+
|
|
36
|
+
- name: Ruff format
|
|
37
|
+
run: python -m ruff format --check --diff .
|
|
38
|
+
|
|
39
|
+
- name: Ruff lint
|
|
40
|
+
run: python -m ruff check --output-format=full .
|
|
41
|
+
|
|
42
|
+
python-checks:
|
|
43
|
+
name: Ruff + Mypy + Pytest
|
|
44
|
+
runs-on: ubuntu-latest
|
|
45
|
+
timeout-minutes: 10
|
|
46
|
+
strategy:
|
|
47
|
+
fail-fast: false
|
|
48
|
+
matrix:
|
|
49
|
+
python-version: ["3.11", "3.12", "3.13"]
|
|
50
|
+
|
|
51
|
+
steps:
|
|
52
|
+
- name: Check out repository
|
|
53
|
+
uses: actions/checkout@v6
|
|
54
|
+
|
|
55
|
+
- name: Set up Python
|
|
56
|
+
uses: actions/setup-python@v6
|
|
57
|
+
with:
|
|
58
|
+
python-version: ${{ matrix.python-version }}
|
|
59
|
+
cache: pip
|
|
60
|
+
cache-dependency-path: pyproject.toml
|
|
61
|
+
|
|
62
|
+
- name: Install Python dependencies
|
|
63
|
+
run: |
|
|
64
|
+
python -m pip install --upgrade pip
|
|
65
|
+
python -m pip install -e ".[dev]"
|
|
66
|
+
|
|
67
|
+
- name: Ruff format
|
|
68
|
+
run: python -m ruff format --check --diff .
|
|
69
|
+
|
|
70
|
+
- name: Ruff lint
|
|
71
|
+
run: python -m ruff check --output-format=full .
|
|
72
|
+
|
|
73
|
+
- name: Mypy static type checks
|
|
74
|
+
run: python -m mypy
|
|
75
|
+
|
|
76
|
+
- name: Pytest tests
|
|
77
|
+
run: python -m pytest
|
|
78
|
+
|
|
79
|
+
package-pip:
|
|
80
|
+
name: Package Build (pip)
|
|
81
|
+
runs-on: ubuntu-latest
|
|
82
|
+
timeout-minutes: 10
|
|
83
|
+
|
|
84
|
+
steps:
|
|
85
|
+
- name: Check out repository
|
|
86
|
+
uses: actions/checkout@v6
|
|
87
|
+
|
|
88
|
+
- name: Set up Python
|
|
89
|
+
uses: actions/setup-python@v6
|
|
90
|
+
with:
|
|
91
|
+
python-version: "3.11"
|
|
92
|
+
cache: pip
|
|
93
|
+
cache-dependency-path: pyproject.toml
|
|
94
|
+
|
|
95
|
+
- name: Install Python dependencies
|
|
96
|
+
run: |
|
|
97
|
+
python -m pip install --upgrade pip
|
|
98
|
+
python -m pip install -e ".[dev]"
|
|
99
|
+
|
|
100
|
+
- name: Build package
|
|
101
|
+
run: python -m build
|
|
102
|
+
|
|
103
|
+
- name: Install built wheel
|
|
104
|
+
run: python -m pip install --force-reinstall dist/*.whl
|
|
105
|
+
|
|
106
|
+
- name: Smoke test installed package
|
|
107
|
+
run: python -c "import mypackage; print(mypackage.do_useful_thing())"
|
|
108
|
+
|
|
109
|
+
package-uv:
|
|
110
|
+
name: Package Build (uv)
|
|
111
|
+
runs-on: ubuntu-latest
|
|
112
|
+
timeout-minutes: 10
|
|
113
|
+
|
|
114
|
+
steps:
|
|
115
|
+
- name: Check out repository
|
|
116
|
+
uses: actions/checkout@v6
|
|
117
|
+
|
|
118
|
+
- name: Set up uv
|
|
119
|
+
uses: astral-sh/setup-uv@v6
|
|
120
|
+
with:
|
|
121
|
+
enable-cache: true
|
|
122
|
+
cache-dependency-glob: uv.lock
|
|
123
|
+
|
|
124
|
+
- name: Set up Python
|
|
125
|
+
run: uv python install 3.11
|
|
126
|
+
|
|
127
|
+
- name: Install Python dependencies
|
|
128
|
+
run: uv sync --extra dev --locked
|
|
129
|
+
|
|
130
|
+
- name: Build package
|
|
131
|
+
run: uv build
|
|
132
|
+
|
|
133
|
+
- name: Install built wheel
|
|
134
|
+
run: uv pip install --force-reinstall dist/*.whl
|
|
135
|
+
|
|
136
|
+
- name: Smoke test installed package
|
|
137
|
+
run: uv run python -c "import mypackage; print(mypackage.do_useful_thing())"
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
publish:
|
|
13
|
+
name: Publish to PyPI
|
|
14
|
+
runs-on: ubuntu-latest
|
|
15
|
+
environment: pypi
|
|
16
|
+
permissions:
|
|
17
|
+
contents: read
|
|
18
|
+
id-token: write
|
|
19
|
+
|
|
20
|
+
steps:
|
|
21
|
+
- name: Check out repository
|
|
22
|
+
uses: actions/checkout@v6
|
|
23
|
+
|
|
24
|
+
- name: Set up Python
|
|
25
|
+
uses: actions/setup-python@v6
|
|
26
|
+
with:
|
|
27
|
+
python-version: "3.11"
|
|
28
|
+
|
|
29
|
+
- name: Build package
|
|
30
|
+
run: |
|
|
31
|
+
python -m pip install --upgrade pip
|
|
32
|
+
python -m pip install build
|
|
33
|
+
python -m build
|
|
34
|
+
|
|
35
|
+
- name: Publish package distributions to PyPI
|
|
36
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[cod]
|
|
3
|
+
*$py.class
|
|
4
|
+
|
|
5
|
+
.Python
|
|
6
|
+
.venv/
|
|
7
|
+
venv/
|
|
8
|
+
env/
|
|
9
|
+
ENV/
|
|
10
|
+
|
|
11
|
+
build/
|
|
12
|
+
dist/
|
|
13
|
+
*.egg-info/
|
|
14
|
+
.eggs/
|
|
15
|
+
|
|
16
|
+
.pytest_cache/
|
|
17
|
+
.mypy_cache/
|
|
18
|
+
.ruff_cache/
|
|
19
|
+
.coverage
|
|
20
|
+
htmlcov/
|
|
21
|
+
|
|
22
|
+
.env
|
|
23
|
+
.env.*
|
|
24
|
+
|
|
25
|
+
.DS_Store
|
|
26
|
+
.idea/
|
|
27
|
+
.vscode/
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
repos:
|
|
2
|
+
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
3
|
+
rev: v0.15.9
|
|
4
|
+
hooks:
|
|
5
|
+
- id: ruff
|
|
6
|
+
- id: ruff-format
|
|
7
|
+
args: ["--check"]
|
|
8
|
+
|
|
9
|
+
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
10
|
+
rev: v6.0.0
|
|
11
|
+
hooks:
|
|
12
|
+
- id: trailing-whitespace
|
|
13
|
+
- id: check-symlinks
|
|
14
|
+
- id: destroyed-symlinks
|
|
15
|
+
- id: end-of-file-fixer
|
|
16
|
+
- id: check-yaml
|
|
17
|
+
- id: check-toml
|
|
18
|
+
- id: check-merge-conflict
|
|
19
|
+
- id: check-case-conflict
|
|
20
|
+
- id: check-executables-have-shebangs
|
|
21
|
+
- id: check-added-large-files
|
|
22
|
+
args: ["--maxkb=2000"]
|
|
23
|
+
- id: check-shebang-scripts-are-executable
|
|
24
|
+
- id: detect-private-key
|
|
25
|
+
- id: debug-statements
|
|
26
|
+
|
|
27
|
+
- repo: https://github.com/codespell-project/codespell
|
|
28
|
+
rev: v2.4.1
|
|
29
|
+
hooks:
|
|
30
|
+
- id: codespell
|
|
31
|
+
additional_dependencies:
|
|
32
|
+
- tomli
|
|
33
|
+
|
|
34
|
+
- repo: https://github.com/pre-commit/pygrep-hooks
|
|
35
|
+
rev: v1.10.0
|
|
36
|
+
hooks:
|
|
37
|
+
- id: rst-backticks
|
|
38
|
+
- id: rst-directive-colons
|
|
39
|
+
- id: rst-inline-touching-normal
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.11
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Repo-specific instructions for agents working with the `mypackage` package.
|
|
4
|
+
|
|
5
|
+
## Package Conventions
|
|
6
|
+
|
|
7
|
+
- Keep importable package code under `src/mypackage/`.
|
|
8
|
+
- Put CLI entrypoint behavior in `src/mypackage/cli.py`.
|
|
9
|
+
|
|
10
|
+
## Validation
|
|
11
|
+
|
|
12
|
+
- Run checks relevant to the files changed.
|
|
13
|
+
- For README/docs-only changes, run formatting and pre-commit hygiene.
|
|
14
|
+
- For Python or packaging changes, also run Ruff, mypy, pytest, and build
|
|
15
|
+
checks.
|
|
16
|
+
|
|
17
|
+
## Pull Requests
|
|
18
|
+
|
|
19
|
+
- Use `.github/PULL_REQUEST_TEMPLATE.md` for PR descriptions.
|
|
20
|
+
- Do not commit secrets, credentials, local runtime config, or scratch notes.
|
|
21
|
+
- Keep `AGENTS.md` updated when recurring agent instructions become
|
|
22
|
+
repo-specific.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ali K
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR Ali KS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-chat-reader
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Read and search Codex CLI and Claude Code chat history from the terminal.
|
|
5
|
+
Project-URL: Homepage, https://github.com/alik-git/agent-chat-reader
|
|
6
|
+
Project-URL: Repository, https://github.com/alik-git/agent-chat-reader
|
|
7
|
+
Project-URL: Issues, https://github.com/alik-git/agent-chat-reader/issues
|
|
8
|
+
Author-email: Ali K <alikgithb@gmail.com>
|
|
9
|
+
Maintainer-email: Ali K <alikgithb@gmail.com>
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: ai-agents,chat-history,claude,cli,codex,developer-tools
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
23
|
+
Requires-Dist: mypy>=1.15; extra == 'dev'
|
|
24
|
+
Requires-Dist: pre-commit>=4.0; extra == 'dev'
|
|
25
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
26
|
+
Requires-Dist: ruff>=0.11; extra == 'dev'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# agent-chat-reader
|
|
30
|
+
|
|
31
|
+
Read and search [Codex CLI](https://github.com/openai/codex) and [Claude Code](https://claude.ai/code) chat history from the terminal.
|
|
32
|
+
|
|
33
|
+
Useful for AI agents that need to recall what was discussed or decided in past sessions, without manually parsing noisy JSONL files.
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
uv tool install agent-chat-reader
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Or for development:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
git clone https://github.com/alik-git/agent-chat-reader
|
|
45
|
+
cd agent-chat-reader
|
|
46
|
+
uv sync --extra dev
|
|
47
|
+
uv run agent-chat-reader --help
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Usage
|
|
51
|
+
|
|
52
|
+
**List recent sessions** (both Codex and Claude Code, sorted by recency):
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
agent-chat-reader --list
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Search across all sessions** for a keyword:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
agent-chat-reader --find "sim2sim"
|
|
62
|
+
agent-chat-reader --find "policy_interface" --source codex
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Read a specific session** by UUID prefix:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
agent-chat-reader 019eaecb
|
|
69
|
+
agent-chat-reader 1bfc739b --verbose # include tool call summaries
|
|
70
|
+
agent-chat-reader 019eaecb --tail 5 # last 5 user turns only
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## What it filters out
|
|
74
|
+
|
|
75
|
+
The raw JSONL files are very noisy. This tool extracts only:
|
|
76
|
+
|
|
77
|
+
- **Codex**: `user_message` events, `agent_message` events, and full `response_item` assistant text. Guardian/subagent sessions (auto-approval bots) are hidden by default.
|
|
78
|
+
- **Claude Code**: real user turns (not tool-result carriers), and assistant text blocks (not thinking blocks or tool calls). Sidechain sub-agent turns are hidden by default.
|
|
79
|
+
|
|
80
|
+
Use `--include-subagents` to see everything.
|
|
81
|
+
|
|
82
|
+
## Options
|
|
83
|
+
|
|
84
|
+
| Flag | Description |
|
|
85
|
+
|------|-------------|
|
|
86
|
+
| `--list` / `-l` | List recent sessions from both sources |
|
|
87
|
+
| `--find KEYWORD` / `-f` | Search all sessions for a keyword |
|
|
88
|
+
| `--source codex\|claude` | Filter to one source |
|
|
89
|
+
| `--verbose` / `-v` | Include brief tool call summaries (Claude sessions) |
|
|
90
|
+
| `--tail N` / `-n N` | Show only the last N user turns of a session |
|
|
91
|
+
| `--include-subagents` | Include guardian/subagent sessions |
|
|
92
|
+
| `--limit N` | Max sessions shown by `--list` (default: 40) |
|
|
93
|
+
|
|
94
|
+
## Session storage locations
|
|
95
|
+
|
|
96
|
+
| Agent | Path |
|
|
97
|
+
|-------|------|
|
|
98
|
+
| Codex CLI | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |
|
|
99
|
+
| Claude Code | `~/.claude/projects/*/*.jsonl` |
|
|
100
|
+
|
|
101
|
+
## Development
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
uv run ruff format --check .
|
|
105
|
+
uv run ruff check .
|
|
106
|
+
uv run mypy
|
|
107
|
+
uv run pytest
|
|
108
|
+
uv build
|
|
109
|
+
```
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# agent-chat-reader
|
|
2
|
+
|
|
3
|
+
Read and search [Codex CLI](https://github.com/openai/codex) and [Claude Code](https://claude.ai/code) chat history from the terminal.
|
|
4
|
+
|
|
5
|
+
Useful for AI agents that need to recall what was discussed or decided in past sessions, without manually parsing noisy JSONL files.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
uv tool install agent-chat-reader
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Or for development:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
git clone https://github.com/alik-git/agent-chat-reader
|
|
17
|
+
cd agent-chat-reader
|
|
18
|
+
uv sync --extra dev
|
|
19
|
+
uv run agent-chat-reader --help
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Usage
|
|
23
|
+
|
|
24
|
+
**List recent sessions** (both Codex and Claude Code, sorted by recency):
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
agent-chat-reader --list
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**Search across all sessions** for a keyword:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
agent-chat-reader --find "sim2sim"
|
|
34
|
+
agent-chat-reader --find "policy_interface" --source codex
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**Read a specific session** by UUID prefix:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
agent-chat-reader 019eaecb
|
|
41
|
+
agent-chat-reader 1bfc739b --verbose # include tool call summaries
|
|
42
|
+
agent-chat-reader 019eaecb --tail 5 # last 5 user turns only
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## What it filters out
|
|
46
|
+
|
|
47
|
+
The raw JSONL files are very noisy. This tool extracts only:
|
|
48
|
+
|
|
49
|
+
- **Codex**: `user_message` events, `agent_message` events, and full `response_item` assistant text. Guardian/subagent sessions (auto-approval bots) are hidden by default.
|
|
50
|
+
- **Claude Code**: real user turns (not tool-result carriers), and assistant text blocks (not thinking blocks or tool calls). Sidechain sub-agent turns are hidden by default.
|
|
51
|
+
|
|
52
|
+
Use `--include-subagents` to see everything.
|
|
53
|
+
|
|
54
|
+
## Options
|
|
55
|
+
|
|
56
|
+
| Flag | Description |
|
|
57
|
+
|------|-------------|
|
|
58
|
+
| `--list` / `-l` | List recent sessions from both sources |
|
|
59
|
+
| `--find KEYWORD` / `-f` | Search all sessions for a keyword |
|
|
60
|
+
| `--source codex\|claude` | Filter to one source |
|
|
61
|
+
| `--verbose` / `-v` | Include brief tool call summaries (Claude sessions) |
|
|
62
|
+
| `--tail N` / `-n N` | Show only the last N user turns of a session |
|
|
63
|
+
| `--include-subagents` | Include guardian/subagent sessions |
|
|
64
|
+
| `--limit N` | Max sessions shown by `--list` (default: 40) |
|
|
65
|
+
|
|
66
|
+
## Session storage locations
|
|
67
|
+
|
|
68
|
+
| Agent | Path |
|
|
69
|
+
|-------|------|
|
|
70
|
+
| Codex CLI | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |
|
|
71
|
+
| Claude Code | `~/.claude/projects/*/*.jsonl` |
|
|
72
|
+
|
|
73
|
+
## Development
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
uv run ruff format --check .
|
|
77
|
+
uv run ruff check .
|
|
78
|
+
uv run mypy
|
|
79
|
+
uv run pytest
|
|
80
|
+
uv build
|
|
81
|
+
```
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# API
|
|
2
|
+
|
|
3
|
+
Document the package's public Python API here.
|
|
4
|
+
|
|
5
|
+
## `do_useful_thing`
|
|
6
|
+
|
|
7
|
+
```python
|
|
8
|
+
import mypackage
|
|
9
|
+
|
|
10
|
+
result = mypackage.do_useful_thing("world")
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`do_useful_thing` is the starter public function exposed by this template.
|
|
14
|
+
Replace it with the functions or classes that should make up the package's
|
|
15
|
+
public API.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# CI Private Submodules
|
|
2
|
+
|
|
3
|
+
If a package created from this template uses private GitHub submodules, the
|
|
4
|
+
default [`GITHUB_TOKEN`](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication)
|
|
5
|
+
may not be able to clone them in GitHub Actions.
|
|
6
|
+
|
|
7
|
+
Use a [GitHub App](https://docs.github.com/en/apps/overview) token pattern for
|
|
8
|
+
private submodules. The
|
|
9
|
+
[`actions/create-github-app-token`](https://github.com/actions/create-github-app-token)
|
|
10
|
+
action creates a short-lived installation access token that can be scoped to the
|
|
11
|
+
parent repo and the private submodule repos:
|
|
12
|
+
|
|
13
|
+
```yaml
|
|
14
|
+
- name: Create GitHub App token
|
|
15
|
+
id: app-token
|
|
16
|
+
uses: actions/create-github-app-token@v3
|
|
17
|
+
with:
|
|
18
|
+
client-id: ${{ vars.CI_APP_CLIENT_ID }}
|
|
19
|
+
private-key: ${{ secrets.CI_APP_PRIVATE_KEY }}
|
|
20
|
+
owner: your-org
|
|
21
|
+
repositories: |
|
|
22
|
+
your_repo
|
|
23
|
+
private_submodule_repo
|
|
24
|
+
permission-contents: read
|
|
25
|
+
|
|
26
|
+
- name: Check out repository
|
|
27
|
+
uses: actions/checkout@v6
|
|
28
|
+
with:
|
|
29
|
+
token: ${{ steps.app-token.outputs.token }}
|
|
30
|
+
submodules: recursive
|
|
31
|
+
persist-credentials: false
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Required repository settings:
|
|
35
|
+
|
|
36
|
+
- Variable: `CI_APP_CLIENT_ID`
|
|
37
|
+
- Secret: `CI_APP_PRIVATE_KEY`
|
|
38
|
+
|
|
39
|
+
Create these under the repository's
|
|
40
|
+
[Actions variables and secrets settings](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables)
|
|
41
|
+
and
|
|
42
|
+
[Actions secrets settings](https://docs.github.com/en/actions/how-tos/security-for-github-actions/security-guides/using-secrets-in-github-actions).
|
|
43
|
+
|
|
44
|
+
The GitHub App must be installed on the parent repo and each private submodule
|
|
45
|
+
repo listed under `repositories`. See GitHub's docs for
|
|
46
|
+
[installing your own GitHub App](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app).
|
|
47
|
+
|
|
48
|
+
Replace the variable and secret names in the YAML with whatever naming
|
|
49
|
+
convention your repository uses.
|
|
50
|
+
|
|
51
|
+
`actions/create-github-app-token` still accepts the older `app-id` input, but
|
|
52
|
+
the upstream action now recommends `client-id`. Prefer `client-id` in new
|
|
53
|
+
workflows to avoid deprecation/legacy-input warnings. GitHub documents where to
|
|
54
|
+
find a GitHub App's client ID in the
|
|
55
|
+
[GitHub App settings](https://docs.github.com/en/apps/maintaining-github-apps/modifying-a-github-app).
|
|
56
|
+
|
|
57
|
+
Symptoms when this is missing:
|
|
58
|
+
|
|
59
|
+
- PR checks stay queued and then fail during checkout.
|
|
60
|
+
- [`actions/checkout`](https://github.com/actions/checkout) reports that it
|
|
61
|
+
cannot clone a private submodule.
|
|
62
|
+
- SSH submodule URLs like `git@github.com:org/private_repo.git` fail in CI even
|
|
63
|
+
though they work locally.
|
|
64
|
+
|
|
65
|
+
When adapting the template, either avoid private submodules in CI or add the
|
|
66
|
+
token step before every `actions/checkout` step that uses `submodules:
|
|
67
|
+
recursive`.
|