Features

Portagenty is a portable, terminal-native workspace and session launcher. It adds committable organization, navigation, and lifecycle controls on top of real filesystem paths and persistent tmux or Zellij sessions—without replacing either.

One binary, two interfaces

Use the interactive TUI for daily navigation or the same pa binary as a scriptable one-shot CLI. There is no Portagenty daemon or GUI to keep running.

Portable by design

Workspace definitions are TOML files. Machine-local recency, registration, and ownership state stay outside the files you commit.

Workspaces and organization

Alternative hierarchies

Build named workspace views across projects that live under different parent directories. A project can appear in multiple workspaces without anything moving on disk.

Workspace picker

Browse registered workspaces from a home screen with recency ordering, live-session counts, fuzzy filtering, tag chips and tag views, plus reversible archive/unarchive controls.

Stable workspace identity

New workspaces receive a UUID. Auto-registration and previous_paths preserve a stable anchor when folders move or the same workspace is used from another environment.

Three-tier configuration

Merge global defaults, a committable *.portagenty.toml workspace, and per-project portagenty.toml session declarations with deterministic precedence.

From the picker you can also rename a workspace, edit its tags, reveal or open its path, unregister it without deleting the file, or explicitly delete it with confirmation. See the workspace-picker command reference and TOML schema.

Persistent sessions

tmux and Zellij

Both multiplexers are first-class adapters. Portagenty creates, lists, attaches to, and exports sessions while the multiplexer remains responsible for terminal persistence.

Tracked and untracked sessions

Workspace-declared sessions show as live or idle. Sessions started manually outside Portagenty appear as untracked rows and remain attachable without adoption or configuration changes.

Human lifecycle feedback

Rows show state, kind, command or description, path, recency, and available client counts. After a client returns, Portagenty prints the human workspace / session identity before any abnormal-exit diagnostic.

Takeover or shared attach

pa claim makes the current device the primary tmux client. --shared preserves other clients, while Zellij’s separately explicit --fresh path handles the multiplexer’s lack of per-client takeover.

Sessions live in tmux or Zellij, not in a Portagenty background process. Closing an SSH connection or leaving the TUI does not stop the session. Learn the exact state and attach semantics in Concepts.

Cross-device workflows

Phone, laptop, or remote shell

SSH into the host from any terminal, run pa, and attach to the same session. The workflow is terminal-native and does not depend on a browser or desktop application.

Termux-friendly UI

Narrow terminals receive two-line rows, shortened footer hints, arrow-key navigation, Android-style back behavior, and no-editor setup and management flows.

Resume-aware agent sessions

For sessions marked kind = "claude-code", pa launch --resume and pa claim --resume append --continue at launch time without mutating the committed workspace command.

The Termux guide covers the complete phone-over-SSH setup.

Find, navigate, and scaffold

Open from anywhere

Bare pa walks upward for a workspace or opens the global picker. Pass a directory or TOML path to jump directly to a specific workspace.

Layered folder search

The picker combines recency, zoxide, indexed search, fd, and a bounded filesystem walker, then fuzzy-ranks the results. Existing absolute and ~/ paths pin an exact result.

Scoped and global navigation

Drill into or widen the current search scope, toggle local/global search without losing the query, use Ctrl+G for an exact absolute-path jump, or switch to the filesystem tree browser.

Scaffold in place

Confirm a folder with no workspace and Portagenty can create and register one immediately. pa init, the first-run wizard, and in-TUI add/edit flows avoid hand-authoring TOML when you do not want to.

Start with the Quickstart or use the full command reference for every key and flag.

Manage, export, and integrate

No-editor session management

Add, rename, edit, and remove sessions from either the TUI or CLI. Manage commands, working directories, kind hints, descriptions, and per-session environment variables with comment-preserving TOML updates.

Open a plain shell

Drop out of Portagenty into a normal shell at a workspace or highlighted tree path—no multiplexer and no session state—when direct terminal work is the simpler choice.

Committable exports

pa export renders a tmux starter script or Zellij KDL layout that teammates can launch without installing Portagenty.

Shell ergonomics

Generate completions and install opt-in, idempotent bash snippets for shorter commands and Termux-friendly behavior.

pa:// deep links

Register pa:// with the operating system, then open a path, workspace UUID, named session, or plain shell from a browser, note, chat, or other link-aware application.

Portaconv companion

pa convos scopes conversation discovery and export to the current workspace. Stable IDs and previous paths let the companion bridge histories across folder moves and WSL/Windows path changes.

See Portaconv integration, snippets, and completion setup for the optional integration workflows.

Experimental Linux resource supervision

On supported Linux hosts, Portagenty includes a first-party, capability-aware supervision backend. It launches an eligible session as a transient systemd user service and records a machine-local receipt for its private tmux or Zellij target. Whole-workload ownership is claimed only when v2 evidence proves the exact workload root and every bounded descendant remains in the service cgroup.

Explicit Claude policy

Only kind = "claude-code" selects Claude placement and defaults: 3G MemoryHigh, 5G MemoryMax, 512MiB MemorySwapMax, 800% CPU, and 1200 tasks. Names and command strings never imply Claude policy; custom Claude values may only be equal or stricter.

Explicit scriptable controls

CLI launches remain ordinary unless --supervise or a resource-limit flag is supplied. Generic sessions receive no Claude defaults and stay in normal user-manager placement.

Soft and hard limits

MemoryHigh asks the kernel to reclaim memory. MemoryMax and MemorySwapMax are hard ceilings. CPU quota limits aggregate CPU time, and TasksMax bounds processes and threads.

Structural Claude placement

Claude services request claude-code.slice, ManagedOOMPreference=omit, and finite per-service TasksMax. Portagenty requires finite aggregate memory and CPU controls, while aggregate TasksMax is optional and may be infinity. It reads back service placement and limits but never creates or modifies the slice.

Workload-anchor proof

The shared tmux/Zellij anchor records a nonce, exact PID, and process start time, then binds proof to the exact tmux pane or Zellij session/runtime target. Portagenty checks the exact cgroup and walks every thread’s bounded /proc children edges before metrics or control are allowed.

Safe transitions and escapes

Live v1 services are legacy/restart-required exact-target attach-only. Current v2 incomplete-policy services may stop non-force but withhold metrics/force-kill. Escaped descendants produce split containment; external build-contained children in agent-work.slice stay externally bounded. Row-scoped and workspace-wide actions may stop the exact target and verified service non-force, but never signal external scopes. Partial unit/target presence remains ambiguous and fail-closed.

Linux-specific backend, portable core

Resource supervision currently requires Linux with a working systemd user manager and unified cgroup v2. On unsupported hosts, Portagenty’s workspace, TUI, CLI, search, export, deep-link, tmux, and Zellij features remain available; only the supervision capability reports unsupported. Portagenty installs no supervision daemon or listener and records no resource history, terminal content, or unattended telemetry.

If routine TUI Enter reaches an ownership-safe, non-creating preflight failure, it announces the reason and may fall back to an ordinary unsupervised launch. Explicit S, stale replacement, CLI supervision, receipt ambiguity, and failures after backend creation may have begun do not silently fall back. A pending-launch journal protects the creation-to-receipt gap. Stale cleanup removes only an exactly confirmed dead receipt and marker and sends no signal; partial presence never stale-cleans.

Use pa resources for capability, status, graceful-stop, and force-kill details. The schema reference explains why stable workspace identity is required.

Where to go next

Install Portagenty

Follow the installation guide and verify pa --version.

Launch a first session

The Quickstart walks through a workspace file, the TUI, and cross-device attach behavior.

Look up a command

The command reference documents every subcommand, flag, picker key, and session-list action.