🔎 Shellscope

Built from Codex source and synthetic fixtures, without inspecting your private transcripts.

Point this read-only Python CLI at completed Codex sessions to rank shell utilities and trace each count back to its original call. It runs locally with only the standard library.

Scanning my Codex sessions on my Mac, with a few utilities hidden:

List the matching filenames:

find ~/.codex/sessions -type f -name 'rollout-*.jsonl' -print

Once you've reviewed the list, scan the matching files:

find ~/.codex/sessions \
  -type f -name 'rollout-*.jsonl' -print0 |
  python3 observer.py --sessions-from - --min-count 40

-print0 separates filenames safely; the final - tells the observer to read that list from stdin.

For a cleaner ranking, copy the example exclusion list and edit it:

cp excluded.example.txt excluded.txt

Then scan with the file:

find ~/.codex/sessions \
  -type f -name 'rollout-*.jsonl' -print0 |
  python3 observer.py --sessions-from - --min-count 40 \
    --exclude-file excluded.txt

Source references are pinned to openai/codex@8d32abcd. The nearby 0.153.0-alpha.6 release provides version context; it is not the exact source revision.

• Hook contract: PreToolUse schema and serialization tests.
• Rollout format: envelope and response item types.
• Saved commands: command item and rollout persistence policy.
• Command mapping: handler and tests.

• Document the Codex rollout formats this parser supports and flag unverified newer formats. Future format changes may require parser updates.

Run the synthetic tests with python3 -m unittest discover -s tests -v.

You can also try the included synthetic session without opening a private one:

python3 observer.py tests/fixtures/synthetic-rollout.jsonl
python3 observer.py tests/fixtures/synthetic-rollout.jsonl --format calls

Does Shellscope help me do something I can't do elsewhere?

Not uniquely. Other projects analyze agent sessions too.

Have I checked other projects' code, tests, and privacy behavior?

Not yet. I've read enough to understand what they offer, not enough to recommend them. For context:

• TraceLab ranks executables across Codex and Claude traces with deeper Bash parsing.
• codex-logger puts local Codex tool calls into a queryable database.
• cxstat reports tool and token usage, with deeper shell-command analysis on its roadmap.

Shellscope stays narrower: choose local sessions, get a quick ranking, and inspect the calls behind it.

These are rough counts of attempted utility invocations: unusual shell syntax, scripts, and code-mode calls may be missed or misread, and copied session history can repeat calls across files.