agent-sessions-cli 0.2.0__py3-none-any.whl

agent_sessions/model.py

@@ -0,0 +1,119 @@
+"""Agent-neutral session model. Adapters produce it, the renderer consumes it."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+# Canonical tool kinds. Adapters map their native tool names onto these; the
+# renderer and the result policy never see agent-specific names.
+KINDS = ("shell", "read", "edit", "write", "search", "web", "agent", "mcp", "ask", "other")
+STUB_KINDS = {"read", "web", "mcp"}          # results replaced by a one-line stub
+SNIPPET_KINDS = {"edit", "write"}            # inputs shown as short snippets
+SENSITIVE_PROBE_KINDS = {"shell", "read", "edit", "write", "search"}
+
+# A user turn that invoked push, in any agent's syntax.
+PUSH_MARKER_RE = re.compile(
+    r"<command-name>\s*/[\w-]*sessions[\w-]*:push\s*</command-name>"
+    r"|/sessions:push\b"
+    r"|\$agent-sessions\s+push\b"
+    r"|\bagent-sessions\s+push\b"
+    r"|\bsessions-push\b",
+    re.I,
+)
+
+# The shell call that *is* the locate preflight. Used to recognise the live
+# session: it is the one whose most recent shell call is this and has no output yet.
+SELF_REF_RE = re.compile(r"sessions(?:\.sh|\.py)?\b[^\n]{0,200}\blocate\b|\bagent-sessions\b[^\n]{0,80}\blocate\b", re.I)
+
+
+@dataclass
+class ToolCall:
+    kind: str                       # one of KINDS
+    name: str                       # agent-native name
+    label: str                      # one-line summary shown in <summary>
+    input: object = None            # dict when structured, str when opaque
+    output: str = ""
+    is_error: bool = False
+    paths: List[str] = field(default_factory=list)   # files this call touched (edit/write)
+    pending: bool = False           # no output recorded yet (call in flight)
+
+
+@dataclass
+class Event:
+    kind: str                       # user | assistant | thinking | tool | compaction | note
+    text: str = ""
+    ts: Optional[dt.datetime] = None
+    is_push_invocation: bool = False
+    command: str = ""               # slash command the user ran ("/compact"), if any
+    tool: Optional[ToolCall] = None
+    meta: dict = field(default_factory=dict)
+
+
+@dataclass
+class Session:
+    agent: str                      # claude-code | codex | opencode | gemini-cli
+    session_id: str
+    short_id: str
+    title: Optional[str]
+    cwd: Optional[str]
+    started: Optional[dt.datetime]
+    ended: Optional[dt.datetime]
+    events: List[Event]
+    source: str                     # file path or "sqlite:<db>#<id>"
+    agent_version: Optional[str] = None
+    originator: Optional[str] = None
+    parent_id: Optional[str] = None
+    subagent_files: int = 0
+    tokens: Optional[dict] = None
+    tested_version: Optional[Tuple[int, ...]] = None
+    warnings: List[str] = field(default_factory=list)
+    record_count: int = 0
+    bad_lines: int = 0
+
+    def files_touched(self) -> List[str]:
+        seen = {}
+        for e in self.events:
+            if e.tool:
+                for p in e.tool.paths:
+                    seen.setdefault(p, None)
+        return list(seen.keys())
+
+    def user_prompts(self, limit: int = 200) -> List[Tuple[Optional[dt.datetime], str]]:
+        out = []
+        for e in self.events:
+            if e.kind != "user" or e.is_push_invocation:
+                continue
+            if e.command:
+                out.append((e.ts, "/" + e.command.lstrip("/")))
+            elif e.text:
+                out.append((e.ts, re.sub(r"\s+", " ", e.text)[:limit]))
+        return out
+
+    def agent_tasks(self) -> List[str]:
+        return [re.sub(r"\s+", " ", e.tool.label)[:120] for e in self.events if e.tool and e.tool.kind == "agent"]
+
+    def last_user_text(self) -> str:
+        for e in reversed(self.events):
+            if e.kind == "user":
+                return e.text or e.command
+        return ""
+
+    def has_pending_self_call(self) -> bool:
+        """True when the most recent shell call is our own `locate` and has produced no output yet."""
+        for e in reversed(self.events):
+            if e.tool and e.tool.kind == "shell":
+                return bool(e.tool.pending and SELF_REF_RE.search(_input_blob(e.tool.input)))
+        return False
+
+
+def _input_blob(value: object) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        return " ".join(_input_blob(v) for v in value.values())
+    if isinstance(value, list):
+        return " ".join(_input_blob(v) for v in value)
+    return "" if value is None else str(value)

agent_sessions/templates/gitattributes

@@ -0,0 +1,2 @@
+# Rendered transcripts are written with LF; keep them that way on every OS.
+* text eol=lf

agent_sessions/templates/sessions-README.md

@@ -0,0 +1,31 @@
+# Shared coding-agent sessions
+
+This folder holds sessions that teammates chose to share, whichever coding agent they used. Each session is one directory:
+
+```
+YYYY-MM-DD_<slug>_<handle>_<short-id>/
+├── summary.md      handoff written by the author's agent at push time: goal, outcome, decisions, files, gotchas, next steps, paste-ready handoff prompt
+├── transcript.md   the conversation rendered to markdown; tool calls collapsed, secrets redacted, query results omitted
+└── meta.json       machine-readable index entry (title, author, agent, branch, files touched, tags, outcome)
+```
+
+Start with `summary.md`. Open `transcript.md` only when you need to see exactly what was tried.
+
+## How to push and pull, by agent
+
+| Agent | Share this session | Read teammates' sessions |
+|---|---|---|
+| Claude Code | `/sessions:push [title] [--yes]` | `/sessions:pull [keyword]` |
+| Codex CLI | `$agent-sessions push [title] --yes` | `$agent-sessions pull [keyword]` |
+| OpenCode, Gemini CLI, Cursor, Copilot | ask the agent to *use the agent-sessions skill to push this session* | ask it to *use the agent-sessions skill to pull [keyword]* |
+| Any terminal | `agent-sessions push` (after `pip install agent-sessions-cli`) | `agent-sessions list` |
+
+Useful pull flags: `--full <id>` reads one full transcript, `--all-branches` includes sessions on unmerged branches, `--mine` filters to your own.
+
+Install once: Claude Code users are prompted to install the `sessions` plugin when they open this repo. Everyone else runs `scripts/setup.sh --skills` (or `setup.ps1 -Skills`) from https://github.com/prajwalgajakesari/agent-sessions, which copies the skill into `~/.agents/skills/`. If `.agents/skills/agent-sessions/` exists in this repo, the skill is already vendored and nothing needs installing.
+
+## What gets redacted
+
+Structured secrets (cloud keys, tokens, JWTs, private keys, connection-string passwords, SAS signatures) are replaced with `[REDACTED:<kind>]` before anything is committed. Results from file reads, web fetches and MCP tools are omitted and other tool output is truncated, so query rows and file contents do not end up here. Keyword-based redactions (`password=`, `api_key=`) are flagged for the author to review at push time. Nothing here is guaranteed clean: treat a transcript as you would treat a chat log.
+
+There is no generated index on purpose. Directories are per session and per author, so concurrent pushes never conflict. `agent-sessions list` builds the index from `meta.json` files on demand.

agent_sessions/templates/summary.md

@@ -0,0 +1,31 @@
+---
+title: "<3 to 8 words naming the work>"
+session_id: "<set by export>"
+author: "<set by export>"
+handle: "<set by export>"
+date: "<set by export>"
+branch: "<set by export>"
+tags: [<area>, <kind-of-work>]
+outcome: "<one sentence: what is true now that was not before>"
+---
+
+## Goal
+What was asked for, in two or three sentences. Include the why when it was stated.
+
+## Outcome
+What was delivered, what was verified, and what was left undone. Say plainly if something failed or was skipped.
+
+## Key decisions and why
+- Decision. Reason. Alternative that was rejected and why.
+
+## Files changed
+- `path/to/file` — what changed and why.
+
+## Commands and gotchas
+Exact commands a teammate will need, in fenced blocks. Anything that bit us: wrong assumptions, flaky steps, environment quirks.
+
+## Open questions and next steps
+- Item. What or who it is waiting on.
+
+## Handoff prompt
+A paste-ready prompt for a teammate starting a fresh Claude Code session: the goal, the current state, the files to read first, and the next concrete action.

agent_sessions_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: agent-sessions-cli
+Version: 0.2.0
+Summary: Share coding-agent sessions (Claude Code, Codex CLI, OpenCode, Gemini CLI) with your team through git.
+Project-URL: Homepage, https://github.com/prajwalgajakesari/agent-sessions
+Project-URL: Repository, https://github.com/prajwalgajakesari/agent-sessions
+Project-URL: Changelog, https://github.com/prajwalgajakesari/agent-sessions/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/prajwalgajakesari/agent-sessions/issues
+Author: Prajwal P
+License: MIT
+License-File: LICENSE
+Keywords: claude-code,codex,gemini-cli,git,handoff,opencode,sessions,team,transcript
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# agent-sessions
+
+Share coding-agent sessions with your team through the git repo you already work in. One folder, `.claude/sessions/`, holds handoffs from **Claude Code, Codex CLI, OpenCode** and (experimentally) **Gemini CLI**; anyone on any agent can pull them back into their own chat.
+
+```
+/sessions:push "Reconcile fabric tables"        Claude Code, end of a session
+$agent-sessions pull reconcile                  a teammate in Codex, next morning
+```
+
+Coding agents keep sessions in private, undocumented, short-lived local stores. This tool turns one into three committed files and gives teammates one command to load them.
+
+## What a pushed session looks like
+
+```
+.claude/sessions/2026-09-22_reconcile-fabric-tables_prajwal-p_7dcecef6/
+├── summary.md      handoff the author's agent wrote at push time: goal, outcome, decisions and why,
+│                   files changed, commands and gotchas, open questions, a paste-ready handoff prompt (≤120 lines)
+├── transcript.md   the conversation as markdown along the active path (rewinds and compaction handled),
+│                   tool calls collapsed, secrets redacted, file reads and query results omitted
+└── meta.json       title, author, agent and version, branch, dates, files touched (subagents included), tags, outcome, tokens
+```
+
+Pull reads `summary.md` first and loads a transcript only when asked, so a teammate gets the reasoning without burning their context window.
+
+## Install
+
+| You use | Do this once |
+|---|---|
+| Claude Code | `/plugin marketplace add prajwalgajakesari/agent-sessions` then `/plugin install sessions@agent-sessions`. Repos set up with `init` prompt you automatically. |
+| Codex CLI, OpenCode, Gemini CLI, Cursor, Copilot | `scripts/setup.sh --skills` (or `scripts\setup.ps1 -Skills`) from a checkout. It copies the `agent-sessions` skill into `~/.agents/skills/`, which all of them read. |
+| Any terminal | `pip install agent-sessions-cli` or `uvx agent-sessions-cli`, then `agent-sessions doctor`. |
+
+Requirements: git and Python 3.9+ (`python3`, `python`, or the Windows `py` launcher). No Python packages.
+
+Then, in each repo you want to share sessions in: `/sessions:init` in Claude Code, or `$agent-sessions init` in Codex, or `agent-sessions init` in a terminal. It fixes a blanket `.claude/` ignore rule so only `.claude/sessions/` and `.claude/settings.json` are tracked, drops a README and `.gitattributes`, registers the Claude plugin in `.claude/settings.json`, and commits exactly those files. Add `--vendor-skill` to also copy the portable skill into `.agents/skills/` so every teammate's agent discovers it on clone.
+
+## Using it
+
+| Agent | Share this session | Read teammates' sessions |
+|---|---|---|
+| Claude Code | `/sessions:push [title] [--yes]` | `/sessions:pull [keyword]` |
+| Codex CLI | `$agent-sessions push [title] --yes` | `$agent-sessions pull [keyword]` |
+| OpenCode, Gemini CLI, Cursor, Copilot | "use the agent-sessions skill to push this session" | "use the agent-sessions skill to pull [keyword]" |
+| Terminal | `agent-sessions locate` → write `summary.md` → `export` → `commit --push` | `agent-sessions list` |
+
+Push flow, whichever agent runs it:
+
+1. `locate` finds this session in the agent's store, checks the repo (ignore rules, detached HEAD, merges in progress, missing upstream) and prints an outline of the conversation.
+2. The agent writes `summary.md` from the template, using the outline plus its own memory, through `write-summary` (agents' file tools tend to refuse `.claude/`).
+3. `export` renders and redacts the transcript, writes `meta.json`, renames the folder to the final title, and prints a redaction report.
+4. You see a short preview and confirm once. `--yes` skips it.
+5. `commit --push` builds the commit on a temporary index inside `.git` and pushes to your current branch. Your staged changes, working tree and any in-progress merge are untouched. `--branch` pushes to a new remote branch instead.
+
+Pushing the same session again updates the same folder and keeps everything after the first push.
+
+Pull flags: `--n N` how many summaries (default 3), `--full <id>` one full transcript, `--all-branches` sessions on unmerged branches, `--mine` your own.
+
+## How the live session is found
+
+No agent tells a shell command which session it belongs to, so `locate` never guesses:
+
+| Signal | Used by |
+|---|---|
+| `--session-id` passed by the skill | Claude Code (`${CLAUDE_SESSION_ID}` is substituted into the preflight) |
+| Environment variable | Claude Code (`CLAUDE_CODE_SESSION_ID`); Codex if `CODEX_THREAD_ID` reaches child shells |
+| **Self-reference**: the `locate` call itself is the newest shell call in exactly one session and has no output yet | Codex, OpenCode, Claude Code |
+| A push invocation in the latest user turn | any |
+| Exactly one session for this repo | any |
+
+If more than one session still matches, `locate` prints `CANDIDATES:` and the skill asks you which one, then re-runs with `--agent` and `--session-id`. Codex fork and compaction stubs are skipped.
+
+## Where each agent keeps sessions
+
+| Agent | Store | Notes |
+|---|---|---|
+| Claude Code | `~/.claude/projects/<encoded-cwd>/<id>.jsonl` (+ `subagents/`) | active path via `parentUuid`, compaction boundaries, subagent edits counted |
+| Codex CLI | `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl`, `session_index.jsonl` for titles | `exec` snippets parsed for `exec_command` and `apply_patch`; `compacted` history rendered once; developer messages and environment wrappers dropped |
+| OpenCode | `~/.local/share/opencode/opencode.db` (SQLite, WAL) | opened read-only, copied if locked; `compaction` parts; child sessions feed files touched; tokens and cost from the session row |
+| Gemini CLI | `~/.gemini/tmp/<hash>/chats/session-*.jsonl` | **experimental**: built from the source schema without a real sample; `$set`/`$rewindTo` applied |
+| Copilot CLI, Cursor | detected, not exported | pull and init work; push says so. Cursor's plain-text agent transcripts are the next adapter once a sample exists |
+
+## What is and is not redacted
+
+| Layer | What it does |
+|---|---|
+| Result policy | Results of file reads, web fetches and MCP tools are replaced by a one-line stub. Other tool output is cut to 30 lines or 2 KB. `--include-results` keeps up to 20 KB per result. |
+| Sensitive files | Any tool call that reads or edits `.env*`, `local.settings.json`, `appsettings*.json`, `secrets.json`, key and certificate files, Terraform state, `.netrc`, `.pypirc`, `.databrickscfg` or anything under `.azure/` has both input and result withheld. |
+| Pattern redaction | AWS keys, GitHub, Slack, OpenAI and Anthropic tokens, JWTs, private keys, credentials in URLs, Azure storage account keys, shared access keys and SAS signatures, Azure DevOps PATs, Entra client secrets, bearer tokens. Keyword hits such as `password=`, `client_secret=`, `-P` after `sqlcmd` are redacted too and listed for you to review. |
+
+GUIDs are never redacted. Placeholders like `${DB_PASSWORD}` and `<your-key>` are left alone. If a high-confidence pattern still matches after redaction, export deletes the transcript and refuses. Treat a pushed transcript the way you treat a chat log: read the preview before you say yes.
+
+## Sandboxes and permissions
+
+Codex's default sandbox blocks network access, so `commit --push` may fail; approve the escalation when Codex offers it, or run the printed `MANUAL` command in your own terminal. The temporary index lives inside `.git`, which stays writable. In OpenCode, allow the skill's script in `opencode.json` permissions to avoid a prompt per step.
+
+## Layout of this repo
+
+```
+agent_sessions/                   the package (stdlib only): cli.py, core.py, model.py, adapters/, templates/
+scripts/sessions.py, sessions.sh  entry point + shim (finds Python, always exits 0, prints STATUS)
+scripts/setup.sh, setup.ps1       teammate bootstrap: --claude, --skills, --repo <path>
+skills/{push,pull,init}/          the Claude Code plugin skills
+agents-skills/agent-sessions/     the portable Agent-Skills skill, with a bundled copy of the package
+tools/sync_bundle.py              keeps that copy identical (`--check` in CI)
+tests/                            python3 -m unittest discover -s tests
+.claude-plugin/                   plugin.json (name: sessions) and marketplace.json (name: agent-sessions)
+```
+
+Test the Claude plugin from a checkout with `claude --plugin-dir /path/to/agent-sessions`. Test the portable skill by copying `agents-skills/agent-sessions` into `~/.agents/skills/`.
+
+## Contributing an adapter
+
+An adapter is one file in `agent_sessions/adapters/` that turns a native store into `Session` events with canonical tool kinds (`shell`, `read`, `edit`, `write`, `search`, `web`, `agent`, `mcp`, `ask`). The renderer, result policy, redaction and files-touched logic never see agent names. Start from `gemini.py` (small) or `codex.py` (complete). A real session sample from your agent, with secrets removed, is the most useful contribution.
+
+## License
+
+MIT

agent_sessions_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+agent_sessions/__init__.py,sha256=ZBlIOF1aJ6SH6KOZXU_pHq97J9AK4729UxBcBXKiaj0,101
+agent_sessions/__main__.py,sha256=iqL5sqaJteojUO-yluSE4moQ3YYJvhp0lJWkXincvCQ,32
+agent_sessions/cli.py,sha256=ySkBiJJwC9Ijl6Su06hQy6Nzb4bgHkLcyR8Jogt1O9A,41456
+agent_sessions/core.py,sha256=pxe_1Cn7pYVSTUYP1M8RZFjGROLw9d7q3toYYd8eR9M,29543
+agent_sessions/model.py,sha256=WgyGmRyJ_JcsYqiR-t0LH7jORgV2TXH8M2Rcko72yEg,4502
+agent_sessions/adapters/__init__.py,sha256=yRdrRfXzb6EJmfvMAEHuN4FuNrpcrcdqQISRbiEB2Hs,4734
+agent_sessions/adapters/base.py,sha256=LFLuEqsY1YYJysP5Mw_sbsWGrO0-irWzBpKbDa7y5PU,3868
+agent_sessions/adapters/claude_code.py,sha256=cFdeX4GGxS-zExjcq4_ByLZy6tltFJChyVXTNClmD5A,13801
+agent_sessions/adapters/codex.py,sha256=aFICqc4dmtypzK4_W7HTKX5cGTqn30Onq8dP9TnJVks,17123
+agent_sessions/adapters/gemini.py,sha256=Tk-TplUD2w-6XSBFFgx3AynDt5rYhA3Rm8sc5koPLas,8753
+agent_sessions/adapters/opencode.py,sha256=aEdSUNtCz9vrdqfPOFgmvrBBgP2C6o6DEGLcVzhbjrI,10900
+agent_sessions/templates/gitattributes,sha256=CqVhUjk5gfSHWcYFxzNC6ljDWHvDjRk0KQT_eD5DKgQ,90
+agent_sessions/templates/sessions-README.md,sha256=iqQsBeH4AbAvwPR41hDHOKMedmYfvPvcqGG11AdXVkQ,2536
+agent_sessions/templates/summary.md,sha256=MgOwZTCR1h1cyXrhEUdWPDMtL7E6TvvdGU8eQQKSu-Q,1041
+agent_sessions_cli-0.2.0.dist-info/METADATA,sha256=i8Vyddks3GotTCqJh7G78OImIawHrFX9HTy7kzQNSfk,10194
+agent_sessions_cli-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agent_sessions_cli-0.2.0.dist-info/entry_points.txt,sha256=7qbuo2GYN9YI36zyanCrTBxcG8gBHwnFaeL8kduHNlU,60
+agent_sessions_cli-0.2.0.dist-info/licenses/LICENSE,sha256=1Xi4rec797g2CpFmhYBuDCNYb8O8rwLvTm6AttWv8H0,1066
+agent_sessions_cli-0.2.0.dist-info/RECORD,,

agent_sessions_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_sessions_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-sessions = agent_sessions.cli:entry

agent_sessions_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prajwal P
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.