Metadata-Version: 2.4
Name: puenteo
Version: 0.6.1
Summary: Puenteo — the bridge between coding agents. List, search, and export Claude/Codex/Grok/Pi/Antigravity/Qwen/Cursor/Continue/Aider/OpenHands/Goose sessions (Python library + CLI).
Author-email: mano7onam <mano7onamm@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mano7onam/puenteo
Project-URL: Repository, https://github.com/mano7onam/puenteo
Project-URL: Issues, https://github.com/mano7onam/puenteo/issues
Project-URL: Changelog, https://github.com/mano7onam/puenteo/releases
Keywords: agents,bridge,puente,claude-code,codex,grok,cli,library,export,markdown,pdf,session,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# puenteo

**The bridge between coding agents.**

Python **library + CLI** to discover, search, and export local sessions from Claude Code, Codex, Grok, and Pi — to Markdown, HTML, PDF, JSON, ZIP, CSV, XML, YAML.

*Puenteo* ← Spanish *puente* (bridge) + *puentear* (to bridge / jump across).

Zero runtime dependencies · Python ≥ 3.9 · **macOS · Linux · Windows**

[![PyPI](https://img.shields.io/pypi/v/puenteo.svg)](https://pypi.org/project/puenteo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Install

```bash
pip install puenteo
# or
uv add puenteo
# or
pipx install puenteo
```

From source:

```bash
git clone https://github.com/mano7onam/puenteo.git
cd puenteo
python3 -m venv .venv && .venv/bin/pip install -e .
```

## Library

```python
import puenteo

print(puenteo.status())

for s in puenteo.list_sessions(limit=10, cwd="~/dev/myapp"):
    print(s.provider, s.session_id[:8], s.title)

t = puenteo.load("019f7a24", include_tools=True)
hits = puenteo.search("gatekeeper dmg", exclude_session="my-current-id")
msgs = puenteo.pull("019f7a24", query="export", mode="query", top_k=15)
print(puenteo.outline("019f7a24"))

puenteo.export_session("019f7a24", fmt="md", output="chat.md")
puenteo.export_session("019f7a24", fmt="md", output="slice.md", query="export")
puenteo.export_session("019f7a24", fmt="pdf", output="chat.pdf")
puenteo.export_session("019f7a24", fmt="all", output="./exports/")

data, media_type, filename = puenteo.export_bytes("019f7a24", fmt="html")
```

## CLI

After `pip install puenteo` three commands point to the same CLI:

| Command | Notes |
|---------|--------|
| **`puenteo`** | main name |
| **`asb`** | short alias (Agent Session Bridge vibe) |
| **`pto`** | ultra-short |

```bash
puenteo status          # same as:
asb status
pto status

# Discover
puenteo list -n 20 --json
asb list --provider claude,grok --cwd ~/dev/myapp
asb list --since 2026-07-01 --group-by cwd

# Map a session, then pull what matters
asb outline <id>
asb show <id> --last 40
asb show <id> --range 100:120
asb search "topic" --json
asb search "topic" --session <id>
asb search "topic" --exclude-session <my-id>   # global search without yourself

asb pull <id> --query "topic" --mode query --top-k 15 --max-chars 8000
asb pull <id> --mode decisions --top-k 15
asb pull <id> --around 500 --radius 5

asb export <id> -f md -o chat.md
asb export <id> --query "topic" -f md -o slice.md
puenteo export <id> -f pdf -o chat.pdf
asb export <id> -f all -o ./out/
```

`<id>` = full uuid, **unique prefix** (e.g. `3627012b`), path, or unique title substring.

### Agent handoff recipe

```bash
puenteo status
puenteo list --cwd ~/dev/myapp
puenteo outline <id>
puenteo pull <id> --mode decisions --top-k 15
puenteo search 'keyword' --session <id>
puenteo pull <id> --around 500
```

## Providers

| Provider | Store |
|----------|--------|
| Claude Code | `~/.claude/projects/**/*.jsonl` |
| Codex | `~/.codex/sessions/**/rollout-*.jsonl` |
| Grok | `~/.grok/sessions/**/chat_history.jsonl` |
| Pi | `~/.pi/agent/sessions/**/*.jsonl` |
| **Antigravity** | `~/.gemini/antigravity/brain/*/…/transcript*.jsonl` |
| Qwen Code | `~/.qwen/projects/**/chats/*` |
| Gemini CLI | `~/.gemini` (non-antigravity chat dumps) |
| Cursor | macOS `~/Library/Application Support/Cursor` · Linux `~/.config/Cursor` · Windows `%APPDATA%\Cursor` |
| Continue | `~/.continue/sessions/**` |
| Aider | `.aider.chat.history.md` (scan with `--cwd` or `PUENTEO_AIDER_ROOTS`) |
| OpenHands | `~/.openhands/openhands.db` |
| Goose | Linux/macOS `~/.config/goose` · Windows `%APPDATA%\goose` |

Agent home dirs (`~/.claude`, `~/.codex`, `~/.pi`, …) are the same layout on all platforms; only a few Electron apps (Cursor) use OS-specific app-data paths.

```bash
asb list --provider antigravity,claude -n 20
asb pull <agy-id> --query "topic" --mode query
```

## Export formats

`md` · `txt` · `html` · `pdf` · `json` · `zip` · `csv` · `xml` · `yaml`

## Agent skill

```bash
./scripts/install_skills.sh
```

## Used by

[Terminal Dashboard](https://github.com/mano7onam/terminal-dashboard) imports **puenteo** for chat export (shared parsers, no duplication).

## License

MIT · [mano7onam/puenteo](https://github.com/mano7onam/puenteo)
