Portaconv integration

portaconv (binary pconv) is portagenty’s sister tool. It’s a terminal-native conversation extractor + MCP server for agent CLIs (Claude Code first, others later). Portagenty is the launcher; portaconv is the bridge.

Portagenty

Launches agent sessions. Cross-device takeover. Workspace files with stable id and auto-maintained previous_paths.

Portaconv

Reads those agent sessions’ conversation history (read-only), emits paste-ready markdown, normalizes OS-specific paths baked into content, exposes it all over MCP.

Why they’re sister tools

The workflow they split between them is:

pa

Launches a Claude Code session at /path/to/project. Records id and (eventually) previous_paths in the workspace TOML.

Claude Code

Writes ~/.claude/projects/<path-encoded-cwd>/*.jsonl. Conversation content references absolute paths (/mnt/c/… on WSL, C:\… on Windows).

pa

User moves the folder. Walk-up on the next run re-registers, appends the old location to previous_paths.

pconv

Reads storage scoped to projects + previous_paths. Finds the pre-move JSONLs. Emits paste-ready markdown with paths rewritten for the current host.

pa

pa convos shim forwards with —workspace-toml injected. pa init —with-agent-hooks scaffolds the MCP wiring so agents self-discover pconv.

The three integration points

1. previous_paths auto-maintenance (config layer).

   Every workspace TOML gets a id = "<uuid>" field on pa init / onboarding wizard / in-TUI scaffold. When walk-up runs on a workspace whose id is already in the global registry at a different canonical path (i.e. you mv’d the folder), pa appends the old directory to a committed previous_paths = [...] array in the TOML and drops the stale registry entry.

   The registry mirrors each workspace’s id alongside its path, so even the realistic move (old file deleted by mv) reconciles correctly — there’s evidence of the prior location in the registry regardless of whether the old file survives on disk.

   name = "my-project"
   id = "76452e59-6066-4628-a6e3-b69cbf45da20"
   projects = ["."]
   previous_paths = [
     "/home/me/code/old-location",
     "/home/me/code/even-older-location",
   ]

   Portaconv reads projects + previous_paths for scope when listing or dumping conversations — without this, the pre-move session history keyed to ~/.claude/projects/<encoded-old-cwd>/ is silently orphaned.

2. pa convos shim (CLI layer).

   Thin pass-through to pconv with --workspace-toml <resolved> injected into the pconv subcommand argv. Any shape pconv supports now or in the future works verbatim via pa convos ...:

   pa convos list                               # scoped to this workspace
   pa convos list --since 7d                    # pconv flags pass through
   pa convos dump <session-id>                  # paste-ready markdown
   pa convos dump <session-id> --rewrite wsl-to-win
   pa convos dump <session-id> --full-results   # un-truncate tool outputs

   Portagenty does NOT bundle pconv. When pconv isn’t on PATH, pa convos exits with a clear install hint (cargo install portaconv) rather than silently becoming a no-op.

3. pa init --with-agent-hooks (scaffold layer).

   Opt-in flag that writes four files next to the workspace TOML:

   File	Purpose
   .mcp.json	Registers pconv mcp serve as an MCP server
   .claude/commands/convos.md	Slash command that uses pa convos
   .claude/skills/portaconv.md	Skill describing what portaconv is + when to reach for it
   .claude/skills/portagenty-workspace.md	Skill describing the workspace TOML contract

   A Claude Code agent entering the workspace self-discovers both tools from these files — no human needs to explain what pconv is or which rewrite flag to use. Idempotent: re-running against an already-scaffolded workspace leaves the TOML alone and only writes missing hook files.

Install portaconv

portagenty doesn’t bundle it — pconv is a separate crate with its own release cadence.

With Rust installed

cargo install --git https://github.com/cybersader/portaconv

Binary lands at ~/.cargo/bin/pconv. pa convos picks it up automatically on the next invocation.

From a local clone

git clone https://github.com/cybersader/portaconv ~/code/portaconv
cargo install --path ~/code/portaconv

Useful if you’re developing pconv alongside pa.

Verify:

pconv --version                 # confirms pconv is on PATH
pa convos list                  # uses it, scoped to this workspace

When you’d actually reach for it

Folder moved

mv ~/code/foo ~/archive/foo. Claude Code can’t --continue the old sessions. pa convos list still sees them via previous_paths. pa convos dump <id> gives you paste-ready content for a fresh session.

WSL ↔ Windows switch

WSL-authored conversation, Windows host trying to resume. The baked-in /mnt/c/… paths will fail. pa convos dump <id> --rewrite wsl-to-win rewrites them to C:\… before you paste.

Agent self-discovery

After pa init --with-agent-hooks, a Claude Code agent entering the workspace can query conversation history via MCP without the user explaining how. Skills file describes the contract.

Paste-ready handoff

Generic transcript export. pa convos dump <id> renders a session as markdown suitable for pasting into another agent CLI (OpenCode, Aider, continue.dev) or a different Claude model.

What portagenty explicitly does NOT do

Note

portagenty is a launcher. It does not read, write, or sync Claude Code’s conversation storage itself. The id + previous_paths fields are anchors that downstream tools consume.

• No daemon, no file watching, no auto-sync.
• No content rewriting — that’s pconv’s job.
• No MCP server of its own — pa convos is a shim, not an MCP provider.
• No bundling of pconv — separate install path, separate release cadence.

The split keeps each tool’s scope tight: portagenty knows about workspaces and sessions, portaconv knows about conversation storage and content normalization.

Relationship to other tools

• portaconv. Direct sister. The workflow above.
• claudecode-project-sync (in agentic-workflow-and-tech-stack). Earlier sibling: a Python script that symlinks WSL and Windows Claude project dirs. Superseded in practice by portaconv (extraction handles the content-poisoning case; symlinks don’t). Kept for reference.
• Claude Code native project-id (if it ships someday). Would make id redundant for the cross-env case, but the id + previous_paths anchors stay useful as a general workspace identity handle for tooling that isn’t Claude Code-specific.