portagenty

The problem

Filesystem: one parent per project

~/code/

portagenty

cyberbase

crosswalker

~/work/

client-app

api-server

~/learn/

rust-book

ml-sandbox

Every project stuck in one parent directory. No cross-cutting views.
Want “all my agentic projects”? You cd between three different folders.

portagenty adds a layer on top

Workspaces: many views, nothing moves

agentic.portagenty.toml

~/code/portagenty

~/work/api-server

~/learn/ml-sandbox

Projects from 3 different parent dirs

client-work.portagenty.toml

~/work/client-app

~/work/api-server

~/code/crosswalker

Same api-server, different context

Projects stay where they are. Workspaces are views — recency, tags, curated groups.
The same project can appear in many workspaces.

Why

Agentic coding — Claude Code, opencode, Aider, and the dev servers and test runners they drive — lives in the terminal. But the terminal is stuck where you started it: one laptop, one window size, one SSH hop. Walk away, switch devices, or lose the connection and you’re rebuilding context from scratch.

portagenty treats your agent sessions as a portable workspace. Define them once in a committable TOML file, launch them on any device over tmux or zellij, and hop between laptop, desktop, and phone-over-SSH (Termux) with a single pa claim. The sessions keep running; only the terminal attached to them changes.

Features

One-command install

cargo install --git https://github.com/cybersader/portagenty. No clone, no cd, no hand compile. Single static Rust binary at ~/.cargo/bin/pa.

Cross-device takeover

SSH in from your phone, run pa claim, and the session reshapes to the new device. On tmux that’s real takeover (other clients get kicked); on zellij, add --fresh for the kill-and-recreate path since zellij doesn’t expose per-client disconnection.

Untracked session adoption

Tmux / zellij sessions you started manually show up in the TUI alongside workspace-defined ones. Attach with Enter — nothing new to set up.

Multiplexer-aware

tmux + zellij first-class. Sessions with cwd, command, and env work consistently across both. WezTerm explicitly skipped — see the roadmap.

First-run wizard

Run pa on a new machine with no config and it walks you through a 30-second setup. No TOML editing required to start.

No-editor session management

pa init / pa add / pa rm / pa edit handle the whole workspace-file lifecycle from the command line. Phone-keyboard friendly, comment-preserving.

Find folder + scaffold

Press n in the workspace picker to fuzzy-search your filesystem for project folders. Tiered backends (recency, zoxide, plocate, fd, stdlib walker) ranked by nucleo. Pick a folder and pa scaffolds a workspace TOML on the spot.

In-TUI session editing

Press e on any session row to edit name, cwd, command, kind, or env vars without leaving the TUI. CWD editing opens the same find/tree browser. All changes are comment-preserving writes to your TOML file.

Committable layouts

pa export renders your workspace as a tmux starter script or zellij KDL layout. Commit it; teammates launch without needing pa installed.

Bundled bash ergonomics

pa snippets install pa-aliases drops curated, idempotent shell snippets into your rc file. Short aliases, Termux-friendly tweaks, all opt-in.

Tree browser

Press Ctrl+T inside the find overlay to switch to a filesystem tree view. Expand/collapse directories, navigate with arrow keys or vim bindings, select a folder with Shift+Enter.

Portaconv integration

Sister tool portaconv extracts Claude Code conversation history, rewrites OS paths baked into content, and exposes it over MCP. pa convos list / pa convos dump <id> scope it to this workspace automatically (including previous_paths from folder moves). pa init --with-agent-hooks drops .mcp.json + .claude/skills/ so agents self-discover it. See Portaconv integration.

How it works

📱

Phone

Termux + SSH

SSH

🖥️

Server

tmux / zellij

SSH

💻

Laptop

direct or SSH

Sessions persist on the server

●claudepa claim

●devpa launch dev

○testsnot started

Tip

Sessions live in the multiplexer, not in pa. When you close your SSH connection, they keep running. pa claim from any device re-attaches and reshapes the terminal to the new screen size.

See it in action

Phone bootstrap

# SSH into your desktop from your phone (Termux)
ssh desktop
cd {`~/code/`}new-project

# Scaffold a workspace — no editor required
pa init
pa add claude -c "claude --resume" --kind claude-code
pa add dev    -c "bun run dev"     --kind dev-server

# Launch the TUI, pick a session, Enter
pa

Cross-device takeover

# On your phone — start a Claude Code session
pa launch claude

# Later, on your laptop — take it over (tmux = real takeover;
# zellij add --fresh for the kill-and-recreate path)
pa claim claude                   # tmux: kicks phone's client
pa claim claude --fresh           # zellij: kill + recreate

# Already inside a tmux session? Kick other clients from here:
paclaim                           # needs the pa-aliases snippet

# Back on phone later — takeover again
pa claim claude

TUI workflow

# Open the TUI from anywhere
pa

# Workspace picker (home screen)
#   ↑/↓  navigate    Enter  open workspace
#   n    find folder + scaffold new workspace
#   ?    help

# Session list
#   Enter  attach/create session
#   e      edit session fields
#   d      delete session     x  kill live session
#   Esc    back to picker     q  quit

The navigation model

Workspace Picker — home screen, Esc always returns here

▸my-project2h ago

 side-hustleyesterday

 live sessions on this machine

n: find   d: unregister   ?: help   q: quit

Enter

Session List [zellij]

●claudeClive · 1 client

○shellidle

○devDidle

?mysteryuntracked

e: edit   d: delete   x: kill   Esc: back

Enter

pa → zellij session “claude”

detach: Ctrl+O then d

re-attach: pa claim claude

Architecture

Three-tier config

portagenty merges configuration from three layers. Any tier can register projects and sessions; the workspace layer is the primary authoring surface.

highest

Workspace

*.portagenty.toml — sessions, projects, mpx choice. Committable.

merges with

medium

Per-project

portagenty.toml at project root — repo-defined sessions. Committable.

merges with

lowest

Global

$XDG_CONFIG_HOME/portagenty/ — default mpx, workspace registry. Machine-local.

The workspace file is designed to commit — no absolute paths, no machine-specific state, no secrets. Volatile state (recency, last- attached timestamps) lives separately in $XDG_STATE_HOME.

Status

v1 is feature-complete and usable daily. Core flows work end-to-end: walk up to find a workspace, render the session list, pick one, attach — in tmux or zellij.

Most v1.x items have shipped: zellij adapter, untracked adoption, pa claim cross-device takeover, kind: hints, per-session env vars, declarative export, first-run wizard, bundled snippets, full no-editor session management, workspace picker home screen, in-TUI find-folder + scaffold with nucleo fuzzy ranking, tree browser, workspace-scoped session names, in-TUI session editing, CWD browse via find overlay, responsive 2-line footer, arrow keys

• Alt+J/K navigation, help overlay, and auto-re-register on walk-up. Tags + custom-groups views and pa up eager-launch are still on the roadmap.

WezTerm is intentionally not supported — its mux is built around the GUI emulator’s window model, not the headless detach/reattach pattern portagenty’s cross-device work depends on. See the roadmap for the rationale.

The design doc is the source of truth for terminology and architecture.