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

Organize workspaces

Layer committable workspace views over real project paths without moving anything. Use recency, live-session counts, fuzzy filtering, tags, archives, stable UUIDs, and move-resilient path history to keep a large registry usable.

Keep sessions persistent

Create or attach to tmux and Zellij sessions, see tracked and untracked state, choose takeover or shared-client behavior, and return to the same work after the terminal or SSH connection changes.

Work across devices

Run the same terminal-native TUI from a laptop, remote shell, or phone over Termux. Narrow layouts, Android-style back behavior, and pa claim make the persistent host session practical from every screen size.

Find, navigate, and scaffold

Walk up from the current path, jump directly to a workspace, fuzzy-search layered filesystem sources, pin exact paths, switch local/global scope, browse a tree, and scaffold a new workspace without opening an editor.

Manage, export, and integrate

Add and edit sessions in the TUI or CLI, open plain shells, export tmux scripts or Zellij layouts, install completions and shell snippets, launch pa:// deep links, and bridge conversation history through Portaconv.

Experimental Linux resource supervision

On supported systemd-user/cgroup-v2 hosts, use explicit kind-selected Claude placement with soft and hard memory/swap, CPU, and task limits; prove the workload root and bounded descendants; and control only complete owned v2 containment while legacy and split workloads remain attach-only.

Explore the complete feature set, platform boundaries, and next steps →

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; supervision-required start for eligible idle UUID rows
#   S      custom limits / legacy upgrade / explicit supervised restart
#   e      edit session fields
#   d      delete session     x  safe stop / stale cleanup
#   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, recency, tags, filtering, archives, in-TUI find-folder + scaffold with nucleo fuzzy ranking, tree browser, exact-path navigation, 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, pa:// deep links, experimental Linux resource supervision, and auto-re-register on walk-up. Custom ordered groups 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.