pos — focus-aligned terminal cockpit

pos (point of service) is a thin CLI that drives cmux (cmuxterm.app — an interactive terminal multiplexer / window manager, built on ghostty) on top of tmux, so your terminal workspaces mirror what you're actually focused on. It turns a pile of terminal tabs into a focus-organized cockpit: open projects by focus area, fan them across the screen, hide everything but the one thing, and keep Claude Code sessions alive across crashes and reboots.

• Repo: https://github.com/glebis/pos
• Runtime: Python ≥ 3.12, stdlib-only (uv-managed). macOS.
• Status: 193 tests green · v0.1.0

Built for a personal setup, but the patterns (cmux socket scripting, tmux-backed durability, resume-aware Claude launch) are reusable.

• Concept
• Install
• Commands
  • Interactive mode
  • Focus & projects
  • Claude Code, with resume
  • Window layout
  • Workspace CRUD
  • Durability & config
• Claude session recovery
• Screen tiling with AeroSpace
• Shell completion
• Settings
• Raycast extension
• Development
• Related
• License
• More from Gleb

┌─ cmux = COCKPIT ────────────────┐     ┌─ tmux = ENGINE ROOM ──────────┐
│ interactive, focus-organized     │  →  │ detached sessions that must    │
│ workspaces. You live here.       │     │ outlive the GUI (jobs, Claude).│
└──────────────────────────────────┘     └────────────────────────────────┘

Workspaces are backed by tmux new-session -A (attach-or-create), so re-opening re-attaches a live session and tmux-resurrect/continuum restore them across reboots. A focus.toml manifest maps focus areas → projects.

git clone https://github.com/glebis/pos && cd pos
uv tool install --editable .          # installs `pos` and `pos-cc` on PATH

The manifest lives at ~/.config/personal-os/focus.toml (override with POS_MANIFEST). pos must run inside a cmux terminal (cmux's socket control mode is cmux-processes-only).

Run pos --help for the full list. Every command is also driveable from the interactive TUI.

Navigate with ↑↓/j k, switch panes with →/Tab, quit with q. Keypress actions on the selection: Enter open · l load (confirms) · c Claude Code · n new workspace · r remove (confirms). Press : (or p) for a fuzzy command palette over the whole command table — anything without a hotkey runs from there. The project pane shows each repo's branch, a * dirty marker, and a ● when it has a live session.

It's TTY-only by design: piped or agent invocation exits with a message, so the JSON output of the other commands is never disturbed. Destructive actions (load, rm) confirm before running, and each action shells out through the same code path as the CLI, so output is identical.

pos cc <focus> launches Claude via the pos-cc wrapper instead of bare claude:

• It runs claude --continue when the cwd already has a stored conversation (under ~/.claude/projects/<cwd>/), else a fresh claude. The cwd is the resume key — no session-id bookkeeping.
• It runs claude as a child (not exec), so tmux-resurrect's ps save-strategy captures claude (one level below the pane) rather than claude's MCP-server children.
• @resurrect-processes maps "claude->pos-cc", so a restored Claude pane reruns pos-cc in its saved cwd → the conversation resumes instead of starting fresh.

Net effect: a reboot restores your tmux sessions and drops you back into the same Claude conversation, per project.

Each cmux internal window is a real macOS window, so a tiling WM can arrange them. pos tile fans projects into windows and asks AeroSpace to grid them. AeroSpace is optional — pos config window_manager none makes pos tile spread-only. pos gather un-tiles.

AeroSpace is a system-wide tiling WM; running it manages your whole desktop. Quit it anytime to return to normal window behaviour.

pos completions zsh  > ~/.zfunc/_pos     # ensure ~/.zfunc is on fpath + compinit runs
pos completions bash > ~/.local/share/bash-completion/completions/pos
pos completions fish > ~/.config/fish/completions/pos.fish

Candidates are dynamic (live focuses, projects, open workspaces, settings) via a hidden pos __list <kind>.

~/.config/personal-os/settings.toml (override with POS_SETTINGS):

A Raycast front-end lives in raycast/. It's a thin client over the same JSON contract the CLI exposes (pos emits JSON whenever stdout isn't a TTY), so it just shells out and renders. Three commands:

• Pos: Focuses — browse focus areas; drill into a focus's projects.
• Pos: Project Status — every project grouped by focus, with git branch + dirty marker; open, launch Claude Code, load the focus, or copy the path.
• Pos: Run Command — fuzzy-pick any pos command and run it; commands taking arguments prompt for them.

It needs the pos CLI on your login shell's PATH (auto-detected via zsh -lc 'command -v pos', overridable in the extension's pos binary preference) and Node ≥ 20.

The extension is pending review for the Raycast Store. Until it's accepted you can run it locally — Raycast loads it as a development extension:

git clone https://github.com/glebis/pos && cd pos/raycast
npm install
npm run dev          # builds, imports into Raycast, and watches for changes

Open Raycast and search "pos" — the three commands appear (tagged Development). Keep that npm run dev running while you use it; if Raycast asks for the dev server again after a restart, just re-run it. To stop, press Ctrl-C in that terminal.

Once the Store PR is merged, install it the normal way from the Raycast Store and you won't need the dev server. See raycast/README.md for development details.

uv run pytest -q        # 193 tests

Pure logic (argv builders, planners, parsers) is separated from side-effecting cmux calls so most of the surface is unit-tested without a live socket.

See CONTRIBUTING.md for how to propose changes, SECURITY.md to report vulnerabilities, and CHANGELOG.md for release notes.

• cmux (cmuxterm.app, com.cmuxterm.app) — the terminal multiplexer pos drives (third-party app, built on ghostty)
• tmux · tmux-resurrect · tmux-continuum
• AeroSpace — tiling WM used by pos tile
• Claude Code — what pos cc launches with resume

Apache-2.0 © 2026 Gleb Kalinin. See AUTHORSHIP.md for the authorship record and NOTICE for attribution. The Raycast extension under raycast/ is MIT-licensed, as the Raycast Store requires.

I build focus tools, AI workflows, and write about creativity & tech.

• claude-skills — a library of Claude Code skills