Codex Session Sharing Plugin

A Codex plugin that saves and shares coding sessions to GitHub as readable Markdown.

Features

• Converts Codex JSONL session logs into clean, readable Markdown
• Includes user and Codex messages with collapsible tool calls
• Excludes system and developer instructions
• Creates a local preview for review before anything is published
• Commits and pushes approved sessions to any GitHub repository
• Organizes exports by GitHub username under sessions/codex/
• Supports optional descriptions for clearer titles and filenames

Prerequisites

• Python 3.10+
• Codex
• GitHub CLI (gh) installed and authenticated
• A GitHub repository for session exports (public or private)

Installation

Quick install (recommended)

For PostHog, run:

curl -fsSL https://raw.githubusercontent.com/PostHog/codex-share-plugin/main/install.sh | bash

This installs the plugin and configures the private PostHog/agent-sessions repository. Restart Codex and start a new thread after installation.

To publish somewhere else:

curl -fsSL https://raw.githubusercontent.com/PostHog/codex-share-plugin/main/install.sh | \
  bash -s -- --codex-share-repo owner/repository

Replace owner/repository with the repository where sessions should be stored. The installer detects your GitHub username with gh and saves the repository to ${CODEX_HOME:-~/.codex}/share-plugin-config.json.

Install from GitHub

codex plugin marketplace add PostHog/codex-share-plugin
codex plugin add codex-share-plugin@codex-share-plugin

Install locally

From a local checkout, run:

codex plugin marketplace add /absolute/path/to/codex-share-plugin
codex plugin add codex-share-plugin@codex-share-plugin

Restart Codex and start a new thread after installing.

Usage

Ask Codex to share the current session:

Share this session.

Add a description to create a more useful title and filename:

Share this session as “fixing authentication”.

Codex writes a local Markdown preview first. Review it, then approve publishing when prompted. You can also invoke the installed share-session skill explicitly.

Output structure

Published sessions are organized like this:

your-sessions-repo/
└── sessions/
    └── codex/
        └── github-username/
            ├── 20260721-142530-fixing-authentication.md
            ├── 20260721-153245-adding-tests.md
            └── ...

The same repository can hold exports from multiple agents by giving each one its own namespace, such as sessions/claude/ and sessions/codex/.

Example Markdown output

# Fixing authentication

**Exported:** 2026-07-21 14:25:30 UTC

## User

Can you help me fix the authentication bug?

## Codex

I'll investigate the authentication flow and start with the relevant files.

<details>
<summary><code>exec_command</code></summary>

```json
{
  "cmd": "rg -n authentication src"
}
```
</details>

Configuration

The quick installer writes the target repository to ${CODEX_HOME:-~/.codex}/share-plugin-config.json.

To change it later, ask Codex:

Configure session sharing to use owner/repository.

Or run the bundled script directly from this repository:

python3 plugins/codex-share-plugin/scripts/share_session.py \
  --configure-repo owner/repository

CODEX_SHARE_REPO overrides the configured repository. The publishing script also supports --repo, --branch, and --base-path overrides when run directly.

How it works

1. Finds the latest Codex session associated with the current working directory.
2. Converts user messages, Codex responses, and tool calls to Markdown.
3. Writes a local preview and waits for explicit approval.
4. Clones the configured repository into a temporary directory.
5. Commits the session under sessions/codex/{github-username}/ and pushes it.
6. Returns a direct GitHub link to the published transcript.

Privacy and security

Session transcripts may contain prompts, source code, tool inputs, local paths, or secrets. Review every preview before publishing and prefer a private repository for sensitive work.

The plugin uses your existing GitHub CLI authentication and never publishes without a preview and explicit approval.

Troubleshooting

Repository is not configured

Re-run the installer with a repository:

curl -fsSL https://raw.githubusercontent.com/PostHog/codex-share-plugin/main/install.sh | \
  bash -s -- --codex-share-repo owner/repository

Or use the configuration command shown above.

GitHub authentication fails

Check that the GitHub CLI is installed and authenticated:

gh --version
gh auth status

If needed, run gh auth login and confirm that your account has write access to the target repository.

The repository cannot be cloned or pushed

Confirm that:

1. The repository exists and uses the owner/repository format.
2. Your GitHub account can access and write to it.
3. The configured branch exists. The default is main.
4. Your authentication has not expired. Run gh auth refresh if necessary.

Development

Run the test suite:

python3 -m unittest discover -s tests

After changing an installed local plugin, upgrade the marketplace and reinstall the plugin before testing it in a new Codex thread.

License

MIT